|
<< Click to Display Table of Contents >> DbiAddFilter |
  
|
|
<< Click to Display Table of Contents >> DbiAddFilter |
|
C syntax
DBIResult DBIFN DbiAddFilter (hCursor, [iClientData], [iPriority], [bCanAbort], pcanExpr, [pfFilter], phFilter);
Delphi syntax
function DbiAddFilter (hCursor: hDBICur; iClientData: Longint; iPriority: Word; bCanAbort: Bool; pcanExpr: pCANExpr; pfFilter: pfGENFilter; var hFilter: hDBIFilter): DBIResult stdcall;
Description
DbiAddFilter adds a filter to a table. When activated with DbiActivateFilter, only those records in the table that satisfy the filter condition are seen.
Parameters |
||
hCursor |
Type: hDBICur |
(Input) |
Specifies the cursor handle of the table to which the filter is being applied. |
||
iClientData |
Type: UINT32 |
(Input) |
Not currently used. Must be 0. |
||
iPriority |
Type: UINT16 |
(Input) |
Not currently used. Must be 1. |
||
bCanAbort |
Type: BOOL |
(Input) |
Not currently used. Must be FALSE. |
||
pcanExpr |
Type: pCANExpr |
(Input) |
Pointer to the CANExpr structure, which describes the filter condition as a Boolean expression in prefix format. |
||
pfFilter |
Type: pfGENFilter |
(Input) |
Not currently used. Must be NULL. |
||
phFilter |
Type: phDBIFilter |
(Output) |
Pointer to the filter handle. |
||
Usage
Filters subset result sets. They are similar to a SQL statement's WHERE clause, but are expressed in prefix format. The filter must be specified by the client as a filter expression returning TRUE or FALSE. Multiple filters are allowed per table, and if more than one filter is active, records that violate any active filter condition are not included in the result set. Filters can be switched on and off when needed (using DbiActivateFilter and DbiDeactivateFilter), and are automatically dropped when the table is closed.
DbiGetSeqNo is not influenced by filters; the sequence number returned is that of the record in the original table. DbiGetRecordCount does not guarantee to return an exact count of all records in the filter set. Use DbiGetExactRecordCount to return the exact count of all records in the filter set. Drivers can return the count of all records (including those not satisfying the filter condition) or can return an estimate.
| Note: | Passthrough SQL query cursors do not support this function currently. |
Oracle8: Not supported for object types (ADT, REF, nested table, and VARARRAY).
DbiResult |
Meaning |
DBIERR_NONE |
The filter has been successfully added. |
DBIERR_INVALIDHNDL |
The specified cursor handle is invalid or NULL. |
DBIERR_NA |
The filter condition described by the filter expression could not be handled by the driver. |
See also