TDataSetState describes the current state of the dataset. During it's lifetime, the dataset's state is described by these enumerated values.

Some state are not used in the default TDataset implementation, and are only used by certain descendents.

TField is an abstract class that defines access methods for a field in a record, controlled by a instance. It provides methods and properties to access the contents of the field in the current record. Reading one of the AsXXX properties of TField will access the field contents and return the contents as the desired type. Writing one of the AsXXX properties will write a value to the buffer represented by the TField instance.

TField is an abstract class, meaning that it should never be created directly. TDataset instances always create one of the descendent classes of TField, depending on the type of the underlying data.

TDataset is the main class of the db unit. This abstract class provides all basic funtionality to access data stored in tabular format: The data consists of records, and the data in each record is organised in several fields.

TDataset has a buffer to cache a few records in memory, this buffer is used by TDatasource to create the ability to use data-aware components.

TDataset is an abstract class, which provides the basic functionality to access, navigate through the data and - in case read-write access is available, edit existing or add new records.

TDataset is an abstract class: it does not have the knowledge to store or load the records from whatever medium the records are stored on. Descendants add the functionality to load and save the data. Therefor TDataset is never used directly, one always instantiates a descendent class.

Initially, no data is available: the dataset is inactive. The Open method must be used to fetch data into memory. After this command, the data is available in memory for browsing or editing purposes: The dataset is active (indicated by the property). Likewise, the Close method can be used to remove the data from memory. Any changes not yet saved to the underlying medium will be lost.

Data is expected to be in tabular format, where each row represents a record. The dataset has an idea of a cursor: this is the current position of the data cursor in the set of rows. Only the data of the current record is available for display or editing purposes. Through the Next, Prev, First and Last methods, it is possible to navigate through the records. The EOF property will be True if the last row has been reached. Likewise, the BOF property will return True if the first record in the dataset has been rechaed when navigating backwards. If both proprties are empty, then there is no data available. For dataset descendents that support counting the number of records, the RecordCount will be zero.

The Append and Insert methods can be used to insert new records to the set of records. The statement is used to delete the current record, and the Edit command must be used to set the dataset in editing mode: the contents of the current record can then be changed. Any changes made to the current record (be it a new or existing record) must be saved by the Post method, or can be undone using the Cancel method.

The data in the various fields properties is available through the Fields array property, giving indexed access to all the fields in a record. The contents of a field is always readable. If the dataset is in one of the editing modes, then the fields can also be written to.

TDatabase is a component whose purpose is to provide a connection to an external database engine, not to provide the database itself. This class provides generic methods for attachment to databases and querying their contents; the details of the actual connection are handled by database-specific components (such as SQLDb for SQL-based databases, or DBA for DBASE/FoxPro style databases).

Like , TDatabase is an abstract class. It provides methods to keep track of datasets connected to the database, and to close these datasets when the connection to the database is closed. To this end, it introduces a Connected boolean property, which indicates whether a connection to the database is established or not. The actual logic to establish a connection to a database must be implemented by descendent classes.

Create is the constructor for the TFieldDef class.

If a simple call is used, with a single argument ACollection, the inherited Create is called and the Field number is set to the incremented current index.

If the more complicated call is used, with multiple arguments, then after the inherited Create call, the Name, datatype, size, precision, FieldNo and the Required property are all set according to the passsed arguments.

CreateField determines, based on the DataType what descendent it should create, and then returns a newly created instance of this class. It sets the appropriate defaults for the Size, FieldName, FieldNo, Precision, ReadOnly and Required properties of the newly created instance. It should nver be necessary to use this call in an end-user program, only TDataset descendent classes should use this call.

The newly created field is owned by the component instance passed in the AOwner parameter.

The array is used to determine which TField Descendent class should be used when creating the TField instance, but descendents of TDataset may override the values in that array.

AssignValue assigns the value of a "array of const" record AValue (of type TVarRec) to the field's value. If the record contains a TPersistent instance, it will be used as argument for the Assign to the field.

The dataset must be in edit mode to execute this method.

Clear clears the contents of the field. After calling this method the value of the field is Null and IsNull returns True.

The dataset must be in edit mode to execute this method.

IsValidChar checks whether InputChar is a valid characters for the current field. It does this by checking whether InputChar is in the set of characters sepcified by the property. The ValidChars property will be initialized to a correct set of characters by descendent classes. For instance, a numerical field will only accept numerical characters and the sign and decimal separator characters.

