Subversion Repositories Applications.gtt

Rev

Rev 94 | Only display areas with differences | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 94 Rev 187
1
<?php
1
<?php
2
 
2
 
3
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
3
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
4
 
4
 
5
/**
5
/**
6
 * Contains the DB_common base class
6
 * Contains the DB_common base class
7
 *
7
 *
8
 * PHP versions 4 and 5
8
 * PHP version 5
9
 *
9
 *
10
 * LICENSE: This source file is subject to version 3.0 of the PHP license
10
 * LICENSE: This source file is subject to version 3.0 of the PHP license
11
 * that is available through the world-wide-web at the following URI:
11
 * that is available through the world-wide-web at the following URI:
12
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
12
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
13
 * the PHP License and are unable to obtain it through the web, please
13
 * the PHP License and are unable to obtain it through the web, please
14
 * send a note to license@php.net so we can mail you a copy immediately.
14
 * send a note to license@php.net so we can mail you a copy immediately.
15
 *
15
 *
16
 * @category   Database
16
 * @category   Database
17
 * @package    DB
17
 * @package    DB
18
 * @author     Stig Bakken <ssb@php.net>
18
 * @author     Stig Bakken <ssb@php.net>
19
 * @author     Tomas V.V. Cox <cox@idecnet.com>
19
 * @author     Tomas V.V. Cox <cox@idecnet.com>
20
 * @author     Daniel Convissor <danielc@php.net>
20
 * @author     Daniel Convissor <danielc@php.net>
21
 * @copyright  1997-2005 The PHP Group
21
 * @copyright  1997-2007 The PHP Group
22
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
22
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
23
 * @version    CVS: $Id: common.php,v 1.137 2005/04/07 14:27:35 danielc Exp $
23
 * @version    CVS: $Id$
24
 * @link       http://pear.php.net/package/DB
24
 * @link       http://pear.php.net/package/DB
25
 */
25
 */
26
 
26
 
27
/**
27
/**
28
 * Obtain the PEAR class so it can be extended from
28
 * Obtain the PEAR class so it can be extended from
29
 */
29
 */
30
require_once 'PEAR.php';
30
require_once 'PEAR.php';
31
 
31
 
32
/**
32
/**
33
 * DB_common is the base class from which each database driver class extends
33
 * DB_common is the base class from which each database driver class extends
34
 *
34
 *
35
 * All common methods are declared here.  If a given DBMS driver contains
35
 * All common methods are declared here.  If a given DBMS driver contains
36
 * a particular method, that method will overload the one here.
36
 * a particular method, that method will overload the one here.
37
 *
37
 *
38
 * @category   Database
38
 * @category   Database
39
 * @package    DB
39
 * @package    DB
40
 * @author     Stig Bakken <ssb@php.net>
40
 * @author     Stig Bakken <ssb@php.net>
41
 * @author     Tomas V.V. Cox <cox@idecnet.com>
41
 * @author     Tomas V.V. Cox <cox@idecnet.com>
42
 * @author     Daniel Convissor <danielc@php.net>
42
 * @author     Daniel Convissor <danielc@php.net>
43
 * @copyright  1997-2005 The PHP Group
43
 * @copyright  1997-2007 The PHP Group
44
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
44
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
45
 * @version    Release: 1.7.6
45
 * @version    Release: 1.9.2
46
 * @link       http://pear.php.net/package/DB
46
 * @link       http://pear.php.net/package/DB
47
 */
47
 */
