xflminterface IF_DbSystem : public XFLMIUnknown


This class represents the XFlaim  database system. It extends XFLMIUnknown. The IF_DbSystem interface is used to represent the actual database system object. The database system object incorporates functionality to startup, shutdown, create, open and copy an XFlaim database.  Note that the database system when XFlaim is running is more than the files that store the data.  The database system also includes all of the in-memory structures and objects that are used, either intermittently or throughout the life of the database system.  The class id for this interface is CLSID_F_DbSystemFactory and the interface id is IID_IF_DbSystem.  An object of this type may also be created by calling FlmAllocDbSystem, as shown below:

FlmAllocDbSystem

    RCODE FlmAllocDbSystem(

        IF_DbSystem **    ppDbSystem);

    Example Code:

    IF_DbSystem *      pDbSystem = NULL;

    RCODE                    rc;

 

    // Create an instance of the DbSystem interface first.

    if (RC_BAD( rc = FlmAllocDbSystem( &pDbSystem)))

    {
        goto Exit;
    }

 


Method Summary

RCODE  

 init - Initializes the database system object.

RCODE  

 updateIniFile - Update an item in the .ini file that is used by the init method.

void 

 exit - Shuts down the database system and closes any open databases.

void   getFileSystem - Return an IF_FileSystem object for performing file system operations.

RCODE 

 dbCreate - Creates a new database.

RCODE 

 dbOpen - Opens an existing database.

RCODE

 dbCheck - Checks a database for corruptions.

RCODE

 dbRebuild - Rebuilds a database.

RCODE 

 dbCopy - Copies a database.

RCODE

 dbRename - Renames a database.

RCODE

 dbRemove - Removes a database.

RCODE

 dbRestore - Restores a database from a backup set.

RCODE

 dbDup - Duplicates the IF_Db interface object.

char *

 errorString - Converts an RCODE error number to a string equivalent.

char *

 checkErrorToStr - Converts an RCODE error number to a string equivalent.

RCODE

 openBufferIStream - Opens a buffered input stream.

RCODE

 openFileIStream - Opens a file input stream.

RCODE

 openMultiFileIStream - Opens a multi-file input stream.

RCODE

 openBufferedIStream - Convert an input stream into a buffered input stream.

RCODE

 openUncompressingIStream - Convert an input stream that gives out compressed data into an input stream that will give out uncompressed data.

RCODE

 openFileOStream - Open a file output stream.

RCODE

 openMultiFileOStream - Open a multi-file output stream.

RCODE

 removeMultiFileStream - Delete a multi-file stream that was created by openMultiFileOStream.

RCODE

 openBufferedOStream - Open a buffered output stream.

RCODE

 openCompressingOStream - Open a compressing output stream.

RCODE

 writeToOStream - Read input from an input stream and write it out to an output stream.

RCODE

 openBase64Encoder - Opens a base 64 encoding stream.

RCODE

 openBase64Decoder - Opens a base 64 decoding stream.

RCODE

 createIFDataVector - Creates an IF_DataVector interface object.

RCODE

 createIFResultSet - Creates an IF_ResultSet interface object.

RCODE

 createIFQuery - Creates an IF_Query interface object.

void

 freeMem - Frees memory for allocations that are returned from various XFlaim methods.

RCODE

 setDynamicMemoryLimit - Set a dynamic memory limit in the XFlaim database system.

RCODE

 setHardMemoryLimit - Set a hard limit on the amount of memory that the database system can access.

RCODE

 getDynamicCacheSupported - Determine if setting of dynamic cache limits via setDynamicMemoryLimit are supported.

void

 getCacheInfo - Query the database system for information regarding the current cache usage.

void

 enableCacheDebug - A method to either enable or disable cache debug mode.

FLMBOOL

 cacheDebugEnabled - A method to find out if cache debug mode is either enabled or disabled.

RCODE

 closeUnusedFiles - Close all file handles (descriptors) that have not been used for a specified amount of time.

void

 setOpenThreshold - Set the threshold for the number of file handles (descriptors) that can be opened by the database system.

FLMUINT

 getOpenThreshold - Get the threshold for the number of file handles that can be opened by the database system.

FLMUINT

 getOpenFileCount - Get the number of files that are currently open in the database system.

void

 startStats - Start the collection of statistics on the database system.

void

 stopStats - Stop the collection of statistics on the database system.

void

 resetStats - Reset the statistics counters on the database system.

RCODE

 getStats - Retrieve the statistics from the database system.

void

 freeStats - Free the statistic object in the database system.

RCODE

 setTempDir - Set the directory where temporary files are created.

RCODE

 getTempDir - Get the directory where temporary files are created.

void

 setCheckpointInterval - Set the time between checkpoints in the database.

FLMUINT

 getCheckpointInterval - Get the current checkpoint interval.

void

 setCacheAdjustInterval - Set the time interval for dynamically adjusting the cache limit.

FLMUINT

 getCacheAdjustInterval - Get the time interval for dynamically adjusting the cache limit.

void

 setCacheCleanupInterval - Set the time interval for dynamically cleaning out old cache blocks from block cache.

FLMUINT

 getCacheCleanupInterval - Get the time interval for dynamically cleaning out old cache blocks from block cache.

void

 setUnusedCleanupInterval - Set time interval for cleaning up unused resources (such as file handles).

FLMUINT

 getUnusedCleanupInterval - Get time interval for cleaning up unused resources (such as file handles).

void

 setMaxUnusedTime - Set maximum time for a resource (such as a file handle) to be unused before it is cleaned up.

FLMUINT

 getMaxUnusedTime - Get maximum time for a resource (such as a file handle) to be unused before it is cleaned up.

void

 setLogger - Set the logger client.

void

 enableExtendedServerMemory - Enable or disable extended server memory (ESM).

FLMBOOL

 extendedServerMemoryEnabled - Determine if extended server memory (ESM) is enabled or disabled.

void

 deactivateOpenDb - Deactivate open database objects, forcing the database(s) to eventually be closed.

void

 setQuerySaveMax - Set the maximum number of queries to save when statistics gathering is enabled.

FLMUINT

 getQuerySaveMax - Get the maximum number of queries to save when statistics gathering is enabled.

void

 setDirtyCacheLimits - Set the minimum and maximum dirty cache limits.

void

 getDirtyCacheLimits - Get the minimum and maximum dirty cache limits.

RCODE

 getThreadInfo - Get an information object that can be used to get information about threads owned by the database system.

RCODE

 registerForEvent - Register a catcher object to catch database events in a particular category.

void

 deregisterForEvent - Deregister a catcher object from catching database events in a particular category.

RCODE

 getNextMetaphone - Returns the metaphone codes for the next word in an input stream.

RCODE

 createMemoryPool - Creates a memory pool for doing memory allocations.

RCODE

 compareUTF8Strings - Compare two UTF8 strings.

RCODE

 compareUnicodeStrings - Compare two unicode strings.

RCODE

 utf8IsSubStr - See if one UTF8 string is a sub-string of another UTF8 string.

FLMBOOL

 uniIsUpper - Determine if a unicode character is an upper-case character.

FLMBOOL

 uniIsLower - Determine if a unicode character is an lower-case character.

FLMBOOL

 uniIsAlpha - Determine if a unicode character is an alphabetic character.

FLMBOOL

 uniIsDecimalDigit - Determine if a unicode character is a decimal digit character.

FLMUNICODE

 uniToLower - Convert a unicode character to lower case (if there is a "lower case" character for the character to be converted).

RCODE

 nextUCS2Char - Get the next unicode character (UCS2 character) from a UTF8 string.

RCODE

 numUCS2Chars - Return the number of unicode characters (UCS2 characters) in a UTF8 string.

RCODE

 waitToClose - Wait for a specific database to close.

RCODE

 createIFNodeInfo - Create an IF_NodeInfo object.

RCODE

 createIFBTreeInfo - Create an IF_BTreeInfo object.

RCODE

 clearCache - Attempt to clear block and node cache.

 

Method Detail

init

    RCODE init( void);

The init method is used to startup the database system engine. This routine may be called multiple times within the same process space.  For each time the init method is called, there must be a corresponding call to exit.  The database engine will only shut down on the last call to exit.

The first time the init method is called, it will look for a file called "_xflm.ini" to set certain startup parameters.  It first looks to see if there is an environment variable named "XFLM_INI_PATH".  If so, this should contain the name of the directory where the _xflm.ini file is located.  If there is no XFLM_INI_PATH environment variable, init will then look in the current working directory for "_xflm.ini".  If it is not found there, it will then attempt to see if it can find it in a "data" subdirectory relative to the current working.  If the "_xflm.ini" file cannot be found in any of these locations, defaults will be used for the parameters that can be specified in "_xflm.ini."  Even if the "_xflm.ini" file is found, some parameters may not be specified, in which case defaults will be used.

Each parameter in the "_xflm.ini" file must be specified as follows:

    paramName=value

Currently, the only parameters that may be set in the "_xflm.ini" file are as follows:

cache Value for cache must be either a number that gives hard cache limit (specified in bytes), or a list of comma separated named sub-values, which are used to specify how the cache limit is to be set.  These are as follows:
  • MAX:<maximum cache> (in bytes)
  • MIN:<minimum cache> (in bytes)
  • %:<Percent of avail or total memory>
  • DYN or HARD (specifies whether to do a dynamic cache limit or a hard cache limit)
  • AVAIL or TOTAL (tells whether the % parameter is to be interpreted as percent of available memory or total memory)
  • LEAVE:<amount of memory to leave> (may be specified instead of giving a MAX)
  • PRE (tells XFLAIM to pre-allocate all of its cache slabs)

 Examples:

cache=400000000 - Set a hard cache limit of 400 MB

cache=HARD,MAX:400000000,MIN:16000000,PRE - Set a hard cache limit, 400 MB maximum, 16 MB minimum, pre-allocate all of the cache slabs up front rather than on demand.

cache=DYN,AVAIL,%:50,MAX:400000000,MIN:16000000 - Set a dynamic limit, 50% of available memory, 400 MB maximum, 16 MB minimum.

Setting the cache parameter will cause the init method to call either the setDynamicMemoryLimit method or the setHardMemoryLimit method.  If the PRE option is set up above, it will

cacheadjustinterval Value for this parameter is the interval (in seconds) for dynamically adjusting the cache limit (if we are using a dynamic cache limit).  See setDynamicMemoryLimit for more information on dynamic cache limits work.  Setting this parameter will cause the init method to call setCacheAdjustInterval with the specified interval.
cachecleanupinterval Value for this parameter is the interval (in seconds) for cleaning up cache.  Setting this parameter will cause the init method to call setCacheCleanupInterval with the specified interval.
maxdirtycache Value for this parameter is the maximum dirty cache (in bytes).  Setting this parameter will cause the init method to call setDirtyCacheLimits with the specified value for maximum dirty cache.  Note: setDirtyCacheLimits actually sets both the maximum dirty cache and the low dirty cache.  If the lowdirtycache parameter is not specified in the _xflm.ini file, the init method will use a default for it.
lowdirtycache Value for this parameter is the low dirty cache (in bytes).  Setting this parameter will cause the init method to call setDirtyCacheLimits with the specified value for low dirty cache.  Note: setDirtyCacheLimits actually sets both the maximum dirty cache and the low dirty cache.  If the maxdirtycache parameter is not specified in the _xflm.ini file, the init method will use a default for it.

 

    cache=<cache limit> | <cache specifiers> -

    cacheadjustinterval=<interval>

    cachecleanupinterval=<interval>

    maxdirtycache=<max dirty cache (in bytes)>

    lowdirtycache=<low dirty cache (in bytes)>

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    IF_DbSystem *      pDbSystem = NULL;

    RCODE                    rc;

    .

    .

    .

    // Create an instance of the DbSystem interface first.

    if (RC_BAD( rc = PsaComCreateInstance( CLSID_F_DbSystemFactory,
                                                                               NULL,

                                                                               IID_IF_DbSystem,

                                                                               (void **)&pDbSystem)))
    {
        goto Exit;
    }

 

    // Startup the database system.
    if( RC_BAD( pDbSystem->init()))
    {
        goto Exit;
    }
    .

    .

    .
 

    See Also: exit, dbOpen, dbCopy, dbRebuild, dbRename, dbRemove, dbRestore, dbDup, updateIniFile

[Back to Top]


updateIniFile

    RCODE updateIniFile(

        char *    pszParamName,

        char *    pszValue);

This method updates a specific value in the .ini file used by XFLAIM.  The .ini file is used to set certain startup parameters when the init method is called.  See documentation on the init method for more information on parameters in the .ini file and how the .ini file to be used is determined.

    Parameters In:

char * pszParamName Name of parameter in .ini file that is to be updated.
char * pszValue Value to be set for the specified parameter.  Value is saved into the .ini file.

    Parameters Out: none

    Example Code:

    RCODE             rc;

 

    // Set the cache size parameter ("cache")in the .ini file to be 300 megabytes.  This does NOT set the current cache limit, but it determines what the

    // cache limit will be set to the next time XFLAIM is started from scratch and the IF_DbSystem::init call is made.

 

    rc = pDbSystem->updateIniFile( XFLM_INI_CACHE, "300000000");

    See Also: init

[Back to Top]


exit

    void exit( void);

The exit method is used to shutdown the database system engine. This routine allows itself to be called multiple times, even before init is called or if the call to init fails.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    IF_DbSystem *        pDbSystem = NULL;

    RCODE                    rc;

    .

    .

    .

    // Create an instance of the DbSystem interface first.

    if (RC_BAD( rc = PsaComCreateInstance( CLSID_F_DbSystemFactory,
                                                                               NULL,

                                                                               IID_IF_DbSystem,

                                                                               (void **)&pDbSystem)))
    {
        goto Exit;
    }

    .

    .

    .

Exit:

    // Shutdown the database system.
    pDbSystem->exit();
 

    See Also: init, dbOpen, dbCopy, dbRebuild, dbRename, dbRemove, dbRestore, dbDup

[Back to Top]


getFileSystem

    void getFileSystem(

        IF_FileSystem **    ppFileSystem);

The getFileSystem method returns an IF_FileSystem object that can be used to perform various operations on files.

    Parameters In: none.

    Parameters Out:

IF_FileSystem ** ppFileSystem A pointer to a file system object that can be used to perform various operations on files.

    Example Code:

    IF_FileSystem *        pFileSystem = NULL;

    .

    .

    .

    // Get a pointer to a file system object..

    pDbSystem->getFileSystem( &pFileSystem);
 

    See Also:

[Back to Top]


dbCreate

    RCODE dbCreate(

        char *                                     pszDbFileName,

        char *                                     pszDataDir,

        char *                                     pszRflDir,

        char *                                     pszDictFileName,

        char *                                     pszDictBuf,

        XFLM_CREATE_OPTS *    pCreateOpts,

        IF_Db **                               ppDb);

Creates a new XFlaim database.  A pointer to a database object (IF_Db) is returned in the ppDb parameter. The database system engine must first be started using the init method.  After creating a new XFlaim database, the database is open and ready to use.

    Parameters In:

char * pszDbFileName Name of the control file for the database.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszDataDir The directory where the data files are to be created.   If a NULL is passed in, data files will be created in the same directory as the control file (as specified by the pszDbFileName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files.
char * pszRflDir The directory where the RFL (roll forward log) files are to be located.  If a NULL is passed, roll forward log files will reside in the same directory as the control file (as specified by the pszDbFileName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the rfl (Roll-forward log) file.

char * pszDictFileName

Name of file containing dictionary definitions to be imported into the dictionary collection during database creation.  Note that this parameter is ignored if pzDictBuf is non-NULL.  See the XFlaim Concepts section for more information about the XFlaim Dictionary.
char * pszDictBuf Null-terminated string buffer containing dictionary definitions in external XML format. If the value of this parameter is NULL, pszDictFileName will be used.  If both pszDictFileName and pszDictBuf are NULL, the database will be created with an empty dictionary.  See the XFlaim Concepts section for more information about the XFlaim Dictionary.
XFLM_CREATE_OPTS * pCreateOpts Create options for the database. All members of the structure should be initialized to specify options desired when the database is created.  If NULL is passed as the value of this parameter, default options will be used.  See the glossary for a description of the XFLM_CREATE_OPTS structure and the default value for each field.

    Parameters Out:

IF_Db ** ppDb A pointer to a database object that references the newly created database.

    Example Code:

    XFLM_CREATE_OPTS      createOpts;

    IF_Db *                                  pDb;

    RCODE                                   rc;

 

    memset( &createOpts, 0, sizeof( XFLM_CREATE_OPTS));

 

    // Create a new database and get a database object back.

    if (RC_BAD( rc = pDbSystem->dbCreate( "c:\\db\\xml.db", NULL, NULL, NULL, NULL, &createOpts, &pDb)))
    {
        goto Exit;
    }
 

    See Also: init, exit, dbOpen, dbCopy, dbRebuild, dbRename, dbRemove, dbRestore, dbDup

[Back to Top]


dbOpen

    RCODE dbOpen(

        char *                pszDbFileName,

        char *                pszDataDir,

        char *                pszRflDir,

        IF_Db **          ppDb,

        char *                pszPassword = NULL,

        FLMBOOL       bAllowLimited = FALSE);

The dbOpen method opens an existing database.  A pointer to a database object (IF_Db) is returned in the ppDb parameter.  The database system engine must first be started using the init method.  After opening an XFlaim database, the database is ready to use.

    Parameters In:

char * pszDbFileName Name of the control file for the database that is to be opened.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszDataDir The directory where the data files are located.   If a NULL is passed in, it is assumed that the data files are located in the same directory as the control file (as specified by the pszDbFileName parameter). See the XFlaim Concepts/Database Files for a discussion on the different database files.
char * pszRflDir The directory where the RFL (roll forward log) files are located.  If a NULL is passed, roll forward log files are assumed to reside in the same directory as the control file (as specified by the pszDbFileName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the rfl (Roll-forward log) file.
char * pszPassword Password needed to open the database.  This is only needed if the database key is currently wrapped in a password.
FLMBOOL bAllowLimited Whenever encryption is enabled, a database key is generated and stored inside the database header.  This key is either shrouded in a password or wrapped in the local NICI storage key.  When the database is opened, the key is unwrapped in order to perform other encryption/decryption operations.  If the database key is wrapped in the local NICI storage key, the database cannot be opened on another computer, because that computer will have a different local NICI storage key.  To get around this problem, the dbOpen method allows the database to be opened in "limited" mode.  In limited mode, no attempt is made to unwrap the database key.  Hence, all data that is encrypted is not accessible.  That is what "limited" means - encrypted data cannot be accessed, but all other data can be.  NOTE: If the database key is wrapped in a password, and the password is not known, the application can still open the database in limited mode.

    Parameters Out:

IF_Db ** ppDb A pointer to a database object that references the newly opened database.

    Example Code:

    IF_Db *                pDb = NULL;

    RCODE                rc;

 

    // Open an existing database and get a database object back.

    if (RC_BAD( rc = pDbSystem->dbOpen( "c:\\db\\xml.db", NULL, NULL, NULL, FALSE, &pDb)))
    {
        goto Exit;
    }
 

    See Also: init, exit, dbCreate, dbCopy, dbDup, dbRebuild, dbRename, dbRemove, dbRestore

[Back to Top]


dbCheck

    RCODE dbCheck(

        char *                                   pszDbFileName,

        char *                                   pszDataDir,

        char *                                   pszRflDir,

        FLMUINT                           uiFlags,

        IF_DbInfo **                       ppDbInfo,

        IF_DbCheckStatus *            pDbCheckStatus,

        char *                                   pszPassword);

The dbCheck method will check the database for corruptions.

    Parameters In:

char * pszDbFileName Name of the control file for the database that is to be checked.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszDataDir The directory where the data files are located.   If a NULL is passed in, it is assumed that the data files are located in the same directory as the control file (as specified by the pszDbFileName parameter). See the XFlaim Concepts/Database Files for a discussion on the different database files.
char * pszRflDir The directory where the RFL (roll forward log) files are located.  If a NULL is passed, roll forward log files are assumed to reside in the same directory as the control file (as specified by the pszDbFileName parameters).  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the rfl (Roll-forward log) file.
FLMUINT uiFlags Flags to specify various checking options.  They may be ORed together, and are as follows:
  • XFLM_ONLINE.  Allow index corruptions to be fixed online - during the check.
  • XFLM_DONT_REDO_LOG. Don't recover the database before doing the check
  • XFLM_DONT_RESUME_THREADS.  Suppress starting of background indexing threads if database is opened for the first time.
  • XFLM_DO_LOGICAL_CHECK.  Check indexes for logical consistency with documents.
  • XFLM_SKIP_DOM_LINK_CHECK.  Skip checking of linkages between DOM nodes.
  • XFLM_ALLOW_LIMITED_MODE.  Allow database to be opened in "limited" mode if cannot access encryption keys.
IF_DbCheckStatus * pDbCheckStatus A pointer to an application defined status reporting object.  Methods on this object are used by dbCheck to report progress and corruptions to the calling application.  A NULL may be passed in this parameter.  This object is NOT implemented by XFlaim, but is implemented by the application.  The application must create a class that inherits from the IF_DbCheckStatus interface and implements the pure virtual methods of that interface.
char * pszPassword Password needed to open the database.  This is only needed if the database key is currently wrapped in a password.

    Parameters Out:

IF_DbInfo ** ppDbInfo If a non-NULL ppDbInfo pointer is passed, an IF_DbInfo object will be returned that contains detailed statistical information about the various B-trees in the database.  The information includes things like percent utilization of various blocks at each level in a B-tree, number of keys, etc.  Methods of the IF_DbInfo object provide for retrieval of this information.

    Example Code:

    RCODE                        rc;

    IF_DbInfo *                  pDbInfo = NULL;

    App_DbCheckStatus    checkStatus;

 

    // Note that App_DbCheckStatus is an object that inherits from IF_DbCheckStatus

    // i.e.: class App_DbCheckStatus : public IF_DbCheckStatus{...};

 

    // Would probably want to do some application specific setup of the

    // checkStatus object here.
 

    // Do the check...

    rc = gv_DbSystem.dbCheck( "c:\\db\\xml.db", NULL, NULL, &pDbInfo, &checkStatus, NULL);

    // Display the results...or whatever...

    See Also: dbCreate, dbOpen, dbRebuild

[Back to Top]


dbRebuild

    RCODE dbRebuild(

        char *                                      pszSourceDbFileName,

        char *                                      pszSourceDataDir,

        char *                                      pszDestDbFileName,

        char *                                      pszDestDataDir,

        char *                                      pszDestRflDir,

        char *                                      pszDictFileName,

        XFLM_CREATE_OPTS *     pCreateOpts

        FLMUINT64  *                      pui64TotalNodes,

        FLMUINT64  *                      pui64NodesRecovered,

        FLMUINT64  *                      pui64NodesQuarantined,

        IF_DbRebuildStatus *             pDbRebuild,

        char *                                      pszPassword = NULL);

The dbRebuild method will attempt to reconstruct a database, recovering everything that it can from the blocks of the database.  If any of the documents nodes cannot be recovered cleanly, the document and any questionable nodes will be quarantined.  Some other application can then attempt to restore the quarantined documents using manual intervention.

    Parameters In:

char * pszSourceDbFileName Name of the source control file for the database that is to be rebuilt.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszSourceDataDir The directory where the data files are located.   If a NULL is passed in, it is assumed that the data files are located in the same directory as the control file (as specified by the pszSourceDbFileName parameter). See the XFlaim Concepts/Database Files for a discussion on the different database files.
char * pszDestDbFileName Name of the destination control file for the recovered database.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszDestDataDir The directory where the data files are to be located.   If a NULL is passed in, it is assumed that the data files are to be located in the same directory as the control file (as specified by the pszDestDbFileName parameter). See the XFlaim Concepts/Database Files for a discussion on the different database files.
char * pszDestRflDir The directory where the RFL (roll forward log) files of the destination database are to be created.  If a NULL is passed, roll forward log files are assumed to reside in the same directory as the control file (as specified by the pszDestDbFileName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the rfl (Roll-forward log) file.
char * pszDictFileName The name of a file containing the dictionary definitions that will be used when rebuilding the database.  A NULL may be passed in this parameter.  In addition to using the definitions specified in this file, dbRebuild will attempt to recover any additional dictionary entries from the dictionary collection.  See XFlaim Concepts / Dictionary for a discussion on the dictionary in XFlaim.
XFLM_CREATE_OPTS * pCreateOpts Create options for the database. All members of the structure should be initialized to specify options desired when the database is created.  If NULL is passed as the value of this parameter, default options will be used.  See the glossary for a description of the XFLM_CREATE_OPTS structure and the default value for each field.
IF_DbRebuildStatus * pDbRebuild A pointer to an application defined status reporting object.  Methods on this object are used by dbRebuild to report progress during the rebuild.  A NULL may be passed in this parameter.  This object is NOT implemented by XFlaim, but is implemented by the application.  The application must create a class that inherits from the IF_DbRebuildStatus interface and implements the pure virtual methods of that interface.
char * pszPassword Password needed to extract the database key from the source database.  This is only needed if the database key is currently wrapped in a password.

    Parameters Out:

FLMUINT64  * pui64TotalNodes The total number of DOM nodes.
FLMUINT64  * pui64NodesRecovered The total number of DOM nodes recovered.
FLMUINT64  * pui64NodesQuarantined The total number of DOM nodes quarantined.

    Example Code:

    RCODE                           rc;

    FLMUINT64                   ui64TotalNodes;

    FLMUINT64                   ui64NodesRecovered;

    FLMUINT64                   ui64NodesQuarantined;

    App_DbRebuildStatus    rebuildStatus;

 

    // Note that App_DbRebuildStatus is an object that inherits from IF_DbRebuildStatus

    // i.e.: class App_DbRebuildStatus : public IF_DbRebuildStatus{...};

 

    // Would probably want to do some application specific setup of the

    // rebuildStatus object here.
 

    // Do the rebuild...

    rc = gv_DbSystem.dbRebuild( "c:\\db\\xml.db", NULL, "c:\\db_rebuild\\xml.db", NULL, NULL,

                                                     NULL, NULL, &uiTotalNodes, &uiNodesRecovered,

                                                     &uiNodesQuarantined, &rebuildStatus, NULL);

    // Display the results...or whatever...

    See Also: dbCreate, dbOpen, dbCheck, dbRename

[Back to Top]


dbCopy

    RCODE dbCopy(

        char *                        pszSrcDbName,

        char *                        pszSrcDataDir,

        char *                        pszSrcRflDir,

        char *                        pszDestDbName,

        char *                        pszDestDataDir,

        char *                        pszDestRflDir,

        IF_DbCopyStatus *  pStatus);

Copies a database to a new database.  The destination database will be created if it does not exist and overwritten if it does exist.

    Parameters In:

char * pszSrcDbName Name of the control file for the database that is to be copied.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszSrcDataDir The directory where the source database's data files are located.   If a NULL is passed in, it is assumed that the source database's data files are located in the same directory as the source database's control file (as specified by the pszSrcDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files.
char * pszSrcRflDir The directory where the RFL (roll forward log) files of the source database are located.  If a NULL is passed, the roll forward log files of the source database are assumed to reside in the same directory as the source database's control file (as specified by the pszSrcDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the rfl (Roll-forward log) file.
char * pszDestDbName Name of the control file for the destination database.  If the destination database already exists, it will be overwritten.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszDestDataDir The directory where the destination database's data files are to be stored.   If a NULL is passed in, the destination database's data files will be put in the same directory as the destination database's control file (as specified by the pszDestDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files.
char * pszDestRflDir The directory where the RFL (roll forward log) files of the destination database are to be put.  If a NULL is passed, the roll forward log files of the destination database will be put in the same directory as the destination database's control file (as specified by the pszDestDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the rfl (Roll-forward log) file.
IF_DbCopyStatus * pStatus A pointer to an application defined status reporting object.  Methods on this object are used by dbCopy to report progress during the copy.  A NULL may be passed in this parameter.  This object is NOT implemented by XFlaim, but is implemented by the application.  The application must create a class that inherits from the IF_DbCopyStatus interface and implements the pure virtual methods of that interface.  Those methods may be called by dbCopy to report copy progress.

    Parameters Out: none.

    Example Code:

    App_DbCopyStatus    copyStatus;

    RCODE                           rc;

 

    // Note that App_DbCopyStatus is an object that inherits from

    //  IF_DbCopyStatus

    // i.e.: class App_DbCopyStatus : public IF_DbCopyStatus{...};

 

 

    // Would probably want to do some application specific setup of the

    // copyStatus object here.
   .

    .

 

    // Copy an existing database to a new database.

    if (RC_BAD( rc = pDbSystem->dbCopy( "c:\\db\\xml.db", NULL, NULL,

                                                                            "c:\\db_backup\\xml.db", NULL, NULL, &copyStatus)))

    {
        goto Exit;
    }
 

    See Also: init, exit, dbCreate, dbOpen, dbRename, dbRemove, dbRestore

[Back to Top]


dbRename

    RCODE dbRename (

        char *                            pszDbName,
        char *                            pszDataDir,
        char *                            pszRflDir,
        char *                            pszNewDbName,
        FLMBOOL                   bOverwriteDestOk,
        IF_DbRenameStatus *   pStatus);

This method will rename an existing database to a specified new name.

    Parameters In:

char * pszDbName Name of the control file for the database that is to be renamed.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszDataDir The directory where the database's data files are located.   If a NULL is passed in, it is assumed that the data files are located in the same directory as the control file (as specified by the pszDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files.
char * pszRflDir The directory where the RFL (roll forward log) files of the database are located.  If a NULL is passed, the roll forward log files of the database are assumed to reside in the same directory as the control file (as specified by the pszDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the RFL (Roll-forward log) file.
char * pszNewDbName Name the control file is to be renamed to.  This name also determines what data files and RFL files will be renamed to.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.  Note that the directory of the new database name must be the same as the directory specified in pszDbName.
FLMBOOL bOverwriteDestOk If pszNewDbName specifies the name of a file that already exists, this flag indicates whether that file should be deleted so that the rename can proceed.  If FALSE, the rename will fail.
IF_DbRenameStatus * pStatus A pointer to an application defined status reporting object.  Methods on this object are used by dbRename to report progress during the rename.  A NULL may be passed in this parameter.  This object is NOT implemented by XFlaim, but is implemented by the application.  The application must create a class that inherits from the IF_DbRenameStatus interface and implements the pure virtual methods of that interface.

    Parameters Out: none.

    Example Code:

    App_DbRenameStatus    renameStatus;

    RCODE                               rc;

 

    // Note that App_DbRenameStatus is an object that inherits from

    //  IF_DbRenameStatus

    // i.e.: class App_DbRenameStatus : public IF_DbRenameStatus{...};

 

 

    // Would probably want to do some application specific setup of the

    // renameStatus object here.
   .

    .

    .

    // Rename an existing database to a new database.

    if (RC_BAD( rc = pDbSystem->dbRename( "c:\\db\\xml.db", NULL, NULL,

                                                                                 "c:\\db\\new.db", TRUE, &renameStatus)))

    {
        goto Exit;
    }

    See Also: init, exit, dbCreate, dbOpen, dbCopy, dbRemove, dbRestore

[Back to Top]


dbRemove

    RCODE dbRemove (

        char *                 pszDbName,
        char *                 pszDataDir,
        char *                 pszRflDir,
        FLMBOOL        bRemoveRflFiles);

This method will remove (delete) an existing database.

    Parameters In:

char * pszDbName Name of the control file for the database that is to be removed.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszDataDir The directory where the database's data files are located.   If a NULL is passed in, it is assumed that the data files are located in the same directory as the control file (as specified by the pszDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files.
char * pszRflDir The directory where the RFL (roll forward log) files of the database are located.  If a NULL is passed, the roll forward log files of the database are assumed to reside in the same directory as the control file (as specified by the pszDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the RFL (Roll-forward log) file.
FLMBOOL bRemoveRflFiles A flag that indicate whether or not the RFL file(s) should be removed as well.

    Parameters Out: none.

    Example Code:

    RCODE                rc;

 

    // Delete an existing database.

    if (RC_BAD( rc = pDbSystem->dbRemove( "c:\\db\\xml.db", NULL, NULL, TRUE)))

    {
        goto Exit;
    }

    See Also: init, exit, dbCreate, dbOpen, dbCopy, dbRename, dbRestore

[Back to Top]


dbRestore

    RCODE dbRestore (

        char *                           pszDbPath,
        char *                           pszDataDir,

        char *                           pszRflDir,
        char *                           pszBackupPath,

        char *                           pszPassword,
        IF_RestoreClient *        pRestoreObj,

        IF_RestoreStatus *       pRestoreStatus);

This method will restore a database from a backup set.  The client is responsible for providing an implementation of the IF_RestoreClient and IF_RestoreStatus interfaces.

    Parameters In:

char * pszDbPath Name of the control file (including path) for the database that is to be restored.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.
char * pszDataDir The directory where the database's data files are located.   If a NULL is passed in, it is assumed that the data files are located in the same directory as the control file (as specified by the pszDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files.

char * pszRflDir

The directory where the RFL (roll forward log) files of the database are located.  If a NULL is passed, the roll forward log files of the database are assumed to reside in the same directory as the control file (as specified by the pszDbName parameter).  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the RFL (Roll-forward log) file.

char * pszBackupPath

The path to the backup file set.

char * pszPassword Password that was specified for the backup.  See IF_Backup::backup,
IF_RestoreClient * pRestoreObj A pointer to an application defined restore client object.  Methods on this object are used by dbRestore to read the backed-up data from the location it is stored in.  The application is responsible for implementing this object.  In this way, an application can have a database restored from virtually any media.

If a NULL is passed in this parameter, pszBackupPath is used to restore from.  Visit: Need to say something about the default backup file set.

IF_RestoreStatus * pRestoreStatus A pointer to an application defined restore status object.  Methods on this object are used by dbRestore to report progress during the restore.  The application is responsible for implementing this object.

    Parameters Out: none.

    Example Code:

    App_RestoreClient     restoreClient;

    App_RestoreStatus    restoreStatus;

    RCODE                          rc;

 

    // Note that App_RestoreClient is a class that inherits from the IF_RestoreClient interface

    // i.e.: class App_RestoreClient : public IF_RestoreClient{...};

 

    // App_RestoreStatus is a class that inherits from the IF_RestoreStatus interface.

    // i.e. class App_RestoreStatus: public IF_RestoreStatus{...};

 

     // Would probably want to do some application specific setup of the

    // restoreClient object and the restoreStatus object here.
   .

    .

    // Restore a database.

    if (RC_BAD( rc = pDbSystem->dbRestore( "c:\\db\\xml.db", NULL, NULL, NULL, NULL, &restoreClient, &restoreStatus)))

    {
        goto Exit;
    }
 

    See Also: dbCreate, dbOpen, IF_Db::backupBegin, IF_Backup::backup, IF_Backup::endBackup

[Back to Top]


dbDup

    RCODE dbDup(

        IF_Db *            pDb,
        IF_Db **          ppDb);

This method will duplicate the IF_Db interface object.  It is similar to the dbOpen method, except that it doesn't take a database file name as input, but takes an already open IF_Db object as input.  The returned IF_Db object is the same as if it had been created by the dbOpen method.  However, calling dbDup is slightly more efficient than calling dbOpen.

Since IF_Db objects cannot be shared between threads (they are not thread-safe), an application would normally have each of its threads call dbOpen to obtain an IF_Db object.  The dbDup method provides an alternative way to create IF_Db objects for multiple threads.  For example, one thread could call dbOpen to obtain the first IF_Db object.  Thereafter, it could call dbDup and pass the created IF_Db objects to different threads.

Although the most common use of dbDup is to create IF_Db objects and pass them to different threads, it is conceivable that one thread might want multiple IF_Db objects on the same database.  The uses for this are probably somewhat exotic.  For example, a single thread using multiple IF_Db objects could have multiple different transactions open simultaneously.

    Parameters In:

IF_Db * pDb The database object to be duplicated.

    Parameters Out:

IF_Db ** ppDb A new database object.

    Example Code:

    IF_Db *                pDb = NULL;

    IF_Db *                pDbDup = NULL;

    RCODE                 rc;

    .

    .

    .

    // Open an existing database and get a database object back.

    if (RC_BAD( rc = pDbSystem->dbOpen( "c:\\db\\xml.db", NULL, NULL, NULL, FALSE, &pDb)))

    {
        goto Exit;
    }

 

    // Duplicate the database object

    if (RC_BAD( rc = pDbSystem->dbDup( pDb, &pDbDup)))
    {
        goto Exit;
    }.

    See Also: init, exit, dbCreate, dbOpen, dbRebuild, dbRename, dbRemove

[Back to Top]


errorString

    char * errorString(

        RCODE             rc);

This method converts an RCODE error number to a string equivalent that can then be printed in a diagnostic log or some other human readable output.

    Parameters In:

RCODE rc The RCODE to be translated.

    Parameters Out: none.

    Example Code:

   .

   .

    // Open an existing database and get a database object back.

    if (RC_BAD( rc = pDbSystem->dbOpen( "c:\\db\\xml.db", NULL, NULL, NULL, FALSE, &pDb)))

    {
        printf( "An error has occurred.  The error is %s.", pDbSystem->errorString( rc));

        goto Exit;
    }

   See Also:

[Back to Top]


checkErrorToStr

    char * checkErrorToStr(

        FLMINT             iCheckErrorCode);

This method converts a check error code number to a string equivalent that can then be printed in a diagnostic log or some other human readable output.

    Parameters In:

FLMINT iCheckErrorCode The check error code to be converted to a string.

    Parameters Out: none.

    Example Code:

   .

   .

    // Get the error string for check error code 1

 

    char * pszErrorCode = pDbSystem->checkErrorToStr( 1);

[Back to Top]


openBufferIStream

    RCODE openBufferIStream(

        FLMBYTE *               pucBuffer,
        FLMUINT                  uiLength,
        IF_PosIStream **       ppIStream);

This method opens a buffered input stream.  The pucBuffer buffer holds that data that is to be streamed through the IF_PosIStream object.  NOTE: The returned IF_PosIStream object's Release() method should be called when the application is done using the object.

    Parameters In:

FLMBYTE * pucBuffer The buffer that will be associated with the input stream.
FLMUINT    uiLength The size of the buffer (bytes).

    Parameters Out:

IF_PosIStream **  ppIStream The input stream object used to read the data in.

    Example Code:

   IF_PosIStream * pBufferIStream = NULL;

   RCODE         rc;

   char  *           pszIndexDef1 =

        "<xflaim:Index "
               " xmlns:xs=\"http://www.w3.org/2001/XMLSchema\""
               " xmlns:xflaim=\"http://www.novell.com/XMLDatabase/Schema\""
               " xs:name=\"Title+Index+Offset\" "
               " xflaim:DictNumber=\"1\"> "
               " <xflaim:ElementComponent "
                        " xs:name=\"title\" "
                        " xflaim:KeyComponent=\"1\" "
                        " xflaim:IndexOn=\"value\"/> "
               " <xflaim:ElementComponent "
                        " xs:name=\"track\" "
                        " xflaim:IndexOn=\"value\"> "
                        " <xflaim:AttributeComponent "
                                " xs:name=\"index\" "
                               " xflaim:KeyComponent=\"2\" "
                               " xflaim:IndexOn=\"value\"/> "
                        " <xflaim:AttributeComponent "
                               " xs:name=\"offset\" "
                               " xflaim:KeyComponent=\"3\" "
                              " xflaim:IndexOn=\"value\"/> "
               " </xflaim:ElementComponent> "
         "</xflaim:Index> ";
   .

   .

   if ( RC_BAD( rc = pDbSystem->openBufferIStream( (FLMBYTE *)pszIndexDef1,
                                                                                               strlen( (char *)pszIndexDef1),
                                                                                               &pBufferIStream)))
   {
       printf( "openBufferIStream failed, rc=%08X.", (unsigned)rc);
      goto Exit;
   }

   if ( RC_BAD( rc = pDb->import( pBufferIStream,
                                                            XFLM_DICT_COLLECTION)))
   {
       printf( "doc #1 import failed, rc=%08X.", (unsigned)rc);
      goto Exit;
   }
   .

   .

 

Exit:

    if (pBufferIStream)

    {

        pBufferIStream->Release();

    }


    See Also: openFileIStream, openBase64Encoder, openBase64Decoder, openMultiFileIStream, openBufferedIStream, openUncompressingIStream

[Back to Top]


openFileIStream

    RCODE openFileIStream(

        char *                          pszPath,
        IF_PosIStream  **      ppIStream);

This method opens a file input stream..  The pszPath parameter points to a file that holds the data that is to be streamed through the IF_PosIStream object.  NOTE: The returned IF_PosIStream object's Release() method should be called when the application is done using the object.

    Parameters In:

char * pszPath The name of file whose data is to be read via the IF_PosIStream object.

    Parameters Out:

IF_PosIStream **  ppIStream The input stream object used to read the data in.

    Example Code:

    IF_PosIStream * pFileIStream = NULL;

    RCODE                rc;

   .
   .

   .

   if ( RC_BAD( rc = pDbSystem->openFileIStream( "Import.xml", &pFileIStream)))
   {
      printf( "openFileIStream failed, rc=%08X.", (unsigned)rc);
      goto Exit;
   }
  
   if ( RC_BAD( rc = pDb->import( pFileIStream,
                                                            XFLM_DATA_COLLECTION)))
   {
       printf( "import failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

   .

   .

Exit:

    if (pFileIStream)

    {

        pFileIStream->Release();

    }


    See Also: openBufferIStream, openBase64Encoder, openBase64Decoder, openMultiFileIStream,openBufferedIStream, openUncompressingIStream

[Back to Top]


openMultiFileIStream

    RCODE openMultiFileIStream(

        const char *        pszDirectory,

        const char *        pszBaseName,

        IF_IStream **    ppIStream);

This method opens a multi-file input stream.  The returned IF_IStream object will read data from the files in the directory (pszDirectory) that match the base name (pszBaseName).  NE_XFLM_EOF is returned when there are no more files to read from.

    Parameters In:

char * pszDirectory The name of the directory that contains the files to be read through.
char * pszBaseName The base name for files in the directory that the stream object is to read.  File names are expected to start with pszBaseName, then pszBaseName.00000001, pszBaseName.00000002, etc.  The extension is a hex number.

    Parameters Out:

IF_IStream **  ppIStream The input stream object is returned here.

    Example Code:

    IF_IStream * pMultiFileIStream = NULL;

    RCODE         rc;

   .
   .

   .

   if ( RC_BAD( rc = pDbSystem->openMultiFileIStream( "ImportDir", "BaseFile", &pMultiFileIStream)))
   {
       printf( "openMultiFileIStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }
  
   .

Exit:

    if (pMultiFileIStream)

    {

        pMultiFileIStream->Release();

    }


    See Also: openFileIStream, openBufferIStream, openBase64Encoder, openBase64Decoder, openBufferedIStream, openUncompressingIStream, removeMultiFileStream

[Back to Top]


openBufferedIStream

    RCODE openBufferedIStream(

        IF_IStream *        pIStream,

        FLMUINT           uiBufferSize,

        IF_IStream **      ppIStream);

This method creates an input stream that buffers the input from another input stream.  The returned IF_IStream object (ppIStream) will read data from the passed in IF_IStream object (pIStream) into an internal buffer of up to uiBufferSize bytes.  This method allows any input stream to be turned into a buffered stream.  However, it is probably most useful when used in conjunction with a file input stream - so that instead of reading one or two bytes at a time from disk, we are reading an entire buffer.

    Parameters In:

IF_IStream  * pIStream The input stream that is to be converted to a buffered input stream.
FLMUINT uiBufferSize The size of the buffer (in bytes) that is to be allocated for buffering input.

    Parameters Out:

IF_IStream **  ppIStream The buffered input stream object is returned here.

    Example Code:

    IF_PosIStream * pFileIStream = NULL;

    IF_IStream *       pBufferedFileIStream = NULL;

    RCODE                rc;

   .
   .

   .

   if ( RC_BAD( rc = pDbSystem->openFileIStream( "Import.xml", &pFileIStream)))
   {
       printf( "openFileIStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

   // Convert pFileIStream to a buffered istream that uses a 32K buffer for reading

 

   if( RC_BAD( rc = pdbSystem->openBufferedIStream( pFileIStream, 32768, &pBufferedFileIStream)))

   {

       printf( "opneBufferedIStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

   if ( RC_BAD( rc = pDb->import( pBufferedFileIStream, XFLM_DATA_COLLECTION)))
   {
       printf( "import failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

  
   .

Exit:

    if (pBufferedFileIStream)

    {

        pBufferedFileIStream->Release();

    }

    if (pFileIStream)

    {

        pFileIStream->Release();

    }


    See Also: openFileIStream, openBufferIStream, openBase64Encoder, openBase64Decoder, openMultiFileIStream, openUncompressingIStream

[Back to Top]


openUncompressingIStream

    RCODE openUncompressingIStream(

        IF_IStream *        pIStream,

        IF_IStream **      ppIStream);

This method creates an input stream that decompresses the input from another input stream.  The returned IF_IStream object (ppIStream) will read data from the passed in IF_IStream object (pIStream) and decompress it.  The pIStream object is assumed to be a stream of data that is compressed.  Note that the compressed data input stream will have been originally created using the openCompressingOStream method.

    Parameters In:

IF_IStream  * pIStream The input stream gives out compressed data when read from.

    Parameters Out:

IF_IStream **  ppIStream The uncompressing input stream object is returned here.

    Example Code:

    IF_PosIStream * pFileIStream = NULL;

    IF_IStream *       pUncompressedIStream = NULL;

    RCODE                rc;

   .
   .

   .

   if ( RC_BAD( rc = pDbSystem->openFileIStream( "compressed.data", &pFileIStream)))
   {
       printf( "openFileIStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

   // The compressed.data file contains compressed data, so in order to read it in uncompressed format, we must convert

   // pFileIStream into an uncompressing input stream.

 

   if( RC_BAD( rc = pdbSystem->openUncompressingIStream( pFileIStream, &pUncompressedIStream)))

   {

       printf( "openUncompressingIStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

   if ( RC_BAD( rc = pDb->import( pUncompressingIStream, XFLM_DATA_COLLECTION)))
   {
       printf( "import failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

  
   .

Exit:

    if (pUncompressedIStream)

    {

        pUncompressedIStream->Release();

    }

    if (pFileIStream)

    {

        pFileIStream->Release();

    }


    See Also: openFileIStream, openBufferIStream, openBase64Encoder, openBase64Decoder, openMultiFileIStream, openBufferedIStream, openCompressingOStream

[Back to Top]


openFileOStream

    RCODE openFileOStream(

        const char *         pszFileName,

        FLMBOOL         bTruncateIfExists,

        IF_OStream **    ppOStream);

This method creates an output stream that writes the output to the file specified in pszFileName.  The file is created if it does not exist.  If it does exist, an error will be returned unless the bTruncateIfExists flag is set to TRUE.

    Parameters In:

const char * pszFileName The name of the file the data written is to be output to.

    Parameters Out:

IF_OStream **  ppOStream The output stream object is returned here.

    Example Code:

    IF_OStream *        pFileOStream = NULL;

    RCODE                   rc;

    IF_DOMNode *    pDocument = NULL;

   .
   .

   .

   if ( RC_BAD( rc = pDbSystem->openFileOStream( "output.xml", TRUE, &pFileOStream)))
   {
       printf( "openFileOStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

    .

    .

    // Assume that pDocument was a document root node that was retrieved from some XFLAIM database by appropriate calls into XFLAIM.

 

    if (RC_BAD( rc = pDbSystem->exportXML( pDocument, pFileOStream, XFLM_EXPORT_INDENT)))

   {

       printf( "exportXML failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

   .

Exit:

    if (pFileOStream )

    {

        pFileOStream ->Release();

    }

    if (pDocument )

    {

        pDocument ->Release();

    }


    See Also: openFileIStream, openMultiFileOStream, openBufferedOStream, openCompressingOStream

[Back to Top]


openMultiFileOStream

    RCODE openMultiFileOStream(

        const char *         pszDirectory,

        const char *         pszBaseName,

        FLMUINT          uiMaxFileSize,

        FLMBOOL         bOkToOverwrite,

        IF_OStream **   ppOStream);

This method creates an output stream that writes the output to multiple files in the directory specified by pszDirectory.  It will create files called pszBaseName, pszBaseName.00000001, pszBaseName.00000002, etc.  A new file is created whenever the maximum file size is reached (as specified in uiMaxFileSize).  The number appended to pszBaseName is a hex number that is incremented for each new file created.  A stream of data written out in this manner may be read in using the openMultiFileIStream method.

    Parameters In:

const char * pszDirectory The name of the directory where the data is to be output.
const char * pszBaseName The base name of files to be created in the directory.
FLMUINT uiMaxFileSize Maximum size (in bytes) that a file can grow to before creating a new output file.
FLMBOOL bOkToOverwrite If set to TRUE, it is ok to overwrite existing files of the same name.

    Parameters Out:

IF_OStream **  ppOStream The output stream object is returned here.

    Example Code:

    IF_OStream *        pFileOStream = NULL;

    RCODE                   rc;

   .
   .

   // Create an output stream that will create files in the BinaryDataDir directory named LargeDataFile, LargeDataFile.00000001, LargeDataFile.00000002, etc.

   // A new file will be created for every 10 megabytes of data written.

 

   if ( RC_BAD( rc = pDbSystem->openMultiFileOStream( "BinaryDataDir", "LargeDataFile", 10000000, TRUE, &pFileOStream)))
   {
       printf( "openMultiFileOStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

    .

    .

    // Loop below will write out 20,000,000 bytes of zeroes - causing two files to be created in the output directory.

 

    for (uiLoop = 0; uiLoop < 20000; uiLoop++)

    {

        char            szBuffer [1000];

 

        memset( szBuffer, 0, sizeof( szBuffer));

 

      if (RC_BAD( rc = pFileOStream->write( szBuffer, sizeof( szBuffer), NULL)))

      {

          printf( "write failed, rc=%08X.", (unsigned)rc);
          goto Exit;
      }

 

   .

Exit:

    if (pFileOStream )

    {

        pFileOStream ->Release();

    }


    See Also: openFileOStream, openMultiFileIStream, openBufferedOStream, openCompressingOStream, removeMultiFileStream

[Back to Top]


removeMultiFileStream

    RCODE removeMultiFileStream(

        const char *    pszDirectory,

        const char *    pszBaseName);

This method removes a multi file stream that was created using openMultiFileOStream.

    Parameters In:

const char * pszDirectory This is the directory where the multi-file stream was created - see openMultiFileOStream.
const char * pszBaseName This is the base name of the files in the directory.  Files to be removed will be pszBaseName, pszBaseName.00000001, pszBaseName.00000002, etc.

    Example Code:

   RCODE rc;

 

   if ( RC_BAD( rc = pDbSystem->removeMultiFileStream( "ImportDir", "BaseFile")))
   {
       printf( "removeMultiFileStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }
  
   .

Exit:


    See Also: openMultiFileIStream, openMultiFileOStream.

[Back to Top]


openBufferedOStream

    RCODE openBufferedOStream(

        IF_OStream *      pOStream,

        FLMUINT           uiBufferSize,

        IF_OStream **    ppOStream);

This method creates an output stream that buffers the output from another output stream.  The returned IF_OStream object (ppOStream) will write data to a buffer and fill the buffer before writing it out to the passed in IF_OStream object (pOStream).  It will fill up to uiBufferSize bytes before writing out to the pOStream object.  This method allows any output stream to be turned into a buffered stream.  However, it is probably most useful when used in conjunction with a file output stream - so that instead of writing one or two bytes at a time to disk, we are writing an entire buffer.

    Parameters In:

IF_OStream * pOStream The output stream that is to be buffered in front of.
FLMUINT uiBufferSize Size of the buffer to be used for buffering.

    Parameters Out:

IF_OStream **  ppOStream The buffering output stream object is returned here.

    Example Code:

    IF_OStream *        pFileOStream = NULL;

    IF_OStream *        pBufferedFileOStream = NULL;

    RCODE                   rc;

    IF_DOMNode *    pDocument = NULL;

   .
   .

   .

   if ( RC_BAD( rc = pDbSystem->openFileOStream( "output.xml", TRUE, &pFileOStream)))
   {
       printf( "openFileOStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

    // Make it into a buffered output stream.  Buffer size of 32K

 

    if (RC_BAD( rc = pDbSystem->openBufferedOStream( pFileOStream, 32768, &pBufferedFileOStream)))

    {

       printf( "openBufferedOStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
    }

    .

    .

    // Assume that pDocument was a document root node that was retrieved from some XFLAIM database by appropriate calls into XFLAIM.

 

    if (RC_BAD( rc = pDbSystem->exportXML( pDocument, pBufferedFileOStream, XFLM_EXPORT_INDENT)))

   {

       printf( "exportXML failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

   .

Exit:

    if (pFileOStream )

    {

        pFileOStream ->Release();

    }

    if (pBufferedFileOStream)

    {

        pBufferedFileOStream->Release();

    }

    if (pDocument )

    {

        pDocument ->Release();

    }


    See Also: openFileOStream, openMultiFileOStream, openCompressingOStream

[Back to Top]


openCompressingOStream

    RCODE openCompressingOStream(

        IF_OStream *      pOStream,

        IF_OStream **    ppOStream);

This method creates an output stream that compresses data before it is output to another output stream.  The returned IF_OStream object (ppOStream) will compress data written to it before passing it on to the passed in IF_OStream object (pOstream).  Note that the compressed output data may be read back in using an uncompressing input stream (see openUncompressingIStream).

    Parameters In:

IF_OStream * pOStream The output stream that will be called to write out the compressed data.

    Parameters Out:

IF_OStream **  ppOStream The compressing output stream is returned here.  Data written to this object is compressed before it is written out to the pOStream object.

    Example Code:

    IF_OStream *        pFileOStream = NULL;

    IF_OStream *        pCompressedFileOStream = NULL;

    RCODE                   rc;

    IF_DOMNode *    pDocument = NULL;

   .
   .

   .

   if ( RC_BAD( rc = pDbSystem->openFileOStream( "compressed_output.xml", TRUE, &pFileOStream)))
   {
       printf( "openFileOStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

    // Make it into a compressed output stream.

 

    if (RC_BAD( rc = pDbSystem->openCompressingOStream( pFileOStream, &pCompressedFileOStream)))

    {

       printf( "openCompressingOStreamfailed, rc=%08X.", (unsigned)rc);
       goto Exit;
    }

    .

    .

    // Assume that pDocument was a document root node that was retrieved from some XFLAIM database by appropriate calls into XFLAIM.

 

    if (RC_BAD( rc = pDbSystem->exportXML( pDocument, pCompressedFileOStream, XFLM_EXPORT_INDENT)))

   {

       printf( "exportXML failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

   .

Exit:

    if (pFileOStream )

    {

        pFileOStream ->Release();

    }

    if (pCompressedFileOStream)

    {

        pCompressedFileOStream->Release();

    }

    if (pDocument )

    {

        pDocument ->Release();

    }


    See Also: openFileOStream, openMultiFileOStream, openBufferedOStream, openUncompressingIStream

[Back to Top]


writeToOStream

    RCODE writeToOStream(

        IF_IStream *      pIStream,

        IF_OStream *    pOStream);

This method reads the input from an input stream (pIStream) and writes it to an output stream (pOStream).

    Parameters In:

IF_IStream * pIStream The input stream the data is read from.
IF_OStream * pOStream The output stream the data is written to.

    Example Code:

    IF_PosIStream *   pFileIStream = NULL;

    IF_OStream *        pFileOStream = NULL;

    IF_OStream *        pCompressedFileOStream = NULL;

    RCODE                   rc;

   .
   .

   .

   // The following code reads the input.xml file, compresses it, and writes it out to compressed_output.xml file.

 

   if (RC_BAD( rc = pDbSystem->openFileIStream( "input.xml", &pFileIStream)))

   {
       printf( "openFileIStreamfailed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

 

   if ( RC_BAD( rc = pDbSystem->openFileOStream( "compressed_output.xml", TRUE, &pFileOStream)))
   {
       printf( "openFileOStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

    // Make it into a compressed output stream.

 

    if (RC_BAD( rc = pDbSystem->openCompressingOStream( pFileOStream, &pCompressedFileOStream)))

    {

       printf( "openCompressingOStreamfailed, rc=%08X.", (unsigned)rc);
       goto Exit;
    }

    .

    .

    // Assume that pDocument was a document root node that was retrieved from some XFLAIM database by appropriate calls into XFLAIM.

 

    if (RC_BAD( rc = pDbSystem->writeToOStream( pFileIStream, pCompressedFileOStream)))

   {

       printf( "writeToOStreamfailed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

   .

Exit:

    if (pFileIStream)

    {

       pFileIStream->Release();

    }

    if (pFileOStream )

    {

        pFileOStream ->Release();

    }

    if (pCompressedFileOStream)

    {

        pCompressedFileOStream->Release();

    }


    See Also: openFileOStream, openFileIStream, and other input and output stream methods.

[Back to Top]glossary.htm#flmbool


openBase64Encoder

    RCODE openBase64Encoder(

        IF_IStream  *             pInputStream,

        FLMBOOL                bInsertLineBreaks,

        IF_IStream  **           ppEncodedStream);

This method opens a stream for encoding a user-supplied input stream to base64 (ASCII).file input stream.  The pInputStream parameter is the stream that is to be output as base64.  The base64 output can be read from the *ppEncodedStream object.   NOTE: The returned IF_IStream object's Release() method should be called when the application is done using the object.

    Parameters In:

IF_IStream  * pInputStream The input stream that is to be converted to base 64.
FLMBOOL bInsertLineBreaks If TRUE, a line break will be inserted into the base 64 output every 72 characters.

    Parameters Out:

IF_IStream  ** ppEncodedStream The stream object used to read out the encoded data.

    Example Code:

    IF_PosIStream * pFileIStream = NULL;

    IF_IStream *       pEncodedStream = NULL;

    RCODE                rc;

   .
   .

   .

   if ( RC_BAD( rc = pDbSystem->openFileIStream( "Import.xml", &pFileIStream)))
   {
       printf( "openFileIStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }
  
   if ( RC_BAD( rc = pDbSystem->openBase64Encoder( pFileIStream, TRUE, &pEncodedStream)))
   {
       printf( "openBase64Encoder failed, rc=%08X.", (unsigned)rc);
      goto Exit;
   }

   .

   .

Exit:

    if (pFileIStream)

    {

        pFileIStream->Release();

    }

   if (pEncodedStream)

   {

       pEncodedStream->Release();

   }


    See Also: openBufferIStream, openFileIStream, openBase64Decoder, openMultiFileIStream, openBufferedIStream, openUncompressingIStream

[Back to Top]


openBase64Decoder

    RCODE openBase64Decoder(

        IF_IStream  *             pEncodedInputStream,

        IF_IStream  **           ppDecodedStream);

This method opens a stream for decoding a user-supplied base-64 encoded input stream.  The pEncodedInputStream parameter is the stream that is to be decocoded.  The decoded output can be read from the *ppDecodedStream object.   NOTE: The returned IF_IStream object's Release() method should be called when the application is done using the object.

    Parameters In:

IF_IStream  * pEncodedInputStream The base-64 encoded input stream that is to be decoded.

    Parameters Out:

IF_IStream  ** ppDecodedStream The stream object used to read out the decoded data.

    Example Code:

    IF_PosIStream * pFileIStream = NULL;

    IF_IStream *       pEncodedStream = NULL;

    IF_IStream *       pDecodedStream = NULL;

    RCODE                rc;

   .
   .

   .

   if ( RC_BAD( rc = pDbSystem->openFileIStream( "Import.xml", &pFileIStream)))
   {
       printf( "openFileIStream failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }
  
   if ( RC_BAD( rc = pDbSystem->openBase64Encoder( pFileIStream, TRUE, &pEncodedStream)))
   {
       printf( "openBase64Encoder failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

 

   // pDecodedStream should return the contents of the Import.xml file.

 

   if ( RC_BAD( rc = pDbSystem->openBase64Decoder( pEncodedStream, TRUE, &pDecodedStream)))
   {
       printf( "openBase64Decoder failed, rc=%08X.", (unsigned)rc);
       goto Exit;
   }

   .

   .

Exit:

    if (pFileIStream)

    {

        pFileIStream->Release();

    }

   if (pEncodedStream)

   {

       pEncodedStream->Release();

   }

   if (pDecodedStream)

   {

       pDecodedStream->Release();

   }


    See Also: openBufferIStream, openFileIStream, openBase64Encoder, openMultiFileIStream, openBufferedIStream, openUncompressingIStream

[Back to Top]


createIFDataVector

    RCODE createIFDataVector(

        IF_DataVector **         ppDataVector);

This method creates an IF_DataVector interface object.  The IF_DataVector is used in index key searches.

    Parameters In: none.

    Parameters Out:

IF_DataVector ** ppDataVector The IF_DataVector object.

    Example Code:

    IF_DataVector *    pSearchKey = NULL;

    RCODE                   rc;

   .
   .

   .

   if (RC_BAD( rc = pDbSystem->createIFDataVector( &pSearchKey)))
   {
      goto Exit;
   }
   if (RC_BAD( rc = pSearchKey->setUINT( 0, (FLMUINT)ui32EntryID)))
   {
      goto Exit;
   }
   if (RC_BAD( rc = pDb()->keyRetrieve( uiCacheEntryIDIndex,
                                                                        pSearchKey,

                                                                        XFLM_EXACT,

                                                                        pSearchKey)))
   {
      if (rc == NE_XFLM_NOT_FOUND)
      {
         rc = NE_XFLM_OK;
      }
      goto Exit;
   }
   .
   .


    See Also:

[Back to Top]


createIFResultSet

    RCODE createIFResultSet(

        IF_ResultSet **         ppResultSet);

This method creates an IF_ResultSet interface object.

    Parameters In: none.

    Parameters Out:

IF_ResultSet ** ppResultSet The IF_ResultSet object.

    Example Code:

    IF_ResultSet *    pResultSet = NULL;

    RCODE                rc

   .
   .

   .

   if (RC_BAD( rc = pDbSystem->createIFResultSet( &pResultSet)))
   {
      goto Exit;
   }
  
   .
   .


    See Also:

[Back to Top]


createIFQuery

    RCODE createIFQuery(

        IF_Query **         ppQuery);

This method creates an IF_Query interface object.

    Parameters In: none.

    Parameters Out:

IF_Query ** ppQuery The IF_Query object.

    Example Code:

    IF_Query *   pQuery = NULL;

    RCODE        rc

   .
   .

   .

   if (RC_BAD( rc = pDbSystem->createIFQuery( &pQuery)))
   {
      goto Exit;
   }
   .
   .


    See Also:

[Back to Top]


freeMem

    void freeMem(

        void **    ppvMem);

This method frees memory that has been allocated by various methods in XFlaim.  If a method allocates memory that needs to be freed by this method, it will be documented in that method.

    Parameters In and Out:

void ** ppvMem Pointer to the pointer of the memory to be freed.  When the memory is successfully freed, the pointer will be set to NULL

    Example Code:

    IF_Query *                     pQuery = NULL;

    XFLM_OPT_INFO *    pOptInfo = NULL;

    FLMUINT                      uiOptCount;

    RCODE                           rc;

   .
   .

   .

   if (RC_BAD( rc = pDbSystem->createIFQuery( &pQuery)))
   {
      goto Exit;
   }

    . // Set up query, do various query operations, etc. here
   .
   .

    // When query has completed, get the statistics and information about the query

 

    if (RC_BAD( rc = pQuery->getStatsAndOptInfo( &uiOptCount, &pOptInfo)))

    {

        goto Exit;

    }

 

    // display the information returned in pOptInfo here.

    .

    .

    // Free the memory that was allocated by the call to getStatsAndOptInfo

 

    pDbSystem->freeMem( (void **)&pOptInfo);


    See Also:

[Back to Top]


setDynamicMemoryLimit

    RCODE setDynamicMemoryLimit(

        FLMUINT         uiCacheAdjustPercent,
        FLMUINT         uiCacheAdjustMin,
        FLMUINT         uiCacheAdjustMax,
        FLMUINT         uiCacheAdjustMinToLeave);

This method sets the dynamic memory parameters in the XFlaim database system.  When this method is called, XFlaim is put into a mode where it periodically (every 15 seconds unless otherwise specified - see setCacheAdjustInterval) adjusts its cache limit.  The parameters passed into this method are used to calculate the new limit.  The new limit remains in effect until the next adjustment is made.

    Parameters In:

FLMUINT uiCacheAdjustPercent Percentage of available physical memory to set or adjust to.
FLMUINT uiCacheAdjustMin Minimum bytes to adjust down to.
FLMUINT uiCacheAdjustMax Maximum bytes to adjust up to.  NOTE: If this parameter is non-zero, the uiCacheAdjustMinToLeave parameter is ignored.
FLMUINT uiCacheAdjustMinToLeave Minimum bytes to leave available after making adjustment.  This is an alternative way to specify a maximum to adjust to.  Using this value, XFlaim will calculate the maximum by subtracting this number from the total bytes it thinks is available.  That calculated number becomes the effective maximum to adjust to.

    Parameters Out: none.

    Example Code:

    if (bDynamicCacheAdjust)
    {
        if (RC_BAD( rc = pDbSystem->setDynamicMemoryLimit( uiCachePercent,
                                                                                                   uiCacheMin, uiCacheMax,
                                                                                                   uiCacheMinToLeave)))
        {
            goto Exit;
        }
    }
    else
    {
        if (RC_BAD( rc = pDbSystem->setHardMemoryLimit( uiCachePercent,
                                                                                             bCalcLimitOnAvail,
                                                                                             uiCacheMin,
                                                                                             uiCacheMax,
                                                                                             uiCacheMinToLeave)))
        {
            goto Exit;
        }
    }
 


    See Also: setHardMemoryLimit, getCacheInfo, setCacheAdjustInterval, getCacheAdjustInterval

[Back to Top]


setHardMemoryLimit

    RCODE setHardMemoryLimit(

        FLMUINT        uiPercent,
        FLMBOOL       bPercentOfAvail,
        FLMUINT         uiMin,
        FLMUINT         uiMax,

        FLMUINT         uiMinToLeave,

        FLMBOOL        bPreallocate = FALSE);

This method sets a hard limit on the amount of memory that the database system can access.  The important difference between this routine and the setDynamicMemoryLimit routine is that the limit remains in force until a subsequent call to setHardMemoryLimit is made, or until a call to setDynamicMemoryLimit is made.  The setDynamicMemoryLimit routine, on the other hand, puts XFlaim into a mode where a new limit is automatically calculated on a preset interval (see setCacheAdjustInterval).  Thus, the purpose of the setHardMemoryLimit routine is to let the application control the limit instead of having it automatically adjusted periodically.

    Parameters In:

FLMUINT uiPercent If this parameter is zero, the uiMax parameter determines the hard cache limit.  Otherwise, this parameter (which must contain a number between 1 and 100) is used to determine a hard cache limit.  The hard limit will be calculated as a percentage of available physical memory on the system.
FLMUINT bPercentOfAvail A flag to indicate that the percentage (uiPercent) is to be interpreted as a percentage of available memory as opposed to a percentage of all of physical memory.  This parameter is only used if uiPercent is non-zero.
FLMUINT uiMin Minimum bytes to set the hard cache limit to.  Note that this parameter is only used if uiPercent is non-zero and we are calculating a hard limit to set.
FLMUINT uiMax Maximum bytes to set the hard limit to.  Note that if uiPercent is zero, this number contains the hard limit.
FLMUINT uiMinToLeave This parameter is only used if uiPercent is non-zero and we are calculating a hard limit to set.  Instead of uiMax determining the maximum cache limit we could set, this value will determine the maximum.  This number will be subtracted from the total memory on the system or the total memory currently available (if bPercentOfAvail is TRUE) to establish a maximum.
FLMBOOL bPreallocate This parameter, if TRUE, tells XFLAIM to preallocate the cache instead of allocating it on demand as database operations happen.  Cache is allocated in 64K slabs.  When cache is pre-allocated, XFLAIM allocates all of the 64k slabs immediately (up to the limit specified) rather than on demand.  The reason an application might want to do this is so that XFLAIM's cache slabs will not get intermixed with memory allocations that other components of the process may be requesting and thus spread all over the virtual address space - which is what tends to happen when they are allocated on demand.  If preallocated, it is more likely that the cache slabs will be in contiguous memory.  When XFLAIM's cache gets spread all over the virtual address space, it can cause fragmentation over time, because the process ends up with long term memory allocations (cache slabs) being mixed with the more traditional short term allocations that most software components tend to use.  It should be obvious that in order for this parameter to be effective, the setHardMemoryLimit method must be called early on when the program first starts up - before other memory allocations have been done. -- This is really only needed for server-type applications that are going to be running more or less continuously - servicing requests from clients that are going to trigger accessess to an XFLAIM database.

    Parameters Out: none.

    Example Code:

    if (bDynamicCacheAdjust)
    {
        if (RC_BAD( rc = pDbSystem->setDynamicMemoryLimit( uiCachePercent,
                                                                                                   uiCacheMin, uiCacheMax,
                                                                                                   uiCacheMinToLeave)))
        {
            goto Exit;
        }
    }
    else
    {
        if (RC_BAD( rc = pDbSystem->setHardMemoryLimit( uiCachePercent,
                                                                                             bCalcLimitOnAvail,
                                                                                             uiCacheMin,
                                                                                             uiCacheMax,
                                                                                             uiCacheMinToLeave)))
        {
            goto Exit;
        }
    }

 


    See Also: setDynamicMemoryLimit, getCacheInfo, setCacheAdjustInterval, getCacheAdjustInterval

[Back to Top]


getDynamicCacheSupported

    FLMBOOL getDynamicCacheSupported( void);

This method returns TRUE if dynamic cache limits are supported, FALSE if not.  TRUE means that the database system is able to dynamically adjust cache limits, and that the setDynamicMemoryLimit method can be used.  FALSE means it cannot.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

   RCODE  rc;

 

   if ( pDbSystem->getDynamicCacheSupported())

   {
      rc = pDbSystem->setDynamicMemoryLimit( 50, 16000000, 500000000, 20000000);
   }


    See Also: setDynamicMemoryLimit

[Back to Top]


getCacheInfo

    void getCacheInfo(

        XFLM_CACHE_INFO *             pCacheInfo);

This method is used to query the database system for information regarding the current cache usage.

    Parameters In: none.

    Parameters Out:

XFLM_CACHE_INFO * pCacheInfo The cache usage structure.

    Example Code:

    XFLM_CACHE_INFO         CacheInfo;
    .

    .

    .
    pDbSystem->getCacheInfo( &CacheInfo);

    .

    .

    if (CacheInfo.bDynamicCacheAdjust)
    {
        uiCacheAdjustPercent = CacheInfo.uiCacheAdjustPercent;
        uiCacheAdjustMin = CacheInfo.uiCacheAdjustMin;
        uiCacheAdjustMax = CacheInfo.uiCacheAdjustMax;
        uiCacheAdjustMinToLeave = CacheInfo.uiCacheAdjustMinToLeave;
        bDynamicCacheAdjust = true;
    }
    else
    {
        uiCacheAdjustPercent = 0;
        uiCacheAdjustMin = 0;
        uiCacheAdjustMax = CacheInfo.uiMaxBytes;
        uiCacheAdjustMinToLeave = 0;
        bDynamicCacheAdjust = false;
    }
    .

    .
    .


    See Also: setDynamicMemoryLimit, setHardMemoryLimit

[Back to Top]


enableCacheDebug

    void enableCacheDebug(

        FLMBOOL             bDebug);

This is a method to either enable or disable cache debug mode.  If bDebug is TRUE (1), then cache debug will be enabled.  If bDebug is FALSE (0), cache debug will be disabled.

    Parameters In: none.

    Parameters Out:

FLMBOOL  bDebug A boolean to indicate whether to enable or disable cache debug mode.

    See Also: cacheDebugEnabled

[Back to Top]


cacheDebugEnabled

    FLMBOOL cacheDebugEnabled( void);

This is a method to find out if cache debug mode is either enabled or disabled.

    Parameters In: none.

    Parameters Out: none.

    See Also: enableCacheDebug

[Back to Top]


closeUnusedFiles

    RCODE closeUnusedFiles(

        FLMUINT    uiSeconds);

This is a method to close all file handles (descriptors) that have not been used or accessed for a specified number of seconds.

    Parameters In:

FLMUINT uiSeconds The number of seconds.  File handles (descriptors) that have been unused for a period of time greater than or equal to this number of seconds will be closed.  A value of zero will have the effect of closing all unused file handles (descriptors), regardless of how long they have been unused.

    Parameters Out: none.

    Example Code:

    .

    .

    // try to close any files currently open
    if ( RC_BAD( rc = pDbSystem->closeUnusedFiles(0)))
    {
        goto Exit;
    }
    .

    .


    See Also: setOpenThreshold, getOpenThreshold, getOpenFileCount

[Back to Top]


setOpenThreshold

    void setOpenThreshold(

        FLMUINT             uiThreshold);

This is a method to set the maximum number of file handles (descriptors) that can be kept open by the database system.

    Parameters In:

FLMUINT uiThreshold The number of file handles (descriptors) that can be open at any one time. The default threshold is 65535.  IMPORTANT NOTE: It is possible for the database system to temporarily have more file handles (descriptors) open than the specified threshold.  It does this when all available file handles (descriptors) are in use and it needs to open a file to perform database work.  However, as soon as it can, the database system will close file handles (descriptors) until it comes back down below the specified threshold.

    Parameters Out: none.

    Example Code:

 

    // Set the open threshhold to 1000 file handles

    pDbSystem->setOpenThreshold( 1000);
 

    See AlsocloseUnusedFiles, getOpenThreshold, getOpenFileCount

[Back to Top]


getOpenThreshold

    FLMUINT getOpenThreshold( void);

This method returns the threshold for the number of file handles (descriptors) that can be held open by the database system.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    FLMUINT                uiMaxOpenFileHandles;

 

    // Get the open threshhold limit

    uiMaxOpenFileHandles = pDbSystem->getOpenThreshold();
 

    See Also: closeUnusedFiles, setOpenThreshold, getOpenFileCount

[Back to Top]


getOpenFileCount

    FLMUINT getOpenFileCount( void);

This method returns the number of file handles (descriptors) that are currently open in the database system.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    FLMUINT                uiNumOpenFileHandles;

 

    // Get the number of currently open file handles

    uiNumOpenFileHandles = pDbSystem->getOpenFileCount();
 

  See Also: closeUnusedFiles, setOpenThreshold, getOpenThreshold

[Back to Top]


startStats

    void startStats( void);

This method starts the collection of statistics on the database system.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    IF_DbSystem *        pDbSystem = NULL;

    XFLM_STATS            flmStats;

    RCODE                    rc;

 

    // Create an instance of the DbSystem interface first.

    if (RC_BAD( rc = PsaComCreateInstance( CLSID_F_DbSystemFactory,
                                                                               NULL,

                                                                               IID_IF_DbSystem,

                                                                               (void **)&pDbSystem)))
    {
        goto Exit;
    }

 

    // Startup the database system.
    if( RC_BAD( pDbSystem->init()))
    {
        goto Exit;
    }

 

    // Start statistics collection

    pDbSystem->startStats();

 

    for (;;)

    {

 

        if (test if system is shutting down)

        {

            break;

        }

 

        // Allow stuff to happen on other threads for 30 seconds.

 

        sleep( 30);

 

        // Get the statistics so they can be displayed

        if (RC_BAD( rc = pDbSystem->getStats( &flmStats)))

        {

            goto Exit;

        }

 

        // display the statistics - or whatever.

 

        // free the statistics collected

 

        pDbSystem->freeStats( &flmStats);

 

        // Reset the statistics for the next 30 second time period.

 

        pDbSystem->resetStats();

    }

.

    // Stop collecting statistics

    pDbSystem->stopStats();

 

   See Also: stopStats, resetStats, getStats, freeStats

[Back to Top]


stopStats

    void stopStats( void);

This method stops the collection of statistics on the database system.

    Parameters In: none.

    Parameters Out: none.

    Example Code: see startStats

    See Also: startStats, resetStats, getStats, freeStats

[Back to Top]


resetStats

    void resetStats( void);

This method resets the statistics counters on the database system.

    Parameters In: none.

    Parameters Out: none.

    Example Code: see startStats

    See Also: startStats, stopStats, getStats, freeStats

[Back to Top]


getStats

    RCODE getStats(

        XFLM_STATS *         pFlmStats);

This method returns the current set of statistics from the database system.

    Parameters In: none.

    Parameters Out:

XFLM_STATS * pFlmStats The structure where statistics are returned.

    Example Code: see startStats

    See Also: startStats, stopStats, resetStats, freeStats

[Back to Top]


freeStats

    void freeStats(

        XFLM_STATS *         pFlmStats);

This method frees any memory allocations that are associated with the XFLM_STATS structure.  The XFLM_STATS structure will have been populated by a call to the getStats method.

    Parameters In: none.

    Parameters Out:

XFLM_STATS * pFlmStats The statistics structure whose memory allocations are to be freed.

    Example Code: see startStats

    See Also: startStats, stopStats, resetStats, getStats

[Back to Top]


setTempDir

    RCODE setTempDir(

        char *         pszPath);

This method sets the directory where temporary files are to be created.

    Parameters In:

char * pszPath The temporary directory path.

    Parameters Out: none.

    Example Code:

    // Set the temporary directory path

    if (RC_BAD( rc = pDbSystem->setTempDir( "c:\\winnt\\temp")))

    {

        goto Exit;

    }
 

   See Also: getTempDir

[Back to Top]


getTempDir

    RCODE getTempDir(

        char *         pszPath);

This method returns the directory name where temporary files are created.  If no temporary directory is set, this function returns NE_XFLM_IO_PATH_NOT_FOUND.

    Parameters In: none.

    Parameters Out:

char * pszPath The temporary directory path is returned here.

    Example Code:

    char szTempDir [256];

 

    // Get the temporary directory
    if( RC_BAD( pDbSystem->getTempDir( szTempDir)))
    {
        goto Exit;
    }

 

    See Also: setTempDir

[Back to Top]


setCheckpointInterval

    void setCheckpointInterval(

        FLMUINT    uiSeconds);

This method sets the maximum time between completed checkpoints in the database.  This is NOT the same thing as how often a checkpoint will be performed.  Checkpoints are actually performed and completed much more frequently, depending on how much update transaction activity there is.  A background thread (often referred to as the checkpoint thread) is responsible for performing database checkpoints.  The checkpoint thread wakes up about once a second to see if there are dirty blocks in the cache that need to be written to disk.  If there are, and there is no currently active update transaction, it will begin performing a checkpoint.  If no update transactions occur while it is performing the checkpoint, it will be able to complete the checkpoint.  If the application attempts to start an update transaction while the checkpoint is being done, the checkpoint thread has the option of yielding to the update transaction and not completing the checkpoint.  The checkpoint thread may also choose to not yield and complete the checkpoint.  One of the conditions under which it will not yield is if the elapsed time since the last completed checkpoint is greater than the time specified by this method.  In that case, the update transaction is held off until the checkpoint completes.

Note that it is possible for the time between completed checkpoints to be longer than the interval specified in this routine.  The checkpoint thread cannot interrupt an active transaction when it wakes up.  If it wakes up and finds that a transaction is active, it must wait for the transaction to complete before it can start a checkpoint.  Thus, if that transaction runs a long time, the time between completed checkpoints could exceed the time specified in this method.

    Parameters In:

FLMUINT uiSeconds The maximum number of seconds allowed to elapse between completed checkpoints.  Default is 180 seconds.  NOTE: It is possible that the time between completed checkpoints can be greater than this value.  This is because the checkpoint thread cannot run if there is an update transaction that is currently active. If an update transaction is active and runs for a long time, the time between completed checkpoints could exceed the time specified in this method.

    Parameters Out: none.

    Example Code:

    // Set the checkpoint interval to 10 minutes
   pDbSystem->setCheckpointInterval( 600);

    See Also: getCheckpointInterval

[Back to Top]


getCheckpointInterval

    FLMUINT getCheckpointInterval( void);

This method returns the current checkpoint interval.

    Parameters In: none

    Parameters Out: none.

    Example Code:

    FLMUINT    uiCheckpointInterval = pDbSystem->getCheckpointInterval();

    See Also: setCheckpointInterval

[Back to Top]


setCacheAdjustInterval

    void setCacheAdjustInterval(

        FLMUINT    uiSeconds);

This method sets the time interval for dynamically adjusting the cache limit.

    Parameters In:

FLMUINT uiSeconds The time interval for dynamically adjusting the cache limit.

    Parameters Out: none.

    Example Code:

     // Set the cache adjust interval to 20 seconds.

    pDbSystem->setCacheAdjustInterval( 20);

    See Also: getCacheAdjustInterval, setCacheCleanupInterval, getCacheCleanupInterval, setUnusedCleanupInterval, getUnusedCleanupInterval

[Back to Top]


getCacheAdjustInterval

    FLMUINT getCacheAdjustInterval( void);

This method returns the time interval (in seconds) for dynamically adjusting the cache limit.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    FLMUINT    uiCacheAdjustInterval = pDbSystem->getCacheAdjustInterval();

    See Also: setCacheAdjustInterval, setCacheCleanupInterval, getCacheCleanupInterval, setUnusedCleanupInterval, getUnusedCleanupInterval

[Back to Top]


setCacheCleanupInterval

    void setCacheCleanupInterval(

        FLMUINT    uiSeconds);

This method sets the time interval for cleaning out old cache blocks from block cache.

    Parameters In:

FLMUINT uiSeconds The time interval for dynamically cleaning out old cache blocks.

    Parameters Out: none.

    Example Code:

     // Set the cache cleanup interval to 20 seconds.

    pDbSystem->setCacheCleanupInterval( 20);

    See Also: setCacheAdjustInterval, getCacheAdjustInterval, getCacheCleanupInterval, setUnusedCleanupInterval, getUnusedCleanupInterval

[Back to Top]


getCacheCleanupInterval

    FLMUINT getCacheCleanupInterval( void);

This method returns the time interval (in seconds) for cleaning out old cache blocks from block cache.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    FLMUINT    uiCacheCleanupInterval = pDbSystem->getCacheCleanupInterval();

    See Also: setCacheAdjustInterval, getCacheAdjustInterval, setCacheCleanupInterval, setUnusedCleanupInterval, getUnusedCleanupInterval

[Back to Top]


setUnusedCleanupInterval

    void setUnusedCleanupInterval(

        FLMUINT    uiSeconds);

This method sets the time interval for cleaning up unused resources (such as file handles).

    Parameters In:

FLMUINT uiSeconds The time interval for cleaning up unused resources (such as file handles).

    Parameters Out: none.

    Example Code:

     // Set the unused cleanup interval to 20 seconds.

    pDbSystem->setUnusedCleanupInterval( 20);

    See Also: getUnusedCleanupInterval, setMaxUnusedTime, getMaxUnusedTime

[Back to Top]


getUnusedCleanupInterval

    FLMUINT getUnusedCleanupInterval( void);

This method returns the time interval (in seconds) for cleaning up unused resources (such as file handles).

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    FLMUINT    uiUnusedCleanupInterval = pDbSystem->getUnusedCleanupInterval();

 

    See Also: setUnusedCleanupInterval, setMaxUnusedTime, getMaxUnusedTime

[Back to Top]


setMaxUnusedTime

    void setMaxUnusedTime(

        FLMUINT    uiSeconds);

This method sets the maximum time for a resource (such as a file handle) to be unused before it is cleaned up.

    Parameters In:

FLMUINT uiSeconds The maximum time for a resource (such as a file handle) to be unused before it is cleaned up.

    Parameters Out: none.

    Example Code:

     // Set the maximum unused time to 3 minutes..

    pDbSystem->setMaxUnusedTime( 180);

    See Also: getMaxUnusedTime, setUnusedCleanupInterval, getUnusedCleanupInterval

[Back to Top]


getMaxUnusedTime

    FLMUINT getMaxUnusedTime( void);

This method returns the maximum time for a resource (such as a file handle) to be unused before it is cleaned up.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    FLMUINT    uiMaxUnusedTime = pDbSystem->getMaxUnusedTime();

    See Also: setMaxUnusedTime, setUnusedCleanupInterval, getUnusedCleanupInterval

[Back to Top]


setLogger

    void setLogger(

        IF_LoggerClient *         pLogger);

This method sets the logger client.

    Parameters In:

IF_LoggerClient * pLogger Pointer to the logger client object.

    Example Code:

    App_LoggerClient    appLogger;

 

    // NOTE: The App_LoggerClient class should be a class that inherits from the IF_LoggerClient interface, as follows:

    // class App_LoggerClient : public IF_LoggerClient {....};

 

    // Probably would be some setup of the appLogger object here.

 

    pDbSystem->setLogger( &appLogger);

    Parameters Out: none.

    See Also:

[Back to Top]


enableExtendedServerMemory

    void enableExtendedServerMemory(

        FLMBOOL         bEnable);

This method enables or disables extended server memory (ESM).

    Parameters In:

FLMBOOL bEnable A boolean flag.  When TRUE, Extended Server Memory is enabled.  When FALSE, Extended Server Memory is disabled.

    Parameters Out: none.

    Example Code:

     // Enable use of extended server memory..

    pDbSystem->enableExtendedServerMemory( TRUE);

 

    // Disable use of extended server memory

    pDbSystem->enableExtendedServerMemory( FALSE);

 

    See Also: extendedServerMemoryEnabled

[Back to Top]


extendedServerMemoryEnabled

    FLMBOOL extendedServerMemoryEnabled( void);

This method returns whether Extended Server Memory is enabled or disabled.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    FLMBOOL    bExtendedServerMemoryEnabled = pDbSystem->extendedServerMemoryEnabled();

    See Also: enableExtendedServerMemory

[Back to Top]


deactivateOpenDb

    void deactivateOpenDb(

        char *    pszDatabasePath,
        char *    pszDataFilePath);

This method deactivates all open database objects (IF_Db objects) for a particular database, forcing the database to eventually be closed.  Passing NULL in the pszDbFileName parameter will deactivate all active database objects for all open databases.

    Parameters In:

char * pszDatabasePath Name of the control file ( including path ) for the database that is to be deactivated.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.  NOTE: Passing a NULL in this parameter will cause all open databases to be deactivated.
char * pszDataFilePath The directory where the data files are located.   If a NULL is passed in, it is assumed that the data files are located in the same directory as the control file (as specified by the pszDbFileName parameter). See the XFlaim Concepts/Database Files for a discussion on the different database files.

    Parameters Out: none.

    Example Code:

    pDbSystem->deactivateOpenDb( "c:\\dbs\\xml.db", NULL);
 

    See Also:

[Back to Top]


setQuerySaveMax

    void setQuerySaveMax(

        FLMUINT         uiMaxToSave);

This method sets the maximum number of queries to save when statistics gathering is enabled.

    Parameters In:

FLMUINT uiMaxToSave The maximum number of queries to save.

    Parameters Out: none.

    Example Code:

    // Enable statistics gathering and set the number of queries to save in the statistics to 10.

 

    pDbSystem->startStats();

    pDbSystem->setQuerySaveMax( 10);

 

   See Also: getQuerySaveMax

[Back to Top]


getQuerySaveMax

    FLMUINT getQuerySaveMax( void);

This method returns the maximum number of queries to save when statistics gathering is enabled.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    FLMUINT                uiMaxQueriesToSave;

 

    // Return the maximum number of queries to save when statistics are being collected.

    uiMaxQueriesToSave = pDbSystem->getQuerySaveMax();
 

    See Also: setQuerySaveMax

[Back to Top]


setDirtyCacheLimits

    void setDirtyCacheLimits(

        FLMUINT        uiMaxDirty,
        FLMUINT        uiLowDirty);

This method sets dirty cache limits - a "maximum" and a "low."  The maximum specifies the maximum dirty cache to be allowed.  When a database exceeds this amount, the checkpoint thread will kick in and write out dirty blocks until the dirty cache comes back down below the amount specified by the "low" value.  In this way, the application can control how much dirty cache builds up between forced checkpoints (see setCheckpointInterval).  The more dirty cache there is when the checkpoint forces a checkpoint, the longer it will take to complete the checkpoint.  It should be noted that the overall time that will be needed to write out dirty blocks is still the same.  It's just that the writing gets spread out more over time.  Instead of doing it all in one big chunk, it gets done in lots of little chunks.  This has both pros and cons, so this method should be used with extreme caution!

In a bulk load situation, where there is one thread doing the bulk loading, lowering the maximum dirty cache could actually lengthen out the overall time it takes to complete the bulk load.  This is because the bulk load will be interrupted more often by the checkpoint thread to do smaller units of writing than it otherwise would.  There will also be less piggy-backing of writes.  Piggy-backing occurs when multiple transactions write to the same data block before the block is flushed out of cache.  If the database system is flushing dirty blocks out of cache more often, it could end up writing the same block multiple times, whereas it might not not have had to if it had waited longer between flushes.

The advantage to spreading out the flushing of dirty cache blocks occurs when there are multiple threads trying to do update transactions.  When the checkpoint thread forces a checkpoint, it holds back all pending update transactions.  If it has to do more writing when it forces a checkpoint, it may cause many threads to wait for a longer period of time than it would if there were less writing to do.  This is less efficient to the overall throughput of the system, because it is likely that each of the threads could be doing other useful work instead of waiting.

    Parameters In: none

FLMUINT            uiMaxDirty The maximum amount (in bytes) of dirty cache allowed.
FLMUINT            uiLowDirty The low threshold (in bytes) for dirty cache.

    Example Code:

    // Set maximum dirty cache to 16 megabytes, low to 8 megabytes

    pDbSystem->setDirtyCacheLimits( 16 * 1024 * 1024, 8 * 1024 * 1024);

 

    Parameters Out: none.

    See Also: getDirtyCacheLimits

[Back to Top]


getDirtyCacheLimits

    void getDirtyCacheLimits(

        FLMUINT *            puiMaxDirty,
        FLMUINT *            puiLowDirty);

This method returns the minimum and maximum dirty cache limits.

    Parameters In: none.

    Parameters Out:

FLMUINT *            puiMaxDirty The maximum number of dirty blocks allowed in the cache.
FLMUINT *            puiLowDirty The low threshold for the number of dirty blocks in cache.

    Example Code:

    FLMUINT    uiMaxDirtyCache;

    FLMUINT    uiLowDirtyCache;

 

    pDbSystem->getDirtyCacheLimits( &uiMaxDirtyCache, &uiLowDirtyCache);

 

    See Also: setDirtyCacheLimits

[Back to Top]


getThreadInfo

    RCODE getThreadInfo(

        IF_ThreadInfo **         ppThreadInfo);

This method returns a thread information object which has methods for retrieving various pieces of information about threads owned by the database system.  NOTE: When the application is done using the returned IF_ThreadInfo object, it should call its Release method.

    Parameters In: none.

    Parameters Out:

IF_ThreadInfo ** ppThreadInfo A pointer to the allocated thread info object is returned here.

 

    Example Code:

    IF_ThreadInfo *    pThreadInfo = NULL;

 

    // Get the thread information

    if (RC_BAD( rc = pDbSystem->getThreadInfo( &pThreadInfo)))

    {

        goto Exit;

    }

 

    // Get the information out of the thread info object and display it here

    .

    .

    .

    pThreadInfo->Release();

    See Also:

[Back to Top]


registerForEvent

    RCODE registerForEvent(

        eEventCategory             eCategory,
        IF_EventClient *            pEventClient);

This method registers an object to catch events in a particular category of database events.

    Parameters In:

eEventCategory eCategory The category of events the application is registering for.
IF_EventClient * pEventClient The client object whose methods are to be invoked when the event occurs.

    Parameters Out: none.

    Example Code:

    App_EventClient    updateEventCatcher;

 

    // The App_EventClient should be a class that implements the IF_EventClient interface, as follows:

    // class App_EventClient : public IF_EventClient {.....};

 

    // The updateEventCatcher object would probably be initialized here.

 

 

    // Register the updateEventCatcher object to catch update events.

    if (RC_BAD( rc = pDbSystem->registerForEvent( XFLM_EVENT_UPDATES, &updateEventCatcher)))

    {

        goto Exit;

    }

    .

    .

    .

    // Deregister the updateEventCatcher object from catching update events.

    if (RC_BAD( rc = pDbSystem->deregisterForEvent( XFLM_EVENT_UPDATES, &updateEventCatcher)))

    {

        goto Exit;

    }

 

    See Also: deregisterForEvent

[Back to Top]


deregisterForEvent

    void deregisterForEvent(

        eEventCategory             eCategory,
        IF_EventClient *            pEventClient);

This method deregisters an object from catching events in a particular category of database events.

    Parameters In:

eEventCategory eCategory The type of event.
IF_EventClient * pEventClient The client object that was passed into the registerForEvent method.  This is necessary so that if there are multiple objects that have registered for an event, XFlaim can know exactly which object to deregister.

    Parameters Out: none.

    Example Code: see registerForEvent

    See Also: registerForEvent

[Back to Top]


getNextMetaphone

    RCODE getNextMetaphone(

        IF_IStream *           pIStream,
        FLMUINT *           puiMetaphone,

        FLMUINT *           puiAltMetaphone = NULL);

This parses the next word from the input stream (pIStream) and returns the metaphone codes for it.  This method returns NE_XFLM_EOF_HIT when it hits the end of the input stream.  Visit: This should probably be a method on the IF_IStream interface, not the IF_DbSystem interface.

    Parameters In:

IF_IStream *    pIStream Input stream object.
FLMUINT *    puiMetaphone Primary metaphone returned for the next word in the input stream.
FLMUINT *    puiAltMetaphone Alternate metaphone returned for the next word in the input stream.

    Parameters Out: none.

    Example Code:

    IF_IStream *    pIStream = NULL;

 

    // Open an input stream on a file

    if (RC_BAD( rc = pDbSystem->openFileIStream( "c:\\files\\inputfile", &pIStream)))

    {

        goto Exit;

    }

    for (;;)

    {

        // Parse the next word from the input stream and returns the metaphone codes for it.

        if (RC_BAD( rc = pDbSystem->getNextMetaphone( pIStream, &uiMetaphone, &uiAltMetaphone)))

        {

            if (rc == NE_XFLM_EOF_HIT)

            {

                rc = NE_XFLM_OK;

                break;

            }

            else

            {

                goto Exit;

            }

        }

 

        // Do something with the metaphone codes here.

    }

Exit:

    if (pIStream)

    {

        pIStream->Release();

    }

 

    See Also:

[Back to Top]


createMemoryPool

    RCODE createMemoryPool(

        IF_Pool **    ppPool);

This method allocates and returns a memory pool object.

    Parameters In: none.

    Parameters Out:

IF_Pool ** ppPool Returned memory pool object.

    Example Code:

   RCODE        rc;

   IF_Pool *    pPool = NULL;

 

   rc = pDbSystem->createMemoryPool( &pPool);

    See Also: Documentation on IF_Pool class.

[Back to Top]


compareUTF8Strings

    RCODE compareUTF8Strings(

        FLMBYTE *    pucLString,

        FLMUINT       uiLStrBytes,

        FLMBOOL      bLeftWild,

        FLMBYTE *    pucRString,

        FLMUINT       uiRStrBytes,

        FLMBOOL     bRightWild,

        FLMUINT       uiCompareRules,

        FLMUINT       uiLanguage,

        FLMINT *       piResult);

This method compares two UTF8 strings.

    Parameters In:

FLMBYTE * pucLString UTF8 string on "left" of comparison.
FLMUINT uiLStrBytes Number of bytes (not characters) in pucLString.  If zero, string is assumed to be null terminated.  Note: Even if a non-zero length is provided in this parameter, the comparison will stop if a null character is encountered before the end that is specified in this parameter.
FLMBOOL bLeftWild If TRUE, indicates that wildcard characters (*), if present in pucLString, are to be used to do wildcard matching instead of being compared as a single "asterisk" character.
FLMBYTE * pucRString UTF8 string on "right" of comparison.
FLMUINT uiRStrBytes Number of bytes (not characters) in pucRString.  If zero, string is assumed to be null terminated.  Note: Even if a non-zero length is provided in this parameter, the comparison will stop if a null character is encountered before the end that is specified in this parameter.
FLMBOOL bRightWild If TRUE, indicates that wildcard characters (*), if present in pucRString, are to be used to do wildcard matching instead of being compared as a single "asterisk" character.
FLMUINT uiCompareRules This is a set of bits that may be ORed together to specify comparison rules.  For the macros that define these comparison bits, see "Comparison Rules" in the glossary.
FLMUINT uiLanguage Language code that specifies the language whose comparison rules are to be used in doing the comparison.  See "Language Codes" in the glossary for a comprehensive list of language codes.

    Parameters Out:

FLMINT * piResult Result of comparison is returned here.  A negative value means that pucLString is "less than" pucRString.  A positive value means that pucLString is "greater than" pucRString.  A zero value means that the two strings are equal.

    Example Code:

   RCODE             rc;

   FLMBYTE *    pszUtf8Str1 = (FLMBYTE *)"Mike";

   FLMBYTE *    pszUtf8Str2 = (FLMBYTE *)"MIKE";

   FLMINT           iCmp;

 

    // iCmp should return a zero - when compared with case-insensitive flag, the two strings are equal.

 

    rc = pDbSystem->compareUTF8Strings( pszUtf8Str1, 0, FALSE, pszUtf8Str2, 0, FALSE, XFLM_COMP_CASE_INSENSITIVE , XFLM_US_LANG,

                                            &iCmp);

    See Also: compareUnicodeStrings, utf8IsSubStr

[Back to Top]


compareUnicodeStrings

    RCODE compareUnicodeStrings(

        FLMUNICODE *    puzLString,

        FLMUINT               uiLStrBytes,

        FLMBOOL              bLeftWild,

        FLMUNICODE *    puzRString,

        FLMUINT               uiRStrBytes,

        FLMBOOL              bRightWild,

        FLMUINT               uiCompareRules,

        FLMUINT               uiLanguage,

        FLMINT *               piResult);

This method compares two unicode strings.

    Parameters In:

FLMUNICODE * puzLString Unicode string on "left" of comparison.
FLMUINT uiLStrBytes Number of bytes (not unicode characters) in puzLString.  If zero, string is assumed to be null terminated (with a FLMUNICODE character).  Note: Even if a non-zero length is provided in this parameter, the comparison will stop if a null character is encountered before the end that is specified in this parameter.
FLMBOOL bLeftWild If TRUE, indicates that wildcard characters (*), if present in puzLString, are to be used to do wildcard matching instead of being compared as a single "asterisk" character.
FLMUNICODE * puzRString Unicode string on "right" of comparison.
FLMUINT uiRStrBytes Number of bytes (not unicode characters) in puzRString.  If zero, string is assumed to be null terminated (with a FLMUNICODE character).  Note: Even if a non-zero length is provided in this parameter, the comparison will stop if a null character is encountered before the end that is specified in this parameter.
FLMBOOL bRightWild If TRUE, indicates that wildcard characters (*), if present in puzRString, are to be used to do wildcard matching instead of being compared as a single "asterisk" character.
FLMUINT uiCompareRules This is a set of bits that may be ORed together to specify comparison rules.  For the macros that define these comparison bits, see "Comparison Rules" in the glossary.
FLMUINT uiLanguage Language code that specifies the language whose comparison rules are to be used in doing the comparison.  See "Language Codes" in the glossary for a comprehensive list of language codes.

    Parameters Out:

FLMINT * piResult Result of comparison is returned here.  A negative value means that puzLString is "less than" puzRString.  A positive value means that puzLString is "greater than" puzRString.  A zero value means that the two strings are equal.

    Example Code:

   RCODE                     rc;

   FLMUNICODE *    puzUnicodeStr1 = {'M', 'i', 'k', 'e', 0};

   FLMUNICODE *    puzUnicodeStr2 = {'M', 'I', 'K', 'E', 0};

   FLMINT                   iCmp;

 

    // iCmp should return a zero - when compared with case-insensitive flag, the two strings are equal.

 

    rc = pDbSystem->compareUnicodeStrings( pszUnicodeStr1, 0, FALSE, pszUnicodeStr2, 0, FALSE,

                                            XFLM_COMP_CASE_INSENSITIVE , XFLM_US_LANG, &iCmp);

    See Also: compareUTF8Strings, utf8IsSubStr

[Back to Top]


utf8IsSubStr

    RCODE utf8IsSubStr(

        FLMBYTE *            pszString,

        FLMBYTE *            pszSubString,

        FLMUINT               uiCompareRules,

        FLMUINT               uiLanguage,

        FLMBOOL *           pbExists);

This method determines if the substring specified by pszSubString is found inside the string specified by pszString.

    Parameters In:

FLMBYTE * pszString UTF8 string that is to be checked to see if it contains the specified substring.  Note: It is assumed that pszString is null terminated.
FLMBYTE * pszSubString UTF8 sub-string that is to be checked to see if it is contain inside of pszString.  Note: It is assumed that pszSubString is null terminated.
FLMUINT uiCompareRules This is a set of bits that may be ORed together to specify comparison rules.  For the macros that define these comparison bits, see "Comparison Rules" in the glossary.
FLMUINT uiLanguage Language code that specifies the language whose comparison rules are to be used in doing the comparison.  See "Language Codes" in the glossary for a comprehensive list of language codes.

    Parameters Out:

FLMBOOL * pbExists Result of check is returned here.  Returns TRUE if pszSubString is contained inside of pszString, FALSE otherwise.

    Example Code:

   RCODE                     rc;

   FLMBYTE *            pszString = (FLMBYTE *)"Smile";

   FLMBYTE *            pszSubString = (FLMBYTE *)"MILE";

   FLMBOOL               bExists;

 

    // bExists should return TRUE - when compared with case-insensitive flag, "MILE" is a substring of "Smile"

 

    rc = pDbSystem->utf8IsSubStr( pszString, pszSubString, XFLM_COMP_CASE_INSENSITIVE , XFLM_US_LANG, &bExists);

    See Also: compareUTF8Strings, compareUnicodeStrings

[Back to Top]


uniIsUpper

    FLMBOOL uniIsUpper(

        FLMUNICODE    uzChar);

This method returns TRUE if the passed in unicode character is an upper-case character as defined by The Unicode Standard, Version 4.0, FALSE otherwise.

    Parameters In:

FLMUNICODE uzChar Character to be tested for "uppercase-ness".

    Parameters Out: none

    Example Code:

   FLMBOOL               bUpperCase;

 

    // bUpperCase should return TRUE

 

    bUpperCase = pDbSystem->uniIsUpper( (FLMUNICODE)'A');

    See Also: uniIsLower, uniIsAlpha, uniIsDecimalDigit, uniToLower

[Back to Top]


uniIsLower

    FLMBOOL uniIsLower(

        FLMUNICODE    uzChar);

This method returns TRUE if the passed in unicode character is a lower-case character as defined by The Unicode Standard, Version 4.0, FALSE otherwise.

    Parameters In:

FLMUNICODE uzChar Character to be tested for "lowercase-ness".

    Parameters Out: none

    Example Code:

   FLMBOOL               bLowerCase;

 

    // bLowerCase should return FALSE

 

    bLowerCase = pDbSystem->uniIsLower( (FLMUNICODE)'A');

    See Also: uniIsUpper, uniIsAlpha, uniIsDecimalDigit, uniToLower

[Back to Top]


uniIsAlpha

    FLMBOOL uniIsAlpha(

        FLMUNICODE    uzChar);

This method returns TRUE if the passed in unicode character is an alphabetic character as defined by The Unicode Standard, Version 4.0, FALSE otherwise.

    Parameters In:

FLMUNICODE uzChar Character to be tested for "alphabetic-ness".

    Parameters Out: none

    Example Code:

   FLMBOOL               bIsAlpha;

 

    // bIsAlpha should return TRUE

 

    bIsAlpha= pDbSystem->uniIsAlpha( (FLMUNICODE)'A');

    See Also: uniIsUpper, uniIsLower, uniIsDecimalDigit, uniToLower

[Back to Top]


uniIsDecimalDigit

    FLMBOOL uniIsDecimalDigit(

        FLMUNICODE    uzChar);

This method returns TRUE if the passed in unicode character is a decimal digit character as defined by The Unicode Standard, Version 4.0, FALSE otherwise.

    Parameters In:

FLMUNICODE uzChar Character to be tested for "decimal-digit-ness".

    Parameters Out: none

    Example Code:

   FLMBOOL               bDigit;

 

    // bDigit should return FALSE

 

    bDigit = pDbSystem->uniIsDecimalDigit( (FLMUNICODE)'A');

    See Also: uniIsUpper, uniIsLower, uniIsAlpha

[Back to Top]


uniToLower

    FLMUNICODE uniToLower(

        FLMUNICODE    uzChar);

This method returns the lower-case character for the passed in character (uzChar), if any.  If the character does not have a corresponding lower-case character as defined by The Unicode Standard, Version 4.0, this method will return the passed in character.

    Parameters In:

FLMUNICODE uzChar Character to be converted to lower case.

    Parameters Out: none

    Example Code:

   FLMUNICODE    uzLowerCaseChar;

 

    // uzLowerCaseChar should return 'a'

 

    uzLowerCaseChar = pDbSystem->uniToLower( (FLMUNICODE)'A');

    See Also: uniIsUpper, uniIsLower, uniIsAlpha

[Back to Top]


nextUCS2Char

    RCODE nextUCS2Char(

        FLMBYTE **       ppszUTF8,
        FLMBYTE *         pszEndOfUTF8String,
        FLMUNICODE * puzChar);

This method returns the next unicode (UCS2) character in a UTF8 string.  It will also increment the UTF8 string pointer past the sequence of UTF8 bytes that were consumed to get the unicode character.

    Parameters In:

FLMBYTE ** ppszUTF8 *ppszUTF8 points to the place in the UTF8 string where we expect to get our next unicode (UCS2) character. Note that this parameter is both an "In" and an "Out" parameter.  Upon successful completion, *ppszUTF8 will be pointing past the bytes in the UTF8 string that were consumed to produce the unicode character.
FLMBYTE * pszEndOfUTF8String This indicates where the end of the UTF8 string is.  If NULL, the string will be processed until we hit a zero byte.  Note: even if pszEndOfUTF8String is non-NULL, if we hit a zero byte before we hit the end of the string as specified by pszEndOfUTF8String, we will quit processing the string and return a zero unicode character.

    Parameters Out:

FLMBYTE ** ppszUTF8 String pointer will be positioned past the bytes in the UTF8 string that were consumed to produce the unicode character.
FLMUNICODE * puzChar Unicode (UCS2) character is returned here.  Note: A zero is returned when *ppszUTF8 >= pszEndOfUTF8String, or if *(*ppszUTF8) == 0 - in other words, we are at the end of the string.

    Example Code:

   RCODE                  rc;

   FLMUNICODE    uzChar;

   FLMBYTE *        pszUTF8Str = (FLMBYTE *)"Test";

   FLMBYTE *        pszEndOfUTF8Str = pszUTF8Str + strlen( pszUTF8Str);

 

   for (;;)

   {

        if (RC_BAD( rc = nextUCS2Char( &pszUTF8Str, pszEndOfUTF8Str, &uzChar)))

        {

            printf( "Error %08X calling nextUCS2Char\n", (unsigned)rc);

            goto Exit;

        }

 

        // Did we hit the end of the string?

 

        if (!uzChar)

        {

            break;

        }

 

        // Do something with the extracted character

        .

        .

    }

 

Exit:

 

    return( rc);

    See Also: numUCS2Chars

[Back to Top]


numUCS2Chars

    FLMUNICODE numUCS2Chars(

        FLMBYTE *    pszUTF8Str,

        FLMUINT *    puiNumChars);

This method counts the number of unicode (UCS2) characters in a UTF8 string.

    Parameters In:

FLMBYTE * pszUTF8Str Null terminated UTF8 string.

    Parameters Out:

FLMUINT * puiNumChars Number of unicode (UCS2) characters returned here.

    Example Code:

    RCODE             rc;

    FLMBYTE *    pszUTF8Str = (FLMBYTE *)"Smile";

    FLMUINT        uiNumChars;

 

    // uiNumChars should return 5

 

    rc = pDbSystem->numUCS2Chars( pszUTF8Str, &uiNumChars);

    See Also: nextUCS2Char

[Back to Top]


waitToClose

    RCODE waitToClose(

        char *    pszDbFileName);

This method waits for the specified database to be closed by all threads that currently have the database open.  If the database is not currently open, it returns immediately.  Note that this method does NOT issue a request to have the database closed.  If other threads have the database open, and they are not currently in a state where they would be closing the the database, this routine will wait forever.

    Parameters In:

char * pszDbFileName Name of the control file for the database.  See the XFlaim Concepts/Database Files for a discussion on the different database files, including the control file.

    Parameters Out: none

    Example Code:

    RCODE             rc;

 

    // wait until dib.db is closed.

 

    rc = pDbSystem->waitToClose( "dib.db");

[Back to Top]


createIFNodeInfo

    RCODE createIFNodeInfo(

        IF_NodeInfo **    ppNodeInfo);

This method creates an IF_NodeInfo interface object.

    Parameters In: none

    Parameters Out:

IF_NodeInfo ** ppNodeInfo IF_NodeInfo object pointer is returned here.

    Parameters Out: none

    Example Code:

    RCODE                 rc;

    IF_NodeInfo *    pNodeInfo = NULL;

 

    if (RC_BAD( rc = pDbSystem->createIFNodeInfo( &pNodeInfo)))
    {

        goto Exit;

    }

    .

    .

    .

 

Exit:

    if (pNodeInfo)

    {

        pNodeInfo->Release();

    }

[Back to Top]


createIFBTreeInfo

    RCODE createIFBTreeInfo(

        IF_BTreeInfo **    ppBTreeInfo);

This method creates an IF_BTreeInfo interface object.

    Parameters In: none

    Parameters Out:

IF_BTreeInfo ** ppBTreeInfo IF_BTreeInfo object pointer is returned here.

    Example Code:

    RCODE                  rc;

    IF_BTreeInfo *    pBTreeInfo = NULL;

 

    if (RC_BAD( rc = pDbSystem->createIFBTreeInfo( &pBTreeInfo)))
    {

        goto Exit;

    }

    .

    .

    .

 

Exit:

    if (pBTreeInfo)

    {

        pBTreeInfo->Release();

    }

[Back to Top]


clearCache

    RCODE clearCache(

        IF_Db *    pDb);

This method attempts to remove all blocks and nodes from cache.

    Parameters In:

IF_Db * pDb Database object for which dirty cache items are to be flushed.  This parameter, if non-NULL, allows this method to flush dirty cache items associated with the database.  Note that the pDb must be the specific IF_Db object that is currently performing an update transaction in order to be able to flush its database's dirty cache items.  If the pDb is performing a read transaction, it will not be able to flush its database's dirty cache items - because those items are only controlled by the pDb that is currently performing the update transaction.  If there are multiple different databases open, and update transactions are active on each of them, and the application wishes to make sure that each database's dirty items are flushed and cleared from cache, it will need to call this method once for each open database - making sure to use the IF_Db object that is currently performing the update transaction.

    Parameters Out: none

    Example Code:

    RCODE                  rc;

 

    // Attempt to clear cache - this particular call will not be able to clear out any dirty items in cache, because it is passing a NULL for the pDb parameter.

 

    if (RC_BAD( rc = pDbSystem->clearCache( NULL)))
    {

        goto Exit;

    }

    .

    .

    .

 

Exit:

[Back to Top]