Descendent classes can override this method to provide custom checks. The ValidChars property can be set to restrict the list of valid characters to a subset of what would normally be available.

SetData saves the value of the field data in Buffer to the dataset internal buffer. The Buffer pointer should point to a memory buffer containing the data for the field in the correct format. If the NativeFormat parameter is true, then date/time formats should use the TDateTime format.

There should normally not be any need to call SetData directly: it is called by the various setter methods of the AsXXX properties of TField.

AsLongint can be used to read or write the contents of the field as a 32-bit signed integer value (of type longint). If the native type of the field is not a longint value, then an attempt will be made to convert the field value from the native format to a longint value when reading the field's content. Likewise, when writing the property, the value will be converted to the native type of the field (if the value allows it). Therefor, when reading or writing a field value for a field whose native data type is not a 32-bit signed integer-compatible value (string values for instance), an exception may be raised.

This is an alias for the .

DisplayName is the name of the field as it will be displayed to the user e.g. in grid column headers. By default it equals the FieldName property, unless assigned another value.

The use of this property is deprecated. Use DisplayLabel instead.

Value can be used to read or write the value of the field as a Variant value. When setting the value, the value will be converted to the actual type of the field as defined in the underlying data. Likewise, when reading the value property, the actual field value will be converted to a variant value. If the field does not contain a value (when IsNull returns True), then Value will contain Null.

It is not recommended to use the Value property: it should only be used when the type of the field is unknown. If the type of the field is known, it is better to use one of the AsXXX properties, which will not only result in faster code, but will also avoid strange type conversions.

CustomConstraint may contain a constraint that will be enforced when the dataset posts it's data. It should be a SQL-like expression that results in a True or False value. Examples of valid constraints are:

Salary < 10000
YearsEducation < Age

If the constraint is not satisfied when the record is posted, then an exception will be raised with the value of ConstraintErrorMessage as a message.

This feature is not yet implemented in FPC.

ConstraintErrorMessage is the message that should be displayed when the dataset checks the constraints and the constraint in is violated.

This feature is not yet implemented in FPC.

DefaultValue can be set to a value that should be entered in the field whenever the or methods are executed. It should contain a valid SQL expression that results in the correct type for the field.

This feature is not yet implemented in FPC.

DisplayLabel is the name of the field as it will be displayed to the user e.g. in grid column headers. By default it equals the FieldName property, unless assigned another value.

ProviderFlags contains a set of flags that can be used by engines that automatically generate update SQL statements or update data packets. The various items in the set tell the engine whether the key is a key field, should be used in the where clause of an update statement or whether - in fact - it should be updated at all.

These properties should be set by the programmer so engines such as SQLDB can create correct update SQL statements whenever they need to post changes to the database. Note that to be able to set these properties in a designer, persistent fields must be created.

TNumericField is an abstract class which overrides some of the methods of to handle numerical data. It also introduces or publishes a couple of properties that are only relevant in the case of numerical data, such as and .

Since TNumericField is an abstract class, it must never be instantiated directly. Instead one of the descendent classes should be created.

TLongintField is instantiated when a dataset must manage a field with 32-bit signed data: the data type ftInteger. It overrides some methods of to handle integer data, and sets some of the properties to values for integer data. It also introduces some methods and properties specific to integer data such as MinValue and MaxValue.

It should never be necessary to create an instance of TLongintField manually, a field of this class will be instantiated automatically for each integer field when a dataset is opened.

TLargeIntField is instantiated when a dataset must manage a field with 64-bit signed data: the data type ftLargeInt. It overrides some methods of to handle int64 data, and sets some of the properties to values for int64 data. It also introduces some methods and properties specific to 64-bit integer data such as MinValue and MaxValue.

It should never be necessary to create an instance of TLargeIntField manually, a field of this class will be instantiated automatically for each int64 field when a dataset is opened.

MaxValue is the maximum value for the field if set to any value different from zero. When setting the field's value, the value may not be larger than MaxValue. Any attempt to write a larger value as the field's content will result in an exception. By default MaxValue equals 0, i.e. any integer value is allowed.

If MaxValue is set, MinValue should also be set, because it will also be checked.