48
class DB_common extends PEAR
48
class DB_common extends PEAR
49
{
49
{
50
    // {{{ properties
50
    // {{{ properties
51
 
51
 
52
    /**
52
    /**
53
     * The current default fetch mode
53
     * The current default fetch mode
54
     * @var integer
54
     * @var integer
55
     */
55
     */
56
    var $fetchmode = DB_FETCHMODE_ORDERED;
56
    var $fetchmode = DB_FETCHMODE_ORDERED;
57
 
57
 
58
    /**
58
    /**
59
     * The name of the class into which results should be fetched when
59
     * The name of the class into which results should be fetched when
60
     * DB_FETCHMODE_OBJECT is in effect
60
     * DB_FETCHMODE_OBJECT is in effect
61
     *
61
     *
62
     * @var string
62
     * @var string
63
     */
63
     */
64
    var $fetchmode_object_class = 'stdClass';
64
    var $fetchmode_object_class = 'stdClass';
65
 
65
 
66
    /**
66
    /**
67
     * Was a connection present when the object was serialized()?
67
     * Was a connection present when the object was serialized()?
68
     * @var bool
68
     * @var bool
69
     * @see DB_common::__sleep(), DB_common::__wake()
69
     * @see DB_common::__sleep(), DB_common::__wake()
70
     */
70
     */
71
    var $was_connected = null;
71
    var $was_connected = null;
72
 
72
 
73
    /**
73
    /**
74
     * The most recently executed query
74
     * The most recently executed query
75
     * @var string
75
     * @var string
76
     */
76
     */
77
    var $last_query = '';
77
    var $last_query = '';
78
 
78
 
79
    /**
79
    /**
80
     * Run-time configuration options
80
     * Run-time configuration options
81
     *
81
     *
82
     * The 'optimize' option has been deprecated.  Use the 'portability'
82
     * The 'optimize' option has been deprecated.  Use the 'portability'
83
     * option instead.
83
     * option instead.
84
     *
84
     *
85
     * @var array
85
     * @var array
86
     * @see DB_common::setOption()
86
     * @see DB_common::setOption()
87
     */
87
     */
88
    var $options = array(
88
    var $options = array(
89
        'result_buffering' => 500,
89
        'result_buffering' => 500,
90
        'persistent' => false,
90
        'persistent' => false,
91
        'ssl' => false,
91
        'ssl' => false,
92
        'debug' => 0,
92
        'debug' => 0,
93
        'seqname_format' => '%s_seq',
93
        'seqname_format' => '%s_seq',
94
        'autofree' => false,
94
        'autofree' => false,
95
        'portability' => DB_PORTABILITY_NONE,
95
        'portability' => DB_PORTABILITY_NONE,
96
        'optimize' => 'performance',  // Deprecated.  Use 'portability'.
96
        'optimize' => 'performance',  // Deprecated.  Use 'portability'.
97
    );
97
    );
98
 
98
 
99
    /**
99
    /**
100
     * The parameters from the most recently executed query
100
     * The parameters from the most recently executed query
101
     * @var array
101
     * @var array
102
     * @since Property available since Release 1.7.0
102
     * @since Property available since Release 1.7.0
103
     */
103
     */
104
    var $last_parameters = array();
104
    var $last_parameters = array();
105
 
105
 
106
    /**
106
    /**
107
     * The elements from each prepared statement
107
     * The elements from each prepared statement
108
     * @var array
108
     * @var array
109
     */
109
     */
110
    var $prepare_tokens = array();
110
    var $prepare_tokens = array();
111
 
111
 
112
    /**
112
    /**
113
     * The data types of the various elements in each prepared statement
113
     * The data types of the various elements in each prepared statement
114
     * @var array
114
     * @var array
115
     */
115
     */
116
    var $prepare_types = array();
116
    var $prepare_types = array();
117
 
117
 
118
    /**
118
    /**
119
     * The prepared queries
119
     * The prepared queries
120
     * @var array
120
     * @var array
121
     */
121
     */
122
    var $prepared_queries = array();
122
    var $prepared_queries = array();
-
 
123
 
-
 
124
    /**
-
 
125
     * Flag indicating that the last query was a manipulation query.
-
 
126
     * @access protected
-
 
127
     * @var boolean
-
 
128
     */
-
 
129
    var $_last_query_manip = false;
-
 
130
 
-
 
131
    /**
-
 
132
     * Flag indicating that the next query <em>must</em> be a manipulation
-
 
133
     * query.
-
 
134
     * @access protected
-
 
135
     * @var boolean
-
 
136
     */
-
 
137
    var $_next_query_manip = false;
123
 
138
 
124
 
139
 
125
    // }}}
140
    // }}}
126
    // {{{ DB_common
141
    // {{{ DB_common
127
 
142
 
128
    /**
143
    /**
129
     * This constructor calls <kbd>$this->PEAR('DB_Error')</kbd>
144
     * This constructor calls <kbd>$this->PEAR('DB_Error')</kbd>
130
     *
145
     *
131
     * @return void
146
     * @return void
132
     */
147
     */
133
    function DB_common()
148
    function __construct()
134
    {
149
    {
135
        $this->PEAR('DB_Error');
150
        $this->PEAR('DB_Error');
136
    }
151
    }
137
 
152
 
138
    // }}}
153
    // }}}
139
    // {{{ __sleep()
154
    // {{{ __sleep()
140
 
155
 
141
    /**
156
    /**
142
     * Automatically indicates which properties should be saved
157
     * Automatically indicates which properties should be saved
143
     * when PHP's serialize() function is called
158
     * when PHP's serialize() function is called
144
     *
159
     *
145
     * @return array  the array of properties names that should be saved
160
     * @return array  the array of properties names that should be saved
146
     */
161
     */
147
    function __sleep()
162
    function __sleep()
148
    {
163
    {
149
        if ($this->connection) {
164
        if ($this->connection) {
150
            // Don't disconnect(), people use serialize() for many reasons
165
            // Don't disconnect(), people use serialize() for many reasons
151
            $this->was_connected = true;
166
            $this->was_connected = true;
152
        } else {
167
        } else {
153
            $this->was_connected = false;
168
            $this->was_connected = false;
154
        }
169
        }
155
        if (isset($this->autocommit)) {
170
        if (isset($this->autocommit)) {
156
            return array('autocommit',
171
            return array('autocommit',
157
                         'dbsyntax',
172
                         'dbsyntax',
158
                         'dsn',
173
                         'dsn',
159
                         'features',
174
                         'features',
160
                         'fetchmode',
175
                         'fetchmode',
161
                         'fetchmode_object_class',
176
                         'fetchmode_object_class',
162
                         'options',
177
                         'options',
163
                         'was_connected',
178
                         'was_connected',
164
                   );
179
                   );
165
        } else {
180
        } else {
166
            return array('dbsyntax',
181
            return array('dbsyntax',
167
                         'dsn',
182
                         'dsn',
168
                         'features',
183
                         'features',
169
                         'fetchmode',
184
                         'fetchmode',
170
                         'fetchmode_object_class',
185
                         'fetchmode_object_class',
171
                         'options',
186
                         'options',
172
                         'was_connected',
187
                         'was_connected',
173
                   );
188
                   );
174
        }
189
        }
175
    }
190
    }
176
 
191
 
177
    // }}}
192
    // }}}
178
    // {{{ __wakeup()
193
    // {{{ __wakeup()
179
 
194
 
180
    /**
195
    /**
181
     * Automatically reconnects to the database when PHP's unserialize()
196
     * Automatically reconnects to the database when PHP's unserialize()
182
     * function is called
197
     * function is called
183
     *
198
     *
184
     * The reconnection attempt is only performed if the object was connected
199
     * The reconnection attempt is only performed if the object was connected
185
     * at the time PHP's serialize() function was run.
200
     * at the time PHP's serialize() function was run.
186
     *
201
     *
187
     * @return void
202
     * @return void
188
     */
203
     */
189
    function __wakeup()
204
    function __wakeup()
190
    {
205
    {
191
        if ($this->was_connected) {
206
        if ($this->was_connected) {
192
            $this->connect($this->dsn, $this->options);
207
            $this->connect($this->dsn, $this->options['persistent']);
193
        }
208
        }
194
    }
209
    }
195
 
210
 
196
    // }}}
211
    // }}}
197
    // {{{ __toString()
212
    // {{{ __toString()
198
 
213
 
199
    /**
214
    /**
200
     * Automatic string conversion for PHP 5
215
     * Automatic string conversion for PHP 5
201
     *
216
     *
202
     * @return string  a string describing the current PEAR DB object
217
     * @return string  a string describing the current PEAR DB object
203
     *
218
     *
204
     * @since Method available since Release 1.7.0
219
     * @since Method available since Release 1.7.0
205
     */
220
     */
206
    function __toString()
221
    function __toString()
207
    {
222
    {
208
        $info = strtolower(get_class($this));
223
        $info = strtolower(get_class($this));
209
        $info .=  ': (phptype=' . $this->phptype .
224
        $info .=  ': (phptype=' . $this->phptype .
210
                  ', dbsyntax=' . $this->dbsyntax .
225
                  ', dbsyntax=' . $this->dbsyntax .
211
                  ')';
226
                  ')';
212
        if ($this->connection) {
227
        if ($this->connection) {
213
            $info .= ' [connected]';
228
            $info .= ' [connected]';
214
        }
229
        }
215
        return $info;
230
        return $info;
216
    }
231
    }
217
 
232
 
218
    // }}}
233
    // }}}
219
    // {{{ toString()
234
    // {{{ toString()
220
 
235
 
221
    /**
236
    /**
222
     * DEPRECATED:  String conversion method
237
     * DEPRECATED:  String conversion method
223
     *
238
     *
224
     * @return string  a string describing the current PEAR DB object
239
     * @return string  a string describing the current PEAR DB object
225
     *
240
     *
226
     * @deprecated Method deprecated in Release 1.7.0
241
     * @deprecated Method deprecated in Release 1.7.0
227
     */
242
     */
228
    function toString()
243
    function toString()
229
    {
244
    {
230
        return $this->__toString();
245
        return $this->__toString();
231
    }
246
    }
232
 
247
 
233
    // }}}
248
    // }}}
234
    // {{{ quoteString()
249
    // {{{ quoteString()
235
 
250
 
236
    /**
251
    /**
237
     * DEPRECATED: Quotes a string so it can be safely used within string
252
     * DEPRECATED: Quotes a string so it can be safely used within string
238
     * delimiters in a query
253
     * delimiters in a query
239
     *
254
     *
240
     * @param string $string  the string to be quoted
255
     * @param string $string  the string to be quoted
241
     *
256
     *
242
     * @return string  the quoted string
257
     * @return string  the quoted string
243
     *
258
     *
244
     * @see DB_common::quoteSmart(), DB_common::escapeSimple()
259
     * @see DB_common::quoteSmart(), DB_common::escapeSimple()
245
     * @deprecated Method deprecated some time before Release 1.2
260
     * @deprecated Method deprecated some time before Release 1.2
246
     */
261
     */
247
    function quoteString($string)
262
    function quoteString($string)
248
    {
263
    {
249
        $string = $this->quote($string);
264
        $string = $this->quoteSmart($string);
250
        if ($string{0} == "'") {
265
        if ($string{0} == "'") {
251
            return substr($string, 1, -1);
266
            return substr($string, 1, -1);
252
        }
267
        }
253
        return $string;
268
        return $string;
254
    }
269
    }
255
 
270
 
256
    // }}}
271
    // }}}
257
    // {{{ quote()
272
    // {{{ quote()
258
 
273
 
259
    /**
274
    /**
260
     * DEPRECATED: Quotes a string so it can be safely used in a query
275
     * DEPRECATED: Quotes a string so it can be safely used in a query
261
     *
276
     *
262
     * @param string $string  the string to quote
277
     * @param string $string  the string to quote
263
     *
278
     *
264
     * @return string  the quoted string or the string <samp>NULL</samp>
279
     * @return string  the quoted string or the string <samp>NULL</samp>
265
     *                  if the value submitted is <kbd>null</kbd>.
280
     *                  if the value submitted is <kbd>null</kbd>.
266
     *
281
     *
267
     * @see DB_common::quoteSmart(), DB_common::escapeSimple()
282
     * @see DB_common::quoteSmart(), DB_common::escapeSimple()
268
     * @deprecated Deprecated in release 1.6.0
283
     * @deprecated Deprecated in release 1.6.0
269
     */
284
     */
270
    function quote($string = null)
285
    function quote($string = null)
271
    {
286
    {
272
        return ($string === null) ? 'NULL'
287
        return $this->quoteSmart($string);
273
                                  : "'" . str_replace("'", "''", $string) . "'";
-
 
274
    }
288
    }
275
 
289
 
276
    // }}}
290
    // }}}
277
    // {{{ quoteIdentifier()
291
    // {{{ quoteIdentifier()
278
 
292
 
279
    /**
293
    /**
280
     * Quotes a string so it can be safely used as a table or column name
294
     * Quotes a string so it can be safely used as a table or column name
281
     *
295
     *
282
     * Delimiting style depends on which database driver is being used.
296
     * Delimiting style depends on which database driver is being used.
283
     *
297
     *
284
     * NOTE: just because you CAN use delimited identifiers doesn't mean
298
     * NOTE: just because you CAN use delimited identifiers doesn't mean
285
     * you SHOULD use them.  In general, they end up causing way more
299
     * you SHOULD use them.  In general, they end up causing way more
286
     * problems than they solve.
300
     * problems than they solve.
287
     *
301
     *
288
     * Portability is broken by using the following characters inside
302
     * Portability is broken by using the following characters inside
289
     * delimited identifiers:
303
     * delimited identifiers:
290
     *   + backtick (<kbd>`</kbd>) -- due to MySQL
304
     *   + backtick (<kbd>`</kbd>) -- due to MySQL
291
     *   + double quote (<kbd>"</kbd>) -- due to Oracle
305
     *   + double quote (<kbd>"</kbd>) -- due to Oracle
292
     *   + brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- due to Access
306
     *   + brackets (<kbd>[</kbd> or <kbd>]</kbd>) -- due to Access
293
     *
307
     *
294
     * Delimited identifiers are known to generally work correctly under
308
     * Delimited identifiers are known to generally work correctly under
295
     * the following drivers:
309
     * the following drivers:
296
     *   + mssql
310
     *   + mssql
297
     *   + mysql
311
     *   + mysql
298
     *   + mysqli
312
     *   + mysqli
299
     *   + oci8
313
     *   + oci8
300
     *   + odbc(access)
314
     *   + odbc(access)
301
     *   + odbc(db2)
315
     *   + odbc(db2)
302
     *   + pgsql
316
     *   + pgsql
303
     *   + sqlite
317
     *   + sqlite
304
     *   + sybase (must execute <kbd>set quoted_identifier on</kbd> sometime
318
     *   + sybase (must execute <kbd>set quoted_identifier on</kbd> sometime
305
     *     prior to use)
319
     *     prior to use)
306
     *
320
     *
307
     * InterBase doesn't seem to be able to use delimited identifiers
321
     * InterBase doesn't seem to be able to use delimited identifiers
308
     * via PHP 4.  They work fine under PHP 5.
322
     * via PHP 4.  They work fine under PHP 5.
309
     *
323
     *
310
     * @param string $str  the identifier name to be quoted
324
     * @param string $str  the identifier name to be quoted
311
     *
325
     *
312
     * @return string  the quoted identifier
326
     * @return string  the quoted identifier
313
     *
327
     *
314
     * @since Method available since Release 1.6.0
328
     * @since Method available since Release 1.6.0
315
     */
329
     */
316
    function quoteIdentifier($str)
330
    function quoteIdentifier($str)
317
    {
331
    {
318
        return '"' . str_replace('"', '""', $str) . '"';
332
        return '"' . str_replace('"', '""', $str) . '"';
319
    }
333
    }
320
 
334
 
321
    // }}}
335
    // }}}
322
    // {{{ quoteSmart()
336
    // {{{ quoteSmart()
323
 
337
 
324
    /**
338
    /**
325
     * Formats input so it can be safely used in a query
339
     * Formats input so it can be safely used in a query
326
     *
340
     *
327
     * The output depends on the PHP data type of input and the database
341
     * The output depends on the PHP data type of input and the database
328
     * type being used.
342
     * type being used.
329
     *
343
     *
330
     * @param mixed $in  the data to be formatted
344
     * @param mixed $in  the data to be formatted
331
     *
345
     *
332
     * @return mixed  the formatted data.  The format depends on the input's
346
     * @return mixed  the formatted data.  The format depends on the input's
333
     *                 PHP type:
347
     *                 PHP type:
334
     * <ul>
348
     * <ul>
335
     *  <li>
349
     *  <li>
336
     *    <kbd>input</kbd> -> <samp>returns</samp>
350
     *    <kbd>input</kbd> -> <samp>returns</samp>
337
     *  </li>
351
     *  </li>
338
     *  <li>
352
     *  <li>
339
     *    <kbd>null</kbd> -> the string <samp>NULL</samp>
353
     *    <kbd>null</kbd> -> the string <samp>NULL</samp>
340
     *  </li>
354
     *  </li>
341
     *  <li>
355
     *  <li>
342
     *    <kbd>integer</kbd> or <kbd>double</kbd> -> the unquoted number
356
     *    <kbd>integer</kbd> or <kbd>double</kbd> -> the unquoted number
343
     *  </li>
357
     *  </li>
344
     *  <li>
358
     *  <li>
345
     *    <kbd>bool</kbd> -> output depends on the driver in use
359
     *    <kbd>bool</kbd> -> output depends on the driver in use
346
     *    Most drivers return integers: <samp>1</samp> if
360
     *    Most drivers return integers: <samp>1</samp> if
347
     *    <kbd>true</kbd> or <samp>0</samp> if
361
     *    <kbd>true</kbd> or <samp>0</samp> if
348
     *    <kbd>false</kbd>.
362
     *    <kbd>false</kbd>.
349
     *    Some return strings: <samp>TRUE</samp> if
363
     *    Some return strings: <samp>TRUE</samp> if
350
     *    <kbd>true</kbd> or <samp>FALSE</samp> if
364
     *    <kbd>true</kbd> or <samp>FALSE</samp> if
351
     *    <kbd>false</kbd>.
365
     *    <kbd>false</kbd>.
352
     *    Finally one returns strings: <samp>T</samp> if
366
     *    Finally one returns strings: <samp>T</samp> if
353
     *    <kbd>true</kbd> or <samp>F</samp> if
367
     *    <kbd>true</kbd> or <samp>F</samp> if
354
     *    <kbd>false</kbd>. Here is a list of each DBMS,
368
     *    <kbd>false</kbd>. Here is a list of each DBMS,
355
     *    the values returned and the suggested column type:
369
     *    the values returned and the suggested column type:
356
     *    <ul>
370
     *    <ul>
357
     *      <li>
371
     *      <li>
358
     *        <kbd>dbase</kbd> -> <samp>T/F</samp>
372
     *        <kbd>dbase</kbd> -> <samp>T/F</samp>
359
     *        (<kbd>Logical</kbd>)
373
     *        (<kbd>Logical</kbd>)
360
     *      </li>
374
     *      </li>
361
     *      <li>
375
     *      <li>
362
     *        <kbd>fbase</kbd> -> <samp>TRUE/FALSE</samp>
376
     *        <kbd>fbase</kbd> -> <samp>TRUE/FALSE</samp>
363
     *        (<kbd>BOOLEAN</kbd>)
377
     *        (<kbd>BOOLEAN</kbd>)
364
     *      </li>
378
     *      </li>
365
     *      <li>
379
     *      <li>
366
     *        <kbd>ibase</kbd> -> <samp>1/0</samp>
380
     *        <kbd>ibase</kbd> -> <samp>1/0</samp>
367
     *        (<kbd>SMALLINT</kbd>) [1]
381
     *        (<kbd>SMALLINT</kbd>) [1]
368
     *      </li>
382
     *      </li>
369
     *      <li>
383
     *      <li>
370
     *        <kbd>ifx</kbd> -> <samp>1/0</samp>
384
     *        <kbd>ifx</kbd> -> <samp>1/0</samp>
371
     *        (<kbd>SMALLINT</kbd>) [1]
385
     *        (<kbd>SMALLINT</kbd>) [1]
372
     *      </li>
386
     *      </li>
373
     *      <li>
387
     *      <li>
374
     *        <kbd>msql</kbd> -> <samp>1/0</samp>
388
     *        <kbd>msql</kbd> -> <samp>1/0</samp>
375
     *        (<kbd>INTEGER</kbd>)
389
     *        (<kbd>INTEGER</kbd>)
376
     *      </li>
390
     *      </li>
377
     *      <li>
391
     *      <li>
378
     *        <kbd>mssql</kbd> -> <samp>1/0</samp>
392
     *        <kbd>mssql</kbd> -> <samp>1/0</samp>
379
     *        (<kbd>BIT</kbd>)
393
     *        (<kbd>BIT</kbd>)
380
     *      </li>
394
     *      </li>
381
     *      <li>
395
     *      <li>
382
     *        <kbd>mysql</kbd> -> <samp>1/0</samp>
396
     *        <kbd>mysql</kbd> -> <samp>1/0</samp>
383
     *        (<kbd>TINYINT(1)</kbd>)
397
     *        (<kbd>TINYINT(1)</kbd>)
384
     *      </li>
398
     *      </li>
385
     *      <li>
399
     *      <li>
386
     *        <kbd>mysqli</kbd> -> <samp>1/0</samp>
400
     *        <kbd>mysqli</kbd> -> <samp>1/0</samp>
387
     *        (<kbd>TINYINT(1)</kbd>)
401
     *        (<kbd>TINYINT(1)</kbd>)
388
     *      </li>
402
     *      </li>
389
     *      <li>
403
     *      <li>
390
     *        <kbd>oci8</kbd> -> <samp>1/0</samp>
404
     *        <kbd>oci8</kbd> -> <samp>1/0</samp>
391
     *        (<kbd>NUMBER(1)</kbd>)
405
     *        (<kbd>NUMBER(1)</kbd>)
392
     *      </li>
406
     *      </li>
393
     *      <li>
407
     *      <li>
394
     *        <kbd>odbc</kbd> -> <samp>1/0</samp>
408
     *        <kbd>odbc</kbd> -> <samp>1/0</samp>
395
     *        (<kbd>SMALLINT</kbd>) [1]
409
     *        (<kbd>SMALLINT</kbd>) [1]
396
     *      </li>
410
     *      </li>
397
     *      <li>
411
     *      <li>
398
     *        <kbd>pgsql</kbd> -> <samp>TRUE/FALSE</samp>
412
     *        <kbd>pgsql</kbd> -> <samp>TRUE/FALSE</samp>
399
     *        (<kbd>BOOLEAN</kbd>)
413
     *        (<kbd>BOOLEAN</kbd>)
400
     *      </li>
414
     *      </li>
401
     *      <li>
415
     *      <li>
402
     *        <kbd>sqlite</kbd> -> <samp>1/0</samp>
416
     *        <kbd>sqlite</kbd> -> <samp>1/0</samp>
403
     *        (<kbd>INTEGER</kbd>)
417
     *        (<kbd>INTEGER</kbd>)
404
     *      </li>
418
     *      </li>
405
     *      <li>
419
     *      <li>
406
     *        <kbd>sybase</kbd> -> <samp>1/0</samp>
420
     *        <kbd>sybase</kbd> -> <samp>1/0</samp>
407
     *        (<kbd>TINYINT(1)</kbd>)
421
     *        (<kbd>TINYINT(1)</kbd>)
408
     *      </li>
422
     *      </li>
409
     *    </ul>
423
     *    </ul>
410
     *    [1] Accommodate the lowest common denominator because not all
424
     *    [1] Accommodate the lowest common denominator because not all
411
     *    versions of have <kbd>BOOLEAN</kbd>.
425
     *    versions of have <kbd>BOOLEAN</kbd>.
412
     *  </li>
426
     *  </li>
413
     *  <li>
427
     *  <li>
414
     *    other (including strings and numeric strings) ->
428
     *    other (including strings and numeric strings) ->
415
     *    the data with single quotes escaped by preceeding
429
     *    the data with single quotes escaped by preceeding
416
     *    single quotes, backslashes are escaped by preceeding
430
     *    single quotes, backslashes are escaped by preceeding
417
     *    backslashes, then the whole string is encapsulated
431
     *    backslashes, then the whole string is encapsulated
418
     *    between single quotes
432
     *    between single quotes
419
     *  </li>
433
     *  </li>
420
     * </ul>
434
     * </ul>
421
     *
435
     *
422
     * @see DB_common::escapeSimple()
436
     * @see DB_common::escapeSimple()
423
     * @since Method available since Release 1.6.0
437
     * @since Method available since Release 1.6.0
424
     */
438
     */
425
    function quoteSmart($in)
439
    function quoteSmart($in)
426
    {
440
    {
427
        if (is_int($in) || is_double($in)) {
441
        if (is_int($in)) {
428
            return $in;
442
            return $in;
-
 
443
        } elseif (is_float($in)) {
-
 
444
            return $this->quoteFloat($in);
429
        } elseif (is_bool($in)) {
445
        } elseif (is_bool($in)) {
430
            return $in ? 1 : 0;
446
            return $this->quoteBoolean($in);
431
        } elseif (is_null($in)) {
447
        } elseif (is_null($in)) {
432
            return 'NULL';
448
            return 'NULL';
433
        } else {
449
        } else {
-
 
450
            if ($this->dbsyntax == 'access'
-
 
451
                && preg_match('/^#.+#$/', $in))
-
 
452
            {
-
 
453
                return $this->escapeSimple($in);
-
 
454
            }
434
            return "'" . $this->escapeSimple($in) . "'";
455
            return "'" . $this->escapeSimple($in) . "'";
435
        }
456
        }
436
    }
457
    }
437
 
458
 
438
    // }}}
459
    // }}}
-
 
460
    // {{{ quoteBoolean()
-
 
461
 
-
 
462
    /**
-
 
463
     * Formats a boolean value for use within a query in a locale-independent
-
 
464
     * manner.
-
 
465
     *
-
 
466
     * @param boolean the boolean value to be quoted.
-
 
467
     * @return string the quoted string.
-
 
468
     * @see DB_common::quoteSmart()
-
 
469
     * @since Method available since release 1.7.8.
-
 
470
     */
-
 
471
    function quoteBoolean($boolean) {
-
 
472
        return $boolean ? '1' : '0';
-
 
473
    }
-
 
474
     
-
 
475
    // }}}
-
 
476
    // {{{ quoteFloat()
-
 
477
 
-
 
478
    /**
-
 
479
     * Formats a float value for use within a query in a locale-independent
-
 
480
     * manner.
-
 
481
     *
-
 
482
     * @param float the float value to be quoted.
-
 
483
     * @return string the quoted string.
-
 
484
     * @see DB_common::quoteSmart()
-
 
485
     * @since Method available since release 1.7.8.
-
 
486
     */
-
 
487
    function quoteFloat($float) {
-
 
488
        return "'".$this->escapeSimple(str_replace(',', '.', strval(floatval($float))))."'";
-
 
489
    }
-
 
490
     
-
 
491
    // }}}
439
    // {{{ escapeSimple()
492
    // {{{ escapeSimple()
440
 
493
 
441
    /**
494
    /**
442
     * Escapes a string according to the current DBMS's standards
495
     * Escapes a string according to the current DBMS's standards
443
     *
496
     *
444
     * In SQLite, this makes things safe for inserts/updates, but may
497
     * In SQLite, this makes things safe for inserts/updates, but may
445
     * cause problems when performing text comparisons against columns
498
     * cause problems when performing text comparisons against columns
446
     * containing binary data. See the
499
     * containing binary data. See the
447
     * {@link http://php.net/sqlite_escape_string PHP manual} for more info.
500
     * {@link http://php.net/sqlite_escape_string PHP manual} for more info.
448
     *
501
     *
449
     * @param string $str  the string to be escaped
502
     * @param string $str  the string to be escaped
450
     *
503
     *
451
     * @return string  the escaped string
504
     * @return string  the escaped string
452
     *
505
     *
453
     * @see DB_common::quoteSmart()
506
     * @see DB_common::quoteSmart()
454
     * @since Method available since Release 1.6.0
507
     * @since Method available since Release 1.6.0
455
     */
508
     */
456
    function escapeSimple($str)
509
    function escapeSimple($str)
457
    {
510
    {
458
        return str_replace("'", "''", $str);
511
        return str_replace("'", "''", $str);
459
    }
512
    }
460
 
513
 
461
    // }}}
514
    // }}}
462
    // {{{ provides()
515
    // {{{ provides()
463
 
516
 
464
    /**
517
    /**
465
     * Tells whether the present driver supports a given feature
518
     * Tells whether the present driver supports a given feature
466
     *
519
     *
467
     * @param string $feature  the feature you're curious about
520
     * @param string $feature  the feature you're curious about
468
     *
521
     *
469
     * @return bool  whether this driver supports $feature
522
     * @return bool  whether this driver supports $feature
470
     */
523
     */
471
    function provides($feature)
524
    function provides($feature)
472
    {
525
    {
473
        return $this->features[$feature];
526
        return $this->features[$feature];
474
    }
527
    }
475
 
528
 
476
    // }}}
529
    // }}}
477
    // {{{ setFetchMode()
530
    // {{{ setFetchMode()
478
 
531
 
479
    /**
532
    /**
480
     * Sets the fetch mode that should be used by default for query results
533
     * Sets the fetch mode that should be used by default for query results
481
     *
534
     *
482
     * @param integer $fetchmode    DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC
535
     * @param integer $fetchmode    DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC
483
     *                               or DB_FETCHMODE_OBJECT
536
     *                               or DB_FETCHMODE_OBJECT
484
     * @param string $object_class  the class name of the object to be returned
537
     * @param string $object_class  the class name of the object to be returned
485
     *                               by the fetch methods when the
538
     *                               by the fetch methods when the
486
     *                               DB_FETCHMODE_OBJECT mode is selected.
539
     *                               DB_FETCHMODE_OBJECT mode is selected.
487
     *                               If no class is specified by default a cast
540
     *                               If no class is specified by default a cast
488
     *                               to object from the assoc array row will be
541
     *                               to object from the assoc array row will be
489
     *                               done.  There is also the posibility to use
542
     *                               done.  There is also the posibility to use
490
     *                               and extend the 'DB_row' class.
543
     *                               and extend the 'DB_row' class.
491
     *
544
     *
492
     * @see DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC, DB_FETCHMODE_OBJECT
545
     * @see DB_FETCHMODE_ORDERED, DB_FETCHMODE_ASSOC, DB_FETCHMODE_OBJECT
493
     */
546
     */
494
    function setFetchMode($fetchmode, $object_class = 'stdClass')
547
    function setFetchMode($fetchmode, $object_class = 'stdClass')
495
    {
548
    {
496
        switch ($fetchmode) {
549
        switch ($fetchmode) {
497
            case DB_FETCHMODE_OBJECT:
550
            case DB_FETCHMODE_OBJECT:
498
                $this->fetchmode_object_class = $object_class;
551
                $this->fetchmode_object_class = $object_class;
499
            case DB_FETCHMODE_ORDERED:
552
            case DB_FETCHMODE_ORDERED:
500
            case DB_FETCHMODE_ASSOC:
553
            case DB_FETCHMODE_ASSOC:
501
                $this->fetchmode = $fetchmode;
554
                $this->fetchmode = $fetchmode;
502
                break;
555
                break;
503
            default:
556
            default:
504
                return $this->raiseError('invalid fetchmode mode');
557
                return $this->raiseError('invalid fetchmode mode');
505
        }
558
        }
506
    }
559
    }
507
 
560
 
508
    // }}}
561
    // }}}
509
    // {{{ setOption()
562
    // {{{ setOption()
510
 
563
 
511
    /**
564
    /**
512
     * Sets run-time configuration options for PEAR DB
565
     * Sets run-time configuration options for PEAR DB
513
     *
566
     *
514
     * Options, their data types, default values and description:
567
     * Options, their data types, default values and description:
515
     * <ul>
568
     * <ul>
516
     * <li>
569
     * <li>
517
     * <var>autofree</var> <kbd>boolean</kbd> = <samp>false</samp>
570
     * <var>autofree</var> <kbd>boolean</kbd> = <samp>false</samp>
518
     *      <br />should results be freed automatically when there are no
571
     *      <br />should results be freed automatically when there are no
519
     *            more rows?
572
     *            more rows?
520
     * </li><li>
573
     * </li><li>
521
     * <var>result_buffering</var> <kbd>integer</kbd> = <samp>500</samp>
574
     * <var>result_buffering</var> <kbd>integer</kbd> = <samp>500</samp>
522
     *      <br />how many rows of the result set should be buffered?
575
     *      <br />how many rows of the result set should be buffered?
523
     *      <br />In mysql: mysql_unbuffered_query() is used instead of
576
     *      <br />In mysql: mysql_unbuffered_query() is used instead of
524
     *            mysql_query() if this value is 0.  (Release 1.7.0)
577
     *            mysql_query() if this value is 0.  (Release 1.7.0)
525
     *      <br />In oci8: this value is passed to ocisetprefetch().
578
     *      <br />In oci8: this value is passed to ocisetprefetch().
526
     *            (Release 1.7.0)
579
     *            (Release 1.7.0)
527
     * </li><li>
580
     * </li><li>
528
     * <var>debug</var> <kbd>integer</kbd> = <samp>0</samp>
581
     * <var>debug</var> <kbd>integer</kbd> = <samp>0</samp>
529
     *      <br />debug level
582
     *      <br />debug level
530
     * </li><li>
583
     * </li><li>
531
     * <var>persistent</var> <kbd>boolean</kbd> = <samp>false</samp>
584
     * <var>persistent</var> <kbd>boolean</kbd> = <samp>false</samp>
532
     *      <br />should the connection be persistent?
585
     *      <br />should the connection be persistent?
533
     * </li><li>
586
     * </li><li>
534
     * <var>portability</var> <kbd>integer</kbd> = <samp>DB_PORTABILITY_NONE</samp>
587
     * <var>portability</var> <kbd>integer</kbd> = <samp>DB_PORTABILITY_NONE</samp>
535
     *      <br />portability mode constant (see below)
588
     *      <br />portability mode constant (see below)
536
     * </li><li>
589
     * </li><li>
537
     * <var>seqname_format</var> <kbd>string</kbd> = <samp>%s_seq</samp>
590
     * <var>seqname_format</var> <kbd>string</kbd> = <samp>%s_seq</samp>
538
     *      <br />the sprintf() format string used on sequence names.  This
591
     *      <br />the sprintf() format string used on sequence names.  This
539
     *            format is applied to sequence names passed to
592
     *            format is applied to sequence names passed to
540
     *            createSequence(), nextID() and dropSequence().
593
     *            createSequence(), nextID() and dropSequence().
541
     * </li><li>
594
     * </li><li>
542
     * <var>ssl</var> <kbd>boolean</kbd> = <samp>false</samp>
595
     * <var>ssl</var> <kbd>boolean</kbd> = <samp>false</samp>
543
     *      <br />use ssl to connect?
596
     *      <br />use ssl to connect?
544
     * </li>
597
     * </li>
545
     * </ul>
598
     * </ul>
546
     *
599
     *
547
     * -----------------------------------------
600
     * -----------------------------------------
548
     *
601
     *
549
     * PORTABILITY MODES
602
     * PORTABILITY MODES
550
     *
603
     *
551
     * These modes are bitwised, so they can be combined using <kbd>|</kbd>
604
     * These modes are bitwised, so they can be combined using <kbd>|</kbd>
552
     * and removed using <kbd>^</kbd>.  See the examples section below on how
605
     * and removed using <kbd>^</kbd>.  See the examples section below on how
553
     * to do this.
606
     * to do this.
554
     *
607
     *
555
     * <samp>DB_PORTABILITY_NONE</samp>
608
     * <samp>DB_PORTABILITY_NONE</samp>
556
     * turn off all portability features
609
     * turn off all portability features
557
     *
610
     *
558
     * This mode gets automatically turned on if the deprecated
611
     * This mode gets automatically turned on if the deprecated
559
     * <var>optimize</var> option gets set to <samp>performance</samp>.
612
     * <var>optimize</var> option gets set to <samp>performance</samp>.
560
     *
613
     *
561
     *
614
     *
562
     * <samp>DB_PORTABILITY_LOWERCASE</samp>
615
     * <samp>DB_PORTABILITY_LOWERCASE</samp>
563
     * convert names of tables and fields to lower case when using
616
     * convert names of tables and fields to lower case when using
564
     * <kbd>get*()</kbd>, <kbd>fetch*()</kbd> and <kbd>tableInfo()</kbd>
617
     * <kbd>get*()</kbd>, <kbd>fetch*()</kbd> and <kbd>tableInfo()</kbd>
565
     *
618
     *
566
     * This mode gets automatically turned on in the following databases
619
     * This mode gets automatically turned on in the following databases
567
     * if the deprecated option <var>optimize</var> gets set to
620
     * if the deprecated option <var>optimize</var> gets set to
568
     * <samp>portability</samp>:
621
     * <samp>portability</samp>:
569
     * + oci8
622
     * + oci8
570
     *
623
     *
571
     *
624
     *
572
     * <samp>DB_PORTABILITY_RTRIM</samp>
625
     * <samp>DB_PORTABILITY_RTRIM</samp>
573
     * right trim the data output by <kbd>get*()</kbd> <kbd>fetch*()</kbd>
626
     * right trim the data output by <kbd>get*()</kbd> <kbd>fetch*()</kbd>
574
     *
627
     *
575
     *
628
     *
576
     * <samp>DB_PORTABILITY_DELETE_COUNT</samp>
629
     * <samp>DB_PORTABILITY_DELETE_COUNT</samp>
577
     * force reporting the number of rows deleted
630
     * force reporting the number of rows deleted
578
     *
631
     *
579
     * Some DBMS's don't count the number of rows deleted when performing
632
     * Some DBMS's don't count the number of rows deleted when performing
580
     * simple <kbd>DELETE FROM tablename</kbd> queries.  This portability
633
     * simple <kbd>DELETE FROM tablename</kbd> queries.  This portability
581
     * mode tricks such DBMS's into telling the count by adding
634
     * mode tricks such DBMS's into telling the count by adding
582
     * <samp>WHERE 1=1</samp> to the end of <kbd>DELETE</kbd> queries.
635
     * <samp>WHERE 1=1</samp> to the end of <kbd>DELETE</kbd> queries.
583
     *
636
     *
584
     * This mode gets automatically turned on in the following databases
637
     * This mode gets automatically turned on in the following databases
585
     * if the deprecated option <var>optimize</var> gets set to
638
     * if the deprecated option <var>optimize</var> gets set to
586
     * <samp>portability</samp>:
639
     * <samp>portability</samp>:
587
     * + fbsql
640
     * + fbsql
588
     * + mysql
641
     * + mysql
589
     * + mysqli
642
     * + mysqli
590
     * + sqlite
643
     * + sqlite
591
     *
644
     *
592
     *
645
     *
593
     * <samp>DB_PORTABILITY_NUMROWS</samp>
646
     * <samp>DB_PORTABILITY_NUMROWS</samp>
594
     * enable hack that makes <kbd>numRows()</kbd> work in Oracle
647
     * enable hack that makes <kbd>numRows()</kbd> work in Oracle
595
     *
648
     *
596
     * This mode gets automatically turned on in the following databases
649
     * This mode gets automatically turned on in the following databases
597
     * if the deprecated option <var>optimize</var> gets set to
650
     * if the deprecated option <var>optimize</var> gets set to
598
     * <samp>portability</samp>:
651
     * <samp>portability</samp>:
599
     * + oci8
652
     * + oci8
600
     *
653
     *
601
     *
654
     *
602
     * <samp>DB_PORTABILITY_ERRORS</samp>
655
     * <samp>DB_PORTABILITY_ERRORS</samp>
603
     * makes certain error messages in certain drivers compatible
656
     * makes certain error messages in certain drivers compatible
604
     * with those from other DBMS's
657
     * with those from other DBMS's
605
     *
658
     *
606
     * + mysql, mysqli:  change unique/primary key constraints
659
     * + mysql, mysqli:  change unique/primary key constraints
607
     *   DB_ERROR_ALREADY_EXISTS -> DB_ERROR_CONSTRAINT
660
     *   DB_ERROR_ALREADY_EXISTS -> DB_ERROR_CONSTRAINT
608
     *
661
     *
609
     * + odbc(access):  MS's ODBC driver reports 'no such field' as code
662
     * + odbc(access):  MS's ODBC driver reports 'no such field' as code
610
     *   07001, which means 'too few parameters.'  When this option is on
663
     *   07001, which means 'too few parameters.'  When this option is on
611
     *   that code gets mapped to DB_ERROR_NOSUCHFIELD.
664
     *   that code gets mapped to DB_ERROR_NOSUCHFIELD.
612
     *   DB_ERROR_MISMATCH -> DB_ERROR_NOSUCHFIELD
665
     *   DB_ERROR_MISMATCH -> DB_ERROR_NOSUCHFIELD
613
     *
666
     *
614
     * <samp>DB_PORTABILITY_NULL_TO_EMPTY</samp>
667
     * <samp>DB_PORTABILITY_NULL_TO_EMPTY</samp>
615
     * convert null values to empty strings in data output by get*() and
668
     * convert null values to empty strings in data output by get*() and
616
     * fetch*().  Needed because Oracle considers empty strings to be null,
669
     * fetch*().  Needed because Oracle considers empty strings to be null,
617
     * while most other DBMS's know the difference between empty and null.
670
     * while most other DBMS's know the difference between empty and null.
618
     *
671
     *
619
     *
672
     *
620
     * <samp>DB_PORTABILITY_ALL</samp>
673
     * <samp>DB_PORTABILITY_ALL</samp>
621
     * turn on all portability features
674
     * turn on all portability features
622
     *
675
     *
623
     * -----------------------------------------
676
     * -----------------------------------------
624
     *
677
     *
625
     * Example 1. Simple setOption() example
678
     * Example 1. Simple setOption() example
626
     * <code>
679
     * <code>
627
     * $db->setOption('autofree', true);
680
     * $db->setOption('autofree', true);
628
     * </code>
681
     * </code>
629
     *
682
     *
630
     * Example 2. Portability for lowercasing and trimming
683
     * Example 2. Portability for lowercasing and trimming
631
     * <code>
684
     * <code>
632
     * $db->setOption('portability',
685
     * $db->setOption('portability',
633
     *                 DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);
686
     *                 DB_PORTABILITY_LOWERCASE | DB_PORTABILITY_RTRIM);
634
     * </code>
687
     * </code>
635
     *
688
     *
636
     * Example 3. All portability options except trimming
689
     * Example 3. All portability options except trimming
637
     * <code>
690
     * <code>
638
     * $db->setOption('portability',
691
     * $db->setOption('portability',
639
     *                 DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);
692
     *                 DB_PORTABILITY_ALL ^ DB_PORTABILITY_RTRIM);
640
     * </code>
693
     * </code>
641
     *
694
     *
642
     * @param string $option option name
695
     * @param string $option option name
643
     * @param mixed  $value value for the option
696
     * @param mixed  $value value for the option
644
     *
697
     *
645
     * @return int  DB_OK on success.  A DB_Error object on failure.
698
     * @return int  DB_OK on success.  A DB_Error object on failure.
646
     *
699
     *
647
     * @see DB_common::$options
700
     * @see DB_common::$options
648
     */
701
     */
649
    function setOption($option, $value)
702
    function setOption($option, $value)
650
    {
703
    {
651
        if (isset($this->options[$option])) {
704
        if (isset($this->options[$option])) {
652
            $this->options[$option] = $value;
705
            $this->options[$option] = $value;
653
 
706
 
654
            /*
707
            /*
655
             * Backwards compatibility check for the deprecated 'optimize'
708
             * Backwards compatibility check for the deprecated 'optimize'
656
             * option.  Done here in case settings change after connecting.
709
             * option.  Done here in case settings change after connecting.
657
             */
710
             */
658
            if ($option == 'optimize') {
711
            if ($option == 'optimize') {
659
                if ($value == 'portability') {
712
                if ($value == 'portability') {
660
                    switch ($this->phptype) {
713
                    switch ($this->phptype) {
661
                        case 'oci8':
714
                        case 'oci8':
662
                            $this->options['portability'] =
715
                            $this->options['portability'] =
663
                                    DB_PORTABILITY_LOWERCASE |
716
                                    DB_PORTABILITY_LOWERCASE |
664
                                    DB_PORTABILITY_NUMROWS;
717
                                    DB_PORTABILITY_NUMROWS;
665
                            break;
718
                            break;
666
                        case 'fbsql':
719
                        case 'fbsql':
667
                        case 'mysql':
720
                        case 'mysql':
668
                        case 'mysqli':
721
                        case 'mysqli':
669
                        case 'sqlite':
722
                        case 'sqlite':
670
                            $this->options['portability'] =
723
                            $this->options['portability'] =
671
                                    DB_PORTABILITY_DELETE_COUNT;
724
                                    DB_PORTABILITY_DELETE_COUNT;
672
                            break;
725
                            break;
673
                    }
726
                    }
674
                } else {
727
                } else {
675
                    $this->options['portability'] = DB_PORTABILITY_NONE;
728
                    $this->options['portability'] = DB_PORTABILITY_NONE;
676
                }
729
                }
677
            }
730
            }
678
 
731
 
679
            return DB_OK;
732
            return DB_OK;
680
        }
733
        }
681
        return $this->raiseError("unknown option $option");
734
        return $this->raiseError("unknown option $option");
682
    }
735
    }
683
 
736
 
684
    // }}}
737
    // }}}
685
    // {{{ getOption()
738
    // {{{ getOption()
686
 
739
 
687
    /**
740
    /**
688
     * Returns the value of an option
741
     * Returns the value of an option
689
     *
742
     *
690
     * @param string $option  the option name you're curious about
743
     * @param string $option  the option name you're curious about
691
     *
744
     *
692
     * @return mixed  the option's value
745
     * @return mixed  the option's value
693
     */
746
     */
694
    function getOption($option)
747
    function getOption($option)
695
    {
748
    {
696
        if (isset($this->options[$option])) {
749
        if (isset($this->options[$option])) {
697
            return $this->options[$option];
750
            return $this->options[$option];
698
        }
751
        }
699
        return $this->raiseError("unknown option $option");
752
        return $this->raiseError("unknown option $option");
700
    }
753
    }
701
 
754
 
702
    // }}}
755
    // }}}
703
    // {{{ prepare()
756
    // {{{ prepare()
704
 
757
 
705
    /**
758
    /**
706
     * Prepares a query for multiple execution with execute()
759
     * Prepares a query for multiple execution with execute()
707
     *
760
     *
708
     * Creates a query that can be run multiple times.  Each time it is run,
761
     * Creates a query that can be run multiple times.  Each time it is run,
709
     * the placeholders, if any, will be replaced by the contents of
762
     * the placeholders, if any, will be replaced by the contents of
710
     * execute()'s $data argument.
763
     * execute()'s $data argument.
711
     *
764
     *
712
     * Three types of placeholders can be used:
765
     * Three types of placeholders can be used:
713
     *   + <kbd>?</kbd>  scalar value (i.e. strings, integers).  The system
766
     *   + <kbd>?</kbd>  scalar value (i.e. strings, integers).  The system
714
     *                   will automatically quote and escape the data.
767
     *                   will automatically quote and escape the data.
715
     *   + <kbd>!</kbd>  value is inserted 'as is'
768
     *   + <kbd>!</kbd>  value is inserted 'as is'
716
     *   + <kbd>&</kbd>  requires a file name.  The file's contents get
769
     *   + <kbd>&</kbd>  requires a file name.  The file's contents get
717
     *                   inserted into the query (i.e. saving binary
770
     *                   inserted into the query (i.e. saving binary
718
     *                   data in a db)
771
     *                   data in a db)
719
     *
772
     *
720
     * Example 1.
773
     * Example 1.
721
     * <code>
774
     * <code>
722
     * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
775
     * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
723
     * $data = array(
776
     * $data = array(
724
     *     "John's text",
777
     *     "John's text",
725
     *     "'it''s good'",
778
     *     "'it''s good'",
726
     *     'filename.txt'
779
     *     'filename.txt'
727
     * );
780
     * );
728
     * $res = $db->execute($sth, $data);
781
     * $res = $db->execute($sth, $data);
729
     * </code>
782
     * </code>
730
     *
783
     *
731
     * Use backslashes to escape placeholder characters if you don't want
784
     * Use backslashes to escape placeholder characters if you don't want
732
     * them to be interpreted as placeholders:
785
     * them to be interpreted as placeholders:
733
     * <pre>
786
     * <pre>
734
     *    "UPDATE foo SET col=? WHERE col='over \& under'"
787
     *    "UPDATE foo SET col=? WHERE col='over \& under'"
735
     * </pre>
788
     * </pre>
736
     *
789
     *
737
     * With some database backends, this is emulated.
790
     * With some database backends, this is emulated.
738
     *
791
     *
739
     * {@internal ibase and oci8 have their own prepare() methods.}}
792
     * {@internal ibase and oci8 have their own prepare() methods.}}
740
     *
793
     *
741
     * @param string $query  the query to be prepared
794
     * @param string $query  the query to be prepared
742
     *
795
     *
743
     * @return mixed  DB statement resource on success. A DB_Error object
796
     * @return mixed  DB statement resource on success. A DB_Error object
744
     *                 on failure.
797
     *                 on failure.
745
     *
798
     *
746
     * @see DB_common::execute()
799
     * @see DB_common::execute()
747
     */
800
     */
748
    function prepare($query)
801
    function prepare($query)
749
    {
802
    {
750
        $tokens   = preg_split('/((?<!\\\)[&?!])/', $query, -1,
803
        $tokens   = preg_split('/((?<!\\\)[&?!])/', $query, -1,
751
                               PREG_SPLIT_DELIM_CAPTURE);
804
                               PREG_SPLIT_DELIM_CAPTURE);
752
        $token     = 0;
805
        $token     = 0;
753
        $types     = array();
806
        $types     = array();
754
        $newtokens = array();
807
        $newtokens = array();
755
 
808
 
756
        foreach ($tokens as $val) {
809
        foreach ($tokens as $val) {
757
            switch ($val) {
810
            switch ($val) {
758
                case '?':
811
                case '?':
759
                    $types[$token++] = DB_PARAM_SCALAR;
812
                    $types[$token++] = DB_PARAM_SCALAR;
760
                    break;
813
                    break;
761
                case '&':
814
                case '&':
762
                    $types[$token++] = DB_PARAM_OPAQUE;
815
                    $types[$token++] = DB_PARAM_OPAQUE;
763
                    break;
816
                    break;
764
                case '!':
817
                case '!':
765
                    $types[$token++] = DB_PARAM_MISC;
818
                    $types[$token++] = DB_PARAM_MISC;
766
                    break;
819
                    break;
767
                default:
820
                default:
768
                    $newtokens[] = preg_replace('/\\\([&?!])/', "\\1", $val);
821
                    $newtokens[] = preg_replace('/\\\([&?!])/', "\\1", $val);
769
            }
822
            }
770
        }
823
        }
771
 
824
 
772
        $this->prepare_tokens[] = &$newtokens;
825
        $this->prepare_tokens[] = &$newtokens;
773
        end($this->prepare_tokens);
826
        end($this->prepare_tokens);
774
 
827
 
775
        $k = key($this->prepare_tokens);
828
        $k = key($this->prepare_tokens);
776
        $this->prepare_types[$k] = $types;
829
        $this->prepare_types[$k] = $types;
777
        $this->prepared_queries[$k] = implode(' ', $newtokens);
830
        $this->prepared_queries[$k] = implode(' ', $newtokens);
778
 
831
 
779
        return $k;
832
        return $k;
780
    }
833
    }
781
 
834
 
782
    // }}}
835
    // }}}
783
    // {{{ autoPrepare()
836
    // {{{ autoPrepare()
784
 
837
 
785
    /**
838
    /**
786
     * Automaticaly generates an insert or update query and pass it to prepare()
839
     * Automaticaly generates an insert or update query and pass it to prepare()
787
     *
840
     *
788
     * @param string $table         the table name
841
     * @param string $table         the table name
789
     * @param array  $table_fields  the array of field names
842
     * @param array  $table_fields  the array of field names
790
     * @param int    $mode          a type of query to make:
843
     * @param int    $mode          a type of query to make:
791
     *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
844
     *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
792
     * @param string $where         for update queries: the WHERE clause to
845
     * @param string $where         for update queries: the WHERE clause to
793
     *                               append to the SQL statement.  Don't
846
     *                               append to the SQL statement.  Don't
794
     *                               include the "WHERE" keyword.
847
     *                               include the "WHERE" keyword.
795
     *
848
     *
796
     * @return resource  the query handle
849
     * @return resource  the query handle
797
     *
850
     *
798
     * @uses DB_common::prepare(), DB_common::buildManipSQL()
851
     * @uses DB_common::prepare(), DB_common::buildManipSQL()
799
     */
852
     */
800
    function autoPrepare($table, $table_fields, $mode = DB_AUTOQUERY_INSERT,
853
    function autoPrepare($table, $table_fields, $mode = DB_AUTOQUERY_INSERT,
801
                         $where = false)
854
                         $where = false)
802
    {
855
    {
803
        $query = $this->buildManipSQL($table, $table_fields, $mode, $where);
856
        $query = $this->buildManipSQL($table, $table_fields, $mode, $where);
804
        if (DB::isError($query)) {
857
        if (DB::isError($query)) {
805
            return $query;
858
            return $query;
806
        }
859
        }
807
        return $this->prepare($query);
860
        return $this->prepare($query);
808
    }
861
    }
809
 
862
 
810
    // }}}
863
    // }}}
811
    // {{{ autoExecute()
864
    // {{{ autoExecute()
812
 
865
 
813
    /**
866
    /**
814
     * Automaticaly generates an insert or update query and call prepare()
867
     * Automaticaly generates an insert or update query and call prepare()
815
     * and execute() with it
868
     * and execute() with it
816
     *
869
     *
817
     * @param string $table         the table name
870
     * @param string $table         the table name
818
     * @param array  $fields_values the associative array where $key is a
871
     * @param array  $fields_values the associative array where $key is a
819
     *                               field name and $value its value
872
     *                               field name and $value its value
820
     * @param int    $mode          a type of query to make:
873
     * @param int    $mode          a type of query to make:
821
     *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
874
     *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
822
     * @param string $where         for update queries: the WHERE clause to
875
     * @param string $where         for update queries: the WHERE clause to
823
     *                               append to the SQL statement.  Don't
876
     *                               append to the SQL statement.  Don't
824
     *                               include the "WHERE" keyword.
877
     *                               include the "WHERE" keyword.
825
     *
878
     *
826
     * @return mixed  a new DB_result object for successful SELECT queries
879
     * @return mixed  a new DB_result object for successful SELECT queries
827
     *                 or DB_OK for successul data manipulation queries.
880
     *                 or DB_OK for successul data manipulation queries.
828
     *                 A DB_Error object on failure.
881
     *                 A DB_Error object on failure.
829
     *
882
     *
830
     * @uses DB_common::autoPrepare(), DB_common::execute()
883
     * @uses DB_common::autoPrepare(), DB_common::execute()
831
     */
884
     */
832
    function autoExecute($table, $fields_values, $mode = DB_AUTOQUERY_INSERT,
885
    function autoExecute($table, $fields_values, $mode = DB_AUTOQUERY_INSERT,
833
                         $where = false)
886
                         $where = false)
834
    {
887
    {
835
        $sth = $this->autoPrepare($table, array_keys($fields_values), $mode,
888
        $sth = $this->autoPrepare($table, array_keys($fields_values), $mode,
836
                                  $where);
889
                                  $where);
837
        if (DB::isError($sth)) {
890
        if (DB::isError($sth)) {
838
            return $sth;
891
            return $sth;
839
        }
892
        }
840
        $ret =& $this->execute($sth, array_values($fields_values));
893
        $ret = $this->execute($sth, array_values($fields_values));
841
        $this->freePrepared($sth);
894
        $this->freePrepared($sth);
842
        return $ret;
895
        return $ret;
843
 
896
 
844
    }
897
    }
845
 
898
 
846
    // }}}
899
    // }}}
847
    // {{{ buildManipSQL()
900
    // {{{ buildManipSQL()
848
 
901
 
849
    /**
902
    /**
850
     * Produces an SQL query string for autoPrepare()
903
     * Produces an SQL query string for autoPrepare()
851
     *
904
     *
852
     * Example:
905
     * Example:
853
     * <pre>
906
     * <pre>
854
     * buildManipSQL('table_sql', array('field1', 'field2', 'field3'),
907
     * buildManipSQL('table_sql', array('field1', 'field2', 'field3'),
855
     *               DB_AUTOQUERY_INSERT);
908
     *               DB_AUTOQUERY_INSERT);
856
     * </pre>
909
     * </pre>
857
     *
910
     *
858
     * That returns
911
     * That returns
859
     * <samp>
912
     * <samp>
860
     * INSERT INTO table_sql (field1,field2,field3) VALUES (?,?,?)
913
     * INSERT INTO table_sql (field1,field2,field3) VALUES (?,?,?)
861
     * </samp>
914
     * </samp>
862
     *
915
     *
863
     * NOTES:
916
     * NOTES:
864
     *   - This belongs more to a SQL Builder class, but this is a simple
917
     *   - This belongs more to a SQL Builder class, but this is a simple
865
     *     facility.
918
     *     facility.
866
     *   - Be carefull! If you don't give a $where param with an UPDATE
919
     *   - Be carefull! If you don't give a $where param with an UPDATE
867
     *     query, all the records of the table will be updated!
920
     *     query, all the records of the table will be updated!
868
     *
921
     *
869
     * @param string $table         the table name
922
     * @param string $table         the table name
870
     * @param array  $table_fields  the array of field names
923
     * @param array  $table_fields  the array of field names
871
     * @param int    $mode          a type of query to make:
924
     * @param int    $mode          a type of query to make:
872
     *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
925
     *                               DB_AUTOQUERY_INSERT or DB_AUTOQUERY_UPDATE
873
     * @param string $where         for update queries: the WHERE clause to
926
     * @param string $where         for update queries: the WHERE clause to
874
     *                               append to the SQL statement.  Don't
927
     *                               append to the SQL statement.  Don't
875
     *                               include the "WHERE" keyword.
928
     *                               include the "WHERE" keyword.
876
     *
929
     *
877
     * @return string  the sql query for autoPrepare()
930
     * @return string  the sql query for autoPrepare()
878
     */
931
     */
879
    function buildManipSQL($table, $table_fields, $mode, $where = false)
932
    function buildManipSQL($table, $table_fields, $mode, $where = false)
880
    {
933
    {
881
        if (count($table_fields) == 0) {
934
        if (count($table_fields) == 0) {
882
            return $this->raiseError(DB_ERROR_NEED_MORE_DATA);
935
            return $this->raiseError(DB_ERROR_NEED_MORE_DATA);
883
        }
936
        }
884
        $first = true;
937
        $first = true;
885
        switch ($mode) {
938
        switch ($mode) {
886
            case DB_AUTOQUERY_INSERT:
939
            case DB_AUTOQUERY_INSERT:
887
                $values = '';
940
                $values = '';
888
                $names = '';
941
                $names = '';
889
                foreach ($table_fields as $value) {
942
                foreach ($table_fields as $value) {
890
                    if ($first) {
943
                    if ($first) {
891
                        $first = false;
944
                        $first = false;
892
                    } else {
945
                    } else {
893
                        $names .= ',';
946
                        $names .= ',';
894
                        $values .= ',';
947
                        $values .= ',';
895
                    }
948
                    }
896
                    $names .= $value;
949
                    $names .= $value;
897
                    $values .= '?';
950
                    $values .= '?';
898
                }
951
                }
899
                return "INSERT INTO $table ($names) VALUES ($values)";
952
                return "INSERT INTO $table ($names) VALUES ($values)";
900
            case DB_AUTOQUERY_UPDATE:
953
            case DB_AUTOQUERY_UPDATE:
901
                $set = '';
954
                $set = '';
902
                foreach ($table_fields as $value) {
955
                foreach ($table_fields as $value) {
903
                    if ($first) {
956
                    if ($first) {
904
                        $first = false;
957
                        $first = false;
905
                    } else {
958
                    } else {
906
                        $set .= ',';
959
                        $set .= ',';
907
                    }
960
                    }
908
                    $set .= "$value = ?";
961
                    $set .= "$value = ?";
909
                }
962
                }
910
                $sql = "UPDATE $table SET $set";
963
                $sql = "UPDATE $table SET $set";
911
                if ($where) {
964
                if ($where) {
912
                    $sql .= " WHERE $where";
965
                    $sql .= " WHERE $where";
913
                }
966
                }
914
                return $sql;
967
                return $sql;
915
            default:
968
            default:
916
                return $this->raiseError(DB_ERROR_SYNTAX);
969
                return $this->raiseError(DB_ERROR_SYNTAX);
917
        }
970
        }
918
    }
971
    }
919
 
972
 
920
    // }}}
973
    // }}}
921
    // {{{ execute()
974
    // {{{ execute()
922
 
975
 
923
    /**
976
    /**
924
     * Executes a DB statement prepared with prepare()
977
     * Executes a DB statement prepared with prepare()
925
     *
978
     *
926
     * Example 1.
979
     * Example 1.
927
     * <code>
980
     * <code>
928
     * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
981
     * $sth = $db->prepare('INSERT INTO tbl (a, b, c) VALUES (?, !, &)');
929
     * $data = array(
982
     * $data = array(
930
     *     "John's text",
983
     *     "John's text",
931
     *     "'it''s good'",
984
     *     "'it''s good'",
932
     *     'filename.txt'
985
     *     'filename.txt'
933
     * );
986
     * );
934
     * $res =& $db->execute($sth, $data);
987
     * $res = $db->execute($sth, $data);
935
     * </code>
988
     * </code>
936
     *
989
     *
937
     * @param resource $stmt  a DB statement resource returned from prepare()
990
     * @param resource $stmt  a DB statement resource returned from prepare()
938
     * @param mixed    $data  array, string or numeric data to be used in
991
     * @param mixed    $data  array, string or numeric data to be used in
939
     *                         execution of the statement.  Quantity of items
992
     *                         execution of the statement.  Quantity of items
940
     *                         passed must match quantity of placeholders in
993
     *                         passed must match quantity of placeholders in
941
     *                         query:  meaning 1 placeholder for non-array
994
     *                         query:  meaning 1 placeholder for non-array
942
     *                         parameters or 1 placeholder per array element.
995
     *                         parameters or 1 placeholder per array element.
943
     *
996
     *
944
     * @return mixed  a new DB_result object for successful SELECT queries
997
     * @return mixed  a new DB_result object for successful SELECT queries
945
     *                 or DB_OK for successul data manipulation queries.
998
     *                 or DB_OK for successul data manipulation queries.
946
     *                 A DB_Error object on failure.
999
     *                 A DB_Error object on failure.
947
     *
1000
     *
948
     * {@internal ibase and oci8 have their own execute() methods.}}
1001
     * {@internal ibase and oci8 have their own execute() methods.}}
949
     *
1002
     *
950
     * @see DB_common::prepare()
1003
     * @see DB_common::prepare()
951
     */
1004
     */
952
    function &execute($stmt, $data = array())
1005
    function &execute($stmt, $data = array())
953
    {
1006
    {
954
        $realquery = $this->executeEmulateQuery($stmt, $data);
1007
        $realquery = $this->executeEmulateQuery($stmt, $data);
955
        if (DB::isError($realquery)) {
1008
        if (DB::isError($realquery)) {
956
            return $realquery;
1009
            return $realquery;
957
        }
1010
        }
958
        $result = $this->simpleQuery($realquery);
1011
        $result = $this->simpleQuery($realquery);
959
 
1012
 
960
        if ($result === DB_OK || DB::isError($result)) {
1013
        if ($result === DB_OK || DB::isError($result)) {
961
            return $result;
1014
            return $result;
962
        } else {
1015
        } else {
963
            $tmp =& new DB_result($this, $result);
1016
            $tmp = new DB_result($this, $result);
964
            return $tmp;
1017
            return $tmp;
965
        }
1018
        }
966
    }
1019
    }
967
 
1020
 
968
    // }}}
1021
    // }}}
969
    // {{{ executeEmulateQuery()
1022
    // {{{ executeEmulateQuery()
970
 
1023
 
971
    /**
1024
    /**
972
     * Emulates executing prepared statements if the DBMS not support them
1025
     * Emulates executing prepared statements if the DBMS not support them
973
     *
1026
     *
974
     * @param resource $stmt  a DB statement resource returned from execute()
1027
     * @param resource $stmt  a DB statement resource returned from execute()
975
     * @param mixed    $data  array, string or numeric data to be used in
1028
     * @param mixed    $data  array, string or numeric data to be used in
976
     *                         execution of the statement.  Quantity of items
1029
     *                         execution of the statement.  Quantity of items
977
     *                         passed must match quantity of placeholders in
1030
     *                         passed must match quantity of placeholders in
978
     *                         query:  meaning 1 placeholder for non-array
1031
     *                         query:  meaning 1 placeholder for non-array
979
     *                         parameters or 1 placeholder per array element.
1032
     *                         parameters or 1 placeholder per array element.
980
     *
1033
     *
981
     * @return mixed  a string containing the real query run when emulating
1034
     * @return mixed  a string containing the real query run when emulating
982
     *                 prepare/execute.  A DB_Error object on failure.
1035
     *                 prepare/execute.  A DB_Error object on failure.
983
     *
1036
     *
984
     * @access protected
1037
     * @access protected
985
     * @see DB_common::execute()
1038
     * @see DB_common::execute()
986
     */
1039
     */
987
    function executeEmulateQuery($stmt, $data = array())
1040
    function executeEmulateQuery($stmt, $data = array())
988
    {
1041
    {
989
        $stmt = (int)$stmt;
1042
        $stmt = (int)$stmt;
990
        $data = (array)$data;
1043
        $data = (array)$data;
991
        $this->last_parameters = $data;
1044
        $this->last_parameters = $data;
992
 
1045
 
993
        if (count($this->prepare_types[$stmt]) != count($data)) {
1046
        if (count($this->prepare_types[$stmt]) != count($data)) {
994
            $this->last_query = $this->prepared_queries[$stmt];
1047
            $this->last_query = $this->prepared_queries[$stmt];
995
            return $this->raiseError(DB_ERROR_MISMATCH);
1048
            return $this->raiseError(DB_ERROR_MISMATCH);
996
        }
1049
        }
997
 
1050
 
998
        $realquery = $this->prepare_tokens[$stmt][0];
1051
        $realquery = $this->prepare_tokens[$stmt][0];
999
 
1052
 
1000
        $i = 0;
1053
        $i = 0;
1001
        foreach ($data as $value) {
1054
        foreach ($data as $value) {
1002
            if ($this->prepare_types[$stmt][$i] == DB_PARAM_SCALAR) {
1055
            if ($this->prepare_types[$stmt][$i] == DB_PARAM_SCALAR) {
1003
                $realquery .= $this->quoteSmart($value);
1056
                $realquery .= $this->quoteSmart($value);
1004
            } elseif ($this->prepare_types[$stmt][$i] == DB_PARAM_OPAQUE) {
1057
            } elseif ($this->prepare_types[$stmt][$i] == DB_PARAM_OPAQUE) {
1005
                $fp = @fopen($value, 'rb');
1058
                $fp = @fopen($value, 'rb');
1006
                if (!$fp) {
1059
                if (!$fp) {
1007
                    return $this->raiseError(DB_ERROR_ACCESS_VIOLATION);
1060
                    return $this->raiseError(DB_ERROR_ACCESS_VIOLATION);
1008
                }
1061
                }
1009
                $realquery .= $this->quoteSmart(fread($fp, filesize($value)));
1062
                $realquery .= $this->quoteSmart(fread($fp, filesize($value)));
1010
                fclose($fp);
1063
                fclose($fp);
1011
            } else {
1064
            } else {
1012
                $realquery .= $value;
1065
                $realquery .= $value;
1013
            }
1066
            }
1014
 
1067
 
1015
            $realquery .= $this->prepare_tokens[$stmt][++$i];
1068
            $realquery .= $this->prepare_tokens[$stmt][++$i];
1016
        }
1069
        }
1017
 
1070
 
1018
        return $realquery;
1071
        return $realquery;
1019
    }
1072
    }
1020
 
1073
 
1021
    // }}}
1074
    // }}}
1022
    // {{{ executeMultiple()
1075
    // {{{ executeMultiple()
1023
 
1076
 
1024
    /**
1077
    /**
1025
     * Performs several execute() calls on the same statement handle
1078
     * Performs several execute() calls on the same statement handle
1026
     *
1079
     *
1027
     * $data must be an array indexed numerically
1080
     * $data must be an array indexed numerically
1028
     * from 0, one execute call is done for every "row" in the array.
1081
     * from 0, one execute call is done for every "row" in the array.
1029
     *
1082
     *
1030
     * If an error occurs during execute(), executeMultiple() does not
1083
     * If an error occurs during execute(), executeMultiple() does not
1031
     * execute the unfinished rows, but rather returns that error.
1084
     * execute the unfinished rows, but rather returns that error.
1032
     *
1085
     *
1033
     * @param resource $stmt  query handle from prepare()
1086
     * @param resource $stmt  query handle from prepare()
1034
     * @param array    $data  numeric array containing the
1087
     * @param array    $data  numeric array containing the
1035
     *                         data to insert into the query
1088
     *                         data to insert into the query
1036
     *
1089
     *
1037
     * @return int  DB_OK on success.  A DB_Error object on failure.
1090
     * @return int  DB_OK on success.  A DB_Error object on failure.
1038
     *
1091
     *
1039
     * @see DB_common::prepare(), DB_common::execute()
1092
     * @see DB_common::prepare(), DB_common::execute()
1040
     */
1093
     */
1041
    function executeMultiple($stmt, $data)
1094
    function executeMultiple($stmt, $data)
1042
    {
1095
    {
1043
        foreach ($data as $value) {
1096
        foreach ($data as $value) {
1044
            $res =& $this->execute($stmt, $value);
1097
            $res = $this->execute($stmt, $value);
1045
            if (DB::isError($res)) {
1098
            if (DB::isError($res)) {
1046
                return $res;
1099
                return $res;
1047
            }
1100
            }
1048
        }
1101
        }
1049
        return DB_OK;
1102
        return DB_OK;
1050
    }
1103
    }
1051
 
1104
 
1052
    // }}}
1105
    // }}}
1053
    // {{{ freePrepared()
1106
    // {{{ freePrepared()
1054
 
1107
 
1055
    /**
1108
    /**
1056
     * Frees the internal resources associated with a prepared query
1109
     * Frees the internal resources associated with a prepared query
1057
     *
1110
     *
1058
     * @param resource $stmt           the prepared statement's PHP resource
1111
     * @param resource $stmt           the prepared statement's PHP resource
1059
     * @param bool     $free_resource  should the PHP resource be freed too?
1112
     * @param bool     $free_resource  should the PHP resource be freed too?
1060
     *                                  Use false if you need to get data
1113
     *                                  Use false if you need to get data
1061
     *                                  from the result set later.
1114
     *                                  from the result set later.
1062
     *
1115
     *
1063
     * @return bool  TRUE on success, FALSE if $result is invalid
1116
     * @return bool  TRUE on success, FALSE if $result is invalid
1064
     *
1117
     *
1065
     * @see DB_common::prepare()
1118
     * @see DB_common::prepare()
1066
     */
1119
     */
1067
    function freePrepared($stmt, $free_resource = true)
1120
    function freePrepared($stmt, $free_resource = true)
1068
    {
1121
    {
1069
        $stmt = (int)$stmt;
1122
        $stmt = (int)$stmt;
1070
        if (isset($this->prepare_tokens[$stmt])) {
1123
        if (isset($this->prepare_tokens[$stmt])) {
1071
            unset($this->prepare_tokens[$stmt]);
1124
            unset($this->prepare_tokens[$stmt]);
1072
            unset($this->prepare_types[$stmt]);
1125
            unset($this->prepare_types[$stmt]);
1073
            unset($this->prepared_queries[$stmt]);
1126
            unset($this->prepared_queries[$stmt]);
1074
            return true;
1127
            return true;
1075
        }
1128
        }
1076
        return false;
1129
        return false;
1077
    }
1130
    }
1078
 
1131
 
1079
    // }}}
1132
    // }}}
1080
    // {{{ modifyQuery()
1133
    // {{{ modifyQuery()
1081
 
1134
 
1082
    /**
1135
    /**
1083
     * Changes a query string for various DBMS specific reasons
1136
     * Changes a query string for various DBMS specific reasons
1084
     *
1137
     *
1085
     * It is defined here to ensure all drivers have this method available.
1138
     * It is defined here to ensure all drivers have this method available.
1086
     *
1139
     *
1087
     * @param string $query  the query string to modify
1140
     * @param string $query  the query string to modify
1088
     *
1141
     *
1089
     * @return string  the modified query string
1142
     * @return string  the modified query string
1090
     *
1143
     *
1091
     * @access protected
1144
     * @access protected
1092
     * @see DB_mysql::modifyQuery(), DB_oci8::modifyQuery(),
1145
     * @see DB_mysql::modifyQuery(), DB_oci8::modifyQuery(),
1093
     *      DB_sqlite::modifyQuery()
1146
     *      DB_sqlite::modifyQuery()
1094
     */
1147
     */
1095
    function modifyQuery($query)
1148
    function modifyQuery($query)
1096
    {
1149
    {
1097
        return $query;
1150
        return $query;
1098
    }
1151
    }
1099
 
1152
 
1100
    // }}}
1153
    // }}}
1101
    // {{{ modifyLimitQuery()
1154
    // {{{ modifyLimitQuery()
1102
 
1155
 
1103
    /**
1156
    /**
1104
     * Adds LIMIT clauses to a query string according to current DBMS standards
1157
     * Adds LIMIT clauses to a query string according to current DBMS standards
1105
     *
1158
     *
1106
     * It is defined here to assure that all implementations
1159
     * It is defined here to assure that all implementations
1107
     * have this method defined.
1160
     * have this method defined.
1108
     *
1161
     *
1109
     * @param string $query   the query to modify
1162
     * @param string $query   the query to modify
1110
     * @param int    $from    the row to start to fetching (0 = the first row)
1163
     * @param int    $from    the row to start to fetching (0 = the first row)
1111
     * @param int    $count   the numbers of rows to fetch
1164
     * @param int    $count   the numbers of rows to fetch
1112
     * @param mixed  $params  array, string or numeric data to be used in
1165
     * @param mixed  $params  array, string or numeric data to be used in
1113
     *                         execution of the statement.  Quantity of items
1166
     *                         execution of the statement.  Quantity of items
1114
     *                         passed must match quantity of placeholders in
1167
     *                         passed must match quantity of placeholders in
1115
     *                         query:  meaning 1 placeholder for non-array
1168
     *                         query:  meaning 1 placeholder for non-array
1116
     *                         parameters or 1 placeholder per array element.
1169
     *                         parameters or 1 placeholder per array element.
1117
     *
1170
     *
1118
     * @return string  the query string with LIMIT clauses added
1171
     * @return string  the query string with LIMIT clauses added
1119
     *
1172
     *
1120
     * @access protected
1173
     * @access protected
1121
     */
1174
     */
1122
    function modifyLimitQuery($query, $from, $count, $params = array())
1175
    function modifyLimitQuery($query, $from, $count, $params = array())
1123
    {
1176
    {
1124
        return $query;
1177
        return $query;
1125
    }
1178
    }
1126
 
1179
 
1127
    // }}}
1180
    // }}}
1128
    // {{{ query()
1181
    // {{{ query()
1129
 
1182
 
1130
    /**
1183
    /**
1131
     * Sends a query to the database server
1184
     * Sends a query to the database server
1132
     *
1185
     *
1133
     * The query string can be either a normal statement to be sent directly
1186
     * The query string can be either a normal statement to be sent directly
1134
     * to the server OR if <var>$params</var> are passed the query can have
1187
     * to the server OR if <var>$params</var> are passed the query can have
1135
     * placeholders and it will be passed through prepare() and execute().
1188
     * placeholders and it will be passed through prepare() and execute().
1136
     *
1189
     *
1137
     * @param string $query   the SQL query or the statement to prepare
1190
     * @param string $query   the SQL query or the statement to prepare
1138
     * @param mixed  $params  array, string or numeric data to be used in
1191
     * @param mixed  $params  array, string or numeric data to be used in
1139
     *                         execution of the statement.  Quantity of items
1192
     *                         execution of the statement.  Quantity of items
1140
     *                         passed must match quantity of placeholders in
1193
     *                         passed must match quantity of placeholders in
1141
     *                         query:  meaning 1 placeholder for non-array
1194
     *                         query:  meaning 1 placeholder for non-array
1142
     *                         parameters or 1 placeholder per array element.
1195
     *                         parameters or 1 placeholder per array element.
1143
     *
1196
     *
1144
     * @return mixed  a new DB_result object for successful SELECT queries
1197
     * @return mixed  a new DB_result object for successful SELECT queries
1145
     *                 or DB_OK for successul data manipulation queries.
1198
     *                 or DB_OK for successul data manipulation queries.
1146
     *                 A DB_Error object on failure.
1199
     *                 A DB_Error object on failure.
1147
     *
1200
     *
1148
     * @see DB_result, DB_common::prepare(), DB_common::execute()
1201
     * @see DB_result, DB_common::prepare(), DB_common::execute()
1149
     */
1202
     */
1150
    function &query($query, $params = array())
1203
    function &query($query, $params = array())
1151
    {
1204
    {
1152
        if (sizeof($params) > 0) {
1205
        if (sizeof($params) > 0) {
1153
            $sth = $this->prepare($query);
1206
            $sth = $this->prepare($query);
1154
            if (DB::isError($sth)) {
1207
            if (DB::isError($sth)) {
1155
                return $sth;
1208
                return $sth;
1156
            }
1209
            }
1157
            $ret =& $this->execute($sth, $params);
1210
            $ret = $this->execute($sth, $params);
1158
            $this->freePrepared($sth, false);
1211
            $this->freePrepared($sth, false);
1159
            return $ret;
1212
            return $ret;
1160
        } else {
1213
        } else {
1161
            $this->last_parameters = array();
1214
            $this->last_parameters = array();
1162
            $result = $this->simpleQuery($query);
1215
            $result = $this->simpleQuery($query);
1163
            if ($result === DB_OK || DB::isError($result)) {
1216
            if ($result === DB_OK || DB::isError($result)) {
1164
                return $result;
1217
                return $result;
1165
            } else {
1218
            } else {
1166
                $tmp =& new DB_result($this, $result);
1219
                $tmp = new DB_result($this, $result);
1167
                return $tmp;
1220
                return $tmp;
1168
            }
1221
            }
1169
        }
1222
        }
1170
    }
1223
    }
1171
 
1224
 
1172
    // }}}
1225
    // }}}
1173
    // {{{ limitQuery()
1226
    // {{{ limitQuery()
1174
 
1227
 
1175
    /**
1228
    /**
1176
     * Generates and executes a LIMIT query
1229
     * Generates and executes a LIMIT query
1177
     *
1230
     *
1178
     * @param string $query   the query
1231
     * @param string $query   the query
1179
     * @param intr   $from    the row to start to fetching (0 = the first row)
1232
     * @param intr   $from    the row to start to fetching (0 = the first row)
1180
     * @param int    $count   the numbers of rows to fetch
1233
     * @param int    $count   the numbers of rows to fetch
1181
     * @param mixed  $params  array, string or numeric data to be used in
1234
     * @param mixed  $params  array, string or numeric data to be used in
1182
     *                         execution of the statement.  Quantity of items
1235
     *                         execution of the statement.  Quantity of items
1183
     *                         passed must match quantity of placeholders in
1236
     *                         passed must match quantity of placeholders in
1184
     *                         query:  meaning 1 placeholder for non-array
1237
     *                         query:  meaning 1 placeholder for non-array
1185
     *                         parameters or 1 placeholder per array element.
1238
     *                         parameters or 1 placeholder per array element.
1186
     *
1239
     *
1187
     * @return mixed  a new DB_result object for successful SELECT queries
1240
     * @return mixed  a new DB_result object for successful SELECT queries
1188
     *                 or DB_OK for successul data manipulation queries.
1241
     *                 or DB_OK for successul data manipulation queries.
1189
     *                 A DB_Error object on failure.
1242
     *                 A DB_Error object on failure.
1190
     */
1243
     */
1191
    function &limitQuery($query, $from, $count, $params = array())
1244
    function &limitQuery($query, $from, $count, $params = array())
1192
    {
1245
    {
1193
        $query = $this->modifyLimitQuery($query, $from, $count, $params);
1246
        $query = $this->modifyLimitQuery($query, $from, $count, $params);
1194
        if (DB::isError($query)){
1247
        if (DB::isError($query)){
1195
            return $query;
1248
            return $query;
1196
        }
1249
        }
1197
        $result =& $this->query($query, $params);
1250
        $result = $this->query($query, $params);
1198
        if (is_a($result, 'DB_result')) {
1251
        if (is_object($result) && is_a($result, 'DB_result')) {
1199
            $result->setOption('limit_from', $from);
1252
            $result->setOption('limit_from', $from);
1200
            $result->setOption('limit_count', $count);
1253
            $result->setOption('limit_count', $count);
1201
        }
1254
        }
1202
        return $result;
1255
        return $result;
1203
    }
1256
    }
1204
 
1257
 
1205
    // }}}
1258
    // }}}
1206
    // {{{ getOne()
1259
    // {{{ getOne()
1207
 
1260
 
1208
    /**
1261
    /**
1209
     * Fetches the first column of the first row from a query result
1262
     * Fetches the first column of the first row from a query result
1210
     *
1263
     *
1211
     * Takes care of doing the query and freeing the results when finished.
1264
     * Takes care of doing the query and freeing the results when finished.
1212
     *
1265
     *
1213
     * @param string $query   the SQL query
1266
     * @param string $query   the SQL query
1214
     * @param mixed  $params  array, string or numeric data to be used in
1267
     * @param mixed  $params  array, string or numeric data to be used in
1215
     *                         execution of the statement.  Quantity of items
1268
     *                         execution of the statement.  Quantity of items
1216
     *                         passed must match quantity of placeholders in
1269
     *                         passed must match quantity of placeholders in
1217
     *                         query:  meaning 1 placeholder for non-array
1270
     *                         query:  meaning 1 placeholder for non-array
1218
     *                         parameters or 1 placeholder per array element.
1271
     *                         parameters or 1 placeholder per array element.
1219
     *
1272
     *
1220
     * @return mixed  the returned value of the query.
1273
     * @return mixed  the returned value of the query.
1221
     *                 A DB_Error object on failure.
1274
     *                 A DB_Error object on failure.
1222
     */
1275
     */
1223
    function &getOne($query, $params = array())
1276
    function &getOne($query, $params = array())
1224
    {
1277
    {
1225
        $params = (array)$params;
1278
        $params = (array)$params;
1226
        // modifyLimitQuery() would be nice here, but it causes BC issues
1279
        // modifyLimitQuery() would be nice here, but it causes BC issues
1227
        if (sizeof($params) > 0) {
1280
        if (sizeof($params) > 0) {
1228
            $sth = $this->prepare($query);
1281
            $sth = $this->prepare($query);
1229
            if (DB::isError($sth)) {
1282
            if (DB::isError($sth)) {
1230
                return $sth;
1283
                return $sth;
1231
            }
1284
            }
1232
            $res =& $this->execute($sth, $params);
1285
            $res = $this->execute($sth, $params);
1233
            $this->freePrepared($sth);
1286
            $this->freePrepared($sth);
1234
        } else {
1287
        } else {
1235
            $res =& $this->query($query);
1288
            $res = $this->query($query);
1236
        }
1289
        }
1237
 
1290
 
1238
        if (DB::isError($res)) {
1291
        if (DB::isError($res)) {
1239
            return $res;
1292
            return $res;
1240
        }
1293
        }
1241
 
1294
 
1242
        $err = $res->fetchInto($row, DB_FETCHMODE_ORDERED);
1295
        $err = $res->fetchInto($row, DB_FETCHMODE_ORDERED);
1243
        $res->free();
1296
        $res->free();
1244
 
1297
 
1245
        if ($err !== DB_OK) {
1298
        if ($err !== DB_OK) {
1246
            return $err;
1299
            return $err;
1247
        }
1300
        }
1248
 
1301
 
1249
        return $row[0];
1302
        return $row[0];
1250
    }
1303
    }
1251
 
1304
 
1252
    // }}}
1305
    // }}}
1253
    // {{{ getRow()
1306
    // {{{ getRow()
1254
 
1307
 
1255
    /**
1308
    /**
1256
     * Fetches the first row of data returned from a query result
1309
     * Fetches the first row of data returned from a query result
1257
     *
1310
     *
1258
     * Takes care of doing the query and freeing the results when finished.
1311
     * Takes care of doing the query and freeing the results when finished.
1259
     *
1312
     *
1260
     * @param string $query   the SQL query
1313
     * @param string $query   the SQL query
1261
     * @param mixed  $params  array, string or numeric data to be used in
1314
     * @param mixed  $params  array, string or numeric data to be used in
1262
     *                         execution of the statement.  Quantity of items
1315
     *                         execution of the statement.  Quantity of items
1263
     *                         passed must match quantity of placeholders in
1316
     *                         passed must match quantity of placeholders in
1264
     *                         query:  meaning 1 placeholder for non-array
1317
     *                         query:  meaning 1 placeholder for non-array
1265
     *                         parameters or 1 placeholder per array element.
1318
     *                         parameters or 1 placeholder per array element.
1266
     * @param int $fetchmode  the fetch mode to use
1319
     * @param int $fetchmode  the fetch mode to use
1267
     *
1320
     *
1268
     * @return array  the first row of results as an array.
1321
     * @return array  the first row of results as an array.
1269
     *                 A DB_Error object on failure.
1322
     *                 A DB_Error object on failure.
1270
     */
1323
     */
1271
    function &getRow($query, $params = array(),
1324
    function &getRow($query, $params = array(),
1272
                     $fetchmode = DB_FETCHMODE_DEFAULT)
1325
                     $fetchmode = DB_FETCHMODE_DEFAULT)
1273
    {
1326
    {
1274
        // compat check, the params and fetchmode parameters used to
1327
        // compat check, the params and fetchmode parameters used to
1275
        // have the opposite order
1328
        // have the opposite order
1276
        if (!is_array($params)) {
1329
        if (!is_array($params)) {
1277
            if (is_array($fetchmode)) {
1330
            if (is_array($fetchmode)) {
1278
                if ($params === null) {
1331
                if ($params === null) {
1279
                    $tmp = DB_FETCHMODE_DEFAULT;
1332
                    $tmp = DB_FETCHMODE_DEFAULT;
1280
                } else {
1333
                } else {
1281
                    $tmp = $params;
1334
                    $tmp = $params;
1282
                }
1335
                }
1283
                $params = $fetchmode;
1336
                $params = $fetchmode;
1284
                $fetchmode = $tmp;
1337
                $fetchmode = $tmp;
1285
            } elseif ($params !== null) {
1338
            } elseif ($params !== null) {
1286
                $fetchmode = $params;
1339
                $fetchmode = $params;
1287
                $params = array();
1340
                $params = array();
1288
            }
1341
            }
1289
        }
1342
        }
1290
        // modifyLimitQuery() would be nice here, but it causes BC issues
1343
        // modifyLimitQuery() would be nice here, but it causes BC issues
1291
        if (sizeof($params) > 0) {
1344
        if (sizeof($params) > 0) {
1292
            $sth = $this->prepare($query);
1345
            $sth = $this->prepare($query);
1293
            if (DB::isError($sth)) {
1346
            if (DB::isError($sth)) {
1294
                return $sth;
1347
                return $sth;
1295
            }
1348
            }
1296
            $res =& $this->execute($sth, $params);
1349
            $res = $this->execute($sth, $params);
1297
            $this->freePrepared($sth);
1350
            $this->freePrepared($sth);
1298
        } else {
1351
        } else {
1299
            $res =& $this->query($query);
1352
            $res = $this->query($query);
1300
        }
1353
        }
1301
 
1354
 
1302
        if (DB::isError($res)) {
1355
        if (DB::isError($res)) {
1303
            return $res;
1356
            return $res;
1304
        }
1357
        }
1305
 
1358
 
1306
        $err = $res->fetchInto($row, $fetchmode);
1359
        $err = $res->fetchInto($row, $fetchmode);
1307
 
1360
 
1308
        $res->free();
1361
        $res->free();
1309
 
1362
 
1310
        if ($err !== DB_OK) {
1363
        if ($err !== DB_OK) {
1311
            return $err;
1364
            return $err;
1312
        }
1365
        }
1313
 
1366
 
1314
        return $row;
1367
        return $row;
1315
    }
1368
    }
1316
 
1369
 
1317
    // }}}
1370
    // }}}
1318
    // {{{ getCol()
1371
    // {{{ getCol()
1319
 
1372
 
1320
    /**
1373
    /**
1321
     * Fetches a single column from a query result and returns it as an
1374
     * Fetches a single column from a query result and returns it as an
1322
     * indexed array
1375
     * indexed array
1323
     *
1376
     *
1324
     * @param string $query   the SQL query
1377
     * @param string $query   the SQL query
1325
     * @param mixed  $col     which column to return (integer [column number,
1378
     * @param mixed  $col     which column to return (integer [column number,
1326
     *                         starting at 0] or string [column name])
1379
     *                         starting at 0] or string [column name])
1327
     * @param mixed  $params  array, string or numeric data to be used in
1380
     * @param mixed  $params  array, string or numeric data to be used in
1328
     *                         execution of the statement.  Quantity of items
1381
     *                         execution of the statement.  Quantity of items
1329
     *                         passed must match quantity of placeholders in
1382
     *                         passed must match quantity of placeholders in
1330
     *                         query:  meaning 1 placeholder for non-array
1383
     *                         query:  meaning 1 placeholder for non-array
1331
     *                         parameters or 1 placeholder per array element.
1384
     *                         parameters or 1 placeholder per array element.
1332
     *
1385
     *
1333
     * @return array  the results as an array.  A DB_Error object on failure.
1386
     * @return array  the results as an array.  A DB_Error object on failure.
1334
     *
1387
     *
1335
     * @see DB_common::query()
1388
     * @see DB_common::query()
1336
     */
1389
     */
1337
    function &getCol($query, $col = 0, $params = array())
1390
    function &getCol($query, $col = 0, $params = array())
1338
    {
1391
    {
1339
        $params = (array)$params;
1392
        $params = (array)$params;
1340
        if (sizeof($params) > 0) {
1393
        if (sizeof($params) > 0) {
1341
            $sth = $this->prepare($query);
1394
            $sth = $this->prepare($query);
1342
 
1395
 
1343
            if (DB::isError($sth)) {
1396
            if (DB::isError($sth)) {
1344
                return $sth;
1397
                return $sth;
1345
            }
1398
            }
1346
 
1399
 
1347
            $res =& $this->execute($sth, $params);
1400
            $res = $this->execute($sth, $params);
1348
            $this->freePrepared($sth);
1401
            $this->freePrepared($sth);
1349
        } else {
1402
        } else {
1350
            $res =& $this->query($query);
1403
            $res = $this->query($query);
1351
        }
1404
        }
1352
 
1405
 
1353
        if (DB::isError($res)) {
1406
        if (DB::isError($res)) {
1354
            return $res;
1407
            return $res;
1355
        }
1408
        }
1356
 
1409
 
1357
        $fetchmode = is_int($col) ? DB_FETCHMODE_ORDERED : DB_FETCHMODE_ASSOC;
1410
        $fetchmode = is_int($col) ? DB_FETCHMODE_ORDERED : DB_FETCHMODE_ASSOC;
1358
 
1411
 
1359
        if (!is_array($row = $res->fetchRow($fetchmode))) {
1412
        if (!is_array($row = $res->fetchRow($fetchmode))) {
1360
            $ret = array();
1413
            $ret = array();
1361
        } else {
1414
        } else {
1362
            if (!array_key_exists($col, $row)) {
1415
            if (!array_key_exists($col, $row)) {
1363
                $ret =& $this->raiseError(DB_ERROR_NOSUCHFIELD);
1416
                $ret = $this->raiseError(DB_ERROR_NOSUCHFIELD);
1364
            } else {
1417
            } else {
1365
                $ret = array($row[$col]);
1418
                $ret = array($row[$col]);
1366
                while (is_array($row = $res->fetchRow($fetchmode))) {
1419
                while (is_array($row = $res->fetchRow($fetchmode))) {
1367
                    $ret[] = $row[$col];
1420
                    $ret[] = $row[$col];
1368
                }
1421
                }
1369
            }
1422
            }
1370
        }
1423
        }
1371
 
1424
 
1372
        $res->free();
1425
        $res->free();
1373
 
1426
 
1374
        if (DB::isError($row)) {
1427
        if (DB::isError($row)) {
1375
            $ret = $row;
1428
            $ret = $row;
1376
        }
1429
        }
1377
 
1430
 
1378
        return $ret;
1431
        return $ret;
1379
    }
1432
    }
1380
 
1433
 
1381
    // }}}
1434
    // }}}
1382
    // {{{ getAssoc()
1435
    // {{{ getAssoc()
1383
 
1436
 
1384
    /**
1437
    /**
1385
     * Fetches an entire query result and returns it as an
1438
     * Fetches an entire query result and returns it as an
1386
     * associative array using the first column as the key
1439
     * associative array using the first column as the key
1387
     *
1440
     *
1388
     * If the result set contains more than two columns, the value
1441
     * If the result set contains more than two columns, the value
1389
     * will be an array of the values from column 2-n.  If the result
1442
     * will be an array of the values from column 2-n.  If the result
1390
     * set contains only two columns, the returned value will be a
1443
     * set contains only two columns, the returned value will be a
1391
     * scalar with the value of the second column (unless forced to an
1444
     * scalar with the value of the second column (unless forced to an
1392
     * array with the $force_array parameter).  A DB error code is
1445
     * array with the $force_array parameter).  A DB error code is
1393
     * returned on errors.  If the result set contains fewer than two
1446
     * returned on errors.  If the result set contains fewer than two
1394
     * columns, a DB_ERROR_TRUNCATED error is returned.
1447
     * columns, a DB_ERROR_TRUNCATED error is returned.
1395
     *
1448
     *
1396
     * For example, if the table "mytable" contains:
1449
     * For example, if the table "mytable" contains:
1397
     *
1450
     *
1398
     * <pre>
1451
     * <pre>
1399
     *  ID      TEXT       DATE
1452
     *  ID      TEXT       DATE
1400
     * --------------------------------
1453
     * --------------------------------
1401
     *  1       'one'      944679408
1454
     *  1       'one'      944679408
1402
     *  2       'two'      944679408
1455
     *  2       'two'      944679408
1403
     *  3       'three'    944679408
1456
     *  3       'three'    944679408
1404
     * </pre>
1457
     * </pre>
1405
     *
1458
     *
1406
     * Then the call getAssoc('SELECT id,text FROM mytable') returns:
1459
     * Then the call getAssoc('SELECT id,text FROM mytable') returns:
1407
     * <pre>
1460
     * <pre>
1408
     *   array(
1461
     *   array(
1409
     *     '1' => 'one',
1462
     *     '1' => 'one',
1410
     *     '2' => 'two',
1463
     *     '2' => 'two',
1411
     *     '3' => 'three',
1464
     *     '3' => 'three',
1412
     *   )
1465
     *   )
1413
     * </pre>
1466
     * </pre>
1414
     *
1467
     *
1415
     * ...while the call getAssoc('SELECT id,text,date FROM mytable') returns:
1468
     * ...while the call getAssoc('SELECT id,text,date FROM mytable') returns:
1416
     * <pre>
1469
     * <pre>
1417
     *   array(
1470
     *   array(
1418
     *     '1' => array('one', '944679408'),
1471
     *     '1' => array('one', '944679408'),
1419
     *     '2' => array('two', '944679408'),
1472
     *     '2' => array('two', '944679408'),
1420
     *     '3' => array('three', '944679408')
1473
     *     '3' => array('three', '944679408')
1421
     *   )
1474
     *   )
1422
     * </pre>
1475
     * </pre>
1423
     *
1476
     *
1424
     * If the more than one row occurs with the same value in the
1477
     * If the more than one row occurs with the same value in the
1425
     * first column, the last row overwrites all previous ones by
1478
     * first column, the last row overwrites all previous ones by
1426
     * default.  Use the $group parameter if you don't want to
1479
     * default.  Use the $group parameter if you don't want to
1427
     * overwrite like this.  Example:
1480
     * overwrite like this.  Example:
1428
     *
1481
     *
1429
     * <pre>
1482
     * <pre>
1430
     * getAssoc('SELECT category,id,name FROM mytable', false, null,
1483
     * getAssoc('SELECT category,id,name FROM mytable', false, null,
1431
     *          DB_FETCHMODE_ASSOC, true) returns:
1484
     *          DB_FETCHMODE_ASSOC, true) returns:
1432
     *
1485
     *
1433
     *   array(
1486
     *   array(
1434
     *     '1' => array(array('id' => '4', 'name' => 'number four'),
1487
     *     '1' => array(array('id' => '4', 'name' => 'number four'),
1435
     *                  array('id' => '6', 'name' => 'number six')
1488
     *                  array('id' => '6', 'name' => 'number six')
1436
     *            ),
1489
     *            ),
1437
     *     '9' => array(array('id' => '4', 'name' => 'number four'),
1490
     *     '9' => array(array('id' => '4', 'name' => 'number four'),
1438
     *                  array('id' => '6', 'name' => 'number six')
1491
     *                  array('id' => '6', 'name' => 'number six')
1439
     *            )
1492
     *            )
1440
     *   )
1493
     *   )
1441
     * </pre>
1494
     * </pre>
1442
     *
1495
     *
1443
     * Keep in mind that database functions in PHP usually return string
1496
     * Keep in mind that database functions in PHP usually return string
1444
     * values for results regardless of the database's internal type.
1497
     * values for results regardless of the database's internal type.
1445
     *
1498
     *
1446
     * @param string $query        the SQL query
1499
     * @param string $query        the SQL query
1447
     * @param bool   $force_array  used only when the query returns
1500
     * @param bool   $force_array  used only when the query returns
1448
     *                              exactly two columns.  If true, the values
1501
     *                              exactly two columns.  If true, the values
1449
     *                              of the returned array will be one-element
1502
     *                              of the returned array will be one-element
1450
     *                              arrays instead of scalars.
1503
     *                              arrays instead of scalars.
1451
     * @param mixed  $params       array, string or numeric data to be used in
1504
     * @param mixed  $params       array, string or numeric data to be used in
1452
     *                              execution of the statement.  Quantity of
1505
     *                              execution of the statement.  Quantity of
1453
     *                              items passed must match quantity of
1506
     *                              items passed must match quantity of
1454
     *                              placeholders in query:  meaning 1
1507
     *                              placeholders in query:  meaning 1
1455
     *                              placeholder for non-array parameters or
1508
     *                              placeholder for non-array parameters or
1456
     *                              1 placeholder per array element.
1509
     *                              1 placeholder per array element.
1457
     * @param int   $fetchmode     the fetch mode to use
1510
     * @param int   $fetchmode     the fetch mode to use
1458
     * @param bool  $group         if true, the values of the returned array
1511
     * @param bool  $group         if true, the values of the returned array
1459
     *                              is wrapped in another array.  If the same
1512
     *                              is wrapped in another array.  If the same
1460
     *                              key value (in the first column) repeats
1513
     *                              key value (in the first column) repeats
1461
     *                              itself, the values will be appended to
1514
     *                              itself, the values will be appended to
1462
     *                              this array instead of overwriting the
1515
     *                              this array instead of overwriting the
1463
     *                              existing values.
1516
     *                              existing values.
1464
     *
1517
     *
1465
     * @return array  the associative array containing the query results.
1518
     * @return array  the associative array containing the query results.
1466
     *                A DB_Error object on failure.
1519
     *                A DB_Error object on failure.
1467
     */
1520
     */
1468
    function &getAssoc($query, $force_array = false, $params = array(),
1521
    function &getAssoc($query, $force_array = false, $params = array(),
1469
                       $fetchmode = DB_FETCHMODE_DEFAULT, $group = false)
1522
                       $fetchmode = DB_FETCHMODE_DEFAULT, $group = false)
1470
    {
1523
    {
1471
        $params = (array)$params;
1524
        $params = (array)$params;
1472
        if (sizeof($params) > 0) {
1525
        if (sizeof($params) > 0) {
1473
            $sth = $this->prepare($query);
1526
            $sth = $this->prepare($query);
1474
 
1527
 
1475
            if (DB::isError($sth)) {
1528
            if (DB::isError($sth)) {
1476
                return $sth;
1529
                return $sth;
1477
            }
1530
            }
1478
 
1531
 
1479
            $res =& $this->execute($sth, $params);
1532
            $res = $this->execute($sth, $params);
1480
            $this->freePrepared($sth);
1533
            $this->freePrepared($sth);
1481
        } else {
1534
        } else {
1482
            $res =& $this->query($query);
1535
            $res = $this->query($query);
1483
        }
1536
        }
1484
 
1537
 
1485
        if (DB::isError($res)) {
1538
        if (DB::isError($res)) {
1486
            return $res;
1539
            return $res;
1487
        }
1540
        }
1488
        if ($fetchmode == DB_FETCHMODE_DEFAULT) {
1541
        if ($fetchmode == DB_FETCHMODE_DEFAULT) {
1489
            $fetchmode = $this->fetchmode;
1542
            $fetchmode = $this->fetchmode;
1490
        }
1543
        }
1491
        $cols = $res->numCols();
1544
        $cols = $res->numCols();
1492
 
1545
 
1493
        if ($cols < 2) {
1546
        if ($cols < 2) {
1494
            $tmp =& $this->raiseError(DB_ERROR_TRUNCATED);
1547
            $tmp = $this->raiseError(DB_ERROR_TRUNCATED);
1495
            return $tmp;
1548
            return $tmp;
1496
        }
1549
        }
1497
 
1550
 
1498
        $results = array();
1551
        $results = array();
1499
 
1552
 
1500
        if ($cols > 2 || $force_array) {
1553
        if ($cols > 2 || $force_array) {
1501
            // return array values
1554
            // return array values
1502
            // XXX this part can be optimized
1555
            // XXX this part can be optimized
1503
            if ($fetchmode == DB_FETCHMODE_ASSOC) {
1556
            if ($fetchmode == DB_FETCHMODE_ASSOC) {
1504
                while (is_array($row = $res->fetchRow(DB_FETCHMODE_ASSOC))) {
1557
                while (is_array($row = $res->fetchRow(DB_FETCHMODE_ASSOC))) {
1505
                    reset($row);
1558
                    reset($row);
1506
                    $key = current($row);
1559
                    $key = current($row);
1507
                    unset($row[key($row)]);
1560
                    unset($row[key($row)]);
1508
                    if ($group) {
1561
                    if ($group) {
1509
                        $results[$key][] = $row;
1562
                        $results[$key][] = $row;
1510
                    } else {
1563
                    } else {
1511
                        $results[$key] = $row;
1564
                        $results[$key] = $row;
1512
                    }
1565
                    }
1513
                }
1566
                }
1514
            } elseif ($fetchmode == DB_FETCHMODE_OBJECT) {
1567
            } elseif ($fetchmode == DB_FETCHMODE_OBJECT) {
1515
                while ($row = $res->fetchRow(DB_FETCHMODE_OBJECT)) {
1568
                while ($row = $res->fetchRow(DB_FETCHMODE_OBJECT)) {
1516
                    $arr = get_object_vars($row);
1569
                    $arr = get_object_vars($row);
1517
                    $key = current($arr);
1570
                    $key = current($arr);
1518
                    if ($group) {
1571
                    if ($group) {
1519
                        $results[$key][] = $row;
1572
                        $results[$key][] = $row;
1520
                    } else {
1573
                    } else {
1521
                        $results[$key] = $row;
1574
                        $results[$key] = $row;
1522
                    }
1575
                    }
1523
                }
1576
                }
1524
            } else {
1577
            } else {
1525
                while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
1578
                while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
1526
                    // we shift away the first element to get
1579
                    // we shift away the first element to get
1527
                    // indices running from 0 again
1580
                    // indices running from 0 again
1528
                    $key = array_shift($row);
1581
                    $key = array_shift($row);
1529
                    if ($group) {
1582
                    if ($group) {
1530
                        $results[$key][] = $row;
1583
                        $results[$key][] = $row;
1531
                    } else {
1584
                    } else {
1532
                        $results[$key] = $row;
1585
                        $results[$key] = $row;
1533
                    }
1586
                    }
1534
                }
1587
                }
1535
            }
1588
            }
1536
            if (DB::isError($row)) {
1589
            if (DB::isError($row)) {
1537
                $results = $row;
1590
                $results = $row;
1538
            }
1591
            }
1539
        } else {
1592
        } else {
1540
            // return scalar values
1593
            // return scalar values
1541
            while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
1594
            while (is_array($row = $res->fetchRow(DB_FETCHMODE_ORDERED))) {
1542
                if ($group) {
1595
                if ($group) {
1543
                    $results[$row[0]][] = $row[1];
1596
                    $results[$row[0]][] = $row[1];
1544
                } else {
1597
                } else {
1545
                    $results[$row[0]] = $row[1];
1598
                    $results[$row[0]] = $row[1];
1546
                }
1599
                }
1547
            }
1600
            }
1548
            if (DB::isError($row)) {
1601
            if (DB::isError($row)) {
1549
                $results = $row;
1602
                $results = $row;
1550
            }
1603
            }
1551
        }
1604
        }
1552
 
1605
 
1553
        $res->free();
1606
        $res->free();
1554
 
1607
 
1555
        return $results;
1608
        return $results;
1556
    }
