F.10 Begin
Mark beginning of transaction.
SHORT NAME
TRANBEG
TYPE
Low-level data file function
DECLARATION
LONG Begin(COUNT trnmod)DESCRIPTION
Begin marks the beginning of a transaction. All files opened by this user, that have been created with a file mode of either ctPREIMG or ctTRNLOG, will have file updates held until they are committed with a matching call to Commit. For a full description of transaction processing, see the Chapter 13 "Data Integrity" of the c-tree Plus Programmer's Reference Guide.
trnmod values presently supported are summarized in the following table:
Either ctPREIMG or ctTRNLOG must be used to specify the transaction logging mode.
Note: Using ctPREIMG with a file created with ctTRNLOG results in a TTYP_ERR.Either ctENABLE or ctREADREC may also be 'OR'ed in to automatically invoke LockISAM. If either is used, ctLK_BLOCK can be 'OR'ed in to convert the locks to blocking locks. This sleeps the process until the lock is available instead of returning DLOK_ERR.
If ctSAVENV is used, or if the user profile in InitCTreeXtd or InitISAMXtd includes USERPRF_SAVENV, then the current ISAM position of the files updated during the transaction is saved. This allows a subsequent Abort or RestoreSavePoint to reset the current ISAM position of the files.
Automatic Savepoints - ctAUTOSAVE automatically follows each successful ISAM update or resource update with a special savepoint. The savepoint permits an update error to be rolled-back so that a compound transaction can continue its updates and subsequently Commit the transaction. This automatic savepoint does NOT support the ctSAVENV profile setting. ctSAVENV is disabled if ctAUTOSAVE is on.
This approach is faster than explicit savepoints after each update since no network traffic is required between updates, and the auto savepoint is more efficient than an explicit savepoint.
If an error occurs in the middle of a set of updates within a single transaction, and if ctAUTOSAVE was in trnmod, the application simply calls RestoreSavePoint(-1) to roll-back the error, and continues update processing.
Explicit calls to SetSavePoint should not be made when ctAUTOSAVE is effective. An ASAV_ERR (error 532) will be returned by SetSavePoint if called after updates have occurred. A typical usage pattern in pseudo-code would be:
Begin(ctTRNLOG | ctAUTOSAVE | ctENABLE)loop: update operationif errorRestoreSavePoint(-1)if not donegoto loopCommit(...)Automatic commit on memory swapping (Server Only) - ctCOMMIT_SWAP causes an automatic Commit(ctKEEP_OUT), followed by a Begin, when memory swapping begins. Memory swapping is caused by exceeding a limit on user memory or guest memory which sets the user OPS_MEMORY_SWP status bit, (see the SetOperationState function description for the definition of the status bits). ctCOMMIT_SWAP can be 'OR'ed in with other modes, such as ctAUTOSAVE, and causes the OPS_COMMIT_SWP bit to be set when a transaction is automatically committed (and restarted) because of a memory limit which causes pre-image space swapping.
Unlike the OPS_MEMORY_SWP bit, which is automatically reset on a Begin call, the OPS_COMMIT_SWP bit must be cleared by the application using SetOperationState(OPS_COMMIT_SWP,OPS_STATE_OFF)). The intent is that inside a loop in which repeated updates are made, the OPS_COMMIT_SWP bit will be tested. If set, the application knows that the original large transaction has been broken down into smaller pieces and it knows where this break occurred. By immediately resetting the bit, the test can be continually made within the loop, as displayed in the following pseudo code example:
counter = 0;Begin(ctENABLE_BLK | ctCOMMIT_SWAP);do {get data;update data;++counter;if (SetOperationState(0L,OPS_STATE_RET) & OPS_COMMIT_SWP) {printf("auto commit on update #%d\n", counter);/* reset OPS_COMMIT_SWP */SetOperationState(OPS_COMMIT_SWP,OPS_STATE_OFF);}} while (still not done);Commit(ctFREE);The natural use for this mode is with very large transactions, (which consume memory for pre-images), in situations where the client memory must be limited. The system can automatically break large transactions into a series of smaller ones. Of course, this might be a problem since a system crash or an application crash might lead to only a portion of the original large transaction being committed.
The automatic commit will not be attempted if a pending error is outstanding. Such an error can be handled using ctAUTOSAVE, (see above), which causes a high speed, automatic SetSavePoint after each ISAM update. If an ISAM update incurs an error, use RestoreSavePoint(-1) to go back to the previous savepoint and clear the error.
RETURN
Begin returns a transaction number if successful, or zero on error. Check uerr_cod for the error code.
See Appendix A "c-tree Plus Error Codes" of the c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus error values.
EXAMPLE
COUNT savepoint;void domaster() {Begin(ctENABLE|ctTRNLOG); /* start transaction with locks */while(another()); { /* get next record to add */savepoint = SetSavePoint(); /* get save point atbeginning of each master record */if (add_master() < 0)Abort(); /* Begin if can't add master rec */dodetail(); /* process detail records */}if (Commit(ctFREE) != 0)printf("\nError %d in transaction",uerr_cod);return;}void dodetail() {while(moredetail()); { /*get next detail record to add */if (add_detail()<0) { /* add details, if possible */RestoreSavePoint(savepoint) /* with error, returnto savept */return;}}}SEE ALSO
Abort, Commit, RestoreSavePoint, SetSavePoint, and ClearTranError.
|
FairCom Corporation www.faircom.com |