creole
[ class tree: creole ] [ index: creole ] [ all elements ]
Packages:
creole
creole.common
creole.drivers.mssql
creole.drivers.mssql.metadata
creole.drivers.mysql
creole.drivers.mysql.metadata
creole.drivers.odbc
creole.drivers.odbc.metadata
creole.drivers.oracle
creole.drivers.oracle.metadata
creole.drivers.pgsql
creole.drivers.pgsql.metadata
creole.drivers.sqlite
creole.drivers.sqlite.metadata
creole.metadata
creole.util
creole.util.sql
jargon


Files:
CallableStatement.php
Connection.php
Creole.php
CreoleTypes.php
IdGenerator.php
PreparedStatement.php
ResultSet.php
ResultSetIterator.php
SQLException.php
Statement.php

Classes:
CallableStatement
Connection
Creole
CreoleTypes
DataSetIterator
IdGenerator
PreparedStatement
ResultSet
ResultSetIterator
SQLException
Statement

Class: ResultSet

Source Location: /creole/ResultSet.php

Interface Overview

IteratorAggregate
   |
   --ResultSet

This is the interface for classes the wrap db results.


Author(s):

Version:

  • $Revision: 1.27 $

Constants

Methods

Class Details

[line 53]
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.

  1.  $rs = $conn->executeQuery("SELECT MAX(stamp) FROM event", ResultSet::FETCHMODE_NUM);
    2. 

  2.  $rs->next();
    3. 

  3.  
    4. 

  4.  $max_stamp = $rs->getTimestamp(1, "d/m/Y H:i:s");
    5. 

  5.  // $max_stamp will be date string or null if no MAX(stamp) was found
    6. 

  6.  
    7. 

  7.  $max_stamp = $rs->getTimestamp("max(stamp)", "d/m/Y H:i:s");
    8. 

  8.  // will THROW EXCEPTION, because the resultset was fetched using numeric indexing
    9.

This class implements SPL IteratorAggregate, so you may iterate over the database results using foreach(): 

  1.  foreach($rs as $row) {
    2. 

  2.    print_r($row); // row is assoc array returned by getRow()
    3. 

  3.  }
    4.




Tags:

version:  $Revision: 1.27 $
author:  Hans Lellelid <hans@xmpl.org>


[ Top ]

Class Methods

method absolute [line 151]

boolean absolute( integer $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.




Tags:

return:  <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
access:  public
throws:  SQLException - if unable to move to absolute position
  • if position is before current pos & ResultSet doesn't support reverse scrolling


Parameters:

integer   $pos   cursor position, first position is 1.

[ Top ]

method afterLast [line 212]

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




Tags:

access:  public


[ Top ]

method beforeFirst [line 202]

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




Tags:

access:  public


[ Top ]

method close [line 256]

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




Tags:

access:  public


[ Top ]

method first [line 186]

boolean first( )

Move cursor to beginning of recordset.



Tags:

return:  <tt>true</tt> on success or <tt>false</tt> if not found.
access:  public
throws:  SQLException - if unable to move to first position
  • if not at first pos & ResultSet doesn't support reverse scrolling


[ Top ]

method get [line 266]

mixed get( mixed $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.




Tags:

return:  Usually expect a string.
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.


Parameters:

mixed   $column   Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used) (if ResultSet::FETCHMODE_NUM was used).

[ Top ]

method getArray [line 276]

array getArray( mixed $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.




Tags:

return:  value or null if database returned null.
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.


Parameters:

mixed   $column   Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).

[ Top ]

method getBlob [line 294]

Blob getBlob( mixed $column)

Returns Blob with contents of column value.



Tags:

return:  New Blob with data from column or null if database returned null.
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.


Parameters:

mixed   $column   Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).

[ Top ]

method getBoolean [line 285]

boolean getBoolean( mixed $column)

Returns value translated to boolean.

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




Tags:

return:  value or null if database returned null.
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.


Parameters:

mixed   $column   Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).

[ Top ]

method getClob [line 303]

Clob getClob( mixed $column)

Returns Clob with contents of column value.



Tags:

return:  New Clob object with data from column or null if database returned null.
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.


Parameters:

mixed   $column   Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).

[ Top ]

method getCursorPos [line 235]

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




Tags:

access:  public


[ Top ]

method getDate [line 318]

