ResultSet Interface Reference

Inheritance diagram for ResultSet:

MSSQLResultSet MySQLiResultSet MySQLResultSet OCI8ResultSet ODBCCachedResultSet ODBCResultSet PgSQLResultSet SQLiteResultSet

List of all members.

Public Member Functions

 getResource ()
 Get the PHP native resource for the result.
 setFetchmode ($mode)
 Sets the fetchmode used to retrieve results.
 getFetchmode ()
 Gets the fetchmode used to retrieve results.
 isLowerAssocCase ()
 Whether assoc result keys get converted to lowercase for compatibility.
 next ()
 Moves the internal cursor to the next position and fetches the row at that position.
 previous ()
 Moves the internal cursor to the previous position and fetches the row at that position.
 relative ($offset)
 Moves the cursor a relative number of rows, either positive or negative and fetches the row at that position.
 absolute ($pos)
 Moves the cursor to an absolute cursor position and fetches the row at that position.
 seek ($rownum)
 Moves cursor position WITHOUT FETCHING ROW AT THAT POSITION.
 first ()
 Move cursor to beginning of recordset.
 last ()
 Move cursor to end of recordset.
 beforeFirst ()
 Sets cursort to before first record.
 afterLast ()
 Sets cursort to after the last record.
 isAfterLast ()
 Checks whether cursor is after the last record.
 isBeforeFirst ()
 Checks whether cursor is before the first record.
 getCursorPos ()
 Returns the current cursor position.
 getRow ()
 Gets current fields (assoc array).
 getRecordCount ()
 Get the number of rows in a result set.
 close ()
 Frees the resources allocated for this result set.
 get ($column)
 A generic get method returns unformatted (=string) value.
 getArray ($column)
 Reads a column as an array.
 getBoolean ($column)
 Returns value translated to boolean.
 getBlob ($column)
 Returns Blob with contents of column value.
 getClob ($column)
 Returns Clob with contents of column value.
 getDate ($column, $format= '%x')
 Return a formatted date.
 getFloat ($column)
 Returns value cast as a float (in PHP this is same as double).
 getInt ($column)
 Returns value cast as integer.
 getString ($column)
 Returns value cast as string.
 getTime ($column, $format= '%X')
 Return a formatted time.
 getTimestamp ($column, $format= 'Y-m-d H:i:s')
 Return a formatted timestamp.

Public Attributes

const FETCHMODE_ASSOC = 1
 Index result set by field name.
const FETCHMODE_NUM = 2
 Index result set numerically.


Detailed Description

Definition at line 53 of file ResultSet.php.


Member Function Documentation

ResultSet::absolute ( pos  ) 

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.

Parameters:
integer $pos cursor position, first position is 1.
Returns:
boolean true if cursor is on a row, false otherwise.
Exceptions:
SQLException - if unable to move to absolute position
  • if position is before current pos & ResultSet doesn't support reverse scrolling

ResultSet::afterLast (  ) 

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.

Returns:
void

Referenced by ODBCCachedResultSet::next().

ResultSet::beforeFirst (  ) 

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.

Returns:
void

Referenced by ODBCResultSet::getRecordCount().

ResultSet::close (  ) 

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.

Returns:
void

Implemented in MSSQLResultSet, MySQLResultSet, MySQLiResultSet, ODBCCachedResultSet, ODBCResultSet, OCI8ResultSet, PgSQLResultSet, and SQLiteResultSet.

ResultSet::first (  ) 

Move cursor to beginning of recordset.

Returns:
boolean true on success or false if not found.
Exceptions:
SQLException - if unable to move to first position
  • if not at first pos & ResultSet doesn't support reverse scrolling

ResultSet::get ( column  ) 

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.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used) (if ResultSet::FETCHMODE_NUM was used).
Returns:
mixed Usually expect a string.
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

ResultSet::getArray ( 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.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
Returns:
array value or null if database returned null.
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

Implemented in PgSQLResultSet.

ResultSet::getBlob ( column  ) 

Returns Blob with contents of column value.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
Returns:
Blob New Blob with data from column or null if database returned null.
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

Implemented in ODBCResultSet, PgSQLResultSet, and SQLiteResultSet.

ResultSet::getBoolean ( column  ) 

Returns value translated to boolean.

Default is to map 0 => false, 1 => true, but some database drivers may override this behavior.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
Returns:
boolean value or null if database returned null.
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

Implemented in PgSQLResultSet.

ResultSet::getClob ( column  ) 

Returns Clob with contents of column value.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
Returns:
Clob New Clob object with data from column or null if database returned null.
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

Implemented in ODBCResultSet.

ResultSet::getCursorPos (  ) 

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)

Returns:
int

