Cursor Instance PropertiesCursor object
platform: Win32; all versions of SE
source: #link <sedbc>
A Cursor object represents a database cursor for a specified SQL SELECT statement or specified database table.
A Cursor is a structure, created from a database table, which represents a subset of that table. When performing a query on a database, the results of the query are returned as a Cursor.
A Cursor object can be used to perform the following operations:
•
Modify data in a database table.
•
Navigate in a database table.
•
Customize the display of the virtual table returned by a database query.
A Cursor object can be constructed in the following manners:
•
The cursor method of a database object.
•
The table method of a database object.
•
The cursor method of an Stproc object.
There is no need to call a Cursor constructor.
A Cursor object has the notion of a "current" row. When operations are performed on a Cursor, they usually affect this row. The current row can be moved forward and backward through a Cursor using the next and previous methods, respectively. Similarly, the first and last methods set the current row to the first or last row in the cursor. Each of these methods will return false if the desired row does not exist within the Cursor. Thus, if the Cursor does not have any rows in it (perhaps because the SELECT statement used to create the cursor did not return any results), each of these methods will return false. Don't forget to check for this condition!
Important - A Cursor does not guarantee the order or positioning of its rows. For example, if a row is added to a Cursor, there is no way of knowing where that row will actually appear within in the cursor. Thus, do not make any assumptions about the ordering of rows within the Cursor. When finished with a Cursor object, use the close method to close it and release the memory it uses. If a database connection that has an open Cursor is released, the runtime engine waits until that Cursor is closed before actually releasing the connection to the database, so it is important to remember to close Cursors. If a Cursor has not been not explicitly closed using the close method by the time the associated Database or DbPool object goes out of scope, the runtime engine will try to close it. This may tie up system resources unnecessarily and/or lead to unpredictable results. Use the prototype property of the Cursor class to add a property to all Cursor instances. The addition applies to all Cursor instances running in all applications on the server, not just the application that made the change. This allows the capabilities of the object to be expanded for the entire server.