xflminterface IF_ResultSet : public XF_RefCount


The IF_ResultSet class defines a result set object.  A result set object allows an application to create a result set, add entries to the result set, sort those entries, and then retrieve entries from the result set.  All of the details of memory allocation, spilling to disk, etc. are handled.  An IF_ResultSet object is created by calling the IF_DbSystem::createIFResultSet method.


Method Summary

   
RCODE setupResultSet - Setup up various options for the result set.
void setSortStatus - Set the sort status callback object for the result set.
void getTotalEntries - Get the total number of entries in the result set.
RCODE addEntry - Add an entry to the result set.
RCODE finalizeResultSet - Finalize the result set - sort entries and eliminate duplicates.
RCODE getFirst - Get the first entry in the result set.
RCODE getNext - Get the next entry in the result set.  Returns first entry in the result set if not currently positioned on an entry.
RCODE getLast - Get the last entry in the result set.
RCODE getPrev - Get the previous entry in the result set.  Returns last entry in the result set if not currently positioned on an entry.
RCODE getCurrent - Get the current entry in the result set.  Returns an error if not currently positioned on an entry.
RCODE modifyCurrent - Modify the current entry in the result set.
RCODE findMatch(1) - Find an entry in a result set where all of the entries are a fixed size.
RCODE findMatch(2) - Find an entry in a result set where the entries are variable size.
FLMUINT64 getPosition - Get the absolute position in the result set where we are currently positioned.
RCODE setPosition - Position to an absolute position in the result set.
RCODE resetResultSet - Reset and clear entries in the result set so it can be reused.
RCODE flushToFile - Flush all entries in the result set to the temporary spill-to-disk file.

 

Method Detail

setupResultSet

    RCODE setupResultSet(

        char *                               pszPath,

        IF_ResultSetCompare *    pResultSetCompare,

        FLMUINT                        uiEntrySize,

        FLMBOOL                       bDropDuplicates = TRUE,

        FLMBOOL                       bEntriesInOrder = FALSE,

        char *                                pszInputFileName = NULL);

This method sets up various options for the result set.

    Parameters In:

char  * pszPath Directory where temporary files will be created if the result set spills to disk.
IF_ResultSetCompare * pResultSetCompare Pointer to object that will be used to compare entries in the result set.  This object is used to sort and lookup entries in the result set.
FLMUINT uiEntrySize Size of entries in the result set.
FLMBOOL bDropDuplicates If TRUE, specifies that duplicate entries should not be kept in the result set.  If FALSE, duplicate entries will be allowed in the result set.
FLMBOOL bEntriesInOrder If TRUE, this parameter tells the result set object that entries will be added in order, so there is no need to sort them.
char  * pszInputFileName Base name of input file to populate result set from.  This is assumed to be a result set file that was created previously by a result set object.  This name should NOT include the directory or the extension.  This file name will be appended to the pszPath parameter to get a full file name.  A file name extension of ".frs" will then be appended to that name.

    Parameters Out: none

    Example Code:

    IF_Resultset *        pResultSet = NULL;

    APP_ResultSetCompare  appResultSetCompare;    // Application implementation of IF_ResultSetCompare interface

    APP_SortStatus        appSortStatus;          // Application implementation of IF_ResultSetSortStatus interface

    RCODE                 rc;

    FLMUINT64             ui64NumEntries;

    char *                ppszEntriesToAdd [] =

    {

        "xyz", "abc", "def", "sdfsdfs", "ksdfoiec", "nmmssdf,mxc", NULL

    };

    char *                pszEntry;

    FLMUINT               uiEntry;

    FLMBOOL               bHaveFirst;

    FLMBOOL               bHaveLast;

    char                  szEntry [100];

    FLMUINT               uiEntrySize;

    FLMUINT64             ui64Position;

 

    // Get a result set object.

 

    if (RC_BAD( rc = pDbSystem->createIFResultSet( &pResultSet)))

    {

        goto Exit;

    }

 

    // Setup the result set - use c:\temp as the path for spilling the result set to disk.

    // Set entry size to 0 to allow for variable size entries.

 

    if (RC_BAD( rc = pResultSet->setupResultSet( "c:\temp", &appResultSetCompare, 0, TRUE, FALSE, NULL)))

    {

        goto Exit;

    }

 

    // Set the sort status callback object

 

    pResultSet->setSortStatus( &appSortStatus);

 

    // Add a bunch of entries to the result set.  In this case, our result set will be a sorted list of strings.

    // We might have chosen to read these strings from a file, but to simplify the example, we just get them

    // from a hard-coded array in memory.

 

    for (uiEntry = 0; ppszEntries [uiEntry ]; uiEntry ++)

    {

        pszEntry = ppszEntries [uiEntry];

 

        // When adding the entry, make sure to specify a length that includes the null-terminating character.

 

        if (RC_BAD( rc = pResultSet->addEntry( pszEntry, strlen( pszEntry) + 1)))

        {

            goto Exit;

        }

    }

 

    // Sort the result set - eliminates duplicates

 

    if (RC_BAD( rc = pResultSet->finalizeResultSet( NULL)))

    {

        goto Exit;

    }

 

    // See how many entries are in the result set

 

    ui64NumEntries = pResultSet->getNumEntries();

 

    // Get the entries and display in ascending order


    bHaveFirst = FALSE;

    for (;;)

    {

        if (bHaveFirst)

        {

            rc = pResultSet->getNext( szEntry, sizeof( szEntry), &uiEntrySize);

        }

        else

        {

            rc = pResultSet->getFirst( szEntry, sizeof( szEntry), &uiEntrySize);

            bHaveFirst = TRUE;

        }

        if (RC_BAD( rc))

        {

            if (rc == NE_XFLM_EOF_HIT)

            {

                rc = NE_XFLM_OK;

                break;

            }

            else

            {

                goto Exit;

            }

        }

        printf( "%s (pos=%u)\n", szEntry, (unsigned)pResultSet->getPosition());

    }

 

    // Find the "abc" entry and print its position

 

    if (RC_BAD( rc = pResultSet->findMatch( "abc", 4, szEntry, &uiEntrySize)))

    {

        goto Exit;

    }

    ui64Position = pResultSet->getPosition();

 

    // Get the entries and display in descending order


    bHaveLast = FALSE;

    for (;;)

    {

        if (bHaveLast)

        {

            rc = pResultSet->getPrev( szEntry, sizeof( szEntry), &uiEntrySize);

        }

        else

        {

            rc = pResultSet->getLast( szEntry, sizeof( szEntry), &uiEntrySize);

            bHaveLast = TRUE;

        }

        if (RC_BAD( rc))

        {

            if (rc == NE_XFLM_BOF_HIT)

            {

                rc = NE_XFLM_OK;

                break;

            }

            else

            {

                goto Exit;

            }

        }

 

        printf( "%s (pos=%u)\n", szEntry, (unsigned)pResultSet->getPosition());

 

        // Modify the current entry to be its current value.  This is just to illustrate

        // the use of modifyEntry - it is unlikely that anyone would actually use it to

        // set it to the value that it already had.

 

        if (RC_BAD( rc = pResultSet->modifyEntry( szEntry, uiEntrySize)))

        {

            goto Exit;

        }

    }

 

    // Position to the 2nd entry in the result set and print it out

 

    if (RC_BAD( rc = pResultSet->setPosition( 2)))

    {

        goto Exit;

    }

    if (RC_BAD( rc = pResultSet->getCurrent( szEntry, sizeof( szEntry), &uiEntrySize)))

    {

        goto Exit;

    }

    printf( "%s (pos=%u)\n", szEntry, (unsigned)pResultSet->getPosition());

 

    // Flush the entries to disk so they can be saved and used later.  Then reset the

    // result set so we can reuse it if we want to.

 

    if (RC_BAD( rc = pResultset->flushToFile()))

    {

        goto Exit;

    }

    if (RC_BAD( rc = pResultSet->resetResultSet( FALSE)))

    {

        goto Exit;

    }

 

[Back to Top]


setSortStatus

    void setSortStatus(

        IF_ResultSetSortStatus *   pSortStatus);

This method set a sort status callback object for the result set.

    Parameters In:

IF_ResultSetSortStatus * pSortStatus Pointer to sort status callback object.

    Parameters Out: none

    Example Code: see setupResultSet

