xflminterface IF_Db : public XF_RefCount

This class contains methods for accessing an open XFLAIM database. It extends XF_RefCount.  Each thread that wants to access the database must have it's own IF_Db object.  The IF_Db object is returned by opening a database using the dbOpen, dbCreate, or dbDup methods of the database system (IF_DbSystem) interface.  The operations that can be performed using the IF_Db interface include such things as beginning and ending transactions, managing indexes and managing documents.

transBegin

    RCODE transBegin(

        eDbTransType             eTransType,

        FLMUINT                  uiMaxLockWait,

        FLMUINT                  uiFlags = 0,

        XFLM_DB_HDR *    pDbHeader = NULL);

Begins a transaction.  There are two types of transaction, Read and Update.

    Parameters In:

eDbTransType eTransType	Specifies the type of transaction to begin. Possible values are: XFLM_READ_TRANS: Begins a read transaction. XFLM_UPDATE_TRANS: Begins an update transaction.
FLMUINT uiMaxLockWait	Specifies the maximum number of seconds to wait to get a database lock.  A value of XFLM_NO_TIMEOUT indicates that there is no maximum - wait forever.
FLMUINT uiFlags	Specifies properties of the transaction.  The flags may be ORed together.  Valid flags are as follows: FLM_DONT_KILL_TRANS: Prevents read transaction from being killed if it runs long. FLM_DONT_POISON_CACHE: Prevents items read by this transaction from poisoning cache.

    Parameters Out:

XFLM_DB_HDR * pDbHeader

If non-NULL, returns the state of the database header as it was at the beginning of the transaction.

    Example Code:

    IF_Db *                pDb = NULL;

 

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

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

 

   // Begin an update transaction

 

    if (RC_BAD( rc = pDb->transBegin( XFLM_UPDATE_TRANS, 0)))
    {
        goto Exit;
    }
   

    // Do some work here

    .

    .

       

   // Commit the transaction

 

    if (RC_BAD( rc = pDb->transCommit( )))
    {

        (void)pDb->transAbort();
        goto Exit;
    }
 

    See Also: transCommit, transAbort, getTransType, transBegin(2)

[Back to Top]

transBegin(2)

    RCODE transBegin(

        IF_Db *    pDb);

Begins a read transaction that has exactly the same snapshot of the database as the passed in pDb.  This method will only work if pDb is currently running a read transaction.

    Parameters In:

IF_Db * pDb

This is the database object whose read transaction snapshot is to be duplicated.  It is assumed that pDb is currently executing a read transaction.  If not, an error will be returned.

    Parameters Out: none

    Example Code:

    IF_Db *                pDb = NULL;

    IF_Db *                pDb2 = NULL;

 

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

 

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

 

    // Dup the database object into pDb2.

 

    if (RC_BAD( rc = pDbSystem->dbDup( pDb, &pDb2)))

    {

        goto Exit;

    }

 

   // Begin a read transaction

 

    if (RC_BAD( rc = pDb->transBegin( XFLM_READ_TRANS)))
    {
        goto Exit;
    }

 

    // Copy the read snapshot from pDb into pDb2 - will start a read transaction for pDb2

 

    if (RC_BAD( rc = pDb2->transBegin( pDb)))

    {

        goto Exit;

    }
   

    // Do some work here

    .

    .

       

    See Also: transBegin, transCommit, transAbort, getTransType

[Back to Top]

transCommit

    RCODE transCommit(

        FLMBOOL *    pbEmpty = NULL);

Commits an active transaction. If the commit fails, a failure RCODE status will be returned, and the transaction is automatically aborted.

    Parameters In: none.

    Parameters Out:

FLMBOOL * pbEmpty

If non-NULL, returns a flag indicating whether or not the transaction was empty.

    Example Code: See transBegin.

    See Also: transBegin, transBegin(2), transAbort, getTransType

[Back to Top]

transAbort

    RCODE transAbort( void);

Aborts an active transaction, abandoning any changes that have occurred during the transaction.  NOTE: Since no changes are allowed during read transactions, it doesn't matter whether a read transaction is committed or aborted, the effect is the same - to terminate the transaction.

    Parameters In: none.

    Parameters Out: none.

    Example Code: See transBegin.

    See Also: transBegin, transBegin(2), transCommit, getTransType

[Back to Top]

getTransType

    eDbTransType getTransType( void);

Get the current transaction type.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    eDbTransType        transType;

 

    // Assume we have an IF_Db * passed in as pDb

 

    transType = pDb->getTransType();
 

    See Also: transBegin, transBegin(2), transCommit, transAbort

[Back to Top]

doCheckpoint

    RCODE doCheckpoint(

        FLMUINT            uiMaxLockWait);

Perform a checkpoint on the database.

    Parameters In:

FLMUINT uiMaxLockWait

Specifies the maximum number of seconds to wait to get a database lock.  A value of XFLM_NO_TIMEOUT indicates that there is no maximum - wait forever.

    Parameters Out: none.

    Example Code:

    IF_Db *                pDb = NULL;

 

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

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

    .

    .

    // Do a checkpoint

    if (RC_BAD( rc = pDb->doCheckpoint( XFLM_NO_TIMEOUT)))
    {
        goto Exit;
    }
 

    See Also: transBegin, transBegin(2) transCommit, transAbort

[Back to Top]

dbLock

    RCODE dbLock(

        eDbLockType               eLockType,
        FLMINT                       iPriority,
        FLMUINT                    uiTimeout);

Obtain a lock on the database.

    Parameters In:

eDbLockType eLockType	The type of lock requested.  It may be one of the following: XFLM_LOCK_EXCLUSIVE.  Obtain an exclusive lock. XFLM_LOCK_SHARED.  Obtain a shared lock.
FLMINT iPriority	The priority for the lock.
FLMUINT uiTimeout	A time to wait for the lock to be satisfied before a timeout occurs.  A value of XFLM_NO_TIMEOUT indicates wait forever.

    Parameters Out: none.

    Example Code:

    IF_Db *                pDb = NULL;

    eDbLockType     eLockType;

    FLMBOOL           bImplicit;

    FLMUINT            uiThreadId;

    FLMUINT            uiNumExclQueued;

    FLMUINT            uiNumSharedQueued;

    FLMUINT            uiCount;

 

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

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

 

    // See if anyone has the database locked.

 

    if (RC_BAD( rc = pDb->getLockInfo( 1, &eLockType, &uiThreadId, &uiNumExclQueued, &uiNumSharedQueued, &uiCount)))

    {

        goto Exit;

    }
 

    // Lock the database

 

    if (RC_BAD( rc = pDb->dbLock( XFLM_LOCK_EXCLUSIVE, 1, XFLM_NO_TIMEOUT)))

    {

        goto Exit;

    }

 

    // See what kind of lock we have, eLockType should return XFLM_LOCK_EXCLUSIVE, bImplicit should return FALSE.

 

    if (RC_BAD( rc = pdb->getLockType( &eLockType, &bImplicit)))

    {

        goto Exit;

    }

 

    // Do stuff while database is locked...

    .

    .

    .

    // Unlock the database

 

    if (RC_BAD( rc = pDb->dbUnlock()))

    {
        goto Exit;
    }
 

    See Also: dbUnlock, getLockType, getLockInfo

[Back to Top]

dbUnlock

    RCODE dbUnlock( void);

Unlock the database.  A prior call to dbLock should have been made.

    Parameters In: none.

    Parameters Out: none.

    Example Code: see dbLock

    See Also: dbLock, getLockType, getLockInfo

[Back to Top]

getLockType

    RCODE getLockType(

        eDbLockType *         peLockType,
        FLMBOOL *             pbImplicit);

This is a method to obtain information about the lock held by the specified database handle.

    Parameters In: none.

    Parameters Out:

eDbLockType * peLockType	The type of lock.
FLMBOOL * pbImplicit	A flag to indicate whether the lock is implicit or not.

    Example Code: see dbLock.

    See Also: dbLock, dbUnlock, getLockInfo

[Back to Top]

getLockInfo

    RCODE getLockInfo(

        FLMINT               iPriority,
        eDbLockType *    peCurrLockType,
        FLMUINT *         puiThreadId,
        FLMUINT *         puiNumExclQueued,
        FLMUINT *         puiNumSharedQueued,
        FLMUINT *         puiPriorityCount);

This is a method to obtain information about current and pending locks on the database.

    Parameters In:

FLMINT iPriority

A count of all locks with a priority >= to this priority level will be returned.

    Parameters Out:

eDbLockType * peCurrLockType	The type of lock.
FLMUINT * puiThreadId	The thread id.
FLMUINT * puiNumExclQueued	The number of requests for exclusive locks queued
FLMUINT * puiNumSharedQueued	The number of requests for shared locks queued
FLMUINT * puiPriorityCount	The number of locks >= to iPriority

    Example Code:  see dbLock.

    See Also: dbLock, dbUnlock, getLockType

[Back to Top]

indexStatus

    RCODE indexStatus(

        FLMUINT                                uiIndexNum,
        XFLM_INDEX_STATUS *     pIndexStatus);

Obtain information about an index.

    Parameters In:

FLMUINT uiIndexNum

The number of the index for which status information is sought.

    Parameters Out:

XFLM_INDEX_STATUS * pIndexStatus

The returned index status structure.

    Example Code:

    IF_Db *                                   pDb = NULL;

    FLMUINT                               uiIndexNum;

    FLMBOOL                              bDbLocked = FALSE;

    RCODE                                    rc;

    XFLM_INDEX_STATUS    ixStatus;

 

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

 

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

 

    // Lock the database

 

    if (RC_BAD( rc = pDb->dbLock( XFLM_LOCK_EXCLUSIVE, 1, XFLM_NO_TIMEOUT)))

    {

        goto Exit;

    }

    bDbLocked = TRUE;

 

    // Go through and resume all suspended indexes, suspend all non-suspended indexes - weird, but it gives an example of

    // both indexSuspend and indexResume

 

    uiIndexNum = 0;

    for (;;)

    {

 

        // Get the next Index

 

        if (RC_BAD( rc = pDb->indexGetNext( &uiIndexNum)))

        {

            if (rc == NE_XFLM_EOF_HIT)

            {

                rc = NE_XFLM_OK;

                break;

            }

        }

 

        // Determine the index's state.  If suspended, resume it.  If non-suspended, suspend it.

 

        if (RC_BAD( rc = pDb->indexStatus( uiIndexNum, &ixStatus)))

        {

            goto Exit;

        }

 

        if (ixStatus.eState == XFLM_INDEX_SUSPENDED)

        {

            rc = pDb->indexResume( uiIndexNum);

        }

        else

        {

            rc = pDb->indexSuspend( uiIndexNum);

        }

        if (RC_BAD( rc))

        {

            goto Exit;

        }

    }

 

Exit:

 

    // Unlock the database

 

    if (bDbLocked)

    {

        if (RC_BAD( rc = pDb->dbUnlock()))

        {
            goto Exit;
        }

    }
 

    See Also: indexSuspend, indexResume, indexGetNext

[Back to Top]

indexGetNext

    RCODE indexGetNext(

        FLMUINT *         puiIndexNum);

Obtain the number of the next index in the database.  Used to get a list of database indexes.

    Parameters In/Out:

FLMUINT * puiIndexNum

*puiIndexNum is the current index number.  The next index number after this one will be returned in *puiIndexNum.  To get the first index in the list, set *puiIndexNum to zero before calling.

    Example Code: see indexStatus.

    See Also: indexSuspend, indexResume, indexStatus

[Back to Top]

indexSuspend

    RCODE indexSuspend(

        FLMUINT    uiIndexNum);

Suspend indexing activity for the specified index.  This means that "some" index updates will be suspended.  For any given index, it is possible that some documents have been indexed and others have not.  Indexes that have documents which have not yet been indexed are said to be in an "offline" state.  Such indexes have a background thread running that is busy populating the index - indexing any documents that have not yet been indexed.  Indexes that have all documents indexed are said to be in an "online" state.  When an index is suspended, two things happen: 1) the indexing of "new" documents is suspended, and 2) if a background thread is running, it is terminated, and the indexing of any existing documents that were not yet indexed is suspended.  Any documents that have already been indexed are unaffected by an index suspend operation.  That is, if they are modified or deleted, the index will still be updated.

Note that an index suspend is persistent.  If the database is closed, when it is reopened, the index will still be suspended.  The indexResume method must be called to resume a suspended index.

    Parameters In:

FLMUINT uiIndexNum

The index to suspend.

    Parameters Out: none.

    Example Code: see indexStatus.

    See Also: indexResume, indexStatus, indexGetNext

[Back to Top]

indexResume

    RCODE indexResume(

        FLMUINT    uiIndexNum);

If the index was suspended, it will restart the background process that will get the index up to date so that it will eventually be online.  If the index is not currently suspended, this method does nothing, but still returns NE_XFLM_OK.

    Parameters In:

FLMUINT uiIndexNum

The index to resume.

   Parameters Out: none.

    Example Code: see indexStatus.

    See Also: indexSuspend, indexStatus, indexGetNext

[Back to Top]

keyRetrieve

    RCODE keyRetrieve(

        FLMUINT          uiIndex,

        IF_DataVector * pSearchKey,

        FLMUINT          uiSearchFlags,

        IF_DataVector * pFoundKey);

Search an index for a key and return the key that was found, if any.  Note that a search key may have multiple components - each of which corresponds to an index component as defined in the index's index definition document.  Each component has two pieces, the key part, and the ID part.  The key part is the actual data for that particular index component - string, number, binary, etc.  The ID part is the Node Identifier that the data for the key part came from.  The keyRetrieve method allows searching on all index components or a subset of them.  It also allows searching on just the key parts of those components or the key parts plus the ID parts.  Search options are specified in the uiSearchFlags parameter.

    Parameters In:

FLMUINT uiIndex	The index to use in the search.
IF_DataVector * pSearchKey	Pointer to the search key.
FLMUINT uiSearchFlags	Flags indicating what the search options are.  Flags may be ORed together (except in cases that are noted below).  Choices are: XFLM_FIRST.  Return the first key in the index.  NOTE: pSearchKey is ignored in this case.  If other flags are ORed with this flag, they will be ignored.  The best course is to simply not OR this flag with other flags. XFLM_LAST.  Return the last key in the index.  NOTE: pSearchKey is ignored in this case.  If other flags are ORed with this flag, they will be ignored.  If XFLM_FIRST and XFLM_LAST are both set, XFLM_FIRST will take precedence.  The best course is to simply not OR this flag with other flags. XFLM_EXACT.  Return the key that exactly matches pSearchKey.  This flag can only be ORed with XFLM_MATCH_IDS.  If ORed with XFLM_MATCH_IDS, it searches for the key that matches both the key parts and the ID parts of the index components.  Otherwise, it searches for the key that matches only the key parts of the index components. XFLM_INCL.  Return the key the exactly matches pSearchKey, or the first key that comes after that key if it is not found.  This flag can only be ORed with XFLM_MATCH_IDS and XFLM_KEY_EXACT.  If XFLM_KEY_EXACT is ORed in, XFLM_MATCH_IDS must also be ORed in.  If ORed with XFLM_MATCH_IDS, it searches for the key that matches both the key parts and the ID parts of the index components.  If it fails to find an exact match, it will return whatever key follows the search key, if any.  However, if the XFLM_KEY_EXACT flag is ORed in, it will not return whatever key follows the search key if the following search key has different key parts than those specified in the search key.  Instead, it will return NE_XFLM_EOF_HIT. XFLM_EXCL.  Return the first key that comes immediately after pSearchKey.  This flag can only be ORed with XFLM_MATCH_IDS and XFLM_KEY_EXACT.  If XFLM_KEY_EXACT is ORed in, XFLM_MATCH_IDS must also be ORed in.  If ORed with XFLM_MATCH_IDS, it searches for the key that comes immediately after the key that is specified in both the key parts and ID parts of the search key.  Note that in this case, the found key may be identical to the search key in its key parts, but different in the ID parts.  If the XFLM_KEY_EXACT flag is used in conjunction with the XFLM_MATCH_IDS flag, whatever key follows the search key will only be returned if it is identical in the key parts, but different in the ID parts.  If such a key does not exist, NE_XFLM_EOF_HIT will be returned.  NOTE: pSearchKey does not have to exist in the index in order to find a key that comes after it. XFLM_KEY_EXACT.  This flag may be used only in conjunction with XFLM_INCL or XFLM_EXCL, and the XFLM_MATCH_IDS flag must also be ORed in.  It indicates that the exclusivity (XFLM_EXCL) or inclusivity (XFLM_INCL) applies to only the ID parts of the search key.  The key parts of the found key must match exactly the key parts of the search key.  The search will not return a key whose key parts do not match the key parts of the search key. XFLM_MATCH_IDS.  This flag may be used only in conjunction with XFLM_EXACT, XFLM_INCL, and XFLM_EXCL.  It indicates that the exactness (XFLM_EXACT), exclusivity (XFLM_EXCL), or inclusivity (XFLM_INCL) is to be applied to the combination of key parts and ID parts.

    Parameters Out:

IF_DataVector * pFoundKey

The key that was found.

    Example Code:

    IF_Db *                           pDb;

    IF_DataVector *            ifpFoundKey = NULL;

    FLMUINT                      uiIndex;

 

    // Open a database to get pDb (not shown)
 

    // Create an instance of the IF_DataVector  interface first.

    if (RC_BAD( rc = pDbSystem->createIFDataVector( &ifpFoundKey)))
    {
        goto Exit;
    }

 

    // Determine the index we are using... (not shown)

 

    // Get the first key in the index.
    if (RC_BAD( rc = pDb->keyRetrieve( uiIndex, NULL, XFLM_FIRST, ifpFoundKey)))

    {
        goto Exit;
    }
 

   See Also:

[Back to Top]

enableEncryption

    RCODE enableEncryption( void);

This method enables encryption on the database.  If encryption is already enabled, a new database key will be generated for the database.

    Parameters In: none

    Parameters Out: none.

    Example Code:

    IF_Db *                pDb = NULL;

 

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

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

    .

    .

    // Enable encryption on the database

    if (RC_BAD( rc = pDb->enableEncryption()))

    {
        goto Exit;
    }
 

    See Also: wrapKey, rollOverDbKey.

[Back to Top]

wrapKey

    RCODE wrapKey(

        char *    pszPassword = NULL);

This method wraps the database key either in a password or in the NICI storage key.

    Parameters In:

char * pszPassword

Specifies the password the database key is to be wrapped in.  If a NULL is passed, the database key will be wrapped in the NICI storage key.

    Parameters Out: none.

    Example Code:

    IF_Db *                pDb = NULL;

 

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

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

    .

    .

    // Wrap the database key in the password "abcdef"

    if (RC_BAD( rc = pdb->wrapKey( "abcdef")))
    {
        goto Exit;
    }
 

    See Also: enableEncryption, rollOverDbKey.

[Back to Top]

rollOverDbKey

    RCODE rollOverDbKey( void);

This method generates a new database key and re-wraps all other encryption keys in the new database key.  The new database key is ALWAYS wrapped in the local NICI storage key, even if it was previously wrapped in a password.

    Parameters In: none

    Parameters Out: none.

    Example Code:

    IF_Db *                pDb = NULL;

 

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

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

    .

    .

    // Generate a new database key and rewrap all other encryption keys in the new database key.

    if (RC_BAD( rc = pdb->rollOverDbKey()))
    {
        goto Exit;
    }
 

    See Also: enableEncryption, wrapKey.

[Back to Top]

changeItemState

    RCODE changeItemState(

        FLMUINT                uiDictType,

        FLMUINT                uiDictNum,

        char *                       pszState);

Change the state of an element or attribute definition document.  NOTE: This method is the only way that the XFLAIM:State attribute of an element definition document or attribute definition document can be changed.  Direct modification of the XFLAIM:State attribute in these definition documents is not allowed.  This is done to ensure that only valid state changes are allowed.

    Parameters In:

FLMUINT uiDictType	Identifies the type of dictionary definition document to change.  It must be either ELM_ELEMENT_TAG or ELM_ATTRIBUTE_TAG.
FLMUINT uiDictNum	The element or attribute identifier in the dictionary.
char * pszState	A native string indicating the new state.  Note that the XFLAIM:State attribute will be modified to the value in this parameter.  The changeItemState method enforces legal state changes.  The only legal state changes are as follows: active --> checking.  This is used to indicate that a check of the database is about to begin to look for occurrences of the element or attribute.  If XFLAIM finds any instances of the element or attribute when it scans the database (in a background thread), it will automatically change the state back to active.  The same is true if XFLAIM detects that an application creates an instance of the element or attribute.  If the background thread gets all the way through the database without finding an instance of the element or attribute, and the state has not been changed back to active, the background thread will change the state to unused.  Note that the background thread that scans the database is only allowed to change the state of the definition document to unused.  Once the state of the definition document is unused, an application may delete the element or attribute definition document from the dictionary. active --> purge.  This is used to indicate that the element or attribute is going to be deleted from the database.  New instances of the element or attribute cannot be created while the element or attribute definition document is in this state.  If XFLAIM finds any instances of the element or attribute when it scans the database (in a background thread), it will delete those instances (as well as any subordinate nodes).  After deleting all instances of the element or attribute, the background thread will also delete the element or attribute definition document from the dictionary. checking --> active.  Note that the background thread that scans the database will make this change if it finds occurrences of the element or attribute in the database.  However, the application is also allowed to make this change. purge --> active.  This is a way for an application to stop the purge of an element or attribute from the database. unused --> active, checking, or purge.

    Parameters Out: none.

    Example Code:

    IF_Db *                           pDb;

    FLMUINT                      uiElmDictNum;

 

    // Open a database to get pDb (not shown)
 

    // Determine the element definition we need to purge... (not shown)

    // uiElmDictNum = ???;

 

    // Set the state of element definition for uiElmDictNum to delete it from the database.
    if (RC_BAD( rc = pDb->changeItemState( ELM_ELEMENT_TAG, uiElmDictNum, "purge")))

    {
        goto Exit;
    }
 

[Back to Top]

reduceSize

    RCODE reduceSize(

        FLMUINT             uiCount,
        FLMUINT *          puiCount);

This method reduces the physical size of a database.  The size of the database is reduced by freeing a specified number of blocks from the available (unused) block list back to the operating system.  The blocks are swapped one at a time with the block at the logical EOF of the database.  The database file that has the logical EOF is then truncated.  The reduceSize method will quite when it has either a) freed all of the blocks in the available block list, or b) freed the number of blocks specified.  NOTE: There must be no active transaction for this IF_Db object when the reduceSize method is called.

    Parameters In:

FLMUINT uiCount

The target number of blocks to reduce the database size by.

    Parameters Out:

FLMUINT * puiCount

The actual number of block that the database was reduced by.

    Example Code:

    IF_Db *                           pDb;

    FLMUINT                      uiBlocksFreed;

 

    // Open a database to get pDb (not shown)
 

    // Reduce the database size by 1000 blocks.

 

    if (RC_BAD( rc = pDb->reduceSize( 1000, &uiBlocksFreed)))

    {

        goto Exit;

    }
 

    See Also:

[Back to Top]

upgrade

    RCODE upgrade(

        IF_UpgradeClient *    pUpgradeClient);

This method upgrades a database to the latest XFLAIM version.  There currently are no methods defined for the IF_UpgradeClient interface.

    Parameters In:

IF_UpgradeClient* pUpgradeClient

User-provided callback interface.

    Parameters Out: none.

    See Also:

[Back to Top]

createRootElement

    RCODE createRootElement(

        FLMUINT                    uiCollection,

        FLMUINT                    uiNameId,

        IF_DOMNode **         ppElementNode,

        FLMUINT64 *             pui64NodeId = NULL);

Create an element node as the root node of a new document.

    Parameters In:

FLMUINT uiCollection	The collection where the new element node and document will be created.
FLMUINT uiNameId	The element name ID to be used for the root node.

    Parameters Out:

IF_DOMNode ** ppElementNode

Returns a pointer to the newly created DOM node.  This node will be an element node that is the root node of a newly created document.  NOTE: *ppElementNode should be NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, createRootElement  will Release that object and *ppElementNode will be assigned to a newly created IF_DOMNode object.  If createRootElement returns an error, the contents of *ppElementNode is unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

FLMUINT64 * pui64NodeId

