EDBDataCursor Class

The EDBDataCursor class descends from the EDBDataReader class, providing a bi-directional cursor that can be created using the ExecuteCursor method of the EDBCommand class. The EDBDataCursor class also supports in-place inserts, updates, and deletes, provided that the result set generated by the command is sensitive and not read-only, which are indicated by the Sensitive and ReadOnly properties of the EDBCommand class, respectively.

In addition, you can set an expression filter on the cursor using the Filter and Filtered properties, and search for a particular row in the cursor using the Locate method. Filter expressions can be any valid Boolean SQL expression that does not contain any sub-queries.

In addition to the normal Set* methods that use column indexes to set column data, there are also matching Set* methods that accept a column name instead of a column index. The only difference in the method parameters for these methods is the first parameter, which is a String instead of an Int32.

Namespace: Elevate.ElevateDB.Data

Inherits From Elevate.ElevateDB.Data.EDBDataReader

Constructors

All constructors are the same as the EDBDataReader class.

Properties

Property

Description

State: EDBDataCursorState Enumeration	Indicates the state of the cursor.
BOF: Boolean	Indicates whether the cursor is at the beginning of the set of rows that comprise the result set.
EOF: Boolean	Indicates whether the cursor is at the end of the set of rows that comprise the result set.
RowLocked: Boolean	Use this property to determine if the current row has been locked by the LockCurrentRow method. This method only includes manually-locked rows and will not indicate if a row is locked via the Update method when the current session's row lock protocol is set to lpPessimistic. Such row locks are considered implicit.
Filter: String	Use this property to specify a Boolean filter expression for limiting the view of the result set to only those rows that match the filter expression. Setting this property by itself does nothing. You must set the Filtered property in order to actually turn on or off the filtering.
Filtered: Boolean	Use this property turn on or off the filter specified by the Filter property.
RowCount: Integer	Indicates the number of rows present in the current view of the result set. If the result set is filtered via the Filter and Filtered properties, then this property will reflect only the count of the rows that satisfy the filter expression.

Methods

Method

Description