[Back to Top]


getTotalEntries

    FLMUINT64 getTotalEntries( void);

Return the total number of entries in the result set.

    Parameters In: none

    Parameters Out: none

    Example Code: see setupResultSet

[Back to Top]


addEntry

    RCODE addEntry(

        void *            pvEntry,

        FLMUINT    uiEntryLength = 0);

Add an entry to the result set.

    Parameters In:

void * pvEntry Pointer to the entry that is to be added to the result set
FLMUINT uiEntryLength Number of bytes in the entry, if the result set is handling variable length entries.  If the entries are fixed size - as specified in setupResultSet - then a zero should be passed here.

    Parameters Out: none

    Example Code: see setupResultSet

[Back to Top]


finalizeResultSet

    RCODE finalizeResultSet(

        FLMUINT64 *    pui64TotalEntries = NULL);

Finalize the result set, sorting entries and eliminate duplicates.

    Parameters In: none

    Parameters Out:

FLMUINT64 * pui64TotalEntries If non-NULL, the total entries that remain after duplicate elimination will be returned.

    Example Code: see setupResultSet

[Back to Top]


getFirst

    RCODE getFirst(

        void *               pvEntryBuffer,

        FLMUINT       uiBufferLength = 0,

        FLMUINT *    puiEntryLength = NULL);

Get the first entry in the result set.

    Parameters In:

void  * pvEntryBuffer Buffer the entry is to be returned in.
FLMUINT uiBufferLength Size of pvEntryBuffer.  If zero, size is assumed to be big enough to hold the entry.

    Parameters Out:

FLMUINT * puiEntryLength Returns the length of the entry.

    Example Code: see setupResultSet

    See Also: getNext, getLast, getPrev, getCurrent, findMatch(1), findMatch(2)

[Back to Top]


getNext

    RCODE getNext(

        void *               pvEntryBuffer,

        FLMUINT       uiBufferLength = 0,

        FLMUINT *    puiEntryLength = NULL);

Get the next entry in the result set.  NOTE: If no entry has yet been retrieved from the result set, this will get the first entry in the result set.

    Parameters In:

void  * pvEntryBuffer Buffer the entry is to be returned in.
FLMUINT uiBufferLength Size of pvEntryBuffer.  If zero, size is assumed to be big enough to hold the entry.

    Parameters Out:

FLMUINT * puiEntryLength Returns the length of the entry.

    Example Code: see setupResultSet

    See Also: getFirst, getLast, getPrev, getCurrent, findMatch(1), findMatch(2)

[Back to Top]


getLast

    RCODE getLast(

        void *               pvEntryBuffer,

        FLMUINT       uiBufferLength = 0,

        FLMUINT *    puiEntryLength = NULL);

Get the last entry in the result set.

    Parameters In:

void  * pvEntryBuffer Buffer the entry is to be returned in.
FLMUINT uiBufferLength Size of pvEntryBuffer.  If zero, size is assumed to be big enough to hold the entry.

    Parameters Out:

FLMUINT * puiEntryLength Returns the length of the entry.

    Example Code: see setupResultSet

    See Also: getFirst, getNext, getPrev, getCurrent, findMatch(1), findMatch(2)

[Back to Top]


getPrev

    RCODE getPrev(

        void *               pvEntryBuffer,

        FLMUINT       uiBufferLength = 0,

        FLMUINT *    puiEntryLength = NULL);

Get the previous entry in the result set.  NOTE: If no entry has yet been retrieved from the result set, this will get the last entry in the result set.

    Parameters In:

void  * pvEntryBuffer Buffer the entry is to be returned in.
FLMUINT uiBufferLength Size of pvEntryBuffer.  If zero, size is assumed to be big enough to hold the entry.

    Parameters Out:

FLMUINT * puiEntryLength Returns the length of the entry.

    Example Code: see setupResultSet

    See Also: getFirst, getNext, getLast, getCurrent, findMatch(1), findMatch(2)

[Back to Top]


getCurrent

    RCODE getCurrent(

        void *               pvEntryBuffer,

        FLMUINT       uiBufferLength = 0,

        FLMUINT *    puiEntryLength = NULL);

