mirror of
https://github.com/atlanticbiomedical/portal-legacy.git
synced 2025-07-02 01:47:28 -04:00
381 lines
17 KiB
PHP
Executable File
381 lines
17 KiB
PHP
Executable File
<?php
|
|
/*
|
|
* $Id: ResultSet.php,v 1.28 2006/01/17 19:44:38 hlellelid Exp $
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*
|
|
* This software consists of voluntary contributions made by many individuals
|
|
* and is licensed under the LGPL. For more information please see
|
|
* <http://creole.phpdb.org>.
|
|
*/
|
|
|
|
/**
|
|
* This is the interface for classes the wrap db results.
|
|
*
|
|
* The get*() methods in this interface will format values before returning them. Note
|
|
* that if they will return null if the database returned NULL. If the requested column does
|
|
* not exist than an exception (SQLException) will be thrown.
|
|
*
|
|
* <code>
|
|
* $rs = $conn->executeQuery("SELECT MAX(stamp) FROM event", ResultSet::FETCHMODE_NUM);
|
|
* $rs->next();
|
|
*
|
|
* $max_stamp = $rs->getTimestamp(1, "d/m/Y H:i:s");
|
|
* // $max_stamp will be date string or null if no MAX(stamp) was found
|
|
*
|
|
* $max_stamp = $rs->getTimestamp("max(stamp)", "d/m/Y H:i:s");
|
|
* // will THROW EXCEPTION, because the resultset was fetched using numeric indexing
|
|
* // SQLException: Invalid resultset column: max(stamp)
|
|
* </code>
|
|
*
|
|
* This class implements SPL IteratorAggregate, so you may iterate over the database results
|
|
* using foreach():
|
|
* <code>
|
|
* foreach($rs as $row) {
|
|
* print_r($row); // row is assoc array returned by getRow()
|
|
* }
|
|
* </code>
|
|
*
|
|
* @author Hans Lellelid <hans@xmpl.org>
|
|
* @version $Revision: 1.28 $
|
|
* @package creole
|
|
*/
|
|
interface ResultSet extends IteratorAggregate {
|
|
|
|
/**
|
|
* Index result set by field name.
|
|
*/
|
|
const FETCHMODE_ASSOC = 1;
|
|
|
|
/**
|
|
* Index result set numerically.
|
|
*/
|
|
const FETCHMODE_NUM = 2;
|
|
|
|
/**
|
|
* Get the PHP native resource for the result.
|
|
* Arguably this should not be part of the interface: i.e. every driver should implement
|
|
* it if they have a result resource, but conceivably drivers could be created that do
|
|
* not. For now every single driver does have a "dblink" resource property, and other
|
|
* classes (e.g. ResultSet) need this info in order to get correct native errors. We'll
|
|
* leave it in for now, as it helps with driver development, with the caveat that it
|
|
* could be removed from the interface at a later point.
|
|
* @return resource Query result or NULL if not not applicable.
|
|
*/
|
|
public function getResource();
|
|
|
|
/**
|
|
* Sets the fetchmode used to retrieve results.
|
|
* Changing fetchmodes mid-result retrieval is supported (haven't encountered any drivers
|
|
* that don't support that yet).
|
|
* @param int $mode ResultSet::FETCHMODE_NUM or ResultSet::FETCHMODE_ASSOC (default).
|
|
* @return void
|
|
*/
|
|
public function setFetchmode($mode);
|
|
|
|
/**
|
|
* Gets the fetchmode used to retrieve results.
|
|
* @return int ResultSet::FETCHMODE_NUM or ResultSet::FETCHMODE_ASSOC (default).
|
|
*/
|
|
public function getFetchmode();
|
|
|
|
/**
|
|
* Whether assoc result keys get converted to lowercase for compatibility.
|
|
*
|
|
* This defaults to FALSE unless Creole::COMPAT_ASSOC_LOWER flag has been passed to connection.
|
|
* This property is read-only since it must be set when connection is created. The
|
|
* reason for this behavior is some drivers (e.g. SQLite) do the case conversions internally
|
|
* based on a PHP ini value; it would not be possible to change the behavior from the ResultSet
|
|
* (since query has already been executed).
|
|
*
|
|
* @return boolean
|
|
*/
|
|
public function isLowerAssocCase();
|
|
|
|
/**
|
|
* Moves the internal cursor to the next position and fetches the row at that position.
|
|
*
|
|
* @return boolean <tt>true</tt> if success, <tt>false</tt> if no next record.
|
|
* @throws SQLException on any driver-level errors.
|
|
*/
|
|
public function next();
|
|
|
|
/**
|
|
* Moves the internal cursor to the previous position and fetches the
|
|
* row at that position.
|
|
*
|
|
* @return boolean <tt>true</tt> if success, <tt>false</tt> if no previous record.
|
|
* @throws SQLException - if unable to move to previous position
|
|
* - if ResultSet doesn't support reverse scrolling
|
|
*/
|
|
public function previous();
|
|
|
|
/**
|
|
* Moves the cursor a relative number of rows, either positive or negative and fetches
|
|
* the row at that position.
|
|
*
|
|
* Attempting to move beyond the first/last row in the result set positions the cursor before/after
|
|
* the first/last row and issues a Warning. Calling relative(0) is valid, but does not change the cursor
|
|
* position.
|
|
*
|
|
* @param integer $offset
|
|
* @return boolean <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
|
|
* @throws SQLException - if unable to move to relative position
|
|
* - if rel pos is negative & ResultSet doesn't support reverse scrolling
|
|
*/
|
|
public function relative($offset);
|
|
|
|
|
|
/**
|
|
* Moves the cursor to an absolute cursor position and fetches the row at that position.
|
|
*
|
|
* Attempting to move beyond the first/last row in the result set positions the cursor before/after
|
|
* the first/last row and issues a Warning.
|
|
*
|
|
* @param integer $pos cursor position, first position is 1.
|
|
* @return boolean <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
|
|
* @throws SQLException - if unable to move to absolute position
|
|
* - if position is before current pos & ResultSet doesn't support reverse scrolling
|
|
*/
|
|
public function absolute($pos);
|
|
|
|
/**
|
|
* Moves cursor position WITHOUT FETCHING ROW AT THAT POSITION.
|
|
*
|
|
* Generally this method is for internal driver stuff (e.g. other methods like
|
|
* absolute() or relative() might call this and then call next() to get the row).
|
|
* This method is public to facilitate more advanced ResultSet scrolling tools
|
|
* -- e.g. cleaner implimentation of ResultSetIterator.
|
|
*
|
|
* Some drivers will emulate seek() and not allow reverse seek (Oracle).
|
|
*
|
|
* Seek is 0-based, but seek() is only for moving to the space _before_ the record
|
|
* that you want to read. I.e. if you seek(0) and then call next() you will have the
|
|
* first row (i.e. same as calling first() or absolute(1)).
|
|
*
|
|
* <strong>IMPORTANT: You cannot rely on the return value of this method to know whether a given
|
|
* record exists for reading. In some cases seek() will correctly return <code>false</code> if
|
|
* the position doesn't exist, but in other drivers the seek is not performed until the
|
|
* record is fetched. You can check the return value of absolute() if you need to know
|
|
* whether a specific rec position is valid.</strong>
|
|
*
|
|
* @param int $rownum The cursor pos to seek to.
|
|
* @return boolean true on success, false if unable to seek to specified record.
|
|
* @throws SQLException if trying to seek backwards with a driver that doesn't
|
|
* support reverse-scrolling
|
|
*/
|
|
public function seek($rownum);
|
|
|
|
/**
|
|
* Move cursor to beginning of recordset.
|
|
* @return boolean <tt>true</tt> on success or <tt>false</tt> if not found.
|
|
* @throws SQLException - if unable to move to first position
|
|
* - if not at first pos & ResultSet doesn't support reverse scrolling
|
|
*/
|
|
public function first();
|
|
|
|
/**
|
|
* Move cursor to end of recordset.
|
|
* @return boolean <tt>true</tt> on success or <tt>false</tt> if not found.
|
|
* @throws SQLException - if unable to move to last position
|
|
* - if unable to get num rows
|
|
*/
|
|
public function last();
|
|
|
|
/**
|
|
* Sets cursort to before first record. This does not actually seek(), but
|
|
* simply sets cursor pos to 0.
|
|
* This is useful for inserting a record before the first in the set, etc.
|
|
* @return void
|
|
*/
|
|
public function beforeFirst();
|
|
|
|
|
|
/**
|
|
* Sets cursort to after the last record. This does not actually seek(), but
|
|
* simply sets the cursor pos to last + 1.
|
|
* This [will be] useful for inserting a record after the last in the set,
|
|
* when/if Creole supports updateable ResultSets.
|
|
* @return void
|
|
*/
|
|
public function afterLast();
|
|
|
|
|
|
/**
|
|
* Checks whether cursor is after the last record.
|
|
* @return boolean
|
|
* @throws SQLException on any driver-level error.
|
|
*/
|
|
public function isAfterLast();
|
|
|
|
/**
|
|
* Checks whether cursor is before the first record.
|
|
* @return boolean
|
|
* @throws SQLException on any driver-level error.
|
|
*/
|
|
public function isBeforeFirst();
|
|
|
|
/**
|
|
* Returns the current cursor position.
|
|
* Cursor positions start at 0, but as soon as first row is fetched
|
|
* cursor position is 1. (so first row is 1)
|
|
* @return int
|
|
*/
|
|
public function getCursorPos();
|
|
|
|
/**
|
|
* Gets current fields (assoc array).
|
|
* @return array
|
|
*/
|
|
public function getRow();
|
|
|
|
/**
|
|
* Get the number of rows in a result set.
|
|
* @return int the number of rows
|
|
* @throws SQLException - if unable to get a rowcount.
|
|
*/
|
|
public function getRecordCount();
|
|
|
|
/**
|
|
* Frees the resources allocated for this result set.
|
|
* Also empties any internal field array so that any calls to
|
|
* get() method on closed ResultSet will result in "Invalid column" SQLException.
|
|
* @return void
|
|
*/
|
|
public function close();
|
|
|
|
/**
|
|
* A generic get method returns unformatted (=string) value.
|
|
* This returns the raw results from the database. Usually this will be a string, but some drivers
|
|
* also can return objects (lob descriptors, etc) in certain cases.
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used) (if ResultSet::FETCHMODE_NUM was used).
|
|
* @return mixed Usually expect a string.
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function get($column);
|
|
|
|
/**
|
|
* Reads a column as an array.
|
|
* The value of the column is unserialized & returned as an array. The generic case of this function is
|
|
* very PHP-specific. Other drivers (e.g. Postgres) will format values into their native array format.
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @return array value or null if database returned null.
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getArray($column);
|
|
|
|
/**
|
|
* Returns value translated to boolean.
|
|
* Default is to map 0 => false, 1 => true, but some database drivers may override this behavior.
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @return boolean value or null if database returned null.
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getBoolean($column);
|
|
|
|
/**
|
|
* Returns Blob with contents of column value.
|
|
*
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @return Blob New Blob with data from column or null if database returned null.
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getBlob($column);
|
|
|
|
/**
|
|
* Returns Clob with contents of column value.
|
|
*
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @return Clob New Clob object with data from column or null if database returned null.
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getClob($column);
|
|
|
|
/**
|
|
* Return a formatted date.
|
|
*
|
|
* The default format for dates returned is preferred (in your locale, as specified using setlocale())
|
|
* format w/o time (i.e. strftime("%x", $val)). Override this by specifying a format second parameter. You
|
|
* can also specify a date()-style formatter; if you do, make sure there are no "%" symbols in your format string.
|
|
*
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
|
|
* If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
|
|
* @return mixed Formatted date, or integer unix timestamp (using 00:00:00 for time) if $format was null.
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getDate($column, $format = '%x');
|
|
|
|
/**
|
|
* Returns value cast as a float (in PHP this is same as double).
|
|
*
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @return float value or null if database returned null
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getFloat($column);
|
|
|
|
/**
|
|
* Returns value cast as integer.
|
|
*
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @return int value or null if database returned null
|
|
* @see getInteger()
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getInt($column);
|
|
|
|
/**
|
|
* Returns value cast as string.
|
|
*
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @return string value or null if database returned null
|
|
* @see get()
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getString($column);
|
|
|
|
/**
|
|
* Return a formatted time.
|
|
*
|
|
* The default format for times returned is preferred (in your locale, as specified using setlocale())
|
|
* format w/o date (i.e. strftime("%X", $val)). Override this by specifying a format second parameter. You
|
|
* can also specify a date()-style formatter; if you do, make sure there are no "%" symbols in your format string.
|
|
*
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
|
|
* If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
|
|
* @return mixed Formatted time, or integer unix timestamp (using today's date) if $format was null.
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getTime($column, $format = '%X');
|
|
|
|
/**
|
|
* Return a formatted timestamp.
|
|
*
|
|
* The default format for timestamp is ISO standard YYYY-MM-DD HH:MM:SS (i.e. date('Y-m-d H:i:s', $val).
|
|
* Override this by specifying a format second parameter. You can also specify a strftime()-style formatter.
|
|
*
|
|
* Hint: if you want to get the unix timestamp use the "U" formatter string.
|
|
*
|
|
* @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
|
|
* @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
|
|
* If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
|
|
* @return mixed Formatted timestamp, or integer unix timestamp (if $format was null)
|
|
* @throws SQLException - If the column specified is not a valid key in current field array.
|
|
*/
|
|
public function getTimestamp($column, $format = 'Y-m-d H:i:s');
|
|
|
|
}
|
|
|