1609
    }
1557
 
1610
 
1558
    // }}}
1611
    // }}}
1559
    // {{{ getAll()
1612
    // {{{ getAll()
1560
 
1613
 
1561
    /**
1614
    /**
1562
     * Fetches all of the rows from a query result
1615
     * Fetches all of the rows from a query result
1563
     *
1616
     *
1564
     * @param string $query      the SQL query
1617
     * @param string $query      the SQL query
1565
     * @param mixed  $params     array, string or numeric data to be used in
1618
     * @param mixed  $params     array, string or numeric data to be used in
1566
     *                            execution of the statement.  Quantity of
1619
     *                            execution of the statement.  Quantity of
1567
     *                            items passed must match quantity of
1620
     *                            items passed must match quantity of
1568
     *                            placeholders in query:  meaning 1
1621
     *                            placeholders in query:  meaning 1
1569
     *                            placeholder for non-array parameters or
1622
     *                            placeholder for non-array parameters or
1570
     *                            1 placeholder per array element.
1623
     *                            1 placeholder per array element.
1571
     * @param int    $fetchmode  the fetch mode to use:
1624
     * @param int    $fetchmode  the fetch mode to use:
1572
     *                            + DB_FETCHMODE_ORDERED
1625
     *                            + DB_FETCHMODE_ORDERED
1573
     *                            + DB_FETCHMODE_ASSOC
1626
     *                            + DB_FETCHMODE_ASSOC
1574
     *                            + DB_FETCHMODE_ORDERED | DB_FETCHMODE_FLIPPED
1627
     *                            + DB_FETCHMODE_ORDERED | DB_FETCHMODE_FLIPPED
1575
     *                            + DB_FETCHMODE_ASSOC | DB_FETCHMODE_FLIPPED
1628
     *                            + DB_FETCHMODE_ASSOC | DB_FETCHMODE_FLIPPED
1576
     *
1629
     *
1577
     * @return array  the nested array.  A DB_Error object on failure.
1630
     * @return array  the nested array.  A DB_Error object on failure.
1578
     */
