TTXlaPersistConnection Reference

This section summarizes then describes the TTXlaPersistConnection public methods.

Public Methods Summary

Method	Description
`ackUpdates()`	Advances the bookmark to the next set of updates.
`Connect()`	Connects with the specified bookmark, or creates one if it does not exist (depending on the method signature).
`deleteBookmarkAndDisconnect()`	Deletes the bookmark and disconnects from the database.
`Disconnect()`	Closes an XLA connection to a database, leaving the bookmark in place.
`fetchUpdatesWait()`	Fetches updates to the transaction log within the specified wait period.
`getBookmarkIndex()`	Gets the current transaction log position.
`setBookmarkIndex()`	Returns to the transaction log position that was acquired by a `getBookmarkIndex()` call.

ackUpdates()

void ackUpdates()

Use this method to advance the bookmark to the next set of updates. After you have acknowledged a set of updates, the updates cannot be viewed again by this bookmark. Therefore, a setBookmarkIndex() call does not allow you to replay XLA records that have been acknowledged by a call to ackUpdates(). (See the descriptions of getBookmarkIndex() and setBookmarkIndex() for information about replaying a set of updates.)

Applications should acknowledge updates when a batch of XLA records have been read and processed, so that the transaction log does not fill up available file system space; however, do not call ackUpdates() too frequently, because it is a relatively expensive operation.

If an application uses XLA to read a batch of records and then a failure occurs before ackUpdates() is called, the records are retrieved when the application reestablishes its XLA connection.

Note:

The transaction log is in a file system location according to the TimesTen LogDir attribute setting, if specified, or the DataStore attribute setting if LogDir is not specified. Refer to Data Store Attributes in Oracle TimesTen In-Memory Database Reference.

Connect()

virtual void Connect(const char* connStr, const char* bookmarkStr, 
                     bool createBookmarkFlag)
virtual void Connect(const char* connStr, const char* username, 
                     const char* password, const char* bookmarkStr, 
                     bool createBookmarkFlag)
virtual void Connect(const char* connStr, 
                     TTConnection::DRIVER_COMPLETION_ENUM driverCompletion,
                     const char* bookmarkStr, bool createBookmarkFlag)

virtual void Connect(const char* connStr, const char* bookmarkStr)
virtual void Connect(const char* connStr, const char* username, 
                     const char* password, const char* bookmarkStr)
virtual void Connect(const char* connStr,
                     TTConnection::DRIVER_COMPLETION_ENUM driverCompletion,
                     const char* bookmarkStr)

Each XLA connection has a bookmark name associated with it, so that after disconnecting and reconnecting, the same place in the transaction log can be found. The name for the bookmark of a connection is specified in the bookmarkStr parameter.

For the first set of methods listed above, the createBookmarkFlag boolean parameter indicates whether the specified bookmark is new or was previously created. If you indicate that a bookmark is new (createBookmarkFlag==true) and it already exists, an error is returned. Similarly, if you indicate that a bookmark already exists (createBookmarkFlag==false) and it does not exist, an error is returned.

For the second set of methods listed, without createBookmarkFlag, TTClasses first tries to connect reusing the supplied bookmark (behavior equivalent to createBookmarkFlag==false). If that bookmark does not exist, TTClasses then tries to connect and create a new bookmark with the name bookmarkStr (behavior equivalent to createBookmarkFlag==true). These methods are provided as a convenience, to simplify XLA connection logic if you would rather not concern yourself with whether the XLA bookmark exists.

In either mode, with or without createBookmarkFlag, specify a user name and password either through the connection string or through the separate parameters, or specify a DRIVER_COMPLETION_ENUM value. Refer to TTConnection Reference for information about DRIVER_COMPLETION_ENUM.

Privilege to connect to a database must be granted to users through the CREATE SESSION privilege, either directly or through the PUBLIC role. See Connection Methods. In addition, the XLA privilege is required to create an XLA connection.

Note:

Only one XLA connection can connect with a given bookmark name. An error is returned if multiple connections try to connect to the same bookmark.

deleteBookmarkAndDisconnect()

void deleteBookmarkAndDisconnect()

This method first deletes the bookmark that is currently associated with the connection, so that the database no longer keeps records relevant to that bookmark, then disconnects from the database.

To disconnect without deleting the bookmark, use the Disconnect() method instead.

Disconnect()

virtual void Disconnect()

This method closes an XLA connection to a database. The XLA bookmark persists after you call this method.

To delete the bookmark and disconnect from the database, use deleteBookmarkAndDisconnect() instead.

fetchUpdatesWait()

void fetchUpdatesWait(ttXlaUpdateDesc_t*** arry, int maxrecs,
                      int* recsP, int seconds)

Use this method to fetch a set of records describing changes to a database. A list of ttXlaUpdateDesc_t structures is returned. If there are no XLA updates to be fetched, this method waits the specified number of seconds before returning.

Specify the number of seconds to wait, seconds, and the maximum number of records to receive, maxrecs. The method returns the number of records actually received, recsP, and an array of pointers, arry, that point to structures defining the changes.

The ttXlaUpdateDesc_t structures that are returned by this method are defined in the XLA specification. No C++ object-oriented encapsulation of these methods is provided. Typically, after calling fetchUpdatesWait(), an application processes these ttXlaUpdateDesc_t structures in a sequence of calls to TTXlaTableList::HandleChange().

See ttXlaUpdateDesc_t in Oracle TimesTen In-Memory Database C Developer's Guide.

getBookmarkIndex()

void getBookmarkIndex()

This method gets the current bookmark location, storing it into a class private data member where it is available for use by subsequent setBookmarkIndex() calls.

setBookmarkIndex()

void setBookmarkIndex()

This method returns to the saved transaction log index, restoring the bookmark to the address previously acquired by a getBookmarkIndex() call. Use this method to replay a batch of XLA records.

Note that ackUpdates() invalidates the stored transaction log placeholder. After ackUpdates(), a call to setBookmarkIndex() returns an error because it is no longer possible to go back to the previously acquired bookmark location.

Public Members

Public Methods