basic.begin.work Statement/BASIC Program

basic.begin.work

Command basic.begin.work Statement/BASIC Program
Applicable release versions: AP 6.2
Category BASIC Program (486)
Description starts a transaction

A transaction is used to perform a series of updates to the database in an atomic manner. To begin the sequence, use the begin work command followed by the desired updated. To commit the updates to the database, use the "commit work" statement. If a problem develops during the series of writes preventing the correct completion of the transaction, then use the "rollback work" statement to undo all changes made so far.

The "work" or "transaction" keywords are optional and are provided purely for additional SQL compatibility.

The optional "name" parameter provides the ability to name the transaction. This name appears when using the TCL "transaction status" command to monitor transaction processing, or when the system is recovering after a halt. The name makes it easier to identify work-in-progress in these situations.

Once a transaction is active, the following special variables contain usefull information:

@TRANSACTION This numeric value is non-zero when a transaction is active.

@TRANSACTION.ID This is the current transaction id number or zero if no transaction is active.

@TRANSACTION.NAME If the optional "name" parameter is specified in the "begin work" statement, then this variable contains that name. This variable is zero if no transaction is active.


Nested transactions are not allowed and cause the "begin work" statement to fail.

The following operations work differently in a transaction:

clearfile Clear all items in a file. This operation is not allowed within a transaction.

execute Execute a system command. No special checking is done on executed system-level commands, and no atomicity is asserted by the system. The programmer is responsible for assuring the atomicity of all executed retrievals by doing the necessary "filelock" and "readu" commands before the execute. Updates performed by an executed system command do NOT participate in the transaction. The following execute operations generate a run-time abort if attempted within a transaction: "create-file," "clear-file," "delete-file," "create-index," "delete-index," and "resize-file."

filelock Sets an exclusive lock on a file so that no other user may update or set an item lock on that file. It is necessary to execute this statement before an operation which may reference the file sequentially during a transaction.

fileunlock Releases a file lock. This statement is ignored during a transaction since all locks are held until the transaction completes.

key Return index information. This operation never participates in a transaction. Index entries are never updated until commit time, and no user-specific cache is provided. This means that it is invalid to access index entries for records which have been updated within a transaction before that transaction has been committed. Also, if strict transaction ordering is required, it is necessary to set a file lock previous to using the index.

read/readu Read a record. By default, this operation will "see" updates already made by the process, but not yet committed (unless "transaction cache off" has appeared in the program previously). The "readu" form should always be used within a transaction to guarantee serialized schedules.

readnext Read an item id from a select list. To use this validly within a transaction, each "readnext" MUST be followed by a read of the associated item id. This allows verification that the item has not been deleted within the transaction. Items which have been inserted within the transaction are returned by the "readnext" after all of the pre-transaction id's are exhausted.

release Release item locks. This operation is ignored during a transaction since all locks are held until commit or rollback.

select Selects a list of items. To enforce serializable transactions, the user must do a "filelock" of the desired file before doing the "select". IF the select list is based on a prior "execute", then the "filelock" must be done prior to that execute.

write Write a record. This operation always participates in the transaction (meaning that the effects of the write, including the release of any associated locks, are not committed to the database until the commit). All other variants of the WRITE follow identical rules including: "writeu," "writev," "writevu," "matwrite," and "matwriteu."

STOP Stop the program. If a transaction is active, then the stop command or any other condition which terminates the program causes the equivalent of a "rollback" to occur.

The SYSTEM-COLDSTART procedure automatically rolls-backward any pre-commit transactions and rolls-forward (if possible) any post-commit transactions if they system halts unexpectedly.

The following additional features are not currently supported within a transaction:

- The callx and bridge correlatives.

- The use of remote (distributed) files.

- The use of non-Pick files.
Syntax begin {work|transaction} {name} {then | else statement.block}
Options
Example
Purpose
Related tcl.create-index
tcl.delete-index
tcl.delete-file
basic.clearfile
basic.execute
basic.abort
basic.stop
basic.readv
basic.readu
basic.read
BASIC.READNEXT
access.select
basic.writev
basic.matwrite
basic.stop
basic.writeu
basic.write
basic.fileunlock
basic.filelock
basic.transaction.start
basic.commit.work
basic.rollback.work
basic.transaction
basic.transaction.cache
basic.transaction.flush
tcl.transaction
cfunc.trans