get_Filter: String	This is the accessor (getter) method for the Filter property.
set_Filter(Value: String)	This is the mutator (setter) method for the Filter property.
get_Filtered: Boolean	This is the accessor (getter) method for the Filtered property.
set_Filtered(Value: Boolean)	This is the mutator (setter) method for the Filtered property.
get_RowCount: Integer	This is the accessor (getter) method for the RowCount property.
ReadFirst: Boolean	Use this method to position the cursor on the first row in the result set and read it into the row buffer. If a filter is in effect on the result set, then this method will position the cursor on the first row that satisfies the filter expression. This method always sets the BOF property to True.
ReadLast: Boolean	Use this method to position the cursor on the last row in the result set and read it into the row buffer. If a filter is in effect on the result set, then this method will position the cursor on the last row that satisfies the filter expression. This method always sets the EOF property to True.
Read: Boolean	Use this method to position the cursor on the next row in the result set and read it into the row buffer. If a filter is in effect on the result set, then this method will position the cursor on the next row that satisfies the filter expression. If there are no more rows in the result set, then this method will set the EOF property to True and the existing row buffer will stay the same.
ReadPrevious: Boolean	Use this method to position the cursor on the previous row in the result set and read it into the row buffer. If a filter is in effect on the result set, then this method will position the cursor on the previous row that satisfies the filter expression. If there are no prior rows in the result set, then this method will set the BOF property to True and the existing row buffer will stay the same.
ReadCurrent: Boolean	Use this method to read the current row in the result set into the row buffer. If there are no rows in the result set, then this method will set the BOF and EOF properties to True and the row buffer will contain NULL values for all columns.
ReadRelative(Position: Integer): Boolean	Use this method to position the cursor on a specific row in relation to the current row in the result set and read it into the row buffer. If a filter is in effect on the result set, then this method will position the cursor on the specific row that satisfies the filter expression. The Position parameter can be either positive or negative. If it is positive, then the cursor will skip forward Position number of rows from the current row. If there are no more rows in the result set, then this method will set the EOF property to True and the existing row buffer will be populated with the last accessible row that was visited. If it is negative, then the cursor will skip backward Position number of rows from the current row. If there are no prior rows in the result set, then this method will set the BOF property to True and the existing row buffer will be populated with the last accessible row that was visited.
ReadAbsolute(Position: Integer): Boolean	Use this method to position the cursor on a specific row in the result set and read it into the row buffer. If a filter is in effect on the result set, then this method will position the cursor on the specific row that satisfies the filter expression. The Position parameter must be positive. If the Position is greater than the number of rows in the result set, then this method will set the EOF property to True and the existing row buffer will be populated with the last accessible row.
LockCurrentRow	Use this method to manually lock the current row. Row locks established via this method are persistent and are maintained across any Update or Delete method calls. You must manually unlock any rows locked using this method via the UnlockCurrentRow or UnlockAllRows methods. Any row locks established using this method are automatically unlocked when the cursor is closed.
UnlockCurrentRow	Use this method to unlock the current row. The current row must have been previously manually locked using the LockCurrentRow method or else an exception will be raised.
UnlockAllRows	Use this method to unlock all rows that have been manually locked using the LockCurrentRow method.
Insert	Use this method to put the cursor in an Inserting state. All column values in the row buffer will be set to their default value as defined for the source table used to generate the result set. To complete the insertion of a new row, use the Set* methods to assign new values to the columns in the row buffer, and then call the Post method. If there are any errors in the insert, they will occur during the Post method call, and one can use a try..catch/except block to handle any exceptions generated due to an error such as a constraint violation.
Update	Use this method to put the cursor in an Updating state. If the row locking protocol in use is the pessimistic protocol, then calling this method will cause a row lock to be placed on the current row in the result set. If the row locking protocol in use is the optimistic protocol, then calling this method will refresh the row buffer from the current row in the result set. Please see the EDBConnectionStringBuilder Class for information on setting the row lock protocol for the connection. To complete the update of the current row, use the Set* methods to assign new values to the columns in the row buffer, and then call the Post method. If there are any errors in the update, they will occur during the Post method call, and one can use a try..catch/except block to handle any exceptions generated due to an error such as a constraint violation. If the Post method succeeds, then any pessimistic row lock obtained during the Update method call will be released. If optimistic row locking is being used, then a row lock will be obtained and released all within the Post method call.
Post	Use this method to complete an insert or update by posting any changes to the row buffer into the result set. If the State of the cursor is Inserting, then calling this method will insert a new row into the result set. If the State of the cursor is Updating, then calling this method will update the current row in the result set.
Cancel	Use this method to cancel an insert or update, discarding any changes to the row buffer that have been made. If the State of the cursor is Updating and pessimistic locking is being used, then this method will release any row lock that was obtained during the prior Update call.
Delete	Use this method to delete the current row from the result set.
Locate(const Columns: array of String; const Values: ObjectArray; PartialLength: Integer; CaseInsensitive: Boolean): Boolean Locate(const Column: String; const Value: Object; PartialLength: Integer; CaseInsensitive: Boolean): Boolean	Use this method to locate a specific row in the result set. Specify the columns to search using the Columns array parameter and the Values to search for in the Values array parameter. You can specify a partial length for the last string value in the Values parameter via the PartialLength parameter. If you don't want a partial-length match on the last value in the Values parameter, then simply specify 0 for th PartialLength parameter. If you want the search to be case-insensitive, then specify true/True for the CaseInsensitive parameter. The Locate method will respect any filter that may be present on the result set.
SetValue(Index: Int32; Value: System.Object)	Use this method to set a column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetValues(Values: ObjectArray): Int32	Use this method to set multiple column values in the row buffer in one call. The values are assigned starting from the first column to the last column that corresponds to the length of the Values parameter.
SetBoolean(Index: Int32; Value: Boolean)	Use this method to set a Boolean column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetByte(Index: Int32; Value: System.Byte)	This method is not supported by ElevateDB, but is included for compatibility with other cursor classes for .Net.
SetBytes(Index: Int32; Offset: Int64; Buffer: array of System.Byte; BufferOffset: Int32; Length: Int32) SetBytes(Index: Int32; SourceStream: Stream): Int64 SetBytes(Index: Int32; const SourceFileName: String): Int64	Use these methods to set a CHAR/VARCHAR, BYTES/VARBYTES, CLOB, or BLOB column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetImage(Index: Int32; SourceImage: Bitmap; SourceFormat: ImageFormat)	Use this method to save a bitmap to a BLOB column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetChar(Index: Int32; Value: System.Char)	This method is not supported by ElevateDB, but is included for compatibility with other cursor classes for .Net.
SetChars(Index: Int32; Offset: Int64; Buffer: array of System.Char; BufferOffset: Int32; Length: Int32)	Use this method to set a specific range of characters for a CLOB or character (CHAR/VARCHAR) column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetGuid(Index: Int32; Value: System.Guid)	Use this method to set a GUID column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetInt16(Index: Int32; Value: Int16)	Use this method to set a signed 16-bit integer column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetInt32(Index: Int32; Value: Int32)	Use this method to set a signed 32-bit integer column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetInt64(Index: Int32; Value: Int64)	Use this method to set a signed 64-bit integer column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetFloat(Index: Int32; Value: Single)	This method is not supported by ElevateDB, but is included for compatibility with other cursor classes for .Net.
SetDouble(Index: Int32; Value: System.Double)	Use this method to set a double-precision floating-point column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetString(Index: Int32; Value: String)	Use this method to set a string column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetDecimal(Index: Int32; Value: System.Decimal)	Use this method to set a decimal column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.
SetDateTime(Index: Int32; Value: System.DateTime)	Use this method to set a date/time column value in the row buffer. The column is specified via the Index parameter (0-based), and the cursor must be in the Inserting or Updating state.

Events

Event

Description

OnStateChange: EDBDataCursorStateChangeEvent	Setting this event adds an event handler to the list of event handlers listening for the OnStateChange event for the cursor. The arguments for the event handler are defined in the EDBCursorStateChangeEvent class. The OnStateChange event is used to respond to any change in the cursor's State property.
OnMove: EDBDataCursorMoveEvent	Setting this event adds an event handler to the list of event handlers listening for the OnMove event for the cursor. The arguments for the event handler are defined in the EDBCursorMoveEvent class. The OnMove event is used to respond to any movement in the cursor due to calls to the ReadFirst, ReadLast, Read, ReadPrevious, ReadRelative, ReadAbsolute, or Locate methods.

More Support Options

Support Forums

Frequently Asked Questions

Technical Bulletins

Technical Articles

Incident Reports

Roadmap