MinValue is the minimum value for the field. When setting the field's value, the value may not be less than MinValue. Any attempt to write a smaller value as the field's content will result in an exception. By default MinValue equals 0, i.e. any integer value is allowed.

If MinValue is set, MaxValue should also be set, because it will also be checked.

TSmallIntField is the class created when a dataset must manage 16-bit signed integer data, of datatype ftSmallInt. It exposes no new properties, but simply overrides some methods to manage 16-bit signed integer data.

It should never be necessary to create an instance of TSmallIntField manually, a field of this class will be instantiated automatically for each smallint field when a dataset is opened.

TWordField is the class created when a dataset must manage 16-bit unsigned integer data, of datatype ftWord. It exposes no new properties, but simply overrides some methods to manage 16-bit unsigned integer data.

It should never be necessary to create an instance of TWordField manually, a field of this class will be instantiated automatically for each word field when a dataset is opened.

TAutoIncField is the class created when a dataset must manage 32-bit signed integer data, of datatype ftAutoInc: This field gets it's data automatically by the database engine. It exposes no new properties, but simply overrides some methods to manage 32-bit signed integer data.

It should never be necessary to create an instance of TAutoIncField manually, a field of this class will be instantiated automatically for each auto-incremental field when a dataset is opened.

TFloatField is the class created when a dataset must manage floating point values of double precision. It exposes a few new properties such as Currency, MaxValue, MinValue and overrides some methods to work with floating point data.

It should never be necessary to create an instance of TFloatField manually, a field of this class will be instantiated automatically for each floating-point field when a dataset is opened.

MaxValue can be set to a value different from zero, it is then the maximum value for the field if set to any value different from zero. When setting the field's value, the value may not be larger than MaxValue. Any attempt to write a larger value as the field's content will result in an exception. By default MaxValue equals 0, i.e. any floating-point value is allowed.

If MaxValue is set, MinValue should also be set, because it will also be checked.

MinValue can be set to a value different from zero, then it is the minimum value for the field. When setting the field's value, the value may not be less than MinValue. Any attempt to write a smaller value as the field's content will result in an exception. By default MinValue equals 0, i.e. any floating-point value is allowed.

If MinValue is set, MaxValue should also be set, because it will also be checked.

TCurrencyField is the field class used by when it needs to manage currency-valued data.( equals ftCurrency). It simply sets some properties to be able to work with currency data.

It should never be necessary to create an instance of TCurrencyField manually, a field of this class will be instantiated automatically for each currency field when a dataset is opened.

TBooleanField is the field class used by whenever it needs to manage boolean data ( equals ftBoolean). It overrides some properties and methods of to be able to work with boolean data.

It should never be necessary to create an instance of TBooleanField manually, a field of this class will be instantiated automatically for each boolean field when a dataset is opened.

DisplayValues contains 2 strings, separated by a semicolon (;) which are used to display the True and False values of the fields. The first string is used for True values, the second value is used for False values. If only one value is given, it will serve as the representation of the True value, the False value will be represented as an empty string.

A value of Yes;No will result in True values being displayed as 'Yes', and False values as 'No'. When writing the value of the field as a string, the string will be compared (case insensitively) with the value for True, and if it matches, the field's value will be set to True. After this it will be compared to the value for False, and if it matches, the field's value will be set to False. If the text matches neither of the two values, an exception will be raised.

TDateTimeField is the class used when a dataset must manage data of type datetime. ( equals ftDateTime). It also serves as base class for the or classes. It overrides some of the properties and methods of the class to be able to work with date/time fields.

It should never be necessary to create an instance of TDateTimeField manually, a field of this class will be instantiated automatically for each datetime field when a dataset is opened.

TDateField is the class used when a dataset must manage data of type date. ( equals ftDate). It initializes some of the properties of the class to be able to work with date fields.

It should never be necessary to create an instance of TDateField manually, a field of this class will be instantiated automatically for each date field when a dataset is opened.

TimeField is the class used when a dataset must manage data of type time. ( equals ftTime). It initializes some of the properties of the class to be able to work with time fields.

It should never be necessary to create an instance of TTimeField manually, a field of this class will be instantiated automatically for each time field when a dataset is opened.

TBinaryField is an abstract class, designed to handle binary data of variable size. It overrides some of the properties and methods of the class to be able to work with binary field data, such as retrieving the contents as a string or as a variant.

