There are times you want to abort a portion, but not all, of a transaction. You may be processing several optional paths of a program, going down one branch, then backing out and trying another branch. It may be possible that you don’t want any of the updates to occur until you are completely finished, but you want the flexibility to back out a part of the updates. Another possibility would be if you have run into some form of update error, such as an AddRecord() failing due to a duplicate key. You would want to back up to a prior point, correct the problem, and continue. The FairCom Server lets you implement this by using savepoints.
A savepoint is a temporary spot in the transaction that you may want to back up to without having to abort the entire transaction. During a transaction, when you want to put a place mark in the process, issue a SetSavePoint() call. This does not commit any of the updates. The function returns a savepoint number, which you should keep track of. You can make as many SetSavePoint() calls as you wish during a transaction, and each time you will be given a unique savepoint number.
When you decide that you want to back up to a savepoint, issue a RestoreSavePoint() call. You will pass this function the savepoint number that you want to back up to. This returns you to the point at which you issued the specified SetSavePoint() call, without aborting the entire transaction.
Record locks that are held on actions after that savepoint will be released, unless they were also locked by actions prior to the savepoint.
ClearSavePoint() removes a savepoint WITHOUT UNDOING the changes made since the savepoint. Calling ClearSavePoint() puts pre-image space in the same state as if the most recently called savepoint had never been called. By comparison, RestoreSavePoint() cancels changes made since the last savepoint, but does NOT remove this savepoint.
ReplaceSavePoint() establishes a savepoint while at the same time clearing the previous savepoint providing a "moving" savepoint within a transaction. Only the most recently established savepoint can be restored to. To restore to this savepoint, call RestoreSavePoint(-1).