Get the entry in the result set we are currently positioned on.  If no entry has yet been retrieved from the result set, this will return NE_XFLM_NOT_FOUND.

    Parameters In:

void  * pvEntryBuffer Buffer the entry is to be returned in.
FLMUINT uiBufferLength Size of pvEntryBuffer.  If zero, size is assumed to be big enough to hold the entry.

    Parameters Out:

FLMUINT * puiEntryLength Returns the length of the entry.

    Example Code: see setupResultSet

    See Also: getFirst, getNext, getLast, getPrev, findMatch(1), findMatch(2)

[Back to Top]


modifyCurrent

    RCODE modifyCurrent(

        void *               pvEntry,

        FLMUINT       uiEntryLength = 0);

Modify the current entry.  NOTE: No check is made to ensure that the result set is positioned on an entry.  This method should NOT be called if we are not positioned on an entry!

    Parameters In:

void  * pvEntry Entry that is to replace the current entry.
FLMUINT uiEntryLength Number of bytes in pvEntry, if the result set is handling variable length entries.  If the entries are fixed size - as specified in setupResultSet - then a zero should be passed here.

    Parameters Out:

FLMUINT * puiEntryLength Returns the length of the entry.

    Example Code: see setupResultSet

    See Also: getFirst, getNext, getLast, getPrev, getCurrent, findMatch(1), findMatch(2)

[Back to Top]


findMatch(1)

    RCODE findMatch(

        void *               pvMatchEntry,

        void *               pvFoundEntry);

Search for an entry in a result set where the entries are a fixed size.

    Parameters In:

void  * pvMatchEntry Entry to search for.  It is assumed that the length of this entry is the same as the number of bytes that was specified in the setupResultSet.

    Parameters Out:

void  * pvFoundEntry Returns the found entry.  It is assumed that the length of this buffer is at least the number of bytes that was specified in the setupResultSet.

    See Also: getFirst, getNext, getLast, getPrev, getCurrent, findMatch(2)

[Back to Top]


findMatch(2)

    RCODE findMatch(

        void *               pvMatchEntry,

        FLMUINT       uiMatchEntryLength,

        void *               pvFoundEntry,

        FLMUINT *    puiFoundEntryLength);

Search for an entry in a result set where the entries are variable size.

    Parameters In:

void  * pvMatchEntry Entry to search for.
FLMUINT uiMatchEntryLength Length (in bytes) of pvMatchEntry.

    Parameters Out:

void  * pvFoundEntry Returns the found entry.  It is assumed that the length of this buffer is at least the number of bytes that will be needed to return an entry of the size anticipated.
FLMUINT * puiFoundEntryLength Returns the length (in bytes) of the entry that was found.

    Example Code: see setupResultSet

    See Also: getFirst, getNext, getLast, getPrev, getCurrent, findMatch(1)

[Back to Top]


getPosition

    FLMUINT64 getPosition( void);

Return the current absolute position in the result set.  Returns FLM_MAX_UINT64 if the result set is not currently positioned on an entry.

    Parameters In: none

    Parameters Out: none

    Example Code: see setupResultSet

    See Also: setPosition

[Back to Top]


setPosition

    RCODE setPosition(

        FLMUINT64    ui64Position);

Return the current absolute position in the result set.  Returns FLM_MAX_UINT64 if the result set is not currently positioned on an entry.

    Parameters In:

FLMUINT64 ui64Position Absolute position to position to in the result set.

    Parameters Out: none

    Example Code: see setupResultSet

    See Also: getPosition

[Back to Top]


resetResultSet

    RCODE resetResultSet(

        FLMBOOL    bDelete = TRUE);

Reset the result set, clearing out all entries.  After this call, the result set may be reused.

    Parameters In:

FLMBOOL bDelete Delete the files associated with the result set, if any.

    Parameters Out: none

    Example Code: see setupResultSet

[Back to Top]


flushToFile

    RCODE flushToFile( void);

Writes out all entries in the result set to the temporary spill-to-disk file.  The name of the file may be specified in the setupResultSet method.

    Parameters In: none

    Parameters Out: none

    Example Code: see setupResultSet

[Back to Top]