FLAIM: FlmUserPredicate Class Reference

- Main Page
- Modules
- Classes
- Files

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# FlmUserPredicate Class Reference

This is an abstract base class which defines the interface that an application must implement to embed its own predicate in a query. More...

`#include <flaim.h>`

List of all members.

## Public Member Functions
virtual RCODE | searchCost (HFDB hDb, FLMBOOL bNotted, FLMBOOL bExistential, FLMUINT *puiCost, FLMUINT *puiDrnCost, FLMUINT *puiTestRecordCost, FLMBOOL *pbPassesEmptyRec)=0
| Method that returns the search cost of this object in providing records for a query.
virtual RCODE | testAllRecordCost (HFDB hDb, FLMUINT *puiCost)=0
| Method that returns the cost of testing ALL record.
virtual RCODE | firstRecord (HFDB hDb, FLMUINT *puiDrn, FlmRecord **ppRecord)=0
| Position to and return the first record that satisfies the predicate.
virtual RCODE | lastRecord (HFDB hDb, FLMUINT *puiDrn, FlmRecord **ppRecord)=0
| Position to and return the last record that satisfies the predicate.
virtual RCODE | nextRecord (HFDB hDb, FLMUINT *puiDrn, FlmRecord **ppRecord)=0
| Position to and return the next record that satisfies the predicate.
virtual RCODE | prevRecord (HFDB hDb, FLMUINT *puiDrn, FlmRecord **ppRecord)=0
| Position to and return the previous record that satisfies the predicate.
virtual RCODE | testRecord (HFDB hDb, FlmRecord *pRecord, FLMUINT uiDrn, FLMUINT *puiResult)=0
| Test a record to see if it passes the criteria of the predicate.
virtual FLMUINT | getIndex (FLMUINT *puiIndex)=0
| Return index being used for this predicate.
virtual FlmUserPredicate * | copy (void)=0
| Copy the predicate.
virtual HFCURSOR | getCursor (void)=0
| Return predicate's FLAIM query handle, if any.
virtual RCODE | positionTo (HFDB hDb, FlmUserPredicate *pPredicate)=0
| Position this predicate to the same position as another predicate.
virtual RCODE | savePosition (void)=0
| Save current position of predicate.
virtual RCODE | restorePosition (void)=0
| Restore last saved position of predicate.
virtual RCODE | isAbsPositionable (HFDB hDb, FLMBOOL *pbIsAbsPositionable)=0
| Determine if predicate is absolute positionable.
virtual RCODE | getAbsCount (HFDB hDb, FLMUINT *puiCount)=0
| Get absolute record count.
virtual RCODE | getAbsPosition (HFDB hDb, FLMUINT *puiPosition)=0
| Get absolute position.
virtual RCODE | positionToAbs (HFDB hDb, FLMUINT uiPosition, FLMBOOL bFallForward, FLMUINT uiTimeLimit, FLMUINT *puiPosition, FLMUINT *puiDrn)=0
| Set absolute position.
virtual void | releaseResources (void)=0
| Release any resources held by this predicate.

## Detailed Description

This is an abstract base class which defines the interface that an application must implement to embed its own predicate in a query.

## Member Function Documentation

virtual FlmUserPredicate* FlmUserPredicate::copy | ( | void |  | ) | `[pure virtual]`

| Copy the predicate. In the new object, it should be as if the predicate had just been defined. The current position, calculated score, etc. should not be preserved in the new predicate. Only the predicate criteria - however that is represented - should be preserved. This method should return NULL if a new predicate cannot be created. FLAIM will call this method whenever it needs to copy an application-defined predicate - such as when a query or some part of a query is cloned.

virtual RCODE FlmUserPredicate::firstRecord | ( | HFDB | hDb,
|  | FLMUINT * | puiDrn,
|  | FlmRecord ** | ppRecord
| ) | `[pure virtual]`

  | Position to and return the first record that satisfies the predicate. Parameters:
  hDb | Database handle. NOTE: Application should NOT save this handle. It may be changed from one call to the next.
  puiDrn | If non-NULL, record's DRN is returned here.
  ppRecord | If non-NULL, record is returned here.

virtual RCODE FlmUserPredicate::getAbsCount | ( | HFDB | hDb,
|  | FLMUINT * | puiCount
| ) | `[pure virtual]`

  | Get absolute record count. NOTE: This method should only be called if the predicate is "absolute" positionable (see FlmUserPredicate::isAbsPositionable()). Parameters:
  hDb | Database handle.
  puiCount | Returns total number of records this predicate would return.

virtual RCODE FlmUserPredicate::getAbsPosition | ( | HFDB | hDb,
|  | FLMUINT * | puiPosition
| ) | `[pure virtual]`

  | Get absolute position. NOTE: This method should only be called if the predicate is "absolute" positionable (see FlmUserPredicate::isAbsPositionable()). Parameters:
  hDb | Database handle.
  puiPosition | Returns the current "absolute" position of this predicate.

virtual HFCURSOR FlmUserPredicate::getCursor | ( | void |  | ) | `[pure virtual]`

| Return predicate's FLAIM query handle, if any. This is useful if an application-defined predicate is implemented as a FLAIM query. It is often very useful to embed one FLAIM query inside another.

virtual FLMUINT FlmUserPredicate::getIndex | ( | FLMUINT * | puiIndex | ) | `[pure virtual]`

  | Return index being used for this predicate. Parameters:
  puiIndex | Index number is returned here. If no index is being used, a zero should be returned.

virtual RCODE FlmUserPredicate::isAbsPositionable | ( | HFDB | hDb,
|  | FLMBOOL * | pbIsAbsPositionable
| ) | `[pure virtual]`

  | Determine if predicate is absolute positionable. Parameters:
  hDb | Database handle.
  pbIsAbsPositionable | Returns TRUE/FALSE indicating if predicate is "absolute" positionable.

