Writing a begin marker to the transaction log¶
begin() |
Write a begin marker to the transaction log |
SYNTAX
begin()
This function is used to mark the start of a set of file updates that are to be treated as a single entity, or transaction, for the purposes of transaction logging. It writes a ‘begin transaction’ marker to the transaction log file and allocates an internal transaction number. All subsequent Sculptor file updates executed by the program (write, delete and insert) are recorded as part of the transaction until either commit() or rollback() is called.
The commit() function indicates that the transaction is complete. All records locked by the transaction are unlocked and the transaction becomes permanent.
The rollback() function reverses all updates made to the database since begin() was last called and unlocks all records locked by the transaction.
Rules to observe¶
Files should not be opened or closed inside a transaction.
If a write lock is required on a file during a transaction, it should be applied before the begin(), and the unlock should be applied after the commit() or rollback(). An attempt to remove a write lock inside a transaction is ignored.
If the above rules are not followed, a file may be left locked or a rollback may not work correctly.
Record locking¶
Every record whose update or creation forms part of the transaction is locked, and remains locked until commit() or rollback() is called. If a program attempts to read a record that it has deleted in a transaction, the No such record error is generated. This may be trapped by nsr, and, if desired, the record can be reinserted. See Traps. Other programs attempting to access the record will see it as still existing but locked. This prevents them from inserting the record until the transaction has been committed.
Transactions should be reasonably short and quick, so that multiple records are not kept locked for a long time. There is also greater scope for deadlocks to occur while multiple records are kept locked, so transactions must be designed to avoid this.
Transaction logging and the recovery program¶
Transaction logging is performed automatically within Sculptor programs unless specifically turned off by setting the Sculptor system variable sys.Logging to OFF within the program. Every file update performed by a program is logged, which enables a system to be brought right back up to date after a crash by running the recovery program.
Additionally, on multitasking systems, the recovery program may be run continuously in order to keep a mirror of the main database in a different directory. Marking a set of file updates as a single transaction tells the recovery program not to update the fallback database until the transaction is complete. The recovery program does not copy the updates to the fallback database until one of the following conditions occurs:
1 |
It sees the corresponding commit transaction marker. This is normally placed by the program which wrote the begin marker. However, if this program terminates, either normally or by means of an interrupt, Sculptor writes the commit marker automatically. |
2 |
The time-out period has expired. This period, measured in seconds, is allocated in the transaction logging control program (trcont.g). |
The begin(), commit() and rollback() functions may also be used on SQL databases such as Informix and Oracle. In these cases, however, there is no time-out period and no automatic commit().
NOTES
This function was introduced in Sculptor V. 5.1.0. Previously it was a command, begin, with very similar (but not identical) functionality. That command, now obsolescent, has been renamed begin_mark.
If a second begin() is encountered before the commit(), then Sculptor automatically calls commit() before the second begin().
File updates which are made by a child process are not included as part of the transaction. This includes newkf; the command “exec newkf invoices” is not treated as part of the transaction, even though it falls between begin() and commit(). However, if a file is opened in create mode, which effectively executes a newkf on the file, then this is recorded as part of the transaction. This is the recommended method of creating an empty file from within a program. See !file.
EXAMPLE
begin()
UpdateFiles()
commit()
RELATED TOPICS |