Functions

OASAVEPOINT

oasavepoint marks a place in an update transaction for oarollback. It can also roll a transaction forward and commit it. oasavepoint, along with oabegin, oacommit, and oarollback are the four routines that support transaction management from within OmniAccess.

oasavepoint can serve either of two functions:

• It can mark a place in a complex transaction to prevent you from having to roll back the indexing for the entire transaction if only a portion of it failed.
• It can post as much of the index transaction that has occurred up to that savepoint if the ROLLFORWARD option is used. This makes the newly added keys available for searches using oaqualify, without actually committing the index updates.

oasavepoint is useful in complex transactions that include several update steps. For example, oasavepoint would be useful in a transaction that inserts a parent row, and then inserts rows to several of its related child tables. If the last child table in a transaction ran out of space before the row was added, it might be easier to rollback indexing for that insertion instead of the entire transaction. If you had set a savepoint before that insertion, you could roll back the insertion, create more space in the target table, and then complete the insertion and its indexing.

As you set savepoints in your native update transactions, you should also call oasavepoint to mark indexing transactions. This keeps the indexes synchronized with native data. If, for example, you roll a native transaction back to a native savepoint, you should also roll the OmniAccess indexing transaction back to a corresponding savepoint, otherwise the indexes will wrongly reflect the rolled back updates to your native data.

Transaction management applies to the Omnidex indexes only. If transaction management is required for the database, use the DBMS transaction management system.

See Also: ODXAIM

Syntax

oasavepoint (instance, options, status, savepoint)

instance -- Identifies a unique connection to a catalog previously established by oaconnect. Instance is a 32-bit signed integer passed by value.

options -- Is a character string, passed by reference, that indicates the action(s) for oasavepoint to take. Terminate the option list with a semicolon or a null character. If options contains only a semicolon or null character, oasavepoint defaults to the DELAYED option.

status -- Indicates the success or failure of the oasavepoint routine. A zero status.error means a successful call to oasavepoint. The status structure is passed by reference and contains fourteen 32-bit signed integers, followed by a 36-byte buffer.

savepoint -- Is a character string passed by value that sets a particular savepoint. If a rollback is required, oarollback can reference this savepoint to roll back to. This prevents having to roll back an entire transaction.

Options

DELAYED -- Default - causes all indexing transactions to be held and then posted either when oacommit is called, or when another oasavepoint is called with the ROLLFORWARD option. Use the DELAYED option to countermand an oabegin that used the IMMEDIATE option so that subsequent index updates are delayed until they are rolled forward or committed.

IMMEDIATE -- causes subsequent indexing transactions to be posted immediately when the call to the index update routine is called. Use the IMMEDIATE option to countermand an oabegin that used the DELAYED option so that subsequent index updates are posted immediately but not committed.

ROLLFORWARD -- causes all indexing transactions since the last call to oabegin to be posted to the indexes. These indexing transactions can still be rolled back if necessary.

Example

Top