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 |
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;
}
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
FLMUINT64 getTotalEntries( void);
Return the total number of entries in the result set.
Parameters In: none
Parameters Out: none
Example Code: see setupResultSet
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
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
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)
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)
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)
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)
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)
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)
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)
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)
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
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
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
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