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 FlmUserPredicatecopy (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


Generated on Wed Oct 4 12:11:43 2006 for FLAIM by  doxygen 1.4.6