One must never create an instance of TBinaryField manually, it is an abstract class. Instead, a descendent class such as or should be created.

TBytesField is the class used when a dataset must manage data of fixed-size binary type. ( equals ftBytes). It initializes some of the properties of the class to be able to work with fixed-size byte fields.

It should never be necessary to create an instance of TBytesField manually, a field of this class will be instantiated automatically for each binary data field when a dataset is opened.

TVarBytesField is the class used when a dataset must manage data of variable-size binary type. ( equals ftVarBytes). It initializes some of the properties of the class to be able to work with variable-size byte fields.

It should never be necessary to create an instance of TVarBytesField manually, a field of this class will be instantiated automatically for each variable-sized binary data field when a dataset is opened.

TBCDField is the class used when a dataset must manage data of Binary Coded Decimal type. ( equals ftBCD). It initializes some of the properties of the class, and overrides some of its methods to be able to work with BCD fields.

TBCDField assumes that the field's contents can be stored in a currency type, i.e. the maximum number of decimals after the decimal separator that can be stored in a TBCDField is 4. Fields that need to store a larger amount of decimals should be represented by a instance.

It should never be necessary to create an instance of TBCDField manually, a field of this class will be instantiated automatically for each BCD field when a dataset is opened.

MaxValue can be set to a value different from zero, it is then the maximum value for the field if set to any value different from zero. When setting the field's value, the value may not be larger than MaxValue. Any attempt to write a larger value as the field's content will result in an exception. By default MaxValue equals 0, i.e. any floating-point value is allowed.

If MaxValue is set, MinValue should also be set, because it will also be checked.

MinValue can be set to a value different from zero, then it is the minimum value for the field. When setting the field's value, the value may not be less than MinValue. Any attempt to write a smaller value as the field's content will result in an exception. By default MinValue equals 0, i.e. any floating-point value is allowed.

If MinValue is set, should also be set, because it will also be checked.

TBLobField is the class used when a dataset must manage BLOB data. ( equals ftBLOB). It initializes some of the properties of the class, and overrides some of its methods to be able to work with BLOB fields. It also serves as parent class for some specialized blob-like field types such as , or

It should never be necessary to create an instance of TBlobField manually, a field of this class will be instantiated automatically for each BLOB field when a dataset is opened.

TMemoField is the class used when a dataset must manage memo (Text BLOB) data. ( equals ftMemo). It initializes some of the properties of the class. All methods to be able to work with memo fields have been implemented in the parent class.

It should never be necessary to create an instance of TMemoField manually, a field of this class will be instantiated automatically for each memo field when a dataset is opened.

TWideMemoField is the class used when a dataset must manage memo (Text BLOB) data. ( equals ftWideMemo). It initializes some of the properties of the class. All methods to be able to work with widestring memo fields have been implemented in the parent class.

It should never be necessary to create an instance of TWideMemoField manually, a field of this class will be instantiated automatically for each widestring memo field when a dataset is opened.

TGraphicField is the class used when a dataset must manage graphical BLOB data. ( equals ftGraphic). It initializes some of the properties of the class. All methods to be able to work with graphical BLOB data have been implemented in the parent class.

It should never be necessary to create an instance of TGraphicsField manually, a field of this class will be instantiated automatically for each graphical BLOB field when a dataset is opened.

TVariantField is the class used when a dataset must manage native variant-typed data. ( equals ftVariant). It initializes some of the properties of the class and overrides some of its methods to be able to work with variant data.

It should never be necessary to create an instance of TVariantField manually, a field of this class will be instantiated automatically for each variant field when a dataset is opened.

TGUIDField is the class used when a dataset must manage native variant-typed data. ( equals ftGUID). It initializes some of the properties of the class and overrides some of its methods to be able to work with variant data. It also adds a method to retrieve the field value as a native TGUID type.

It should never be necessary to create an instance of TGUIDField manually, a field of this class will be instantiated automatically for each GUID field when a dataset is opened.

Fields is a list of fieldnames, separated by semicolons: the fields that make up the index, in case the index is not based on an expression. The list contains the names of all fields, regardless of whether the sort order for a particular field is ascending or descending. The fields should be in the right order, i.e. the first field is sorted on first, and so on.

The property can be used to determine the fields in the list that have a descending sort order. The property determines which fields are sorted in a case-insensitive manner.