1631
     */
1579
    function &getAll($query, $params = array(),
1632
    function &getAll($query, $params = array(),
1580
                     $fetchmode = DB_FETCHMODE_DEFAULT)
1633
                     $fetchmode = DB_FETCHMODE_DEFAULT)
1581
    {
1634
    {
1582
        // compat check, the params and fetchmode parameters used to
1635
        // compat check, the params and fetchmode parameters used to
1583
        // have the opposite order
1636
        // have the opposite order
1584
        if (!is_array($params)) {
1637
        if (!is_array($params)) {
1585
            if (is_array($fetchmode)) {
1638
            if (is_array($fetchmode)) {
1586
                if ($params === null) {
1639
                if ($params === null) {
1587
                    $tmp = DB_FETCHMODE_DEFAULT;
1640
                    $tmp = DB_FETCHMODE_DEFAULT;
1588
                } else {
1641
                } else {
1589
                    $tmp = $params;
1642
                    $tmp = $params;
1590
                }
1643
                }
1591
                $params = $fetchmode;
1644
                $params = $fetchmode;
1592
                $fetchmode = $tmp;
1645
                $fetchmode = $tmp;
1593
            } elseif ($params !== null) {
1646
            } elseif ($params !== null) {
1594
                $fetchmode = $params;
1647
                $fetchmode = $params;
1595
                $params = array();
1648
                $params = array();
1596
            }
1649
            }
1597
        }
1650
        }
1598
 
1651
 
1599
        if (sizeof($params) > 0) {
1652
        if (sizeof($params) > 0) {
1600
            $sth = $this->prepare($query);
1653
            $sth = $this->prepare($query);
1601
 
1654
 
1602
            if (DB::isError($sth)) {
1655
            if (DB::isError($sth)) {
1603
                return $sth;
1656
                return $sth;
1604
            }
1657
            }
1605
 
1658
 
1606
            $res =& $this->execute($sth, $params);
1659
            $res = $this->execute($sth, $params);
1607
            $this->freePrepared($sth);
1660
            $this->freePrepared($sth);
1608
        } else {
1661
        } else {
1609
            $res =& $this->query($query);
1662
            $res = $this->query($query);
1610
        }
1663
        }
1611
 
1664
 
1612
        if ($res === DB_OK || DB::isError($res)) {
1665
        if ($res === DB_OK || DB::isError($res)) {
1613
            return $res;
1666
            return $res;
1614
        }
1667
        }
1615
 
1668
 
1616
        $results = array();
1669
        $results = array();
1617
        while (DB_OK === $res->fetchInto($row, $fetchmode)) {
1670
        while (DB_OK === $res->fetchInto($row, $fetchmode)) {
1618
            if ($fetchmode & DB_FETCHMODE_FLIPPED) {
1671
            if ($fetchmode & DB_FETCHMODE_FLIPPED) {
1619
                foreach ($row as $key => $val) {
1672
                foreach ($row as $key => $val) {
1620
                    $results[$key][] = $val;
1673
                    $results[$key][] = $val;
1621
                }
1674
                }
1622
            } else {
1675
            } else {
1623
                $results[] = $row;
1676
                $results[] = $row;
1624
            }
1677
            }
1625
        }
1678
        }
1626
 
1679
 
1627
        $res->free();
1680
        $res->free();
1628
 
1681
 
1629
        if (DB::isError($row)) {
1682
        if (DB::isError($row)) {
1630
            $tmp =& $this->raiseError($row);
1683
            $tmp = $this->raiseError($row);
1631
            return $tmp;
1684
            return $tmp;
1632
        }
1685
        }
1633
        return $results;
1686
        return $results;
1634
    }
1687
    }