ResultSet::getDate ( column,
format = '%x' 
)

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.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
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).
Returns:
mixed Formatted date, or integer unix timestamp (using 00:00:00 for time) if $format was null.
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

ResultSet::getFetchmode (  ) 

Gets the fetchmode used to retrieve results.

Returns:
int ResultSet::FETCHMODE_NUM or ResultSet::FETCHMODE_ASSOC (default).

ResultSet::getFloat ( column  ) 

Returns value cast as a float (in PHP this is same as double).

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
Returns:
float value or null if database returned null
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

ResultSet::getInt ( column  ) 

Returns value cast as integer.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
Returns:
int value or null if database returned null
See also:
getInteger()
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

ResultSet::getRecordCount (  ) 

Get the number of rows in a result set.

Returns:
int the number of rows
Exceptions:
SQLException - if unable to get a rowcount.

Implemented in MSSQLResultSet, MySQLResultSet, MySQLiResultSet, ODBCCachedResultSet, ODBCResultSet, OCI8ResultSet, PgSQLResultSet, and SQLiteResultSet.

ResultSet::getResource (  ) 

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.

Returns:
resource Query result or NULL if not not applicable.

ResultSet::getRow (  ) 

Gets current fields (assoc array).

Returns:
array

Referenced by Record::createValues().

ResultSet::getString ( column  ) 

Returns value cast as string.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
Returns:
string value or null if database returned null
See also:
get()
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

Implemented in MySQLResultSet, and MySQLiResultSet.

ResultSet::getTime ( column,
format = '%X' 
)

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.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
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).
Returns:
mixed Formatted time, or integer unix timestamp (using today's date) if $format was null.
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

ResultSet::getTimestamp ( column,
format = 'Y-m-d H:i:s' 
)

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.

Parameters:
mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
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).
Returns:
mixed Formatted timestamp, or integer unix timestamp (if $format was null)
Exceptions:
SQLException - If the column specified is not a valid key in current field array.

Implemented in MySQLResultSet, and MySQLiResultSet.

ResultSet::isAfterLast (  ) 

Checks whether cursor is after the last record.

Returns:
boolean
Exceptions:
SQLException on any driver-level error.

Implemented in ODBCCachedResultSet, and ODBCResultSet.

ResultSet::isBeforeFirst (  ) 

Checks whether cursor is before the first record.

Returns:
boolean
Exceptions:
SQLException on any driver-level error.

ResultSet::isLowerAssocCase (  ) 

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).

Returns:
boolean

ResultSet::last (  ) 

Move cursor to end of recordset.

Returns:
boolean true on success or false if not found.
Exceptions:
SQLException - if unable to move to last position
  • if unable to get num rows

ResultSet::next (  ) 

Moves the internal cursor to the next position and fetches the row at that position.

Returns:
boolean true if success, false if no next record.
Exceptions:
SQLException on any driver-level errors.

Implemented in MSSQLResultSet, MySQLResultSet, MySQLiResultSet, ODBCCachedResultSet, ODBCResultSet, OCI8ResultSet, PgSQLResultSet, and SQLiteResultSet.

ResultSet::previous (  ) 

Moves the internal cursor to the previous position and fetches the row at that position.

Returns:
boolean true if success, false if no previous record.
Exceptions:
SQLException - if unable to move to previous position
  • if ResultSet doesn't support reverse scrolling

ResultSet::relative ( offset  ) 

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.

Parameters:
integer $offset
Returns:
boolean true if cursor is on a row, false otherwise.
Exceptions:
SQLException - if unable to move to relative position
  • if rel pos is negative & ResultSet doesn't support reverse scrolling

ResultSet::seek ( rownum  ) 

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)).

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 false 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.

Parameters:
int $rownum The cursor pos to seek to.
Returns:
boolean true on success, false if unable to seek to specified record.
Exceptions:
SQLException if trying to seek backwards with a driver that doesn't support reverse-scrolling

Implemented in MSSQLResultSet, MySQLResultSet, MySQLiResultSet, ODBCCachedResultSet, ODBCResultSet, OCI8ResultSet, PgSQLResultSet, and SQLiteResultSet.

ResultSet::setFetchmode ( mode  ) 

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).

Parameters:
int $mode ResultSet::FETCHMODE_NUM or ResultSet::FETCHMODE_ASSOC (default).
Returns:
void


Member Data Documentation

Index result set numerically.

Definition at line 63 of file ResultSet.php.

Referenced by PgSQLIdGenerator::getId(), OCI8IdGenerator::getId(), ODBCIdGenerator::getId(), and MSSQLIdGenerator::getId().


The documentation for this interface was generated from the following file:

Generated on Wed May 6 23:10:50 2009 for fareofficelib by  doxygen 1.5.8