virtual RCODE FlmUserPredicate::lastRecord | ( | HFDB | hDb,
|  | FLMUINT * | puiDrn,
|  | FlmRecord ** | ppRecord
| ) | `[pure virtual]`

  | Position to and return the last record that satisfies the predicate. Parameters:
  hDb | Database handle. NOTE: Application should NOT save this handle. It may be changed from one call to the next.
  puiDrn | If non-NULL, record's DRN is returned here.
  ppRecord | If non-NULL, record is returned here.

virtual RCODE FlmUserPredicate::nextRecord | ( | HFDB | hDb,
|  | FLMUINT * | puiDrn,
|  | FlmRecord ** | ppRecord
| ) | `[pure virtual]`

  | Position to and return the next record that satisfies the predicate. If no prior positioning has been done, position to and return the first record. Parameters:
  hDb | Database handle. NOTE: Application should NOT save this handle. It may be changed from one call to the next.
  puiDrn | If non-NULL, record's DRN is returned here.
  ppRecord | If non-NULL, record is returned here.

virtual RCODE FlmUserPredicate::positionTo | ( | HFDB | hDb,
|  | FlmUserPredicate * | pPredicate
| ) | `[pure virtual]`

  | Position this predicate to the same position as another predicate. Parameters:
  hDb | Database handle.
  pPredicate | Predicate whose position this predicate is to be positioned to.

virtual RCODE FlmUserPredicate::positionToAbs | ( | HFDB | hDb,
|  | FLMUINT | uiPosition,
|  | FLMBOOL | bFallForward,
|  | FLMUINT | uiTimeLimit,
|  | FLMUINT * | puiPosition,
|  | FLMUINT * | puiDrn
| ) | `[pure virtual]`

  | Set absolute position. NOTE: This method should only be called if the predicate is "absolute" positionable (see FlmUserPredicate::isAbsPositionable()). Parameters:
  hDb | Database handle.
  uiPosition | Absolute position to position this predicate to.
  bFallForward | If the record at the position specified cannot be returned, this flag indicates whether the method should attempt to "fall forward" to the next record in the result set that can be returned.
  uiTimeLimit | Time limit (seconds) for this operation.
  puiPosition | Returns the actual position that was positioned to. The only time this could be different than the position requested in the uiPosition parameter is if the record at the requested position cannot be returned and the bFallForward flag is TRUE.
  puiDrn | Returns the DRN of the record at the position we ended getting positioned to.

virtual RCODE FlmUserPredicate::prevRecord | ( | HFDB | hDb,
|  | FLMUINT * | puiDrn,
|  | FlmRecord ** | ppRecord
| ) | `[pure virtual]`

  | Position to and return the previous record that satisfies the predicate. If no prior positioning has been done, position to and return the last record. Parameters:
  hDb | Database handle. NOTE: Application should NOT save this handle. It may be changed from one call to the next.
  puiDrn | If non-NULL, record's DRN is returned here.
  ppRecord | If non-NULL, record is returned here.

virtual void FlmUserPredicate::releaseResources | ( | void |  | ) | `[pure virtual]`

| Release any resources held by this predicate. This method should release any resources (memory, etc.) consumed by the predicate except those that would be needed to show the predicate's query criteria. At the point in time where FLAIM calls this method, the predicate is no longer going to be used to retrieve or test records, but the query is being kept around to allow a user to see information about queries that have been run. Thus, enough information should be preserved to allow the predicate to show its query criteria and any statistics it may have collected if it was called to get records (firstRecord, lastRecord, nextRecord, prevRecord).

virtual RCODE FlmUserPredicate::searchCost | ( | HFDB | hDb,
|  | FLMBOOL | bNotted,
|  | FLMBOOL | bExistential,
|  | FLMUINT * | puiCost,
|  | FLMUINT * | puiDrnCost,
|  | FLMUINT * | puiTestRecordCost,
|  | FLMBOOL * | pbPassesEmptyRec
| ) | `[pure virtual]`

  | Method that returns the search cost of this object in providing records for a query. FLAIM uses the information returned from this method to determine how to optimize the query. Parameters:
  hDb | Database handle. NOTE: Application should NOT save this handle. It may be changed from one call to the next.
  bNotted | Flag indicating predicate is notted in the search criteria.
  bExistential | Flag indicating predicate is "existential" (TRUE) or "universal" (FALSE).
  puiCost | Estimated cost is returned here.
  puiDrnCost | Estimated DRN cost is returned here.
  puiTestRecordCost | Test record cost is returned here.
  pbPassesEmptyRec | Returns flag indicating whether the predicate would pass or fail an empty record.

virtual RCODE FlmUserPredicate::testAllRecordCost | ( | HFDB | hDb,
|  | FLMUINT * | puiCost
| ) | `[pure virtual]`

  | Method that returns the cost of testing ALL record. Parameters:
  hDb | Database handle.
  puiCost | Estimated cost is returned here.

virtual RCODE FlmUserPredicate::testRecord | ( | HFDB | hDb,
|  | FlmRecord * | pRecord,
|  | FLMUINT | uiDrn,
|  | FLMUINT * | puiResult
| ) | `[pure virtual]`

  | Test a record to see if it passes the criteria of the predicate. Parameters:
  hDb | Database handle. NOTE: Application should NOT save this handle. It may be changed from one call to the next.
  pRecord | Record to be tested.
  uiDrn | DRN of record to be tested.
  puiResult | Result is returned here. Should be one of the following: FLM_FALSE - should be returned if predicate fails the record FLM_TRUE - should be returned if the predicate passes the record FLM_UNK - should be returned if it cannot be determined whether the record passes or fails