1635
 
1688
 
1636
    // }}}
1689
    // }}}
1637
    // {{{ autoCommit()
1690
    // {{{ autoCommit()
1638
 
1691
 
1639
    /**
1692
    /**
1640
     * Enables or disables automatic commits
1693
     * Enables or disables automatic commits
1641
     *
1694
     *
1642
     * @param bool $onoff  true turns it on, false turns it off
1695
     * @param bool $onoff  true turns it on, false turns it off
1643
     *
1696
     *
1644
     * @return int  DB_OK on success.  A DB_Error object if the driver
1697
     * @return int  DB_OK on success.  A DB_Error object if the driver
1645
     *               doesn't support auto-committing transactions.
1698
     *               doesn't support auto-committing transactions.
1646
     */
1699
     */
1647
    function autoCommit($onoff = false)
1700
    function autoCommit($onoff = false)
1648
    {
1701
    {
1649
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1702
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1650
    }
1703
    }
1651
 
1704
 
1652
    // }}}
1705
    // }}}
1653
    // {{{ commit()
1706
    // {{{ commit()
1654
 
1707
 
1655
    /**
1708
    /**
1656
     * Commits the current transaction
1709
     * Commits the current transaction
1657
     *
1710
     *
1658
     * @return int  DB_OK on success.  A DB_Error object on failure.
1711
     * @return int  DB_OK on success.  A DB_Error object on failure.
1659
     */