Options describes the various properties of the index. This is usually filled by the dataset that provides the index definitions. For datasets that provide In-memory indexes, this should be set prior to creating the index: it cannot be changed once the index is created.

See the description of for more information on the various available options.

TLocateOption is used in the call to enumerate the possible options available when locating a record in the dataset.

For string-type fields, this option indicates that fields starting with the search value are considered a match. For other fields (e.g. integer, date/time), this option is ignored and only equal field values are considered a match.

Cancel cancels the current editing operation and sets the dataset again in browse mode. This operation triggers the and events. If the dataset wa sin insert mode, then the and events are triggered after and respectively before the OnBeforeCancel and OnAfterCancel events.

If the dataset was not in one of the editing modes when Cancel is called, then nothing will happen.

DataConvert converts the data from field AField in buffer ASource to native format and puts the result in ADest. If the aToNative parameter equals False, then the data is converted from native format to non-native format. Currently, only date/time/datetime and BCD fields are converted from/to native data. This means the routine handles conversion between TDateTime (the native format) and TDateTimeRec, and between TBCD and currency (the native format) for BCD fields.

DataConvert is used internally by TDataset and descendent classes. There should be no need to use this routine in application code.

DisableControls tells the dataset to stop sending data-related events to the controls. This can be used before starting operations that will cause the current record to change a lot, or before any other lengthy operation that may cause a lot of events to be sent to the controls that show data from the dataset: each event will cause the control to update itself, which is a time-consuming operation that may also cause a lot of flicker on the screen.

The sending of events to the controls can be re-enabled with . Note that for each call to DisableControls, a matching call to EnableControls must be made: an internal count is kept and only when the count reaches zero, the controls are again notified of changes to the dataset. It is therefore essential that the call to EnableControls is put in a Finally block:

EnableControls tells the dataset to resume sending data-related events to the controls. This must be used after a call to to re-enable updating of controls.

Note that for each call to DisableControls, a matching call to EnableControls must be made: an internal count is kept and only when the count reaches zero, the controls are again notified of changes to the dataset. It is therefore essential that the call to EnableControls is put in a Finally block:

FindFirst positions the cursor on the first record (taking into account filtering), and returns True if the cursor position was changed. This method must be implemented by descendents of TDataset: The implementation in TDataset always returns False, indicating that the position was not changed.

This method is deprecated, use instead.

FindLast positions the cursor on the last record (taking into account filtering), and returns True if the cursor position was changed. This method must be implemented by descendents of TDataset: The implementation in TDataset always returns False, indicating that the position was not changed.

This method is deprecated, use instead.

FindLast positions the cursor on the next record (taking into account filtering), and returns True if the cursor position was changed. This method must be implemented by descendents of TDataset: The implementation in TDataset always returns False, indicating that the position was not changed.

This method is deprecated, use instead.

FindPrior positions the cursor on the previous record (taking into account filtering), and returns True if the cursor position was changed. This method must be implemented by descendents of TDataset: The implementation in TDataset always returns False, indicating that the position was not changed.

This method is deprecated, use instead.

GetBookmark gets a bookmark pointer to the current cursor location. The call can be used to return to the current record in the dataset. After use, the bookmark must be disposed of with the call. The bookmark will be Nil if the dataset is empty or not active.

This call is deprecated. Use the property instead to get a bookmark.

GotoBookmark positions the dataset to the bookmark position indicated by ABookMark. ABookmark is a bookmark obtained by the function.

This function is deprecated, use the property instead.

Last puts the cursor at the last record in the dataset, fetching more records from the underlying database if needed. It is equivalent to moving to the last record and calling . After a call to Last, the property will be True.

Calling this method will trigger the and events.

Locate attempts to locate a record in the dataset. There are 2 possible cases when using Locate.

1. Keyvalues is a single value. In that case, KeyFields is the name of the field whose value must be matched to the value in KeyValues
2. Keyvalues is a variant array. In that case, KeyFields must contain a list of names of fields (separated by semicolons) whose values must be matched to the values in the KeyValues array

The matching always happens according to the Options parameter. For a description of the possible values, see .

If a record is found that matches the criteria, then the locate operation positions the cursor on this record, and returns True. If no record is found to match the criteria, False is returned, and the position of the cursor is unchanged.

The implementation in TDataset always returns False. It is up to TDataset descendents to implement this method and return an appropriate value.