Returns the node identifier of the newly created node.  A NULL may be passed in this parameter if the node identifier is not needed.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pElementNode = NULL;

    FLMUINT                      uiElementNameId;

 

    // Open a database to get pDb (not shown)

 

    // Determine uiElementNameId (not shown) - this is the dictionary id of the element to be created.
 

    // Create a new document with the root node being an element node

 

    if (RC_BAD( rc = pDb->createRootElement( XFLM_DATA_COLLECTION, uiElementNameId, &pElementNode , NULL))

    {

        goto Exit;

    }
 

    See Also: createDocument, documentDone, IF_DOMNode::createNode, IF_DOMNode::createAttribute, IF_DOMNode::createAnnotation

[Back to Top]

createDocument

    RCODE createDocument(

        FLMUINT            uiCollection,

        IF_DOMNode ** ppDocumentNode,

        FLMUINT64 *     pui64NodeId = NULL);

Create a document node as the root node of a new document.

    Parameters In:

FLMUINT uiCollection

The collection where the new node will be created.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

Returns a pointer to the newly created DOM node.  This node will be a document node that is the root node of a newly created document.  NOTE: *ppDocumentNode should be NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, createDocument will Release that object and *ppDocumentNode will be assigned to a newly created IF_DOMNode object.  If createDocument returns an error, the contents of *ppDocumentNode is unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

FLMUINT64 * pui64NodeId

Returns the node identifier of the newly created node.  A NULL may be passed in this parameter if the node identifier is not needed.

  Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDocumentNode = NULL;

 

    // Open a database to get pDb (not shown)

 

    // Create a new document.

 

    if (RC_BAD( rc = pDb->createDocument( XFLM_DATA_COLLECTION, &pDocumentNode, NULL))

    {

        goto Exit;

    }
 

    See Also: createRootElement, documentDone, IF_DOMNode::createNode, IF_DOMNode::createAttribute, IF_DOMNode::createAnnotation

[Back to Top]

getFirstDocument

    RCODE getFirstDocument(

        FLMUINT                     uiCollection,
        IF_DOMNode **          ppDocumentNode);

Retrieve the root node of the first document in the specified collection.

    Parameters In:

FLMUINT uiCollection

The target collection number.

    Parameters Out:

IF_DOMNode **  ppDocumentNode

Returns the root node of the first document.  NOTE: *ppDocumentNode should be NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, getFirstDocument will Release that object and *ppDocumentNode will be assigned to the found IF_DOMNode object (if any).  If getFirstDocument returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

  Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDocumentNode = NULL;

 

    // Open a database to get pDb (not shown)

 

    // Get the first document in the default data collection.

 

    if (RC_BAD( rc = pDb->getFirstDocument( XFLM_DATA_COLLECTION, &pDocumentNode))

    {

        goto Exit;

    }
 

    See Also: getLastDocument, getDocument

[Back to Top]

getLastDocument

    RCODE getLastDocument(

        FLMUINT                     uiCollection,
        IF_DOMNode **          ppDocumentNode);

Retrieve the root node of the last document in the specified collection.

    Parameters In:

FLMUINT uiCollection

The target collection number.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

Returns the root node of the last document.  NOTE: *ppDocumentNode should be NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, getLastDocument will Release that object and *ppDocumentNode will be assigned to the found IF_DOMNode object (if any).  If getLastDocument returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

  Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDocumentNode = NULL;

 

    // Open a database to get pDb (not shown)

 

    // Get the last document in the default data collection.

 

    if (RC_BAD( rc = pDb->getLastDocument( XFLM_DATA_COLLECTION, &pDocumentNode))

    {

        goto Exit;

    }
 

    See Also: getFirstDocument, getDocument

[Back to Top]

getDocument

    RCODE getDocument(

        FLMUINT                     uiCollection,
        FLMUINT                     uiFlags,
        FLMUINT64                 ui64DocumentId,
        IF_DOMNode **          ppDocumentNode);

This is a method to retrieve the root node of the last document in the specified collection.

    Parameters In:

FLMUINT uiCollection	The target collection number.
FLMUINT uiFlags	Flags for the retrieval.  It may be one of the following: XFLM_FIRST.  Retrieve the first document in the collection.  ui64DocumentId is ignored. XFLM_LAST. Retrieve the last document in the collection.  ui64DocumentId is ignored. XFLM_EXACT.  Retrieve the exact document specified by the ui64DocumentId parameter.  If ui64DocumentId does not refer to a node that is the root node of a document, getDocument will return NE_XFLM_DOM_NODE_NOT_FOUND. XFLM_INCL.  Retrieve the document whose document identifier is greater than or equal to the document identifier specified in the ui64DocumentId parameter. XFLM_EXCL.  Retrieve the document whose document identifier is greater than the document identifier specified in the ui64DocumentId parameter.
FLMUINT64 ui64DocumentId	The document id to be retrieved.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

Returns the root node of the desired document.  NOTE: *ppDocumentNode should be NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, getDocument will Release that object and *ppDocumentNode will be assigned to the found IF_DOMNode object (if any).  If getDocument returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

  Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDocumentNode = NULL;

 

    // Open a database to get pDb (not shown)

 

    // Get the next document after the document whose document ID is 27, if any.  Could return

    // any document ID of 28 or higher.

 

    if (RC_BAD( rc = pDb->getDocument( XFLM_DATA_COLLECTION, XFLM_EXCL, 27, &pDocumentNode))

    {

        goto Exit;

    }
 

    See Also: getFirstDocument, getLastDocument

[Back to Top]

documentDone

    RCODE documentDone(

        FLMUINT         uiCollection,

        FLMUINT64     ui64DocumentId);

Signal that a document creation/modification is complete.  If uiCollection is the dictionary collection (XFLM_DICT_COLLECTION), documentDone will perform any work that needs to be done to verify that the dictionary document is a valid dictionary document.  If the document is an index definition document, calling documentDone may also trigger the creation or rebuilding of the index.  If an application wants to create an element or attribute definition document and begin creating instances of that element or attribute in other documents in the same transaction or reference the element or attribute from an index definition document, it must call documentDone on the element or attribute definition document before XFLAIM will allow instances to be created and before the element or attribute can be referenced from an index definition document.  The calling of documentDone is XFLAIM's cue that the application is ready to use the definition to create other documents.

Note that when a transaction is committed XFLAIM automatically calls documentDone for every document that was modified or created during the transaction.  However, it is better for an application to call documentDone when it knows it is done working on a document.  This is because XFLAIM only keeps a limited number of document identifiers in its "pending documents" list.  When that list fills up, XFLAIM will return the error code: NE_XFLM_TOO_MANY_PENDING_DOCUMENTS.  This problem can be alleviated by calling documentDone immediately after finishing the updating or creating of a particular document.

    Parameters In:

FLMUINT uiCollection	The collection where the document is stored.
FLMUINT64 ui64DocumentId	The document identifier of the document whose creation/modification is complete.

  Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUINT64                  ui64DocumentId;

 

    // Open a database to get pDb (not shown)

 

    // Create an element definition document.

 

    if (RC_BAD( rc = pDb->createRootElement( XFLM_DICT_COLLECTION, ELM_ELEMENT_TAG,

                                                    &pDictDoc, &ui64DocumentId))

    {

        goto Exit;

    }

 

    // Create the necessary attributes for an element definition document (not shown)
 

    // Declare the element definition document "done".

 

    if (RC_BAD( rc = pDb->documentDone( XFLM_DICT_COLLECTION, ui64DocumentId)))

    {

        goto Exit;

    }

    Parameters Out: none.

    See Also: createDocument, createRootElement, IF_DOMNode::createNode, IF_DOMNode::createAttribute, documentDone(2).

[Back to Top]

documentDone(2)

    RCODE documentDone(

        IF_DOMNode *    pDocumentNode);

See documentation for documentDone.  This method is an alternate way to specify the document.  Instead of passing a collection number and a document node ID, the pointer to the DOM node object that is the root node of the document is passed.

    Parameters In:

IF_DOMNode * pDocumentNode

The DOM node that is the root of a document whose creation/modification is complete.

  Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUINT64                  ui64DocumentId;

 

    // Open a database to get pDb (not shown)

 

    // Create an element definition document.

 

    if (RC_BAD( rc = pDb->createRootElement( XFLM_DICT_COLLECTION, ELM_ELEMENT_TAG,

                                                    &pDictDoc, &ui64DocumentId))

    {

        goto Exit;

    }

 

    // Create the necessary attributes for an element definition document (not shown)
 

    // Declare the element definition document "done".

 

    if (RC_BAD( rc = pDb->documentDone( pDictDoc)))

    {

        goto Exit;

    }

    Parameters Out: none.

    See Also: createDocument, createRootElement, IF_DOMNode::createNode, IF_DOMNode::createAttribute, documentDone

[Back to Top]

createElementDef(1)

    RCODE createElementDef(

        char *                       pszNamespaceURI,

        char *                       pszElementName,

        FLMUINT                uiDataType,

        FLMUINT *             puiElementNameId = NULL,

        IF_DOMNode **     ppDocumentNode = NULL);

Create a new element definition document.  Element name and namespace are specified as native strings.  Note that createElementDef automatically calls the documentDone method after it has created the element definition document.

    Parameters In:

char * pszNamespaceURI	Native string containing the URI of the namespace.  May be NULL.
char * pszElementName	Native string containing the element name to be given the new element definition.
FLMUINT uiDataType	The data type of the new element.

    Parameters In/Out:

FLMUINT * puiElementNameId

If *puiElementNameId is non-zero, this is the numeric name identifier that will be assigned to the new element definition.  If *puiElementNameId is zero, XFLAIM will assign a name identifier and return it here.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

If non-NULL, the root node of the new element definition document is returned.  NOTE: If ppDocumentNode is non-NULL, *ppDocumentNode should be set to NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, createElementDef will Release that object and *ppDocumentNode will be assigned to the newly created IF_DOMNode object.  If createElementDef returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

  Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUINT                      uiSalaryElementId;

 

    // Open a database to get pDb (not shown)

 

    // Create an element definition document whose element name is "salary".

    // Namespace is "www.acme.com".  Type is number.

    // Allow XFLAIM to assign the element name identifier.

 

    uiSalaryElementId = 0;

    if (RC_BAD( rc = pDb->createElementDef( "www.acme.com", "salary", XFLM_NUMBER_TYPE, &uiSalaryElementId,

                                                    &pDictDoc)))

    {

        goto Exit;

    }

    See Also: createElementDef(2), createUniqueElmDef(1), createUniqueElmDef(2), getElementNameId(1), getElementNameId(2), createAttributeDef(1), createAttributeDef(2)

[Back to Top]

createElementDef(2)

    RCODE createElementDef(

        FLMUNICODE *         puzNamespaceURI,

        FLMUNICODE *         puzElementName,

        FLMUINT                    uiDataType,

        FLMUINT *                 puiElementNameId = NULL,

        IF_DOMNode **         ppDocumentNode = NULL);

Create a new element definition document.  Element name and namespace are specified as unicode strings.  Note that createElementDef automatically calls the documentDone method after it has created the element definition document.

    Parameters In:

FLMUNICODE * puzNamespaceURI	A unicode string containing the URI of the namespace.  May be NULL.
FLMUNICODE * puzElementName	A unicode string containing the element name to be given the new element definition.
FLMUINT uiDataType	The data type of the new element.

    Parameters In/Out:

FLMUINT * puiElementNameId

If *puiElementNameId is non-zero, this is the numeric name identifier that will be assigned to the new element definition.  If *puiElementNameId is zero, XFLAIM will assign a name identifier and return it here.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

If non-NULL, the root node of the new element definition document is returned.  NOTE: If ppDocumentNode is non-NULL, *ppDocumentNode should be set to NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, createElementDef will Release that object and *ppDocumentNode will be assigned to the newly created IF_DOMNode object.  If createElementDef returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUNICODE *          puzNamespace = {'w', 'w', 'w', '.', 'a', 'c', 'm', 'e', '.', 'c', 'o', 'm', 0};

    FLMUNICODE *          puzSalaryName = {'s', 'a', 'l', 'a', 'r', 'y', 0};

    FLMUINT                      uiSalaryElementId;

 

    // Open a database to get pDb (not shown)

 

    // Create an element definition document whose element name is "salary".

    // Namespace is "www.acme.com".  Type is number.

    // Force the element name identifier to be 35 instead of allowing XFLAIM to assign it.

 

    uiSalaryElementId = 35;

    if (RC_BAD( rc = pDb->createElementDef( puzNamespace, puzSalaryName, XFLM_NUMBER_TYPE,

                                                     &uiSalaryElementId, &pDictDoc)))

    {

        goto Exit;

    }

    See Also: createElementDef(1), createUniqueElmDef(1), createUniqueElmDef(2), getElementNameId(1), getElementNameId(2), createAttributeDef(1), createAttributeDef(2)

[Back to Top]

createUniqueElmDef(1)

    RCODE createUniqueElmDef(

        char *                       pszNamespaceURI,

        char *                       pszElementName,

        FLMUINT *             puiElementNameId = NULL,

        IF_DOMNode **     ppDocumentNode = NULL);

Create a new element definition document.  Element name and namespace are specified as native strings.  The difference between this method and the createElementDef methods is that this method creates a definition that specifies that the child elements of this element must all be unique (the UniqueSubElements attribute on the element definition will be set to "true").  The data type for this definition is automatically set to be XFLM_NODATA_TYPE, since an element of this type can only have element nodes as child nodes. Note that createUniqueElmDef automatically calls the documentDone method after it has created the element definition document.

    Parameters In:

char * pszNamespaceURI	Native string containing the URI of the namespace.  May be NULL.
char * pszElementName	Native string containing the element name to be given the new element definition.

    Parameters In/Out:

FLMUINT * puiElementNameId

If *puiElementNameId is non-zero, this is the numeric name identifier that will be assigned to the new element definition.  If *puiElementNameId is zero, XFLAIM will assign a name identifier and return it here.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

If non-NULL, the root node of the new element definition document is returned.  NOTE: If ppDocumentNode is non-NULL, *ppDocumentNode should be set to NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, createElementDef will Release that object and *ppDocumentNode will be assigned to the newly created IF_DOMNode object.  If createElementDef returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

  Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUINT                      uiChaptersElementId;

 

    // Open a database to get pDb (not shown)

 

    // Create an element definition document whose element name is "chapters".  Child elements to this element must all be unique.

    // Namespace is "www.acme.com".

    // Allow XFLAIM to assign the element name identifier.

 

    uiChaptersElementId = 0;

    if (RC_BAD( rc = pDb->createUniqueElmDef( "www.acme.com", "chapters", &uiChaptersElementId,

                                                    &pDictDoc)))

    {

        goto Exit;

    }

    See Also: createElementDef(1), createElementDef(2), createUniqueElmDef(2), getElementNameId(1), getElementNameId(2), createAttributeDef(1), createAttributeDef(2)

[Back to Top]

createUniqueElmDef(2)

    RCODE createUniqueElmDef(

        FLMUNICODE *         puzNamespaceURI,

        FLMUNICODE *         puzElementName,

        FLMUINT *                 puiElementNameId = NULL,

        IF_DOMNode **         ppDocumentNode = NULL);

Create a new element definition document.  Element name and namespace are specified as unicode strings.  The difference between this method and the createElementDef methods is that this method creates a definition that specifies that the child elements of this element must all be unique (the UniqueSubElements attribute on the element definition will be set to "true").  The data type for this definition is automatically set to be XFLM_NODATA_TYPE, since an element of this type can only have element nodes as child nodes. Note that createUniqueElmDef automatically calls the documentDone method after it has created the element definition document.

    Parameters In:

FLMUNICODE * puzNamespaceURI	A unicode string containing the URI of the namespace.  May be NULL.
FLMUNICODE * puzElementName	A unicode string containing the element name to be given the new element definition.

    Parameters In/Out:

FLMUINT * puiElementNameId

If *puiElementNameId is non-zero, this is the numeric name identifier that will be assigned to the new element definition.  If *puiElementNameId is zero, XFLAIM will assign a name identifier and return it here.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

If non-NULL, the root node of the new element definition document is returned.  NOTE: If ppDocumentNode is non-NULL, *ppDocumentNode should be set to NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, createElementDef will Release that object and *ppDocumentNode will be assigned to the newly created IF_DOMNode object.  If createElementDef returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUNICODE *          puzNamespace = {'w', 'w', 'w', '.', 'a', 'c', 'm', 'e', '.', 'c', 'o', 'm', 0};

    FLMUNICODE *          puzChaptersName = {'c', 'h', 'a', 'p', 't', 'e', 'r', 's', 0};

    FLMUINT                      uiChaptersElementId;

 

    // Open a database to get pDb (not shown)

 

    // Create an element definition document whose element name is "chapters".  Child elements of this element must all be unique.

    // Namespace is "www.acme.com".

    // Force the element name identifier to be 36 instead of allowing XFLAIM to assign it.

 

    uiChaptersElementId = 36;

    if (RC_BAD( rc = pDb->createElementDef( puzNamespace, puzChaptersName,

                                                     &uiChaptersElementId, &pDictDoc)))

    {

        goto Exit;

    }

    See Also: createElementDef(1), createElementDef(2), createUniqueElmDef(1), getElementNameId(1), getElementNameId(2), createAttributeDef(1), createAttributeDef(2)

[Back to Top]

getElementNameId(1)

    RCODE getElementNameId(

        char *             pszNamespaceURI,

        char *             pszElementName,

        FLMUINT *   puiElementNameId);

Return the numeric name identifier of the specified element name.

    Parameters In:

char * pszNamespaceURI	A native string containing the URI of the namespace for the element.  May be NULL.
char * pszElementName	A native string containing the name of the element.

    Parameters Out:

FLMUINT * puiElementNameId

The numeric name identifier for the specified element name and namespace is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUINT                      uiSalaryElementId;

 

    // Open a database to get pDb (not shown)

 

    // Get the element name id for the element whose name is "salary" and namespace is "www.acme.com"

 

    if (RC_BAD( rc = pDb->getElementNameId( "www.acme.com", "salary", &uiSalaryElementId)))

    {

        goto Exit;

    }

    See Also: createElementDef(1), createElementDef(2), createUniqueElmDef(1), createUniqueElmDef(2), getElementNameId(2)

[Back to Top]

getElementNameId(2)

    RCODE getElementNameId(

        FLMUNICODE *    puzNamespaceURI,

        FLMUNICODE *    puzElementName,

        FLMUINT *            puiElementNameId);

Return the numeric name identifier of the specified element name.

    Parameters In:

FLMUNICODE * puzNamespaceURI	A unicode string containing the URI of the namespace for the element.  May be NULL.
FLMUNICODE * puzElementName	A unicode string containing the name of the element.

    Parameters Out:

FLMUINT * puiElementNameId

The numeric name identifier for the specified element name and namespace is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUNICODE *          puzNamespace = {'w', 'w', 'w', '.', 'a', 'c', 'm', 'e', '.', 'c', 'o', 'm', 0};

    FLMUNICODE *          puzSalaryName = {'s', 'a', 'l', 'a', 'r', 'y', 0};

    FLMUINT                      uiSalaryElementId;

 

    // Open a database to get pDb (not shown)

 

    // Get the element name id for the element whose name is "salary" and namespace is "www.acme.com"

 

    if (RC_BAD( rc = pDb->getElementNameId( puzNamespace, puzSalaryName, &uiSalaryElementId)))

    {

        goto Exit;

    }

    See Also: createElementDef(1), createElementDef(2), createUniqueElmDef(1), createUniqueElmDef(2), getElementNameId(1)

[Back to Top]

createAttributeDef(1)

    RCODE createAttributeDef(

        char *                       pszNamespaceURI,
        char *                       pszAttributeName,
        FLMUINT               uiDataType,
        FLMUINT *            puiAttributeNameId,
        IF_DOMNode **    ppDocumentNode = NULL);

Create a new attribute definition document.  Attribute name and namespace are specified as native strings.  Note that createAttributeDef automatically calls the documentDone method after it has created the attribute definition document.

    Parameters In:

char * pszNamespaceURI	A native string containing the namespace URI of the new attribute.
char * pszAttributeName	A native string containing the attribute name to be given the new attribute definition.
FLMUINT uiDataType	The data type for the attribute.

    Parameters In/Out:

FLMUINT * puiAttributeNameId

If *puiAttributeNameId is non-zero, this is the numeric name identifier that will be assigned to the new attribute definition.  If *puiAttributeNameId is zero, XFLAIM will assign a name identifier and return it here.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

If non-NULL, the root node of the new attribute definition document is returned.  NOTE: If ppDocumentNode is non-NULL, *ppDocumentNode should be set to NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, createAttributeDef will Release that object and *ppDocumentNode will be assigned to the newly created IF_DOMNode object.  If createAttributeDef returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUINT                      uiSalaryAttributeId;

 

    // Open a database to get pDb (not shown)

 

    // Create an attribute definition document whose attribute name is "salary".

    // Namespace is "www.acme.com".  Type is number.

    // Allow XFLAIM to assign the attribute name identifier.

 

    uiSalaryAttributeId = 0;

    if (RC_BAD( rc = pDb->createAttributeDef( "www.acme.com", "salary", XFLM_NUMBER_TYPE, &uiSalaryAttributeId,

                                                    &pDictDoc)))

    {

        goto Exit;

    }

    See Also: createAttributeDef( 2), getAttributeNameId(1), getAttributeNameId(2), createElementDef(1), createElementDef(2), createUniqueElmDef(1), createUniqueElmDef(2)

[Back to Top]

createAttributeDef(2)

    RCODE createAttributeDef(

        FLMUNICODE *     puzNamespaceURI,
        FLMUNICODE *     puzAttributeName,
        FLMUINT                uiDataType,
        FLMUINT *             puiAttributeNameId,
        IF_DOMNode **     ppDocumentNode = NULL);

Create a new attribute definition document.  Attribute name and namespace are specified as unicode strings.  Note that createAttributeDef automatically calls the documentDone method after it has created the attribute definition document.

    Parameters In:

FLMUNICODE * puzNamespaceURI	A unicode string containing the namespace URI of the new attribute.
FLMUNICODE * puzAttributeName	A unicode string containing the attribute name to be given the new attribute definition.
FLMUINT uiDataType	The data type for the attribute.

    Parameters In/Out:

FLMUINT * puiAttributeNameId

If *puiAttributeNameId is non-zero, this is the numeric name identifier that will be assigned to the new attribute definition.  If *puiAttributeNameId is zero, XFLAIM will assign a name identifier and return it here.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

If non-NULL, the root node of the new attribute definition document is returned.  NOTE: If ppDocumentNode is non-NULL, *ppDocumentNode should be set to NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, createAttributeDef will Release that object and *ppDocumentNode will be assigned to the newly created IF_DOMNode object.  If createAttributeDef returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUNICODE *          puzNamespace = {'w', 'w', 'w', '.', 'a', 'c', 'm', 'e', '.', 'c', 'o', 'm', 0};

    FLMUNICODE *          puzSalaryName = {'s', 'a', 'l', 'a', 'r', 'y', 0};

    FLMUINT                      uiSalaryAttributeId;

 

    // Open a database to get pDb (not shown)

 

    // Create an attribute definition document whose attribute name is "salary".

    // Namespace is "www.acme.com".  Type is number.

    // Force the attribute name identifier to be 35 instead of allowing XFLAIM to assign it.

 

    uiSalaryAttributeId = 35;

    if (RC_BAD( rc = pDb->createAttributeDef( puzNamespace, puzSalaryName, XFLM_NUMBER_TYPE,

                                                     &uiSalaryAttributeId, &pDictDoc)))

    {

        goto Exit;

    }

    See Also: createAttributeDef(1), getAttributeNameId(1), getAttributeNameId(2), createElementDef(1), createElementDef(2), createUniqueElmDef(1), createUniqueElmDef(2)

[Back to Top]

getAttributeNameId(1)

    RCODE getAttributeNameId(

        char *             pszNamespaceURI,

        char *             pszAttributeName,

        FLMUINT *   puiAttributeNameId);

Return the numeric name identifier of the specified attribute name.

    Parameters In:

char * pszNamespaceURI	A native string containing the URI of the namespace for the attribute.  May be NULL.
char * pszAttributeName	A native string containing the name of the attribute.

    Parameters Out:

FLMUINT * puiAttributeNameId

The numeric name identifier for the specified attribute name and namespace is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUINT                      uiSalaryAttributeId;

 

    // Open a database to get pDb (not shown)

 

    // Get the attribute name id for the attribute whose name is "salary" and namespace is "www.acme.com"

 

    if (RC_BAD( rc = pDb->getAttributeNameId( "www.acme.com", "salary", &uiSalaryAttributeId)))

    {

        goto Exit;

    }

    See Also: createAttributeDef(1), createAttributeDef(2), getAttributeNameId(2)

[Back to Top]

getAttributeNameId(2)

    RCODE getAttributeNameId(

        FLMUNICODE *    puzNamespaceURI,

        FLMUNICODE *    puzAttributeName,

        FLMUINT *            puiAttributeNameId);

Return the numeric name identifier of the specified attribute name.

    Parameters In:

FLMUNICODE * puzNamespaceURI	A unicode string containing the URI of the namespace for the attribute.  May be NULL.
FLMUNICODE * puzAttributeName	A unicode string containing the name of the attribute.

    Parameters Out:

FLMUINT * puiAttributeNameId

The numeric name identifier for the specified attribute name and namespace is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUNICODE *          puzNamespace = {'w', 'w', 'w', '.', 'a', 'c', 'm', 'e', '.', 'c', 'o', 'm', 0};

    FLMUNICODE *          puzSalaryName = {'s', 'a', 'l', 'a', 'r', 'y', 0};

    FLMUINT                      uiSalaryAttributeId;

 

    // Open a database to get pDb (not shown)

 

    // Get the attribute name id for the attribute whose name is "salary" and namespace is "www.acme.com"

 

    if (RC_BAD( rc = pDb->getAttributeNameId( puzNamespace, puzSalaryName, &uiSalaryAttributeId)))

    {

        goto Exit;

    }

    See Also: createAttributeDef(1), createAttributeDef(2), getAttributeNameId(1)

[Back to Top]

createPrefixDef(1)

    RCODE createPrefixDef(

        char *           pszPrefixName,
        FLMUINT * puiPrefixNumber);

Create a new prefix definition using a native string for the name of the prefix.  Note that createPrefixDef automatically calls the documentDone method after it has created the prefix definition document.

    Parameters In:

char * pszPrefixName

The prefix name - a native string.

    Parameters In/Out:

FLMUINT * puiPrefixNumber

If puiPrefixNumber is non-NULL and *puiPrefixNumber is non-zero, this is the prefix number that will be assigned to the new prefix definition.  If puiPrefixNumber is NULL or *puiPrefixNumber is zero, XFLAIM will assign a prefix number.  If puiPrefixNumber is non-NULL, the assigned prefix number will be returned in *puiPrefixNumber.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUINT                      uiPrefixNumber;

 

    // Open a database to get pDb (not shown)

 

    // Create a prefix definition document whose prefix name name is "abc".

    // Allow XFLAIM to assign the prefix number..

 

    uiPrefixNumber = 0;

    if (RC_BAD( rc = pDb->createPrefixDef( "abc", &uiPrefixNumber)))

    {

        goto Exit;

    }

    See Also: createPrefixDef(2), getPrefixId(1), getPrefixId(2)

[Back to Top]

createPrefixDef(2)

    RCODE createPrefixDef(

        FLMUNICODE *    puzPrefixName,
        FLMUINT *            puiPrefixNumber);

Create a new prefix definition using a unicode string for the name of the prefix.  Note that createPrefixDef automatically calls the documentDone method after it has created the prefix definition document.

    Parameters In:

FLMUNICODE * puzPrefixName

The prefix name - a unicode string.

    Parameters In/Out:

FLMUINT * puiPrefixNumber

If puiPrefixNumber is non-NULL and *puiPrefixNumber is non-zero, this is the prefix number that will be assigned to the new prefix definition.  If puiPrefixNumber is NULL or *puiPrefixNumber is zero, XFLAIM will assign a prefix number.  If puiPrefixNumber is non-NULL, the assigned prefix number will be returned in *puiPrefixNumber.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUNICODE *          puzPrefixName = {'a', 'b', 'c', 0};

    FLMUINT                      uiPrefixNumber;

 

    // Open a database to get pDb (not shown)

 

    // Create a prefix definition document whose prefix name name is "abc".

    // Force the prefix number to be 35 instead of allowing XFLAIM to assign it..

 

    uiPrefixNumber = 35;

    if (RC_BAD( rc = pDb->createPrefixDef( puzPrefixName, &uiPrefixNumber)))

    {

        goto Exit;

    }

    See Also: createPrefixDef(1), getPrefixId(1), getPrefixId(2)

[Back to Top]

getPrefixId(1)

    RCODE getPrefixId(

        char *                       pszPrefixName,
        FLMUINT *            puiPrefixNumber);

Return the prefix number for the specified prefix name.

    Parameters In:

char * pszPrefixName

The prefix name - a native string.

    Parameters Out:

FLMUINT * puiPrefixNumber

The prefix number for the specified prefix name is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUINT                      uiPrefixNumber;

 

    // Open a database to get pDb (not shown)

 

    // Get the prefix number for the prefix whose name is "abc"

 

    if (RC_BAD( rc = pDb->getPrefixId( "abc", &uiPrefixNumber)))

    {

        goto Exit;

    }

    See Also: createPrefixDef(1), createPrefixDef(2), getPrefixId(2)

[Back to Top]

getPrefixId(2)

    RCODE getPrefixId(

        FLMUNICODE *    puzPrefixName,
        FLMUINT *            puiPrefixNumber);

Return the prefix number for the specified prefix name.

    Parameters In:

FLMUNICODE * puzPrefixName

The prefix name - a unicode string.

    Parameters Out:

FLMUINT * puiPrefixNumber

The prefix number for the specified prefix name is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUNICODE *          puzPrefixName = {'a', 'b', 'c', 0};

    FLMUINT                      uiPrefixNumber;

 

    // Open a database to get pDb (not shown)

 

    // Get the prefix number for the prefix whose name is "abc"

 

    if (RC_BAD( rc = pDb->getPrefixId( puzPrefixName, &uiPrefixNumber)))

    {

        goto Exit;

    }

    See Also: createPrefixDef(1), createPrefixDef(2), getPrefixId(1)

[Back to Top]

createEncDef(1)

    RCODE createEncDef(

        char *               pszEncType,

        char *               pszEncName,

        FLMUINT       uiKeySize,
        FLMUINT *    puiEncNumber);

Create a new encryption definition using a native string for the name of the encryption definition.  Note that createEncDef automatically calls the documentDone method after it has created the encryption definition document.

    Parameters In:

char * pszEncType	The encryption type name - a native string.  Legal encryption types are "aes" and "des3".  NOTE: An application may also use the #defines for these (see xflaim.h): XFLM_ENC_AES_OPTION_STR and XFLM_ENC_DES3_OPTION_STR.
char * pszEncName	The encryption definition name - a native string.
FLMUINT uiKeySize	Size of the encryption key to be generated (in bits).

    Parameters In/Out:

FLMUINT * puiEncNumber

If puiEncNumber is non-NULL and *puiEncNumber is non-zero, this is the encryption number that will be assigned to the new encryption definition.  If puiEncNumber is NULL or *puiEncNumber is zero, XFLAIM will assign an encryption number.  If puiEncNumber is non-NULL, the assigned encryption number will be returned in *puiEncNumber.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUINT                      uiEncNumber;

 

    // Open a database to get pDb (not shown)

 

    // Create an encryption definition document whose encryption name name is "aes-256bit".  Encryption type is AES, key size is 256 bits.

    // Allow XFLAIM to assign the encryption number..

 

    uiEncNumber = 0;

    if (RC_BAD( rc = pDb->createEncDef( XFLM_ENC_AES_OPTION_STR, "aes-256bit", 256, &uiEncNumber)))

    {

        goto Exit;

    }

    See Also: createEncDef(2), getEncDefId(1), getEncDefId(2)

[Back to Top]

createEncDef(2)

    RCODE createEncDef(

        FLMUNICODE *    puzEncType,

        FLMUNICODE *    puzEncName,

        FLMUINT               uiKeySize,
        FLMUINT *            puiEncNumber);

Create a new encryption definition using a unicode string for the name of the encryption definition.  Note that createEncDef automatically calls the documentDone method after it has created the encryption definition document.

    Parameters In:

FLMUNICODE * puzEncType	The encryption type name - a native string.  Legal encryption types are "aes" and "des3" (encoded as a unicode stringof course).
FLMUNICODE * puzEncName	The encryption definition name - a unicode string.
FLMUINT uiKeySize	Size of the encryption key to be generated (in bits).

    Parameters In/Out:

FLMUINT * puiEncNumber

If puiEncNumber is non-NULL and *puiEncNumber is non-zero, this is the encryption number that will be assigned to the new encryption definition.  If puiEncNumber is NULL or *puiEncNumber is zero, XFLAIM will assign an encryption number.  If puiEncNumber is non-NULL, the assigned encryption number will be returned in *puiEncNumber.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc  = NULL;

    FLMUNICODE *           puzEncType = {'a', 'e', 's', 0};

    FLMUNICODE *           puzEncName = {'a', 'e', 's', '-', '2', '5', '6', 'b', 'i', 't', 0};

    FLMUINT                      uiEncNumber;

 

    // Open a database to get pDb (not shown)

 

    // Create an encryption definition document whose encryption name name is "aes-256bit".  Encryption type is AES, key size is 256 bits.

    // Assign the encryption number to be 39.

 

    uiEncNumber = 39;

    if (RC_BAD( rc = pDb->createEncDef( puzEncType, puzEncName, 256, &uiEncNumber)))

    {

        goto Exit;

    }

    See Also: createEncDef(1), getEncDefId(1), getEncDefId(2)

[Back to Top]

getEncDefId(1)

    RCODE getEncDefId(

        char *                       pszEncName,
        FLMUINT *            puiEncNumber);

Return the encryption number for the specified encryption definition name.

    Parameters In:

char * pszEncName

The encryption definition name - a native string.

    Parameters Out:

FLMUINT * puiEncNumber

The encryption number for the specified encryption definition name is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUINT                      uiEncNumber;

 

    // Open a database to get pDb (not shown)

 

    // Get the encryption number for the encryption definition whose name is "aes-256bit"

 

    if (RC_BAD( rc = pDb->getEncDefId( "aes-256bit", &uiEncNumber)))

    {

        goto Exit;

    }

    See Also: createEncDef(1), createEncDef(2), getEncDefId(2)

[Back to Top]

getEncDefId(2)

    RCODE getEncDefId(

        FLMUNICODE *    puzEncName,
        FLMUINT *             puiEncNumber);

Return the encryption number for the specified encryption definition name.

    Parameters In:

FLMUNICODE * puzEncName

The encryption definition name - a unicode string.

    Parameters Out:

FLMUINT * puiEncNumber

The encryption number for the specified encryption definition name is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUNICODE *          puzEncName = {'a', 'e', 's', '-', '2', '5', '6', 'b', 'i', 't', 0};

    FLMUINT                      uiEncNumber;

 

    // Open a database to get pDb (not shown)

 

    // Get the encryption number for the encryption definition whose name is "aes-256bit"

 

    if (RC_BAD( rc = pDb->getEncDefId( puzEncName, &uiEncNumber)))

    {

        goto Exit;

    }

    See Also: createEncDef(1), createEncDef(2), getEncDefId(1)

[Back to Top]

createCollectionDef(1)

    RCODE createCollectionDef(

        char *                pszCollectionName,
        FLMUINT *     puiCollectionNumber,

        FLMUINT        uiEncNumber = 0);

This is a method to create a new collection definition using a native string value for the name.  Note that createCollectionDef automatically calls the documentDone method after it has created the collection definition document.

    Parameters In:

char * pszCollectionName	A native string containing the collection name to be given the new collection definition.
FLMUINT uiEncNumber	If non-zero, the collection will be encrypted using the encryption key defined by this encryption number.

    Parameters In/Out:

FLMUINT * puiCollectionNumber

If puiCollectionNumber is non-NULL and *puiCollectionNumber is non-zero, this is the collection number that will be assigned to the new collection definition.  If puiCollectionNumber is NULL or *puiCollectionNumber is zero, XFLAIM will assign a collection number.  If puiCollectionNumber is non-NULL, the assigned collection number will be returned in *puiCollectionNumber.

    Example Code:

    IF_Db *                          pDb;

    FLMUINT                      uiCollectionNumber;

 

    // Open a database to get pDb (not shown)

 

    // Create a collection definition document whose collection name name is "MyDocuments".

    // Allow XFLAIM to assign the collection number..

 

    uiCollectionNumber = 0;

    if (RC_BAD( rc = pDb->createCollectionDef( "MyDocuments", &uiCollectionNumber, 0)))

    {

        goto Exit;

    }

    See Also: createCollectionDef(2), getCollectionNumber(1), getCollectionNumber(2)

[Back to Top]

createCollectionDef(2)

    RCODE createCollectionDef(

        FLMUNICODE *      puzCollectionName,
        FLMUINT *              puiCollectionNumber,

        FLMUINT                 uiEncNumber = 0);

This is a method to create a new collection definition using a unicode string value for the name.  Note that createCollectionDef automatically calls the documentDone method after it has created the collection definition document.

    Parameters In:

FLMUNICODE * puzCollectionName	A unicode string containing the collection name to be given the new collection definition.
FLMUINT uiEncNumber	If non-zero, the collection will be encrypted using the encryption key defined by this encryption number.

    Parameters Out/Out:

FLMUINT * puiCollectionNumber

If puiCollectionNumber is non-NULL and *puiCollectionNumber is non-zero, this is the collection number that will be assigned to the new collection definition.  If puiCollectionNumber is NULL or *puiCollectionNumber is zero, XFLAIM will assign a collection number.  If puiCollectionNumber is non-NULL, the assigned collection number will be returned in *puiCollectionNumber.

    Example Code:

    IF_Db *                          pDb;

    FLMUNICODE *          puzCollectionName = {'M', 'y', 'D', 'o', 'c', 'u', 'm', 'e', 'n', 't', 's', 0};

    FLMUINT                      uiCollectionNumber;

 

    // Open a database to get pDb (not shown)

 

    // Create a collection definition document whose collection name name is "MyDocuments".

    // Force the collection number to be 40 instead of allowing XFLAIM to assign the collection number..

 

    uiCollectionNumber = 40;

    if (RC_BAD( rc = pDb->createCollectionDef( puzCollectionName, &uiCollectionNumber, 0)))

    {

        goto Exit;

    }

    See Also: createCollectionDef(1), getCollectionNumber(1), getCollectionNumber(2)

[Back to Top]

getCollectionNumber(1)

    RCODE getCollectionNumber(

        char *                    pszCollectionName,

        FLMUINT *         puiCollectionNumber);

Return the collection number for the specified collection name.

    Parameters In:

char * pszCollectionName

A native string containing the name of the collection.

    Parameters Out:

FLMUINT * puiCollectionNumber

The collection number for the specified collection name is returned here.

    Example Code:

    IF_Db *                          pDb;

    char *                              pszCollectionName = "MyCollection";

    FLMUINT                      uiCollectionNumber;

 

    // Open a database to get pDb (not shown)

 

    // Get the collection number for the collection whose name is "MyCollection"

 

    if (RC_BAD( rc = pDb->getCollectionNumber( pszCollectionName, &uiCollectionNumber)))

    {

        goto Exit;

    }

    See Also: createCollectionDef(1), createCollectionDef(2), getCollectionNumber(2)

getCollectionNumber(2)

    RCODE getCollectionNumber(

        FLMUNICODE *    puzCollectionName,

        FLMUINT *             puiCollectionNumber);

Return the collection number for the specified collection name.

    Parameters In:

FLMUNICODE * puzCollectionName

A unicode string containing the name of the collection.

    Parameters Out:

FLMUINT * puiCollectionNumber

The collection number for the specified collection name is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUNICODE *          puzCollectionName = {'M', 'y', 'C', 'o', 'l', 'l', 'e', 'c', 't', 'i', 'o', 'n'};

    FLMUINT                      uiCollectionNumber;

 

    // Open a database to get pDb (not shown)

 

    // Get the collection number for the collection whose name is "MyCollection"

 

    if (RC_BAD( rc = pDb->getCollectionNumber( puzCollectionName, &uiCollectionNumber)))

    {

        goto Exit;

    }

    See Also: createCollectionDef(1), createCollectionDef(2), getCollectionNumber(1)

getIndexNumber(1)

    RCODE getIndexNumber(

        char *                    pszIndexName,

        FLMUINT *         puiIndexNumber);

Return the index number for the specified index name.

    Parameters In:

char * pszIndexName

A native string containing the name of the index.

    Parameters Out:

FLMUINT * puiIndexNumber

The index number for the specified index name is returned here.

    Example Code:

    IF_Db *                          pDb;

    char *                              pszIndexName = "MyIndex";

    FLMUINT                      uiIndexNumber;

 

    // Open a database to get pDb (not shown)

 

    // Get the index number for the index whose name is "MyIndex"

 

    if (RC_BAD( rc = pDb->getIndexNumber( pszIndexName, &uiIndexNumber)))

    {

        goto Exit;

    }

    See Also: getIndexNumber(2)

getIndexNumber(2)

    RCODE getIndexNumber(

        FLMUNICODE *    puzIndexName,

        FLMUINT *            puiIndexNumber);

Return the index number for the specified index name.

    Parameters In:

FLMUNICODE * puzIndexName

A unicode string containing the name of the index.

    Parameters Out:

FLMUINT * puiIndexNumber

The index number for the specified index name is returned here.

    Example Code:

    IF_Db *                          pDb;

    FLMUNICODE *          puzIndexName = {'M', 'y', 'I', 'n', 'd', 'e', 'x'};

    FLMUINT                      uiIndexNumber;

 

    // Open a database to get pDb (not shown)

 

    // Get the index number for the index whose name is "MyIndex"

 

    if (RC_BAD( rc = pDb->getIndexNumber( puzIndexName, &uiIndexNumber)))

    {

        goto Exit;

    }

    See Also: getIndexNumber(1)

getDictionaryDef

    RCODE getDictionaryDef(

        FLMUINT             uiDictType,

        FLMUINT             uiDictNumber,

        IF_DOMNode **  ppDocumentNode);

Retrieve a dictionary definition document that defines an element, attribute, collection, index, or prefix in the database.

    Parameters In:

FLMUINT uiDictType	The type of item being searched for.  Choices include the following: ELM_ELEMENT_TAG - retrieve element definition ELM_ATTRIBUTE_TAG - retrieve attribute definition ELM_INDEX_TAG - retrieve index definition ELM_COLLECTION_TAG - retrieve collection definition ELM_PREFIX_TAG - retrieve prefix definition.
FLMUINT uiDictNumber	The number that represent the dictionary item we are looking for.

    Parameters Out:

IF_DOMNode ** ppDocumentNode

If non-NULL, a pointer to the root node of the dictionary definition document is returned in *ppDocumentNode.  NOTE: If ppDocumentNode is non-NULL, *ppDocumentNode should be set to NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, getDictionaryDef will Release that object and *ppDocumentNode will be assigned to the found IF_DOMNode object.  If getDictionaryDefDef returns an error, the contents of *ppDocumentNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pDictDoc = NULL;

 

    // Open a database to get pDb (not shown)

 

    // Get the dictionary document for collection number 34.

 

    if (RC_BAD( rc = pDb->getDictionaryDef( ELM_COLLECTION_TAG, 34, &pDictDoc)))

    {

        goto Exit;

    }

    See Also: getDictionaryName(1), getDictionaryName(2)

[Back to Top]

getDictionaryName(1)

    RCODE getDictionaryName(

        FLMUINT             uiDictType,

        FLMUINT             uiDictNumber,

        char *                     pszName,

        FLMUINT *          puiNameBufSize,

        char *                     pszNamespace = NULL,

        FLMUINT *          puiNamespaceBufSize = NULL);

Retrieve the name and namespace (if applicable) of a dictionary definition for an element, attribute, collection, index, or prefix in the database.  The name and namespace are returned as native strings.

    Parameters In:

FLMUINT uiDictType	The type of item being searched for.  Choices include the following: ELM_ELEMENT_TAG - retrieve element definition ELM_ATTRIBUTE_TAG - retrieve attribute definition ELM_INDEX_TAG - retrieve index definition ELM_COLLECTION_TAG - retrieve collection definition ELM_PREFIX_TAG - retrieve prefix definition.
FLMUINT uiDictNumber	The number that represent the dictionary item we are looking for.

    Parameters In/Out:

FLMUINT  * puiNameBufSize

On input *puiNameBufSize should be set to the size of the pszName buffer in bytes.  On output it will return the number of characters in the name (not counting the null terminating byte).  NOTE: If the pszName parameter is NULL, this parameter is not used on input, and will return the total number of characters needed in the name (not counting the null terminating character).

FLMUINT  * puiNamespaceBufSize

On input *puiNamespaceBufSize should be set to the size of the pszNamespace buffer in bytes.  On output it will return the number of characters in the namespace URI (not counting the null terminating byte).  NOTE: If the pszNamespace parameter is NULL, this parameter is not used on input, and will return the total number of characters in the namespace URI (not counting the null terminating character).  ADDITIONAL NOTE: This parameter is only used if the uiDictType is ELM_ELEMENT_TAG or ELM_ATTRIBUTE_TAG.

    Parameters Out:

char * pszName	Name of item is returned here.  The buffer size specified by *puiNameBufSize will not be exceeded.
char * pszNamespace	Namespace of the item is returned here, if applicable.  This parameter is only used for elements (ELM_ELEMENT_TAG) and attributes (ELM_ATTRIBUTE_TAG).  The buffer size specified by *puiNamespaceBufSize will not be exceeded.

    Example Code:

    IF_Db *                          pDb;

    char                                 szElementName [100];

    FLMUINT                      uiNameBufSize;

    char                                 szNamespace [256];

    FLMUINT                      uiNamespaceBufSize;

 

    // Open a database to get pDb (not shown)

 

    // Get the element name and namespace for element number 34.

 

    uiNameBufSize = sizeof( szElementName);

    uiNamespaceBufSize = sizeof( szNamespace);

    if (RC_BAD( rc = pDb->getDictionaryName( ELM_ELEMENT_TAG, 34, szName, &uiNameBufSize,

                                                                szNamespace, &uiNamespaceBufSize)))

    {

        goto Exit;

    }

    See Also: getDictionaryName(2), getDictionaryDef

[Back to Top]

getDictionaryName(2)

    RCODE getDictionaryName(

        FLMUINT             uiDictType,

        FLMUINT             uiDictNumber,

        FLMUNICODE *  puzName,

        FLMUINT *          puiNameBufSize,

        FLMUNICODE *  puzNamespace = NULL,

        FLMUINT *          puiNamespaceBufSize = NULL);

Retrieve the name and namespace (if applicable) of a dictionary definition for an element, attribute, collection, index, or prefix in the database.  The name and namespace are returned as unicode strings.

    Parameters In:

FLMUINT uiDictType	The type of item being searched for.  Choices include the following: ELM_ELEMENT_TAG - retrieve element definition ELM_ATTRIBUTE_TAG - retrieve attribute definition ELM_INDEX_TAG - retrieve index definition ELM_COLLECTION_TAG - retrieve collection definition ELM_PREFIX_TAG - retrieve prefix definition.
FLMUINT uiDictNumber	The number that represent the dictionary item we are looking for.

    Parameters In/Out:

FLMUINT  * puiNameBufSize

On input *puiNameBufSize should be set to the size of the puzName buffer in bytes.  On output it will return the number of unicode characters in the name (not counting the null terminating unicode character).  NOTE: If the puzName parameter is NULL, this parameter is not used on input, and will return the total number of unicode characters in the name (not counting the null terminating unicode character).

FLMUINT  * puiNamespaceBufSize

On input *puiNamespaceBufSize should be set to the size of the puzNamespace buffer in bytes.  On output it will return the number of unicode characters in the namespace URI (not counting the null terminating unicode character).  NOTE: If the puzNamespace parameter is NULL, this parameter is not used on input, and will return the total number of unicode characters in the namespace URI (not counting the null terminating unicode character).  ADDITIONAL NOTE: This parameter is only used if the uiDictType is ELM_ELEMENT_TAG or ELM_ATTRIBUTE_TAG.

    Parameters Out:

FLMUNICODE * puzName

Name of item is returned here.  The buffer size specified by *puiNameBufSize will not be exceeded.  Note that the buffer size is assumed to be number of bytes, not unicode characters.  However, the number returned in *puiNameBufSize is the number of unicode characters, not counting the null terminator.

FLMUNICODE * puzNamespace

Namespace of the item is returned here, if applicable.  This parameter is only used for elements (ELM_ELEMENT_TAG) and attributes (ELM_ATTRIBUTE_TAG).  The buffer size specified by *puiNamespaceBufSize will not be exceeded. Note that the buffer size is assumed to be number of bytes, not unicode characters.  However, the number returned in *puiNamespaceBufSize is the number of unicode characters, not counting the null terminator.

    Example Code:

    IF_Db *                          pDb;

    FLMUNICODE *          puzElementName = NULL;

    FLMUINT                      uiNameBufSize;

    FLMUNICODE *          puzNamespace = NULL;

    FLMUINT                      uiNamespaceBufSize;

 

    // Open a database to get pDb (not shown)

 

    // Get the element name and namespace for element number 34.

    // First step, determine what size buffers we will need for element name and namespace.

 

    if (RC_BAD( rc = pDb->getDictionaryName( ELM_ELEMENT_TAG, 34, NULL, &uiNameBufSize,

                                                                NULL, &uiNamespaceBufSize)))

    {

        goto Exit;

    }

 

    // Next step, allocate memory for the element name buffer and the namespace buffer.  Remember,

    // the sizes returned in uiNameBufSize and uiNamespaceBufSize represent the number of characters,

    // not the number of bytes - and do not include the terminating null.

 

    uiNameBufSize++;                                                        // Add one for null terminating character.

    uiNameBufSize *= sizeof( FLMUNICODE);             // Need to allocate enough bytes to hold FLMUNICODE characters

    uiNamespaceBufSize++;                                               // Add one for null terminating character.

    uiNamespaceBufSize *= sizeof( FLMUNICODE);    // Need to allocate enough bytes to hold FLMUNICODE characters

 

    // Allocate the element name buffer

 

    if ((puzElementName = (FLMUNICODE *)malloc(  uiNameBufSize)) == NULL)

    {

        rc = RC_SET( NE_XFLM_MEM);

        goto Exit;

    }

 

    // Allocate the namespace buffer

 

    if ((puzNamespace = (FLMUNICODE *)malloc( uiNamespaceBufSize)) == NULL)

    {

        rc = RC_SET( NE_XFLM_MEM);

        goto Exit;

    }

 

    // Finally, get the element name and namespace into the allocated buffers.  In this case, uiNameBufSize and

    // uiNamespaceBufSize represent the size of the buffers in bytes, NOT FLMUNICODE characters.

 

    if (RC_BAD( rc = pDb->getDictionaryName( FLM_ELEMENT_TAG, 34, puzElementName, &uiNameBufSize,

                                                            puzNamespace, &uiNamespaceBufSize)))

    {

        goto Exit;

    }

 

    See Also: getDictionaryName(1), getDictionaryDef

[Back to Top]

getNode

    RCODE getNode(

        FLMUINT             uiCollection,

        FLMUINT64         ui64NodeId,

        IF_DOMNode **  ppNode);

Retrieve the specified DOM Node from the specified collection.

    Parameters In:

FLMUINT uiCollection	The collection to look in for the desired DOM node.
FLMUINT64 ui64NodeId	The node Id of the desired DOM node.

    Parameters Out:

IF_DOMNode ** ppNode

The desired DOM node is returned here.  ppNode must be non-NULL.  NOTE: *ppNode should be set to NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, getNode will Release that object and *ppNode will be assigned to the found IF_DOMNode object.  If getNode returns an error, the contents of *ppNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pNode = NULL;

 

    // Open a database to get pDb (not shown)

 

    // Get the node for node identifier 3047 in the default data collection.

 

    if (RC_BAD( rc = pDb->getNode( XFLM_DATA_COLLECTION, 3047, &pNode)))

    {

        goto Exit;

    }

    See Also: getAttribute, IF_DOMNode::getParentNode, IF_DOMNode::getFirstChild, IF_DOMNode::getLastChild, IF_DOMNode::getPreviousSibling, IF_DOMNode::getNextSibling, IF_DOMNode::getPreviousDocument, IF_DOMNode::getNextDocument

[Back to Top]

getAttribute

    RCODE getAttribute(

        FLMUINT             uiCollection,

        FLMUINT64         ui64ElementNodeId,

        FLMUINT             uiAttrNameId,

        IF_DOMNode **  ppNode);

Retrieve the specified attribute DOM node from the specified collection.

    Parameters In:

FLMUINT uiCollection	The collection to look in for the desired attri ute DOM node.
FLMUINT64 ui64ElementNodeId	The node Id of the desired element node that contains the attribute to be retrieved.
FLMUINT uiAttrNameId	The name Id of the attribute DOM node to be retrieved.
FLMUINT64 ui64NodeId	The node Id of the desired DOM node.

    Parameters Out:

IF_DOMNode ** ppNode

The desired attribute DOM node is returned here.  ppNode must be non-NULL.  NOTE: *ppNode should be set to NULL or should already be pointing to a valid IF_DOMNode object before calling this method.  If it is already pointing to a valid IF_DOMNode object, getNode will Release that object and *ppNode will be assigned to the found IF_DOMNode object.  If getNode returns an error, the contents of *ppNode will be unchanged.  It is the caller's responsibility to call the Release method on the returned IF_DOMNode object when it is finished using the object.

    Example Code:

    IF_Db *                          pDb;

    IF_DOMNode *            pAttrNode = NULL;

 

    // Open a database to get pDb (not shown)

 

    // Get the attribute node whose name id is 37 and whose element node id is 3047 in the default data collection.

 

    if (RC_BAD( rc = pDb->getAttribute( XFLM_DATA_COLLECTION, 3047, 37, &pAttrNode)))

    {

        goto Exit;

    }

    See Also: getNode, IF_DOMNode::getParentNode, IF_DOMNode::getFirstChild, IF_DOMNode::getLastChild, IF_DOMNode::getPreviousSibling, IF_DOMNode::getNextSibling, IF_DOMNode::getPreviousDocument, IF_DOMNode::getNextDocument

[Back to Top]

getDataType

    RCODE getDataType(

        FLMUINT             uiDictType,

        FLMUINT             uiNameId,

        FLMUINT *          puiDataType);

Get the data type for the specified attribute or element.

    Parameters In:

FLMUINT uiDictType	The type of entity that is the target of our search.  This must be either ELM_ELEMENT_TAG (for elements) or ELM_ATTRIBUTE_TAG (for attributes).
FLMUINT uiNameId	The name identifier of the element or attribute in the dictionary.

    Parameters Out:

FLMUINT * puiDataType

A number that represents the data type (follow hyperlink to see defines for those numbers).

    Example Code:

    IF_Db *        pDb;

    FLMUINT    uiDataType;

    FLMUINT    uiElementNameId;

 

    // Open a database to get pDb (not shown)

 

    // Get the element name id for the salary element in the www.acme.com namespace.

 

    if (RC_BAD( rc = pDb->getElementNameId( "www.acme.com", "salary", &uiElementNameId)))

    {

        goto Exit;

    }

 

    // Get the data type for element

 

    if (RC_BAD( rc = pDb->getDataType( ELM_ELEMENT_TAG, uiElementNameId, &uiDataType)))

    {

        goto Exit;

    }

    See Also:

[Back to Top]

backupBegin

    RCODE backupBegin(

        eDbBackupType    eBackupType,

        eDbTransType        eTransType,

        FLMUINT              uiMaxLockWait,

        IF_Backup **         ppBackup);

Start a backup of the database.

    Parameters In:

eDbBackupType eBackupType	Represents the type of backup to be performed.  This must be either XFLM_FULL_BACKUP or XFLM_INCREMENTAL_BACKUP.  See information on backup and restore for more information about these types of backups.
eDbTransType eTransType	Indicates what type of the transaction the backup should be performed under.  This must be either XFLM_UPDATE_TRANS or XFLM_READ_TRANS.  If the backup is performed under a read transaction, it is, in essence, a "hot" backup.  That is, the database may still be modified while the backup is running.  However, updates that occur after the call to backupBegin will not be in the backup.  If the backup is performed under an update transaction, it is a "warm" backup.  The database may still be read by other threads while the backup is in progress, but it cannot be updated.
FLMUINT uiMaxLockWait	Indicates how long to wait for an exclusive lock to the database.  A value of zero indicates an infinite wait time.  This parameter is time in seconds.  NOTE: This parameter is only used if eTransType is XFLM_UPDATE_TRANS.

    Parameters Out:

IF_Backup ** ppBackup

A pointer to a new backup object is returned here.  ppBackup must be non-NULL.  NOTE: If *ppBackup is pointing to a previously returned IF_Backup object, it will NOT be released.  If that is the case, it is the responsibility of the application to release the object before calling backupBegin.

    Example Code:

    IF_Db *                   pDb;

    IF_Backup *           pBackup = NULL;

    MyBackupClient    backupClient;

    MyBackupStatus   backupStatus;

    FLMUINT                uiIncSequenceNum;

 

    // Open a database to get pDb (not shown)

 

    // Begin a backup under a read transaction.  This is a "hot" backup - i.e., updates will be allowed on the database while

    // the backup is running, but no updates that occur after this point will appear in the backup.

 

    if (RC_BAD( rc = pDb->beginBackup( XFLM_FULL_BACKUP, XFLM_READ_TRANS, 0, &pBackup)))

    {

        goto Exit;

    }

 

    // Perform the backup.  Note that the application must provide an implementation for the MyBackupClient class

    // that inherits from the IF_BackupClient interface.  It must also provide an implementation for the MyBackupStatus

    // class that inherits from the IF_BackupStatus interface.

 

    if (RC_BAD( rc = pBackup->backup( NULL, &backupClient, &backupStatus, &uiIncSequenceNum)))

    {

        goto Exit;

    }

    if (RC_BAD( rc = pBackup->endBackup()))
    {
        goto Exit;
    }

    See Also: F_Backup::backup, F_Backup::endBackup, IF_BackupClient, IF_BackupStatus

[Back to Top]

getRflFileName

    void getRflFileName(

        FLMUINT        uiFileNum,

        FLMBOOL       bBaseOnly,
        char *                pszFileName,

        FLMUINT *     puiFileNameBufSize,

        FLMBOOL *    pbNameTruncated = NULL);

This is a method to retrieve the name of the RFL file specified by the uiFileNum parameter.

    Parameters In:

FLMUINT uiFileNum	The RFL file number whose file name is to be returned.
FLMBOOL bBaseOnly	This indicates whether or not to return the full RFL file name or just the base RFL file name.  TRUE=return only the base, FALSE=return full RFL name.

    Parameters In/Out:

FLMUINT * puiFileNameBufSize

On input *puiFileNameBufSize is the size of the buffer pointed to by pszFileName (in bytes).  On output, it returns the number of characters in the name.

    Parameters Out:

char * pszFileName	The RFL file name is returned here.  The name may be truncated if the buffer is not large enough to hold the entire name.
FLMBOOL pbNameTruncated	If non-NULL, this returns a flag indicating whether or not the name was truncated.

    Example Code:

    IF_Db *                   pDb;

    char                          szFileName [256];

    FLMUINT               uiFileNameBufSize;

    FLMBOOL              bNameTruncated;

 

    // Open a database to get pDb (not shown)

 

    // Get the full roll forward file name for roll forward log file number 1.

 

    uiFileNameBufSize = sizeof( szFileName);

    if (RC_BAD( rc = pDb->getRflFileName( 1, FALSE, szFileName, &uiFileNameBufSize, &bNameTruncated)))

    {

        goto Exit;

    }

    See Also:

[Back to Top]

import

    RCODE import(

        IF_IStream *                           pIStream,

        FLMUINT                              uiCollection,

        IF_DOMNode *                     pNodeToLinkTo = NULL,
        eNodeInsertLoc                      eInsertLoc = XFLM_LAST_CHILD,
        XFLM_IMPORT_STATS *   pImportStats = NULL);

Imports an XML document into the database.  When importing a document, if element names and attribute names are encountered which are not currently defined in the database's dictionary, the import method will automatically create appropriate definitions.  The data type for these element and attribute definitions will be string.

Insignificant whitespace is ignored by import.  Thus, the following two xml snippets would be identical in the database:

Document 1:

    <abc> <xyz>TestData</xyz> </abc>

 

Document 2:

    <abc>

        <xyz>

            TestData

        </xyz>

    </abc>

    Parameters In:

IF_IStream * pIStream	A pointer to an input stream object.
FLMUINT uiCollection	The collection to import the document into.
IF_DOMNode * pNodeToLinkTo	Node that the imported document is to be linked to.  If NULL, the imported document will be created as a standalone document.  Otherwise, it will be linked into an existing document as specified by pNodeToLinkTo and eInsertLoc.
eNodeInsertLoc eInsertLoc	This is only used if pNodeToLinkTo is non-NULL.  It specifies the location relative to pNodeToLinkTo where the imported document is to be linked in.

    Parameters Out:

XFLM_IMPORT_STATS * pImportStats

The import stats will be returned in the structure if this parameter is non-NULL.

    Example Code:

    IF_Db *                   pDb;

    IF_PosIStream *    pIStream = NULL;

 

    // Open a database to get pDb (not shown)

 

    // Get a file stream for a file that contains an XML document we want to import.

 

    if (RC_BAD( rc = pDbSystem->openFileIStream( "c:\\xml\\doc1.xml", &pIStream)))

    {

        goto Exit;

    }

 

    // Import the document into the database

 

    if (RC_BAD( rc = pDb->import( pIStream, XFLM_DATA_COLLECTION, NULL)))

    {

        goto Exit;

    }

    See Also: importDocument, exportXML.

[Back to Top]

importDocument

    RCODE importDocument(

        IF_IStream *                               pIStream,

        FLMUINT                                  uiCollection,

        IF_DOMNode **                       ppDocumentNode = NULL,

        XFLM_IMPORT_STATS *       pImportStats = NULL )

Imports an XML document into the database and returns a pointer to the root node of that document.  When importing a document, if element names and attribute names are encountered which are not currently defined in the database's dictionary, the importDocument method will automatically create appropriate definitions.  The data type for these element and attribute definitions will be string.

Insignificant whitespace is ignored by import.  Thus, the following two xml snippets would be identical in the database:

Document 1:

    <abc> <xyz>TestData</xyz> </abc>

 

Document 2:

    <abc>

        <xyz>

            TestData

        </xyz>

    </abc>

    Parameters In:

IF_IStream * pIStream	A pointer to an input stream object.
FLMUINT uiCollection	The collection to import the document into.

    Parameters Out:

IF_DOMNode ** ppDocumentNode	Root node of the document is returned here if a non-NULL value is passed in.
XFLM_IMPORT_STATS * pImportStats	The import stats will be returned if a non-NULL pointer is passed in.

    Example Code:

    IF_Db *                   pDb;

    IF_PosIStream *    pIStream = NULL;

    IF_DOMNode *     pDocNode = NULL;

    char *                       pszXml = "<abc>\n"

                                                            "<xyz>TestData</xyz>\n"

                                                       "</abc>\n";

 

    // Open a database to get pDb (not shown)

 

    // Get a buffer stream for the buffer shown above that contains an XML document we want to import.

 

    if (RC_BAD( rc = pDbSystem->openBufferIStream( pszXml, strlen( pszXml), &pIStream)))

    {

        goto Exit;

    }

 

    // Import the document into the database.

 

    if (RC_BAD( rc = pDb->importDocument( pIStream, XFLM_DATA_COLLECTION, &pDocNode, NULL)))

    {

        goto Exit;

    }

    See Also: import, exportXML.

[Back to Top]

exportXML

    RCODE exportXML(

        IF_DOMNode *         pStartNode,

        IF_OStream *             pOStream,

        eExportFormatType     eFormat = XFLM_EXPORT_INDENT);

Exports the sub-tree specified by pStartNode to a serialized XML format.  For attributes and elements that belong to a non-empty namespaces, appropriate prefixes and namespace declaration attributes will be added to the output stream.  Wherever available, the prefixes defined in already existing namespace declarations will be used.  However, only namespace declarations which are defined at or below the starting node will be used.  Nodes above pStartNode in the document are not examined for namespace declarations.

    Parameters In:

IF_DOMNode * pStartNode

Node that is at the top of the sub-tree that is to be exported.  If pStartNode is the root of a document, this routine effectively exports an entire XML document.

eExportFormatType eFormat

This specifies how the XML is to be formatted for output.  For a complete list of potential values, see xflaim.h.  Currently, the following are supported: XFLM_EXPORT_NO_FORMAT - no formatting. XFLM_EXPORT_NEW_LINE - Output a new line for each element. XFLM_EXPORT_INDENT - Output a new line for each element and indent elements according to their nesting level in the document. XFLM_EXPORT_INDENT_DATA - Output a new line for each element, indenting elements according to their nesting level.  Also indent data inside elements when it goes to multiple lines.  Whitespace is potentially added to an element's value using this option - to make it more human readable.

    Parameters Out:

IF_OStream * pOStream

Output stream the document or sub-tree is to be exported to.

    Example Code:

    IF_Db *                  pDb;

    AppOStream          OutputStream;

    IF_DOMNode *    pStartNode;

 

    // Open a database to get pDb (not shown)

 

    // Find the sub-tree we want to export (not shown) - sub-tree node comes back in pStartNode

 

    // Note that AppOStream is a class that inherits from IF_OStream

    // i.e.: class AppOStream : public IF_OStream{...};

 

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

    // OutputStream object here.
 

    // Export the sub-tree to the output stream.

 

    if (RC_BAD( rc = pDb->exportXML( pStartNode, &OutputStream, XFLM_EXPORT_INDENT)))

    {

        goto Exit;

    }

    See Also: import, importDocument

[Back to Top]

setNextNodeId

    RCODE setNextNodeId(

        FLMUINT            uiCollection,
        FLMUINT64        ui64NextNodeId);

Set the next node identifier for a collection.  The specified node identifier will be used for the next node that is created in the collection.  This method can only be called while in an update transaction.

    Parameters In:

FLMUINT uiCollection	The collection whose next node identifier is to be set.
FLMUINT64 ui64NextNodeId	The next node identifier.  NOTE: The next node identifier will only be set if it is greater than the highest node identifier ever used for a node in the specified collection.

    Parameters Out: none.

    Example Code:

    IF_Db *                   pDb;

 

    // Open a database to get pDb (not shown)

 

    // Set the next node identifier for the data collection to be 789.  The next node that is created after this call will

    // be given a node identifier of 789..

 

    if (RC_BAD( rc = pDb->setNextNodeId( XFLM_DATA_COLLECTION, (FLMUINT64)789)))

    {

        goto Exit;

    }

    See Also:

[Back to Top]

setNextDictNum

    RCODE setNextDictNum(

        FLMUINT    uiDictType,
        FLMUINT    uiDictNumber);

Set the next dictionary number to be used for a particular type of definition document.  The next definition document of that type that is created will be assigned this number, if the document definition does not explicitly assign a number.  This method can only be called while in an update transaction.

    Parameters In:

FLMUINT uiDictType	The type of dictionary definition document.  It may be one of the following: ELM_ELEMENT_TAG ELM_ATTRIBUTE_TAG ELM_INDEX_TAG ELM_COLLECTION_TAG ELM_PREFIX_TAG ELM_ENCDEF_TAG
FLMUINT uiDictNumber	The next dictionary number.  NOTE: The next dictionary number will only be set if it is greater than the highest dictionary number that has ever been set for the specified type of dictionary definition document.

    Parameters Out: none.

    Example Code:

    IF_Db *                   pDb;

 

    // Open a database to get pDb (not shown)

 

    // Set the next dictionary number for element definition documents to be 1000.  Any element definition documents

    // which are created after this point without an explicitly set element number will be assigned 1000, 1001, etc.

 

    if (RC_BAD( rc = pDb->setNextDictNum( ELM_ELEMENT_TAG, 1000)))

    {

        goto Exit;

    }

    See Also:

[Back to Top]

setRflKeepFilesFlag

    RCODE setRflKeepFilesFlag(

        FLMBOOL         bKeep);

Set the RflKeepFiles flag.  A parameter value of TRUE will cause XFLAIM to keep all Roll Forward Log (RFL) files.  As RFL files fill up, new ones are created with the next sequential RFL file number.  A parameter value of FALSE will cause XFLAIM to reuse the same RFL file over and over again.  NOTE: No transaction may be in progress when this method is called.

    Parameters In:

FLMBOOL bKeep

A value of TRUE (keep the RFL files) or FALSE (re-use the same RFL file)

    Parameters Out: none.

    Example Code:

    IF_Db *                   pDb;

 

    // Open a database to get pDb (not shown)

 

    // Set the "keep RFL files" flag to TRUE.

 

    if (RC_BAD( rc = pDb->setRflKeepFilesFlag( TRUE)))

    {

        goto Exit;

    }

    See Also: setRflDir, setRflFileSizeLimits, rflRollToNextFile, setKeepAbortedTransInRflFlag, setAutoTurnOffKeepRflFlag

[Back to Top]

getRflKeepFlag

    RCODE getRflKeepFlag(

        FLMBOOL *    pbKeep);

This is a method to get the keep RFL file flag.

    Parameters In: none.

    Parameters Out:

FLMBOOL * pbKeep

The keep RFL file flag.  A value of TRUE indicates that RFL files are being kept.  A value of FALSE indicates that RFL files are not being kept.

    See Also: setRflKeepFilesFlag, setRflDir, setRflFileSizeLimits, rflRollToNextFile, setKeepAbortedTransInRflFlag, setAutoTurnOffKeepRflFlag, getRflDir, getRflFileNum, getHighestNotUsedRflFileNum, getRflFileSetLimits

[Back to Top]

setRflDir

    RCODE setRflDir(

        char *    pszNewRflDir);

Set the directory where the RFL files should be located. This method is typically used to change the RFL directory to a new location.  The directory specified must exist prior to making this call.  Note that changing the RFL directory will cause a database checkpoint to be executed (see doCheckpoint), and a new RFL file (with the next RFL file sequence number) will be created on the new directory.  No transaction may be in progress when this method is called.

    Parameters In:

char * pszNewRflDir

The new directory where RFL files are to be created.  If the name of the database is "abc.db", a subdirectory called "abc.rfl" will be created below this directory for storing RFL files.

    Parameters Out: none.

    Example Code:

    IF_Db *                   pDb;

 

    // Open a database to get pDb (not shown)

 

    // Set the RFL directory to a different disk volume - wherever the e: drive specifies

 

    if (RC_BAD( rc = pDb->setRflDir( "e:\\rflfiles")))

    {

        goto Exit;

    }

    See Also: setRflKeepFilesFlag, setRflFileSizeLimits, rflRollToNextFile, setKeepAbortedTransInRflFlag, setAutoTurnOffKeepRflFlag, getRflDir, getRflFileNum, getHighestNotUsedRflFileNum, getRflFileSetLimits, getRflKeepFlag

[Back to Top]

getRflDir

    void getRflDir(

        char *    pszRflDir);

Returns the RFL directory for the database.

    Parameters In: none.

    Parameters Out:

char * pszRflDir

The RFL directory.

    See Also: setRflKeepFilesFlag, setRflDir, setRflFileSizeLimits, rflRollToNextFile, setKeepAbortedTransInRflFlag, setAutoTurnOffKeepRflFlag, getRflFileNum, getHighestNotUsedRflFileNum, getRflFileSetLimits, getRflKeepFlag

[Back to Top]

getRflFileNum

    RCODE getRflFileNum(

        FLMUINT *    puiRflFileNum);

This is a method to get the current RFL file number.

    Parameters In: none.

    Parameters Out:

FLMUINT * puiRflFileNum

The current RFL file number.

    See Also: setRflKeepFilesFlag, setRflDir, setRflFileSizeLimits, rflRollToNextFile, setKeepAbortedTransInRflFlag, setAutoTurnOffKeepRflFlag, getRflDir, getHighestNotUsedRflFileNum, getRflFileSetLimits, getRflKeepFlag

[Back to Top]

getHighestNotUsedRflFileNum

    RCODE getHighestNotUsedRflFileNum(

        FLMUINT *    puiHighestNotUsedRflFileNum);

This is a method to get the highest unused RFL file number.

    Parameters In: none.

    Parameters Out:

FLMUINT * puiHighestNotUsedRflFileNum

The highest unused RFL file number.

    See Also: setRflKeepFilesFlag, setRflDir, setRflFileSizeLimits, rflRollToNextFile, setKeepAbortedTransInRflFlag, setAutoTurnOffKeepRflFlag, getRflDir, getRflFileNum, getRflFileSetLimits, getRflKeepFlag

[Back to Top]

setRflFileSizeLimits

    RCODE setRflFileSizeLimits(

        FLMUINT    uiMinRflFileSize,
        FLMUINT    uiMaxRflFileSize);

Set the minimum and maximum RFL file sizes.  When an RFL file size reaches the minimum, if XFLAIM is keeping the RFL files, a new RFL file will be created - using the next RFL file sequence number.  However, it is preferable that we keep transactions entirely contained in the same RFL file if at all possible.  Hence, if the minimum size is reached in the middle of a transaction, XFLAIM will continue logging to the current RFL file until the transaction ends, at which time it will switch to the next RFL file.  The exception to this rule is if the current transaction would exceed the maximum RFL file size.  XFLAIM will not allow this to occur.  Instead, it will switch to the new RFL file mid-transaction if necessary in order to prevent it.  The maximum file size will never be exceeded.  Note that if the minimum and maximum are equal, the maximum takes precedence.  Because we will never exceed the maximum, we will never really exceed the minimum size. -- NOTE: No transaction may be in progress when this method is called.

    Parameters In:

FLMUINT uiMinRflFileSize	Minimum RFL file size - see explanation above.
FLMUINT uiMaxRflFileSize	Maximum RFL file size - see explanation above.

    Parameters Out: none.

   Example Code:

    IF_Db *                   pDb;

    FLMUINT               uiMin;

    FLMUINT               uiMax;

 

    // Open a database to get pDb (not shown)

 

    // Set a minimum RFL file size of 100 megabytes, and a maximum of 200 megabytes.

 

    uiMin = 100 * 1024 * 1024;

    uiMax = 200 * 1024 * 1024;

    if (RC_BAD( rc = pDb->setRflFileSizeLimits( uiMin, uiMax)))

    {

        goto Exit;

    }

    See Also: setRflKeepFilesFlag, setRflDir, rflRollToNextFile, setKeepAbortedTransInRflFlag, setAutoTurnOffKeepRflFlag, getRflDir, getRflFileNum, getHighestNotUsedRflFileNum, getRflFileSetLimits, getRflKeepFlag

[Back to Top]

getRflFileSizeLimits

    RCODE getRflFileSizeLimits(

        FLMUINT *    puiRflMinFileSize,

        FLMUINT *    puiRflMaxFileSize);

This is a method to get the RFL file size limits.  The maximum and the minimum RFL file sizes are returned.

    Parameters In: none.

    Parameters Out:

FLMUINT * puiRflMinFileSize	The minimum RFL file size
FLMUINT * puiRflMaxFileSize	The maximum RFL file size

    See Also: setRflKeepFilesFlag, setRflDir, setRflFileSizeLimits, rflRollToNextFile, setKeepAbortedTransInRflFlag, setAutoTurnOffKeepRflFlag, getRflDir, getRflFileNum, getHighestNotUsedRflFileNum, getRflKeepFlag

[Back to Top]

rflRollToNextFile

    RCODE rflRollToNextFile( void);

Force XFLAIM to close the current RFL file and start a new one.  No transaction may be in progress when this method is called.  Note that this method will go to a new RFL file even if the database is not currently saving RFL files.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    IF_Db *                   pDb;

 

    // Open a database to get pDb (not shown)

 

    // Roll to the next RFL file.

 

    if (RC_BAD( rc = pDb->rflRollToNextFile()))

    {

        goto Exit;

    }

    See Also: setRflKeepFilesFlag, setRflDir, setRflFileSizeLimits, setKeepAbortedTransInRflFlag, setAutoTurnOffKeepRflFlag, getRflDir, getRflFileNum, getHighestNotUsedRflFileNum, getRflFileSetLimits, getRflKeepFlag

[Back to Top]

setKeepAbortedTransInRflFlag

    RCODE setKeepAbortedTransInRflFlag(

        FLMBOOL    bKeep);

Set a flag that indicates whether or not aborted transactions should be kept in the RFL file.  Ordinarily, aborted transactions are not preserved in RFL files.  NOTE: No transaction may be in progress when this method is called.

    Parameters In:

FLMBOOL bKeep

Flag.  A value of TRUE indicates keep aborted transactions.  A value of FALSE indicates that we will not keep aborted transactions.

    Parameters Out: none.

    Example Code:

    IF_Db *                   pDb;

 

    // Open a database to get pDb (not shown)

 

    // Enable keeping of aborted transactions in roll forward log files.

 

    if (RC_BAD( rc = pDb->setKeepAbortedTransInRflFlag( TRUE)))

    {

        goto Exit;

    }

    See Also: setRflKeepFilesFlag, setRflDir, setRflFileSizeLimits, rflRollToNextFile, setAutoTurnOffKeepRflFlag, getRflDir, getRflFileNum, getHighestNotUsedRflFileNum, getRflFileSetLimits, getRflKeepFlag

[Back to Top]

getKeepAbortedTransInRflFlag

    RCODE getKeepAbortedTransInRflFlag(

        FLMBOOL *    pbKeep);

This is a method to get the keep aborted transactions in the RFL flag.  This flag tells XFLAIM to keep aborted transactions in the RFL files.

    Parameters In: none.

    Parameters Out:

FLMBOOL * pbKeep

A boolean value matching the state of the Keep Aborted Trans In RFL flag.

    See Also: getAutoTurnOffKeepRflFlag

[Back to Top]

setAutoTurnOffKeepRflFlag

    RCODE setAutoTurnOffKeepRflFlag(

        FLMBOOL    bAutoTurnOff);

Set a flag that indicates whether or not XFLAIM should automatically disable the "keep RFL files flag" (see setRflKeepFilesFlag) when a disk I/O error occurs on the RFL disk volume.  Although the "keep RFL files flag" is disabled on any disk I/O error that occurs on the RFL disk volume, the primary purpose of this routine is to allow XFLAIM to continue processing update transactions even when the RFL disk volume gets full (i.e., we get a "disk full" error).  If auto-turn-off flag is set to TRUE, then when XFLAIM encounters a disk full error on the RFL volume (or any other I/O error), it will switch off the "keep RFL files flag".  This causes XFLAIM to attempt to reuse the current RFL file instead of continually extending it and creating new ones.  The hope is that XFLAIM can continue to process update transactions without consuming more disk space on the RFL volume.  Of course, if the I/O error encountered is something other than "disk full", XFLAIM may not be able to continue running even if it disables the "keep RFL files flag".  And, there is really no guarantee that XFLAIM will be able to keep running even in the "disk full" case, because there are various scenarios where XFLAIM would have to extend the current RFL file even though it is being reused over and over.

NOTE: It is not normally recommended that this method be used.  If the "keep RFL files flag" is turned on, it is likely that the administrator is keeping them for backup purposes.  If the flag is automatically disabled when a disk full condition is encountered, and the current RFL file starts to be used over and over, some transactions will be overwritten in that file.  If it became necessary to restore a backup and replay transactions from the RFL files, those transactions could not be recovered.  Thus, it is almost better to allow update transactions to come to a halt when a disk gets full rather than risk losing some.

    Parameters In:

FLMBOOL bAutoTurnOff

The auto turn off flag.

    Parameters Out: none.

    Example Code:

    IF_Db *                   pDb;

 

    // Open a database to get pDb (not shown)

 

    // Setup so that if the RFL disk volume runs out of disk space, the "keep RFL files" flag is automatically

    // disabled so that the current RFL file can be reused.

 

    if (RC_BAD( rc = pDb->setAutoTurnOffKeepRflFlag( TRUE)))

    {

        goto Exit;

    }

    See Also: setRflKeepFilesFlag, setRflDir, setRflFileSizeLimits, rflRollToNextFile, setKeepAbortedTransInRflFlag, getRflDir, getRflFileNum, getHighestNotUsedRflFileNum, getRflFileSetLimits, getRflKeepFlag

[Back to Top]

getAutoTurnOffKeepRflFlag

    RCODE getAutoTurnOffKeepRflFlag(

        FLMBOOL *    pbAutoTurnOff);

This is a method to get the auto turn-off keep RFL flag.  This flag tells XFLAIM to stop keeping RFL files if it should encounter any type of I/O error.

    Parameters In: none.

    Parameters Out:

FLMBOOL * pbAutoTurnOff

A boolean value matching the state of the Auto Turn Off Keep RFL flag.

    See Also: getKeepAbortedTransInRflFlag

[Back to Top]

setFileExtendSize

    void setFileExtendSize(

        FLMUINT    uiFileExtendSize);

Set the database file extend size.  When the database runs out of free blocks, the data files will be extended by uiFileExtendSize bytes.  (See the XFLAIM Concepts/Database Files for a discussion on database data files.)

    Parameters In:

FLMUINT uiFileExtendSize

The number of bytes to extend the data files by.  This value should not be less than the size of one block.  The block size may vary from database to database, but ordinarily, it is 4 KB.

    Parameters Out: none.

    Example Code:

    IF_Db *                   pDb;

 

    // Open a database to get pDb (not shown)

 

    // Set the extend size for the database's data files to be 8 megabytes.

 

    pDb->setFileExtendSize( 8 * 1024 * 1024);

    See Also:

[Back to Top]

getFileExtendSize

    FLMUINT getFileExtendSize( void);

This is a method to get the number of bytes that the XFLAIM data file will extend by when needed.  This default value is 8MB.

    Parameters In: none.

    Parameters Out: none.

    See Also:

[Back to Top]

setAppData

    void setAppData(

        void *    pvAppData);

Set the application data.  The data is not interpreted by XFLAIM.  It allows an application to associate an application object with a database object.

    Parameters In:

void * pvAppData

A pointer to the application data.

    Parameters Out: none.

    Example Code:

    IF_Db *                   pDb;

    MyClass *               pObject = new MyClass;

 

    // Open a database to get pDb (not shown)

 

    // Set a pointer to some application data.

 

    pDb->setAppData(  pObject);

 

    assert( pDb->getAppData() == (void *)pObject);

    See Also: getAppData

[Back to Top]

getAppData

    void * getAppData( void);

Returns a pointer to the application data that was set by calling setAppData.

    Parameters In: none.

    Parameters Out: none.

    See Also: setAppData

[Back to Top]

setDeleteStatusObject

    void setDeleteStatusObject(

        IF_DeleteStatus *    pDeleteStatus);

Set the delete status object.  The delete status object must be implemented by the application according to the IF_DeleteStatus interface.  Whenever an index or collection is deleted, the delete status object's reporting methods will be called by XFLAIM to report progress of the delete operation.

    Parameters In:

IF_DeleteStatus * pDeleteStatus

A pointer to the delete status object. XFLAIM will call the AddRef() method on the object to prevent the object from going away.  Thus, the object should not simply be declared on the stack, but should be allocated.  Passing in a NULL will cause XFLAIM to Release() any delete status object it may be pointing to.

    Parameters Out: none.

    Example Code:

    IF_Db *                        pDb;

    App_DeleteStatus *    pDeleteStatus = new App_DeleteStatus;

 

    // Open a database to get pDb (not shown)

 

    // Note that App_DeleteStatus is a class that inherits from IF_DeleteStatus.  Its implementation is provided by

    // the application.

    // i.e.: class App_DeleteStatus : public IF_DeleteStatus

 

    // Set the delete status object.  Would probably want to do some application specific setup of the

    // deleteStatus object here.

 

    pDb->setDeleteStatusObject( pDeleteStatus);

 

    // Make calls to delete an index definition document or collection definition document (not shown)

    // The reporting methods on the delete status object will be called while the index or collection

    // is being deleted.

    See Also: setCommitClientObject, setIndexingClientObject, setIndexingStatusObject

[Back to Top]

setCommitClientObject

    void setCommitClientObject(

        IF_CommitClient *    pCommitClient)

Set the transaction commit client object.  The client is used to perform any actions the client wants to perform immediately after the transaction is committed (durable), but before the database is unlocked.  NOTE: The object is only used during the commit of an update transaction, not read transactions.

    Parameters In:

IF_CommitClient * pCommitClient

A pointer to the commit client object. XFLAIM will call the AddRef() method on the object to prevent the object from going away.  Thus, the object should not simply be declared on the stack, but should be allocated.  Passing in a NULL will cause XFLAIM to Release() any commit client object it may be pointing to.

    Parameters Out: none.

    Example Code:

    IF_Db *                           pDb;

    App_CommitClient  *    pCommitClient = new App_CommitClient;

 

    // Open a database to get pDb (not shown)

 

    // Start an update transaction

 

    if (RC_BAD( rc = pDb->transBegin( XFLM_UPDATE_TRANS, XFLM_NO_TIMEOUT)))

    {

        goto Exit;

    }

 

    // Do some stuff in the transaction (not shown)

 

    // Note that App_CommitClient is a class that inherits from IF_CommitClient.  Its implementation is provided by

    // the application.

    // i.e.: class App_CommitClient : public IF_CommitClient

 

    // Set the commit client object.  Would probably want to do some application specific setup of the

    // commit client object here.

 

    pDb->setCommitClientObject(  pCommitClient);

 

    // Commit the transaction

 

    if (RC_BAD( rc = pDb->transCommit()))

    {

        goto Exit;

    }

    See Also: setDeleteStatusObject, setIndexingClientObject, setIndexingStatusObject

[Back to Top]

setIndexingClientObject

    void setIndexingClientObject(

        IF_IxClient *    pIndexingClient);

Set the indexing client object.  This object's methods are called by XFLAIM whenever a new index is created in the foreground.  If an index is created in the foreground, the collection associated with the index is scanned, and the index is populated as needed.  The methods on the IF_IxClient object allow the application to get called back after each document in the collection is indexed.  It allows the application to perform special post-processing of the document if needed.

    Parameters In:

IF_IxClient * pIndexingClient

A pointer to the indexing client object. XFLAIM will call the AddRef() method on the object to prevent the object from going away.  Thus, the object should not simply be declared on the stack, but should be allocated.  Passing in a NULL will cause XFLAIM to Release() any indexing client object it may be pointing to.

    Parameters Out: none.

    Example Code:

    IF_Db *                               pDb;

    App_IndexingClient  *     pIndexingClient = new App_IndexingClient;

    App_IndexingStatus *     pIndexingStatus = new App_IndexingStatus;

 

    // Open a database to get pDb (not shown)

 

    // Note that App_IndexingClient is a class that inherits from IF_IxClient.  Its implementation is provided by

    // the application.

    // i.e.: class App_IndexingClient : public IF_IxClient

    // Note also that App_IndexingStatus is a class that inherits from IF_IxStatus.  Its implementation is also provided by

    // the application.

    // i.e.: class App_IndexingStatus : public IF_IxStatus

 

 

    // Set the indexing client object and the indexing status object..  Would probably want to do some

    // application specific setup of both objects here.

 

    pDb->setIndexingClientObject(  pIndexingClient);

    pDb->setIndexingStatusObject( pIndexingStatus);

 

    // Add an index to the database (not shown).  The methods on the indexing client object and the indexing status

    // object will be called while the index is being built.

    See Also: setDeleteStatusObject, setCommitClientObject, setIndexingStatusObject

[Back to Top]

setIndexingStatusObject

    void setIndexingStatusObject(

        IF_IxStatus *    pIndexingStatus);

Set the indexing status object.  This object's methods are called by XFLAIM whenever a new index is created in the foreground.  If an index is created in the foreground, the collection associated with the index is scanned, and the index is populated as needed.  The methods on the IF_IxStatus object allow the application to get called back with progress reports during that indexing process.

    Parameters In:

IF_IxStatus * pIndexingStatus

A pointer to the indexing status object. XFLAIM will call the AddRef() method on the object to prevent the object from going away.  Thus, the object should not simply be declared on the stack, but should be allocated.  Passing in a NULL will cause XFLAIM to Release() any indexing status object it may be pointing to.

    Parameters Out: none.

    Example Code:  See setIndexingClientObject.

    See Also: setDeleteStatusObject, setCommitClientObject, setIndexingClientObject

[Back to Top]

getDbVersion

    FLMUINT getDbVersion( void);

Get the version number of the XFLAIM database.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    IF_Db *                            pDb;

    FLMUINT                        uiDbVersion;

 

    // Open a database to get pDb (not shown)

 

    // Get the database version.

 

    uiDbVersion = pDb->getDbVersion();

    See Also:

[Back to Top]

getBlockSize

    FLMUINT getBlockSize( void);

Get the block size of the XFLAIM database.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    IF_Db *                            pDb;

    FLMUINT                        uiDbBlockSize;

 

    // Open a database to get pDb (not shown)

 

    // Get the database block size.

 

    uiDbBlockSize = pDb->getBlockSize();

    See Also:

[Back to Top]

getDefaultLanguage

    FLMUINT getDefaultLanguage( void);

Get the default language of the XFLAIM database.  The language of the database affects how the string data is sorted in indexes.  Different languages have different sorting and collating rules.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    IF_Db *                            pDb;

    FLMUINT                        uiDbLanguage;

 

    // Open a database to get pDb (not shown)

 

    // Get the database default language.

 

    uiDbLanguage = pDb->getDefaultLanguage();

    See Also:

[Back to Top]

getTransID

    FLMUINT64 getTransID( void);

Return the current transaction identifier.  If called from within an update transaction, the current transaction ID is returned.  Although the primary purpose of this method is to return the transaction ID of the current update transaction, it may be called from within a read transaction or outside of any transaction.  If called from within a read transaction, the transaction ID of the last update transaction that was committed prior to starting this read transaction will be returned.  If no transaction is currently active, a zero will be returned, unless the database has been locked, in which case the ID of the last committed transaction will be returned.

    Parameters In: none.

    Parameters Out: none.

    Example Code:

    IF_Db *                            pDb;

    FLMUINT64                    ui64CurrTransID;

 

    // Open a database to get pDb (not shown)

    .

    .

    // Start a transaction

 

    if (RC_BAD( rc = pDb->transBegin( XFLM_UPDATE_TRANS, XFLM_NO_TIMEOUT)))

    {

        goto Exit;

    }

 

    // Get the transaction id.

 

    ui64CurrTransID = pDb->getTransID();

    See Also:

[Back to Top]

getCheckpointInfo

    void getCheckpointInfo(

        XFLM_CHECKPOINT_INFO *    pCheckpointInfo);

Get information about the current state of the checkpoint thread.

    Parameters In: none.

    Parameters Out:

XFLM_CHECKPOINT_INFO * pCheckpointInfo

A pointer to a XFLM_CHECKPOINT_INFO structure where information is returned.

    Example Code:

    IF_Db *                                          pDb;

    XFLM_CHECKPOINT_INFO    checkpointInfo;

 

    // Open a database to get pDb (not shown)

 

    // Get the latest checkpoint information.

 

    pDb->getCheckpointInfo( &checkpointInfo);

 

    // Display the information (or whatever the application wants to do with it)

    See Also:

[Back to Top]

getDbControlFileName

    RCODE getDbControlFileName(

        char *            pszControlFileName,

        FLMUINT    uiControlFileBufSize);

Return the name of the database control file.  See the XFLAIM Concepts/Database Files for a discussion on the database control file.

    Parameters In: none.

    Parameters Out:

char * pszControlFileName	A pointer to a buffer where the name of the control file will be copied.
FLMUINT uiControlFileBufSize	Size of the buffer pointed to by pszControlFileName.  This buffer size will not be exceeded.

    Example Code:

    IF_Db *                            pDb;

    char                                   szControlFileName [200];

 

    // Open a database to get pDb (not shown)

 

    // Get the name of the database control file.

 

    if (RC_BAD( rc = pDb->getControlFileName( szControlFileName, sizeof( szControlFileName))))

    {

        goto Exit;

    }

    See Also:

[Back to Top]

getLockWaiters

    RCODE getLockWaiters(

        IF_LockInfoClient *    pLockInfo);

Get information on the lock holder (if any) and all lock waiters (if any).

    Parameters In:

IF_LockInfoClient * pLockInfo

This is a pointer to an object supplied by the application whose methods will be called to return lock information to the application.

    Parameters Out: none.

    Example Code:

    IF_Db *                            pDb;

    App_LockInfoClient       lockInfoClient;

 

    // Open a database to get pDb (not shown)

 

    // Note that App_LockInfoClient is a class that inherits from IF_LockInfoClient.  Its implementation is provided by

    // the application.

    // i.e.: class App_LockInfoClient : public IF_LockInfoClient

 

    // Would probably want to do some application specific setup of the lock info. client object here.

 

    // Get the lock information.  Methods on the lock info. client object will be called to return the information..

 

    if (RC_BAD( rc = pDb->getLockWaiters( &lockInfoClient)))

    {

        goto Exit;

    }

    See Also: 

[Back to Top]

getLastBackupTransID

    RCODE getLastBackupTransID(

        FLMUINT64 *    pui64LastBackupTransID);

This is a method to get the last transaction ID from the most recent backup.

    Parameters In: none.

    Parameters Out:

FLMUINT64 * pui64LastBackupTransID

The last transaction ID of the most recent backup.

    See Also: getBlocksChangedSinceBackup

[Back to Top]

getBlocksChangedSinceBackup

    RCODE getBlocksChangedSinceBackup(

        FLMUINT *    puiBlocksChangedSinceBackup);

This is a method to get the number of blocks that have changed since the last backup.

    Parameters In: none.

    Parameters Out:

FLMUINT * puiBlocksChangedSinceBackup

The number of blocks changed since the last backup.

    See Also: getLastBackupTransID

[Back to Top]

getNextIncBackupSequenceNum

    RCODE getNextIncBackupSequenceNum(

        FLMUINT *    puiNextIncBackupSequenceNum);

This is a method to get the next incremental backup sequence number.

    Parameters In: none.

    Parameters Out:

FLMUINT * puiNextIncBackupSequenceNum

The next incremental backup sequence number.

    See Also:

[Back to Top]

getSerialNumber

    RCODE getSerialNumber(

        char *    pucSerialNumber);

This is a method to get the serial number of the database.  The serial number is a 16 byte binary value.

    Parameters In: none.

    Parameters Out:

char * pucSerialNumber

The database serial number.

    See Also:

[Back to Top]

getDiskSpaceUsage

    RCODE getDiskSpaceUsage(

        FLMUINT64 *    pui64DataSize,
        FLMUINT64 *    pui64RollbackSize,
        FLMUINT64 *    pui64RflSize);

This is a method to get the size of the three components of the XFLAIM database.

    Parameters In: none.

    Parameters Out:

FLMUINT64 * pui64DataSize	The size (bytes) of the XFLAIM data file(s).
FLMUINT64 * pui64RollbackSize	The size (bytes) of the XFLAIM Rollback log file(s)
FLMUINT64 * pui64RflSize	The size (bytes) of the XFLAIM RFL file(s).

    See Also:

[Back to Top]

getMustCloseRC

    RCODE getMustCloseRC( void);

This is a method to the RCODE that caused the "must close" condition.

    Parameters In: none.

    Parameters Out: none.

    See Also: mustAbortTrans, getAbortRC

[Back to Top]

getAbortRC

    RCODE getAbortRC( void);

This is a method to the RCODE that caused the transaction to abort.

    Parameters In: none.

    Parameters Out: none.

    See Also: mustAbortTrans, getMustCloseRC

[Back to Top]

setMustAbortTrans

    void setMustAbortTrans(

        RCODE    rc);

This method sets the state of the current transaction so that it will be required to be aborted.  This is useful to allow an inner module of an application to force the current transaction to ultimately be aborted, but not have to call the transAbort method itself.  It is usually preferable that a module which did not begin a transaction not abort the transaction.  However, it is quite often desirable for the inner module to be able to at least ensure that the transaction will not be committed.  It may know that something occurred which should prevent the transaction from being committed.  Generally, one would expect the inner module to return an error code and for that error code to be passed out to outer layers, where it is ultimately received and the outer module knows to abort the transaction.  However, this is sometimes not what occurs in practice.  By using this routine, an inner module can ensure that the transaction has to be aborted at some point.

    Parameters In:

RCODE   rc

In forcing a transaction to be aborted, the caller of this routine is allowed to set an RCODE that will be remembered and can be retrieved by any module that wants to determine the reason the transaction was forced to be aborted (see getAbortRC).

    Parameters Out: none.

    See Also: getAbortRC

[Back to Top] [IF_DbSystem] [Introduction] [Next]