1712
     */
1660
    function commit()
1713
    function commit()
1661
    {
1714
    {
1662
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1715
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1663
    }
1716
    }
1664
 
1717
 
1665
    // }}}
1718
    // }}}
1666
    // {{{ rollback()
1719
    // {{{ rollback()
1667
 
1720
 
1668
    /**
1721
    /**
1669
     * Reverts the current transaction
1722
     * Reverts the current transaction
1670
     *
1723
     *
1671
     * @return int  DB_OK on success.  A DB_Error object on failure.
1724
     * @return int  DB_OK on success.  A DB_Error object on failure.
1672
     */
1725
     */
1673
    function rollback()
1726
    function rollback()
1674
    {
1727
    {
1675
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1728
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1676
    }
1729
    }
1677
 
1730
 
1678
    // }}}
1731
    // }}}
1679
    // {{{ numRows()
1732
    // {{{ numRows()
1680
 
1733
 
1681
    /**
1734
    /**
1682
     * Determines the number of rows in a query result
1735
     * Determines the number of rows in a query result
1683
     *
1736
     *
1684
     * @param resource $result  the query result idenifier produced by PHP
1737
     * @param resource $result  the query result idenifier produced by PHP
1685
     *
1738
     *
1686
     * @return int  the number of rows.  A DB_Error object on failure.
1739
     * @return int  the number of rows.  A DB_Error object on failure.
1687
     */