Open must be used to make the TDataset Active. It does nothing if the dataset is already active. Open initialises the TDataset and brings the dataset in a browsable state:

Effectively the following happens:

1. The BeforeOpen event is triggered.
2. The descendents InternalOpen method is called to actually fetch data and initialize fielddefs and field instances.
3. BOFis set to True
4. Internal buffers are allocated and filled with data
5. If the dataset is empty, EOF is set to true
6. State is set to dsBrowse
7. The AfterOpen event is triggered

Bookmark can be read to obtain a bookmark to the current position in the dataset. The obtained value can be used to return to current position at a later stage. Writing the Bookmark property with a value previously obtained like this, will reposition the dataset on the same position as it was when the property was read.

This is often used when scanning all records, like this:

At the end of this code, the dataset will be positioned on the same record as when the code was started. The and calls prevent the controls from receiving update notifications as the dataset scrolls through the records, tus recuding flicker on the screen.

Note that bookmarks become invalid as soon as the dataset closes. A call to refresh may also destroy the bookmarks.

DefaultFields is True if the fields were generated dynamically when the dataset was opened. If it is False then the field instances are persistent, i;e. they were created at desin time with the fields editor. If DefaultFields is True, then for each item in the property, a field instance is created. These fields instances are freed again when the dataset is closed.

If DefaultFields is False, then there may be less field instances than there are items in the FieldDefs property. This can be the case for instance when opening a DBF file at runtime which has more fields than the file used at design time.

EOF is True if the cursor is on the last record in the dataset, and no more records are available. It is also True for an empty dataset. The EOF property will be set to True in the following cases:

1. The cursor is on the last record, and the method is called.
2. The method is called (which is equivalent to moving to the last record and calling ).
3. The dataset is empty when opened.

In all other cases, EOF is False. Note: when the cursor is on the last-but-one record, and Next is called (moving the cursor to the last record), EOF will not yet be True. Only if both the cursor is on the last record and Next is called, will EOF become True.

This means that the following loop will stop after the last record was visited:

IsUniDirectional is True if the dataset is unidirectional. By default it is False, i.e. scrolling backwards is allowed. If the dataset is unidirectional, then any attempt to scroll backwards (using one of or ), random positioning of the cursor, editing or filtering will result in an . Unidirectional datasets are also not suitable for display in a grid, as they have only 1 record in memory at any given time: they are only useful for performing an action on all records:

RecordCount is the number of records in the dataset. This number is not necessarily equal to the number of records returned by a query. For optimization purposes, a TDataset descendent may choose not to fetch all records from the database when the dataset is opened. If this is the case, then the RecordCount will only reflect the number of records that have actually been fetched at the current time, and therefor the value will change as more records are fetched from the database.

Only when Last has been called (and the dataset has been forced to fetch all records returned by the database), will the value of RecordCount be equal to the number of records returned by the query.

In general, datasets based on in-memory data or flat files, will return the correct number of records in RecordCount.

RecNo returns the current position in the dataset. It can be written to set the cursor to the indicated position. This property must be implemented by TDataset descendents, for TDataset the property always returns -1.

This property should not be used if exact positioning is required. it is inherently unreliable.

State determines the current operational state of the dataset. During it's lifetime, the dataset is in one of many states, depending on which operation is currently in progress:

• If a dataset is closed, the State is dsInactive.
• As soon as it is opened, it is in dsBrowse mode, and remains in this state while changing the cursor position.
• If the Edit or Insert or Append methods is called, the State changes to dsEdit or dsInsert, respectively.
• As soon as edits have been posted or cancelled, the state is again dsBrowse.
• Closing the dataset sets the state again to dsInactive.

There are some other states, mainly connected to internal operations, but which can become visible in some of the dataset's events.

FieldValues provides array-like access to the values of the fields, based on the names of the fields. The value is read or written as a variant type. It is equivalent to the following:

It can be read as well as written.

Filter is not implemented by TDataset. It is up to descendent classes to implement actual filtering: the filtering happens on in-memory data, and is not applied on the database level. (in particular: setting the filter property will in no way influence the WHERE clause of an SQL-based dataset).

In general, the filter property accepts a SQL-like syntax usually encountered in the WHERE clause of an SQL SELECT statement.

The filter is only applied if the Filtered property is set to True. If the Filtered property is False, the Filter property is ignored.