mixed getDate( mixed $column, [string $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.




Tags:

return:  Formatted date, or integer unix timestamp (using 00:00:00 for time) if $format was null.
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.


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

[ Top ]

method getFetchmode [line 90]

int getFetchmode( )

Gets the fetchmode used to retrieve results.



Tags:

return:  ResultSet::FETCHMODE_NUM or ResultSet::FETCHMODE_ASSOC (default).
access:  public


[ Top ]

method getFloat [line 327]

float getFloat( mixed $column)

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



Tags:

return:  value or null if database returned null
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.


Parameters:

mixed   $column   Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).

[ Top ]

method getInt [line 337]

int getInt( mixed $column)

Returns value cast as integer.



Tags:

return:  value or null if database returned null
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.
see:  getInteger()


Parameters:

mixed   $column   Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).

[ Top ]

method getRecordCount [line 248]

int getRecordCount( )

Get the number of rows in a result set.



Tags:

return:  the number of rows
access:  public
throws:  SQLException - if unable to get a rowcount.


[ Top ]

method getResource [line 75]

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




Tags:

return:  Query result or NULL if not not applicable.
access:  public


[ Top ]

method getRow [line 241]

array getRow( )

Gets current fields (assoc array).



Tags:

access:  public


[ Top ]

method getString [line 347]

string getString( mixed $column)

Returns value cast as string.



Tags:

return:  value or null if database returned null
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.
see:  ResultSet::get()


Parameters:

mixed   $column   Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).

[ Top ]

method getTime [line 362]

mixed getTime( mixed $column, [string $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.




Tags:

return:  Formatted time, or integer unix timestamp (using today's date) if $format was null.
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.


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

[ Top ]

method getTimestamp [line 378]

mixed getTimestamp( mixed $column, [string $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.




Tags:

return:  Formatted timestamp, or integer unix timestamp (if $format was null)
access:  public
throws:  SQLException - If the column specified is not a valid key in current field array.


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

[ Top ]

method isAfterLast [line 220]

boolean isAfterLast( )

Checks whether cursor is after the last record.



Tags:

access:  public
throws:  SQLException on any driver-level error.


[ Top ]

method isBeforeFirst [line 227]

boolean isBeforeFirst( )

Checks whether cursor is before the first record.



Tags:

access:  public
throws:  SQLException on any driver-level error.


[ Top ]

method isIgnoreAssocCase [line 104]

boolean isIgnoreAssocCase( )

Whether assoc result keys get left alone -- as opposed to converted to lowercase.

If the case change stuff goes back to being more complicated (allowing conver to upper, e.g.) then we'll add new methods but this method will always indicate whether any case conversions should be (or have been) performed at all. This defaults to true unless Creole::NO_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).




Tags:

access:  public


[ Top ]

method last [line 194]

boolean last( )

Move cursor to end of recordset.



Tags:

return:  <tt>true</tt> on success or <tt>false</tt> if not found.
access:  public
throws:  SQLException - if unable to move to last position
  • if unable to get num rows


[ Top ]

method next [line 112]

boolean next( )

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



Tags:

return:  <tt>true</tt> if success, <tt>false</tt> if no next record.
access:  public
throws:  SQLException on any driver-level errors.


[ Top ]

method previous [line 122]

boolean previous( )

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



Tags:

return:  <tt>true</tt> if success, <tt>false</tt> if no previous record.
access:  public
throws:  SQLException - if unable to move to previous position
  • if ResultSet doesn't support reverse scrolling


[ Top ]

method relative [line 137]

boolean relative( integer $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.




Tags:

return:  <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
access:  public
throws:  SQLException - if unable to move to relative position
  • if rel pos is negative & ResultSet doesn't support reverse scrolling


Parameters:

integer   $offset  

[ Top ]

method seek [line 178]

boolean seek( int $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)).

<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 

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




Tags:

return:  true on success, false if unable to seek to specified record.
access:  public
throws:  SQLException if trying to seek backwards with a driver that doesn't support reverse-scrolling


Parameters:

int   $rownum   The cursor pos to seek to.

[ Top ]

method setFetchmode [line 84]

void setFetchmode( int $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).




Tags:

access:  public


Parameters:

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

[ Top ]

Class Constants

FETCHMODE_ASSOC =  1

[line 58]

Index result set by field name.


[ Top ]

FETCHMODE_NUM =  2

[line 63]

Index result set numerically.


[ Top ]


Documentation generated on Mon, 23 Aug 2004 21:52:59 -0400 by phpDocumentor 1.3.0RC3