1740
     */
1688
    function numRows($result)
1741
    function numRows($result)
1689
    {
1742
    {
1690
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1743
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1691
    }
1744
    }
1692
 
1745
 
1693
    // }}}
1746
    // }}}
1694
    // {{{ affectedRows()
1747
    // {{{ affectedRows()
1695
 
1748
 
1696
    /**
1749
    /**
1697
     * Determines the number of rows affected by a data maniuplation query
1750
     * Determines the number of rows affected by a data maniuplation query
1698
     *
1751
     *
1699
     * 0 is returned for queries that don't manipulate data.
1752
     * 0 is returned for queries that don't manipulate data.
1700
     *
1753
     *
1701
     * @return int  the number of rows.  A DB_Error object on failure.
1754
     * @return int  the number of rows.  A DB_Error object on failure.
1702
     */
1755
     */
1703
    function affectedRows()
1756
    function affectedRows()
1704
    {
1757
    {
1705
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1758
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1706
    }
1759
    }
1707
 
1760
 
1708
    // }}}
1761
    // }}}
1709
    // {{{ getSequenceName()
1762
    // {{{ getSequenceName()
1710
 
1763
 
1711
    /**
1764
    /**
1712
     * Generates the name used inside the database for a sequence
1765
     * Generates the name used inside the database for a sequence
1713
     *
1766
     *
1714
     * The createSequence() docblock contains notes about storing sequence
1767
     * The createSequence() docblock contains notes about storing sequence
1715
     * names.
1768
     * names.
1716
     *
1769
     *
1717
     * @param string $sqn  the sequence's public name
1770
     * @param string $sqn  the sequence's public name
1718
     *
1771
     *
1719
     * @return string  the sequence's name in the backend
1772
     * @return string  the sequence's name in the backend
1720
     *
1773
     *
1721
     * @access protected
1774
     * @access protected
1722
     * @see DB_common::createSequence(), DB_common::dropSequence(),
1775
     * @see DB_common::createSequence(), DB_common::dropSequence(),
1723
     *      DB_common::nextID(), DB_common::setOption()
1776
     *      DB_common::nextID(), DB_common::setOption()
1724
     */
1777
     */
1725
    function getSequenceName($sqn)
1778
    function getSequenceName($sqn)
1726
    {
1779
    {
1727
        return sprintf($this->getOption('seqname_format'),
1780
        return sprintf($this->getOption('seqname_format'),
1728
                       preg_replace('/[^a-z0-9_.]/i', '_', $sqn));
1781
                       preg_replace('/[^a-z0-9_.]/i', '_', $sqn));
1729
    }
1782
    }
1730
 
1783
 
1731
    // }}}
1784
    // }}}
1732
    // {{{ nextId()
1785
    // {{{ nextId()
1733
 
1786
 
1734
    /**
1787
    /**
1735
     * Returns the next free id in a sequence
1788
     * Returns the next free id in a sequence
1736
     *
1789
     *
1737
     * @param string  $seq_name  name of the sequence
1790
     * @param string  $seq_name  name of the sequence
1738
     * @param boolean $ondemand  when true, the seqence is automatically
1791
     * @param boolean $ondemand  when true, the seqence is automatically
1739
     *                            created if it does not exist
1792
     *                            created if it does not exist
1740
     *
1793
     *
1741
     * @return int  the next id number in the sequence.
1794
     * @return int  the next id number in the sequence.
1742
     *               A DB_Error object on failure.
1795
     *               A DB_Error object on failure.
1743
     *
1796
     *
1744
     * @see DB_common::createSequence(), DB_common::dropSequence(),
1797
     * @see DB_common::createSequence(), DB_common::dropSequence(),
1745
     *      DB_common::getSequenceName()
1798
     *      DB_common::getSequenceName()
1746
     */
1799
     */
1747
    function nextId($seq_name, $ondemand = true)
1800
    function nextId($seq_name, $ondemand = true)
1748
    {
1801
    {
1749
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1802
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1750
    }
1803
    }
1751
 
1804
 
1752
    // }}}
1805
    // }}}
1753
    // {{{ createSequence()
1806
    // {{{ createSequence()
1754
 
1807
 
1755
    /**
1808
    /**
1756
     * Creates a new sequence
1809
     * Creates a new sequence
1757
     *
1810
     *
1758
     * The name of a given sequence is determined by passing the string
1811
     * The name of a given sequence is determined by passing the string
1759
     * provided in the <var>$seq_name</var> argument through PHP's sprintf()
1812
     * provided in the <var>$seq_name</var> argument through PHP's sprintf()
1760
     * function using the value from the <var>seqname_format</var> option as
1813
     * function using the value from the <var>seqname_format</var> option as
1761
     * the sprintf()'s format argument.
1814
     * the sprintf()'s format argument.
1762
     *
1815
     *
1763
     * <var>seqname_format</var> is set via setOption().
1816
     * <var>seqname_format</var> is set via setOption().
1764
     *
1817
     *
1765
     * @param string $seq_name  name of the new sequence
1818
     * @param string $seq_name  name of the new sequence
1766
     *
1819
     *
1767
     * @return int  DB_OK on success.  A DB_Error object on failure.
1820
     * @return int  DB_OK on success.  A DB_Error object on failure.
1768
     *
1821
     *
1769
     * @see DB_common::dropSequence(), DB_common::getSequenceName(),
1822
     * @see DB_common::dropSequence(), DB_common::getSequenceName(),
1770
     *      DB_common::nextID()
1823
     *      DB_common::nextID()
1771
     */
1824
     */
1772
    function createSequence($seq_name)
1825
    function createSequence($seq_name)
1773
    {
1826
    {
1774
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1827
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1775
    }
1828
    }
1776
 
1829
 
1777
    // }}}
1830
    // }}}
1778
    // {{{ dropSequence()
1831
    // {{{ dropSequence()
1779
 
1832
 
1780
    /**
1833
    /**
1781
     * Deletes a sequence
1834
     * Deletes a sequence
1782
     *
1835
     *
1783
     * @param string $seq_name  name of the sequence to be deleted
1836
     * @param string $seq_name  name of the sequence to be deleted
1784
     *
1837
     *
1785
     * @return int  DB_OK on success.  A DB_Error object on failure.
1838
     * @return int  DB_OK on success.  A DB_Error object on failure.
1786
     *
1839
     *
1787
     * @see DB_common::createSequence(), DB_common::getSequenceName(),
1840
     * @see DB_common::createSequence(), DB_common::getSequenceName(),
1788
     *      DB_common::nextID()
1841
     *      DB_common::nextID()
1789
     */
1842
     */
1790
    function dropSequence($seq_name)
1843
    function dropSequence($seq_name)
1791
    {
1844
    {
1792
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1845
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1793
    }
1846
    }
1794
 
1847
 
1795
    // }}}
1848
    // }}}
1796
    // {{{ raiseError()
1849
    // {{{ raiseError()
1797
 
1850
 
1798
    /**
1851
    /**
1799
     * Communicates an error and invoke error callbacks, etc
1852
     * Communicates an error and invoke error callbacks, etc
1800
     *
1853
     *
1801
     * Basically a wrapper for PEAR::raiseError without the message string.
1854
     * Basically a wrapper for PEAR::raiseError without the message string.
1802
     *
1855
     *
1803
     * @param mixed   integer error code, or a PEAR error object (all
1856
     * @param mixed   integer error code, or a PEAR error object (all
1804
     *                 other parameters are ignored if this parameter is
1857
     *                 other parameters are ignored if this parameter is
1805
     *                 an object
1858
     *                 an object
1806
     * @param int     error mode, see PEAR_Error docs
1859
     * @param int     error mode, see PEAR_Error docs
1807
     * @param mixed   if error mode is PEAR_ERROR_TRIGGER, this is the
1860
     * @param mixed   if error mode is PEAR_ERROR_TRIGGER, this is the
1808
     *                 error level (E_USER_NOTICE etc).  If error mode is
1861
     *                 error level (E_USER_NOTICE etc).  If error mode is
1809
     *                 PEAR_ERROR_CALLBACK, this is the callback function,
1862
     *                 PEAR_ERROR_CALLBACK, this is the callback function,
1810
     *                 either as a function name, or as an array of an
1863
     *                 either as a function name, or as an array of an
1811
     *                 object and method name.  For other error modes this
1864
     *                 object and method name.  For other error modes this
1812
     *                 parameter is ignored.
1865
     *                 parameter is ignored.
1813
     * @param string  extra debug information.  Defaults to the last
1866
     * @param string  extra debug information.  Defaults to the last
1814
     *                 query and native error code.
1867
     *                 query and native error code.
1815
     * @param mixed   native error code, integer or string depending the
1868
     * @param mixed   native error code, integer or string depending the
1816
     *                 backend
1869
     *                 backend
-
 
1870
     * @param mixed   dummy parameter for E_STRICT compatibility with
-
 
1871
     *                 PEAR::raiseError
-
 
1872
     * @param mixed   dummy parameter for E_STRICT compatibility with
-
 
1873
     *                 PEAR::raiseError
1817
     *
1874
     *
1818
     * @return object  the PEAR_Error object
1875
     * @return object  the PEAR_Error object
1819
     *
1876
     *
1820
     * @see PEAR_Error
1877
     * @see PEAR_Error
1821
     */
1878
     */
1822
    function &raiseError($code = DB_ERROR, $mode = null, $options = null,
1879
    function &raiseError($code = DB_ERROR, $mode = null, $options = null,
1823
                         $userinfo = null, $nativecode = null)
1880
                         $userinfo = null, $nativecode = null, $dummy1 = null,
-
 
1881
                         $dummy2 = null)
1824
    {
1882
    {
1825
        // The error is yet a DB error object
1883
        // The error is yet a DB error object
1826
        if (is_object($code)) {
1884
        if (is_object($code)) {
1827
            // because we the static PEAR::raiseError, our global
1885
            // because we the static PEAR::raiseError, our global
1828
            // handler should be used if it is set
1886
            // handler should be used if it is set
1829
            if ($mode === null && !empty($this->_default_error_mode)) {
1887
            if ($mode === null && !empty($this->_default_error_mode)) {
1830
                $mode    = $this->_default_error_mode;
1888
                $mode    = $this->_default_error_mode;
1831
                $options = $this->_default_error_options;
1889
                $options = $this->_default_error_options;
1832
            }
1890
            }
1833
            $tmp = PEAR::raiseError($code, null, $mode, $options,
1891
            $tmp = PEAR::raiseError($code, null, $mode, $options,
1834
                                    null, null, true);
1892
                                    null, null, true);
1835
            return $tmp;
1893
            return $tmp;
1836
        }
1894
        }
1837
 
1895
 
1838
        if ($userinfo === null) {
1896
        if ($userinfo === null) {
1839
            $userinfo = $this->last_query;
1897
            $userinfo = $this->last_query;
1840
        }
1898
        }
1841
 
1899
 
1842
        if ($nativecode) {
1900
        if ($nativecode) {
1843
            $userinfo .= ' [nativecode=' . trim($nativecode) . ']';
1901
            $userinfo .= ' [nativecode=' . trim($nativecode) . ']';
1844
        } else {
1902
        } else {
1845
            $userinfo .= ' [DB Error: ' . DB::errorMessage($code) . ']';
1903
            $userinfo .= ' [DB Error: ' . DB::errorMessage($code) . ']';
1846
        }
1904
        }
1847
 
1905
 
1848
        $tmp = PEAR::raiseError(null, $code, $mode, $options, $userinfo,
1906
        $tmp = PEAR::raiseError(null, $code, $mode, $options, $userinfo,
1849
                                'DB_Error', true);
1907
                                'DB_Error', true);
1850
        return $tmp;
1908
        return $tmp;
1851
    }
1909
    }
1852
 
1910
 
1853
    // }}}
1911
    // }}}
1854
    // {{{ errorNative()
1912
    // {{{ errorNative()
1855
 
1913
 
1856
    /**
1914
    /**
1857
     * Gets the DBMS' native error code produced by the last query
1915
     * Gets the DBMS' native error code produced by the last query
1858
     *
1916
     *
1859
     * @return mixed  the DBMS' error code.  A DB_Error object on failure.
1917
     * @return mixed  the DBMS' error code.  A DB_Error object on failure.
1860
     */
1918
     */
1861
    function errorNative()
1919
    function errorNative()
1862
    {
1920
    {
1863
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1921
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
1864
    }
1922
    }
1865
 
1923
 
1866
    // }}}
1924
    // }}}
1867
    // {{{ errorCode()
1925
    // {{{ errorCode()
1868
 
1926
 
1869
    /**
1927
    /**
1870
     * Maps native error codes to DB's portable ones
1928
     * Maps native error codes to DB's portable ones
1871
     *
1929
     *
1872
     * Uses the <var>$errorcode_map</var> property defined in each driver.
1930
     * Uses the <var>$errorcode_map</var> property defined in each driver.
1873
     *
1931
     *
1874
     * @param string|int $nativecode  the error code returned by the DBMS
1932
     * @param string|int $nativecode  the error code returned by the DBMS
1875
     *
1933
     *
1876
     * @return int  the portable DB error code.  Return DB_ERROR if the
1934
     * @return int  the portable DB error code.  Return DB_ERROR if the
1877
     *               current driver doesn't have a mapping for the
1935
     *               current driver doesn't have a mapping for the
1878
     *               $nativecode submitted.
1936
     *               $nativecode submitted.
1879
     */
1937
     */
1880
    function errorCode($nativecode)
1938
    function errorCode($nativecode)
1881
    {
1939
    {
1882
        if (isset($this->errorcode_map[$nativecode])) {
1940
        if (isset($this->errorcode_map[$nativecode])) {
1883
            return $this->errorcode_map[$nativecode];
1941
            return $this->errorcode_map[$nativecode];
1884
        }
1942
        }
1885
        // Fall back to DB_ERROR if there was no mapping.
1943
        // Fall back to DB_ERROR if there was no mapping.
1886
        return DB_ERROR;
1944
        return DB_ERROR;
1887
    }
1945
    }
1888
 
1946
 
1889
    // }}}
1947
    // }}}
1890
    // {{{ errorMessage()
1948
    // {{{ errorMessage()
1891
 
1949
 
1892
    /**
1950
    /**
1893
     * Maps a DB error code to a textual message
1951
     * Maps a DB error code to a textual message
1894
     *
1952
     *
1895
     * @param integer $dbcode  the DB error code
1953
     * @param integer $dbcode  the DB error code
1896
     *
1954
     *
1897
     * @return string  the error message corresponding to the error code
1955
     * @return string  the error message corresponding to the error code
1898
     *                  submitted.  FALSE if the error code is unknown.
1956
     *                  submitted.  FALSE if the error code is unknown.
1899
     *
1957
     *
1900
     * @see DB::errorMessage()
1958
     * @see DB::errorMessage()
1901
     */
1959
     */
1902
    function errorMessage($dbcode)
1960
    function errorMessage($dbcode)
1903
    {
1961
    {
1904
        return DB::errorMessage($this->errorcode_map[$dbcode]);
1962
        return DB::errorMessage($this->errorcode_map[$dbcode]);
1905
    }
1963
    }
1906
 
1964
 
1907
    // }}}