AutoCalcFields is by default true, meaning that the values of calculated fields will be computed in the following cases:

• When the dataset is opened
• When the dataset is put in edit mode
• When a data field changed

When AutoCalcFields is False, then the calculated fields are called whenever

• The dataset is opened
• The dataset is put in edit mode

Both proper calculated fields and lookup fields are computed. Calculated fields are computed through the event.

OnDeleteError is triggered when the method fails to delete the record in the underlying database. The event handler can be used to indicate what the response to the failed delete should be. To this end, it gets the exception object passed to it (parameter E), and it can examine this object to return an appropriate action in the DataAction parameter. The following responses are supported:

daFail

daAbort

daRetry

For more information, see also the description of the event handler type.

OnEditError is triggered when the method fails to put the dataset in edit mode because the underlying database engine reported an error. The event handler can be used to indicate what the response to the failed edit operation should be. To this end, it gets the exception object passed to it (parameter E), and it can examine this object to return an appropriate action in the DataAction parameter. The following responses are supported:

daFail

daAbort

daRetry

For more information, see also the description of the event handler type.

OnPostError is triggered when the method fails to post the changes in the dataset buffer to the underlying database, because the database engine reported an error. The event handler can be used to indicate what the response to the failed post operation should be. To this end, it gets the exception object passed to it (parameter E), and it can examine this object to return an appropriate action in the DataAction parameter. The following responses are supported:

daFail

daAbort

daRetry

For more information, see also the description of the event handler type.

TDataLink is used by GUI controls or datasets in a master-detail relationship to handle data events coming from a instance. It is a class that exists for component programmers, application coders should never need to use TDataLink or one of it's descendents.

DB-Aware Component coders must use a TDatalink instance to handle all communication with a instance, rather than communicating directly with the dataset. TDataLink contains methods which are called by the various events triggered by the dataset. Inversely, it has some methods to trigger actions in the dataset.

TDatalink is an abstract class; it is never used directly. Instead, a descendent class is used which overrides the various methods that are called in response to the events triggered by the dataset. Examples are .

TMasterDataLink is a TDatalink descendent which handles master-detail relations. It can be used in descendents that must have master-detail functionality: the detail dataset creates an instance of TMasterDataLink to point to the master dataset, which is subsequently available through the property.

The class also provides functionailty for keeping a list of fields that make up the master-detail functionality, in the and properties.

This class should never be used in application code.

TDBDataset is a TDataset descendent which introduces the concept of a database: a central component () which represents a connection to a database. This central component is exposed in the property. When the database is no longer connected, or is no longer in memory, all TDBDataset instances connected to it are disabled.

TDBDataset also introduces the notion of a transaction, exposed in the Transaction property.

TDBDataset is an abstract class, it should never be used directly.

Dataset component writers should descend their component from TDBDataset if they wish to introduce a central database connection component. The database connection logic will be handled automatically by TDBDataset.

Database should be set to the instance this dataset is connected to. It can only be set when the dataset is closed.

Descendent classes should check in the property setter whether the database instance is of the correct class.

Transaction points to a component that represents the transaction this dataset is active in. This property should only be used for databases that support transactions.

The property can only be set when the dataset is disabled.

Close closes the connection with the server if it was connected. Calling this method first triggers the BeforeDisconnect event. If an exception is raised during the execution of that event handler, the disconnect process is aborted. After calling this event, the connection is actually closed. After the connection was closed, the AfterDisconnect event is triggered.

Calling the Close method is equivalent to setting the Connected property to False.

If ForceClose is True then the descendent should ignore errors from the underlying connection, allowing all datasets to be closed properly.

Open establishes the connection with the server if it was not yet connected. Calling this method first triggers the BeforeConnect event. If an exception is raised during the execution of that event handler, the connect process is aborted. If LoginPrompt is True, the OnLogin event handler is called. Only after this event, the connection is actually established. After the connection was established, the AfterConnect event is triggered.

Calling the Open method is equivalent to setting the Connected property to True.

TParamType indicates the kind of parameter represented by a instance. it has one of the following values:

ptUnknown

ptInput

ptOutput

ptInputOutput

ptResult

TParamStyle denotes the style in which parameters are specified in a query. It is used in the method, and can have the following values:

psInterbase

psPostgreSQL

psSimulated

