Cursor Objects |
Active Web |
 |
|
Cursor Objects |
Active Web |
|
A Cursor object can not be created, it can only be obtained as the result of executing the cursor function on a Database object.
The Cursor object represents the results returned from executing the SQL select statement on the database.
Shown below is the Cursor object prototype chain.
Cursor objects are of class Cursor.
The cursor holds the result set returned by the database. This is in the form of a table with rows and columns. The Cursor only reveals the data one row at a time and the next() function is used to discard the current row and get the next row. To start with the Cursor does not have a current row and the next() function needs to be called before data is available.
The current row of data in the Cursor object is available as properties held by the cursor. These properties can be selected by using either the column name or the column index (note that the first column index is zero).
e.g.
myCursor.date - gets the data for the column called "date" in the current row.
myCursor[0] - gets the data for the first column in the current row.
|
Property |
Description |
|
prototype |
A reference to the Object Prototype. This property does not enumerate and can not be deleted but can be changed. |
|
[column name] |
The column data for the current row is a property of the cursor object and can be accessed by using the column name. |
|
[index] |
The column data for the current row is a property of the cursor object and can be accessed by using the column index. |
By default the Cursor range of rows, accessed by the next() function, is all the rows returned by the database starting at row zero (note that the first row index is zero). This range can be change by either the moveTo() or the setRange() functions.
The moveTo() function changes the current row to the row specified (if no row is specified then it moves to the end). The next() function will then carry on from the 'moved to' row. Note that the moveTo() function changes the current row to its target row so the next() function is not required to access this row.
The setRange() function changes the range of rows that the next() function will access. The setRange() function, unlike the moveTo() function, does not change the current row but makes its start row the next row that will be accessed by the next() function. When the next() function reaches the end of the range it will return false to indicate that there are no more rows. The range can be altered at any time, even after the end of a previous range has been reached, and will then affect the next next() function call.
The row data in the cursor is sequential, this means you can only move the current row forwards through the result set, it is not possible to go back to a previous row (if you need to access a previous row then you will need to get a new Cursor object). If the moveTo() function specifies a row before the current row it will have no affect. If the setRange() function specifies a range before the current row the next next() function call will return false.
|
Function |
Description |
|
close() |
Close the Cursor object and free all resources. |
|
columnCount() |
Return the number of columns in a result set. |
|
columnName(index) |
Return the column name for the column at the specified index. |
|
moveTo(row) |
Move to the specified row in the cursor. If the row argument is not supplied then move to the end of the cursor. Returns the number of the current row. You can not move backwards through the result set, attempting to move to a row before the current row has no affect. |
|
next() |
Set the next row from the result set as the current row. Return true if there are more rows, false if there are no more rows. |
|
setRange(start[, range]) |
Sets up the current range of rows for the cursor. The start is the first row that will be returned by the next function. The range is optional, if specified then it determines how many rows the cursor will return and if not specified the cursor returns rows up to the end of the result set. You can not move backwards through the result set, setting a range before the current row will cause the next function to return false. |
Topic ID: 150044