1965
    // }}}
1908
    // {{{ tableInfo()
1966
    // {{{ tableInfo()
1909
 
1967
 
1910
    /**
1968
    /**
1911
     * Returns information about a table or a result set
1969
     * Returns information about a table or a result set
1912
     *
1970
     *
1913
     * The format of the resulting array depends on which <var>$mode</var>
1971
     * The format of the resulting array depends on which <var>$mode</var>
1914
     * you select.  The sample output below is based on this query:
1972
     * you select.  The sample output below is based on this query:
1915
     * <pre>
1973
     * <pre>
1916
     *    SELECT tblFoo.fldID, tblFoo.fldPhone, tblBar.fldId
1974
     *    SELECT tblFoo.fldID, tblFoo.fldPhone, tblBar.fldId
1917
     *    FROM tblFoo
1975
     *    FROM tblFoo
1918
     *    JOIN tblBar ON tblFoo.fldId = tblBar.fldId
1976
     *    JOIN tblBar ON tblFoo.fldId = tblBar.fldId
1919
     * </pre>
1977
     * </pre>
1920
     *
1978
     *
1921
     * <ul>
1979
     * <ul>
1922
     * <li>
1980
     * <li>
1923
     *
1981
     *
1924
     * <kbd>null</kbd> (default)
1982
     * <kbd>null</kbd> (default)
1925
     *   <pre>
1983
     *   <pre>
1926
     *   [0] => Array (
1984
     *   [0] => Array (
1927
     *       [table] => tblFoo
1985
     *       [table] => tblFoo
1928
     *       [name] => fldId
1986
     *       [name] => fldId
1929
     *       [type] => int
1987
     *       [type] => int
1930
     *       [len] => 11
1988
     *       [len] => 11
1931
     *       [flags] => primary_key not_null
1989
     *       [flags] => primary_key not_null
1932
     *   )
1990
     *   )
1933
     *   [1] => Array (
1991
     *   [1] => Array (
1934
     *       [table] => tblFoo
1992
     *       [table] => tblFoo
1935
     *       [name] => fldPhone
1993
     *       [name] => fldPhone
1936
     *       [type] => string
1994
     *       [type] => string
1937
     *       [len] => 20
1995
     *       [len] => 20
1938
     *       [flags] =>
1996
     *       [flags] =>
1939
     *   )
1997
     *   )
1940
     *   [2] => Array (
1998
     *   [2] => Array (
1941
     *       [table] => tblBar
1999
     *       [table] => tblBar
1942
     *       [name] => fldId
2000
     *       [name] => fldId
1943
     *       [type] => int
2001
     *       [type] => int
1944
     *       [len] => 11
2002
     *       [len] => 11
1945
     *       [flags] => primary_key not_null
2003
     *       [flags] => primary_key not_null
1946
     *   )
2004
     *   )
1947
     *   </pre>
2005
     *   </pre>
1948
     *
2006
     *
1949
     * </li><li>
2007
     * </li><li>
1950
     *
2008
     *
1951
     * <kbd>DB_TABLEINFO_ORDER</kbd>
2009
     * <kbd>DB_TABLEINFO_ORDER</kbd>
1952
     *
2010
     *
1953
     *   <p>In addition to the information found in the default output,
2011
     *   <p>In addition to the information found in the default output,
1954
     *   a notation of the number of columns is provided by the
2012
     *   a notation of the number of columns is provided by the
1955
     *   <samp>num_fields</samp> element while the <samp>order</samp>
2013
     *   <samp>num_fields</samp> element while the <samp>order</samp>
1956
     *   element provides an array with the column names as the keys and
2014
     *   element provides an array with the column names as the keys and
1957
     *   their location index number (corresponding to the keys in the
2015
     *   their location index number (corresponding to the keys in the
1958
     *   the default output) as the values.</p>
2016
     *   the default output) as the values.</p>
1959
     *
2017
     *
1960
     *   <p>If a result set has identical field names, the last one is
2018
     *   <p>If a result set has identical field names, the last one is
1961
     *   used.</p>
2019
     *   used.</p>
1962
     *
2020
     *
1963
     *   <pre>
2021
     *   <pre>
1964
     *   [num_fields] => 3
2022
     *   [num_fields] => 3
1965
     *   [order] => Array (
2023
     *   [order] => Array (
1966
     *       [fldId] => 2
2024
     *       [fldId] => 2
1967
     *       [fldTrans] => 1
2025
     *       [fldTrans] => 1
1968
     *   )
2026
     *   )
1969
     *   </pre>
2027
     *   </pre>
1970
     *
2028
     *
1971
     * </li><li>
2029
     * </li><li>
1972
     *
2030
     *
1973
     * <kbd>DB_TABLEINFO_ORDERTABLE</kbd>
2031
     * <kbd>DB_TABLEINFO_ORDERTABLE</kbd>
1974
     *
2032
     *
1975
     *   <p>Similar to <kbd>DB_TABLEINFO_ORDER</kbd> but adds more
2033
     *   <p>Similar to <kbd>DB_TABLEINFO_ORDER</kbd> but adds more
1976
     *   dimensions to the array in which the table names are keys and
2034
     *   dimensions to the array in which the table names are keys and
1977
     *   the field names are sub-keys.  This is helpful for queries that
2035
     *   the field names are sub-keys.  This is helpful for queries that
1978
     *   join tables which have identical field names.</p>
2036
     *   join tables which have identical field names.</p>
1979
     *
2037
     *
1980
     *   <pre>
2038
     *   <pre>
1981
     *   [num_fields] => 3
2039
     *   [num_fields] => 3
1982
     *   [ordertable] => Array (
2040
     *   [ordertable] => Array (
1983
     *       [tblFoo] => Array (
2041
     *       [tblFoo] => Array (
1984
     *           [fldId] => 0
2042
     *           [fldId] => 0
1985
     *           [fldPhone] => 1
2043
     *           [fldPhone] => 1
1986
     *       )
2044
     *       )
1987
     *       [tblBar] => Array (
2045
     *       [tblBar] => Array (
1988
     *           [fldId] => 2
2046
     *           [fldId] => 2
1989
     *       )
2047
     *       )
1990
     *   )
2048
     *   )
1991
     *   </pre>
2049
     *   </pre>
1992
     *
2050
     *
1993
     * </li>
2051
     * </li>
1994
     * </ul>
2052
     * </ul>
1995
     *
2053
     *
1996
     * The <samp>flags</samp> element contains a space separated list
2054
     * The <samp>flags</samp> element contains a space separated list
1997
     * of extra information about the field.  This data is inconsistent
2055
     * of extra information about the field.  This data is inconsistent
1998
     * between DBMS's due to the way each DBMS works.
2056
     * between DBMS's due to the way each DBMS works.
1999
     *   + <samp>primary_key</samp>
2057
     *   + <samp>primary_key</samp>
2000
     *   + <samp>unique_key</samp>
2058
     *   + <samp>unique_key</samp>
2001
     *   + <samp>multiple_key</samp>
2059
     *   + <samp>multiple_key</samp>
2002
     *   + <samp>not_null</samp>
2060
     *   + <samp>not_null</samp>
2003
     *
2061
     *
2004
     * Most DBMS's only provide the <samp>table</samp> and <samp>flags</samp>
2062
     * Most DBMS's only provide the <samp>table</samp> and <samp>flags</samp>
2005
     * elements if <var>$result</var> is a table name.  The following DBMS's
2063
     * elements if <var>$result</var> is a table name.  The following DBMS's
2006
     * provide full information from queries:
2064
     * provide full information from queries:
2007
     *   + fbsql
2065
     *   + fbsql
2008
     *   + mysql
2066
     *   + mysql
2009
     *
2067
     *
2010
     * If the 'portability' option has <samp>DB_PORTABILITY_LOWERCASE</samp>
2068
     * If the 'portability' option has <samp>DB_PORTABILITY_LOWERCASE</samp>
2011
     * turned on, the names of tables and fields will be lowercased.
2069
     * turned on, the names of tables and fields will be lowercased.
2012
     *
2070
     *
2013
     * @param object|string  $result  DB_result object from a query or a
2071
     * @param object|string  $result  DB_result object from a query or a
2014
     *                                string containing the name of a table.
2072
     *                                string containing the name of a table.
2015
     *                                While this also accepts a query result
2073
     *                                While this also accepts a query result
2016
     *                                resource identifier, this behavior is
2074
     *                                resource identifier, this behavior is
2017
     *                                deprecated.
2075
     *                                deprecated.
2018
     * @param int  $mode   either unused or one of the tableInfo modes:
2076
     * @param int  $mode   either unused or one of the tableInfo modes:
2019
     *                     <kbd>DB_TABLEINFO_ORDERTABLE</kbd>,
2077
     *                     <kbd>DB_TABLEINFO_ORDERTABLE</kbd>,
2020
     *                     <kbd>DB_TABLEINFO_ORDER</kbd> or
2078
     *                     <kbd>DB_TABLEINFO_ORDER</kbd> or
2021
     *                     <kbd>DB_TABLEINFO_FULL</kbd> (which does both).
2079
     *                     <kbd>DB_TABLEINFO_FULL</kbd> (which does both).
2022
     *                     These are bitwise, so the first two can be
2080
     *                     These are bitwise, so the first two can be
2023
     *                     combined using <kbd>|</kbd>.
2081
     *                     combined using <kbd>|</kbd>.
2024
     *
2082
     *
2025
     * @return array  an associative array with the information requested.
2083
     * @return array  an associative array with the information requested.
2026
     *                 A DB_Error object on failure.
2084
     *                 A DB_Error object on failure.
2027
     *
2085
     *
2028
     * @see DB_common::setOption()
2086
     * @see DB_common::setOption()
2029
     */
2087
     */
2030
    function tableInfo($result, $mode = null)
2088
    function tableInfo($result, $mode = null)
2031
    {
2089
    {
2032
        /*
2090
        /*
2033
         * If the DB_<driver> class has a tableInfo() method, that one
2091
         * If the DB_<driver> class has a tableInfo() method, that one
2034
         * overrides this one.  But, if the driver doesn't have one,
2092
         * overrides this one.  But, if the driver doesn't have one,
2035
         * this method runs and tells users about that fact.
2093
         * this method runs and tells users about that fact.
2036
         */
2094
         */
2037
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
2095
        return $this->raiseError(DB_ERROR_NOT_CAPABLE);
2038
    }
2096
    }
2039
 
2097
 
2040
    // }}}
2098
    // }}}
2041
    // {{{ getTables()
2099
    // {{{ getTables()
2042
 
2100
 
2043
    /**
2101
    /**
2044
     * Lists the tables in the current database
2102
     * Lists the tables in the current database
2045
     *
2103
     *
2046
     * @return array  the list of tables.  A DB_Error object on failure.
2104
     * @return array  the list of tables.  A DB_Error object on failure.
2047
     *
2105
     *
2048
     * @deprecated Method deprecated some time before Release 1.2
2106
     * @deprecated Method deprecated some time before Release 1.2
2049
     */
2107
     */
2050
    function getTables()
2108
    function getTables()
2051
    {
2109
    {
2052
        return $this->getListOf('tables');
2110
        return $this->getListOf('tables');
2053
    }
2111
    }
2054
 
2112
 
2055
    // }}}
2113
    // }}}
2056
    // {{{ getListOf()
2114
    // {{{ getListOf()
2057
 
2115
 
2058
    /**
2116
    /**
2059
     * Lists internal database information
2117
     * Lists internal database information
2060
     *
2118
     *
2061
     * @param string $type  type of information being sought.
2119
     * @param string $type  type of information being sought.
2062
     *                       Common items being sought are:
2120
     *                       Common items being sought are:
2063
     *                       tables, databases, users, views, functions
2121
     *                       tables, databases, users, views, functions
2064
     *                       Each DBMS's has its own capabilities.
2122
     *                       Each DBMS's has its own capabilities.
2065
     *
2123
     *
2066
     * @return array  an array listing the items sought.
2124
     * @return array  an array listing the items sought.
2067
     *                 A DB DB_Error object on failure.
2125
     *                 A DB DB_Error object on failure.
2068
     */
2126
     */
2069
    function getListOf($type)
2127
    function getListOf($type)
2070
    {
2128
    {
2071
        $sql = $this->getSpecialQuery($type);
2129
        $sql = $this->getSpecialQuery($type);
2072
        if ($sql === null) {
2130
        if ($sql === null) {
2073
            $this->last_query = '';
2131
            $this->last_query = '';
2074
            return $this->raiseError(DB_ERROR_UNSUPPORTED);
2132
            return $this->raiseError(DB_ERROR_UNSUPPORTED);
2075
        } elseif (is_int($sql) || DB::isError($sql)) {
2133
        } elseif (is_int($sql) || DB::isError($sql)) {
2076
            // Previous error
2134
            // Previous error
2077
            return $this->raiseError($sql);
2135
            return $this->raiseError($sql);
2078
        } elseif (is_array($sql)) {
2136
        } elseif (is_array($sql)) {
2079
            // Already the result
2137
            // Already the result
2080
            return $sql;
2138
            return $sql;
2081
        }
2139
        }
2082
        // Launch this query
2140
        // Launch this query
2083
        return $this->getCol($sql);
2141
        return $this->getCol($sql);
2084
    }
2142
    }
2085
 
2143
 
2086
    // }}}
2144
    // }}}
2087
    // {{{ getSpecialQuery()
2145
    // {{{ getSpecialQuery()
2088
 
2146
 
2089
    /**
2147
    /**
2090
     * Obtains the query string needed for listing a given type of objects
2148
     * Obtains the query string needed for listing a given type of objects
2091
     *
2149
     *
2092
     * @param string $type  the kind of objects you want to retrieve
2150
     * @param string $type  the kind of objects you want to retrieve
2093
     *
2151
     *
2094
     * @return string  the SQL query string or null if the driver doesn't
2152
     * @return string  the SQL query string or null if the driver doesn't
2095
     *                  support the object type requested
2153
     *                  support the object type requested
2096
     *
2154
     *
2097
     * @access protected
2155
     * @access protected
2098
     * @see DB_common::getListOf()
2156
     * @see DB_common::getListOf()
2099
     */
2157
     */
2100
    function getSpecialQuery($type)
2158
    function getSpecialQuery($type)
2101
    {
2159
    {
2102
        return $this->raiseError(DB_ERROR_UNSUPPORTED);
2160
        return $this->raiseError(DB_ERROR_UNSUPPORTED);
2103
    }
2161
    }
-
 
2162
 
-
 
2163
    // }}}
-
 
2164
    // {{{ nextQueryIsManip()
-
 
2165
 
-
 
2166
    /**
-
 
2167
     * Sets (or unsets) a flag indicating that the next query will be a
-
 
2168
     * manipulation query, regardless of the usual DB::isManip() heuristics.
-
 
2169
     *
-
 
2170
     * @param boolean true to set the flag overriding the isManip() behaviour,
-
 
2171
     * false to clear it and fall back onto isManip()
-
 
2172
     *
-
 
2173
     * @return void
-
 
2174
     *
-
 
2175
     * @access public
-
 
2176
     */
-
 
2177
    function nextQueryIsManip($manip)
-
 
2178
    {
-
 
2179
        $this->_next_query_manip = $manip;
-
 
2180
    }
-
 
2181
 
-
 
2182
    // }}}
-
 
2183
    // {{{ _checkManip()
-
 
2184
 
-
 
2185
    /**
-
 
2186
     * Checks if the given query is a manipulation query. This also takes into
-
 
2187
     * account the _next_query_manip flag and sets the _last_query_manip flag
-
 
2188
     * (and resets _next_query_manip) according to the result.
-
 
2189
     *
-
 
2190
     * @param string The query to check.
-
 
2191
     *
-
 
2192
     * @return boolean true if the query is a manipulation query, false
-
 
2193
     * otherwise
-
 
2194
     *
-
 
2195
     * @access protected
-
 
2196
     */
-
 
2197
    function _checkManip($query)
-
 
2198
    {
-
 
2199
        if ($this->_next_query_manip || DB::isManip($query)) {
-
 
2200
            $this->_last_query_manip = true;
-
 
2201
        } else {
-
 
2202
            $this->_last_query_manip = false;
-
 
2203
        }
-
 
2204
        $this->_next_query_manip = false;
-
 
2205
        return $this->_last_query_manip;
-
 
2206
        $manip = $this->_next_query_manip;
-
 
2207
    }
2104
 
2208
 
2105
    // }}}
2209
    // }}}
2106
    // {{{ _rtrimArrayValues()
2210
    // {{{ _rtrimArrayValues()
2107
 
2211
 
2108
    /**
2212
    /**
2109
     * Right-trims all strings in an array
2213
     * Right-trims all strings in an array
2110
     *
2214
     *
2111
     * @param array $array  the array to be trimmed (passed by reference)
2215
     * @param array $array  the array to be trimmed (passed by reference)
2112
     *
2216
     *
2113
     * @return void
2217
     * @return void
2114
     *
2218
     *
2115
     * @access protected
2219
     * @access protected
2116
     */
2220
     */
2117
    function _rtrimArrayValues(&$array)
2221
    function _rtrimArrayValues(&$array)
2118
    {
2222
    {
2119
        foreach ($array as $key => $value) {
2223
        foreach ($array as $key => $value) {
2120
            if (is_string($value)) {
2224
            if (is_string($value)) {
2121
                $array[$key] = rtrim($value);
2225
                $array[$key] = rtrim($value);
2122
            }
2226
            }
2123
        }
2227
        }
2124
    }
2228
    }
2125
 
2229
 
2126
    // }}}
2230
    // }}}
2127
    // {{{ _convertNullArrayValuesToEmpty()
2231
    // {{{ _convertNullArrayValuesToEmpty()
2128
 
2232
 
2129
    /**
2233
    /**
2130
     * Converts all null values in an array to empty strings
2234
     * Converts all null values in an array to empty strings
2131
     *
2235
     *
2132
     * @param array  $array  the array to be de-nullified (passed by reference)
2236
     * @param array  $array  the array to be de-nullified (passed by reference)
2133
     *
2237
     *
2134
     * @return void
2238
     * @return void
2135
     *
2239
     *
2136
     * @access protected
2240
     * @access protected
2137
     */
2241
     */
2138
    function _convertNullArrayValuesToEmpty(&$array)
2242
    function _convertNullArrayValuesToEmpty(&$array)
2139
    {
2243
    {
2140
        foreach ($array as $key => $value) {
2244
        foreach ($array as $key => $value) {
2141
            if (is_null($value)) {
2245
            if (is_null($value)) {
2142
                $array[$key] = '';
2246
                $array[$key] = '';
2143
            }
2247
            }
2144
        }
2248
        }
2145
    }
2249
    }
2146
 
2250
 
2147
    // }}}
2251
    // }}}
2148
}
2252
}
2149
 
2253
 
2150
/*
2254
/*
2151
 * Local variables:
2255
 * Local variables:
2152
 * tab-width: 4
2256
 * tab-width: 4
2153
 * c-basic-offset: 4
2257
 * c-basic-offset: 4
2154
 * End:
2258
 * End:
2155
 */
2259
 */
2156
 
2260
 
2157
?>
2261
?>