TParams is a collection of values. It is used to specify parameter values for parametrized SQL statemens, but is also used to specify parameter values for stored procedures. Its default property is an array of values. The class also offers a method to scan a SQL statement for parameter names and replace them with placeholders understood by the SQL engine: .

itself does not use TParams. The class is provided in the DB unit, so all TDataset descendents that need some kind of parametrization make use of the same interface. The class can be used to establish a master-detail relationship between a parameter-aware TDataset instance and another dataset; it will automatically refresh parameter values when the fields in the master dataset change. To this end, the method exists.

ParamTyp specifies the type of parameter: is the parameter value written to the database engine, or is it received from the database engine, or both ? It can have the following value:

ptUnknown

ptInput

ptOutput

ptInputOutput

ptResult

The ParamType property is usually set by the database engine that creates the parameter instances.

FindParam searches the collection for the instance with property Name equal to Value. It will return the last instance with the given name, and will only return one instance. If no match is found, Nil is returned.

ParamByName searches the collection for the instance with property Name equal to Value. It will return the last instance with the given name, and will only return one instance. If no match is found, an exception is raised.

ParseSQl parses the SQL statement for parameter names in the form :ParamName. It replaces them with a SQL parameter placeholder. If DoCreate is True then a TParam instance is added to the collection with the found parameter name.

The parameter placeholder is determined by the ParameterStyle property, which can have the following values:

psInterbase

psPostgreSQL

psSimulated

psInterbase is the default.

If the EscapeSlash parameter is True, then backslash characters are used to quote the next character in the SQL statement. If it is False, the backslash character is regarded as a normal character.

If the EscapeRepeat parameter is True (the default) then embedded quotes in string literals are escaped by repeating themselves. If it is false then they should be quoted with backslashes.

ParamBinding, if specified, is filled with the indexes of the parameter instances in the parameter collection: for each SQL parameter placeholder, the index of the corresponding TParam instance is returned in the array.

ReplaceString, if specified, contains the placeholder used for the parameter names (by default, $). It has effect only when ParameterStyle equals psSimulated.

The function returns the SQL statement with the parameter names replaced by placeholders.

ParamValues provides access to the parameter values () by name. It is equivalent to reading and writing

SkipComments examines the null-terminated string in P and skips any SQL comment or string literal found at the start. It returns P the first non-comment or non-string literal position. The EscapeSlash parameter determines whether the backslash character (\) functions as an escape character (i.e. the following character is not considered a delimiter). EscapeRepeat must be set to True if the quote character is repeated to indicate itself.

The function returns True if a comment was found and skipped, False otherwise.

EditMask can be used to specify an edit mask for controls that allow to edit this field. It has no effect on the field value, and serves only to ensure that the user can enter only correct data for this field.

For more information on valid edit masks, see the documentation of the GUI controls.

EditMask can be used to specify an edit mask for controls that allow to edit this field. It has no effect on the field value, and serves only to ensure that the user can enter only correct data for this field.

TDateTimeField just changes the visibility of the EditMark property, it is introduced in TField.

For more information on valid edit masks, see the documentation of the GUI controls.

EditMask can be used to specify an edit mask for controls that allow to edit this field. It has no effect on the field value, and serves only to ensure that the user can enter only correct data for this field.

TStringField just changes the visibility of the EditMark property, it is introduced in TField.

For more information on valid edit masks, see the documentation of the GUI controls.

TFieldsEnumerator implements all the methods of IEnumerator so a instance can be used in a for..in construct. TFieldsEnumerator returns all the fields in the TFields collection. Therefor the following construct is possible:

Do not create an instance of TFieldsEnumerator manually. The compiler will do all that is needed when it encounters the for..in construct.

PSExecuteStatement will execute the ASQL SQL statement in the current transaction. The SQL statement can have parameters embedded in it (in the form :ParamName), values for these parameters will be taken from AParams. If the SQL statement returns a result-set, then the result set can be returned in ResultSet. The function returns True if the statement was executed succefully.

PSExecuteStatement does not modify the content of CommandText: returns the same value before and after a call to PSExecuteStatement.

PSUpdateRecord is called before attempting to update the records through generated SQL statements. The update to be performed is passed in UpdateKind parameter. The Delta Dataset's current record contains all data for the record that must be updated.

The function returns True if the update was succesfully applied, False if not. In that case the provider will attempt to update the record using SQL statements if the dataset allows it.