Begin Transaction (19 or 1019)
The Begin Transaction operation (B_BEGIN_TRAN) defines the start of a transaction. Transactions are useful when you need to perform multiple Btrieve API operations as a single event. For example, use a transaction if your database would become logically inconsistent if some operations were successful, but at least one operation failed to complete successfully.
By enclosing a set of operations between Begin and End Transaction operations, you can ensure that the transactional interface does not permanently complete any operations in the set unless you request the completion with an explicit End Transaction operation (20). Changes made within a transaction are not visible to other users until the End Transaction operation is successfully performed.
The transactional interface prohibits certain operations during transactions because they have too great an effect on the file or on performance. These operations include Set Owner, Clear Owner, Create Index, and Drop Index.
Parameters
Op Code
Pos Block
Data Buf
Data Buf Len
Key Buffer
Key Number
Sent
Returned
Prerequisites
Your application must end or abort any previous transaction before issuing a Begin Transaction operation.
Procedure
Set the Operation Code to 19 to begin an exclusive transaction, or 1019 to begin a concurrent transaction. The transactional interface ignores all parameters except the Operation Code on any Begin Transaction call.
On any Begin Transaction operation, you can specify default lock biases:
•
+100—Single wait record lock.
•
+200—Single no-wait record lock.
•
+300—Multiple wait record lock.
•
+400—Multiple no-wait record lock.
On a Begin Concurrent Transaction operation, you can add +500 to the Operation Code (1519), which forces the transactional interface not to retry the Insert, Update, and Delete operations within a transaction.
In addition, you can combine the +500 bias with a default lock bias. For example, using 1019 + 500 + 200 (1719) begins a concurrent transaction, suppresses retries for Insert, Update, and Delete operations,
and
specifies single no-wait read locks at the same time.
For more information about transactions and locking, refer to the
Pervasive PSQL Programmer's Guide
.
Result
If the Begin Transaction operation is successful, the transactional interface returns Status Code 0.
If the Begin Transaction operation is unsuccessful, the transactional interface returns one of the following status codes:
36
The application encountered a transaction error.
37
Another transaction is active.
Positioning
The Begin Transaction operation has no effect on any file currency information.
