TRANSACTION

9.0

The TRANSACTION instruction performs a group PLB file IO operations without modifying any data files until a COMMIT action is executed. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

action

Required. One of the actions from the table below.

options

Optional. A list of options from the table below based upon the action parameter.

Flags Affected: EOS, OVER

Note the Following

1. The {action} operand must be one of the following:

 

Action	Meaning
START	Starts a transaction
COMMIT	Ends the transaction and commits the data
ROLLBACK	Ends the transaction without committing the data
SAVE	Create a new save point
RESTORE	Restores back to a save point
INFO	Provides information on the state of the transaction

 

2. For a START {action}, the {options} parameter is a list of logical FILE, IFILE, AFILE, and/or FILELIST variables that are locked for the duration of the transaction. The list of files is referenced as a {file lock list}. A maximum of fifty (50) files may be specified. At least one file must be specified.

3. For a COMMIT {action}, the {options} parameter may be the VERIFY or VERIFYREAD keyword. By default there is no data integrity verification performed by the COMMIT action. The is because all files specified by the TRANSACTION statement are locked for the transaction duration and thus the data files cannot be changed by other processes that are using expected locking rules.

 

However, there may be some special situations where a user application wants to perform additional data integrity verification. Additional data verification is initiated using the VERIFY or VERIFYREAD keywords with the transaction COMMIT action.

 

Keyword	Effect
VERIFY	Verifies all read/write data that is cached for the transaction when the transaction is committed. This mode insures that no data associated with the transaction has changed while the transaction was active. The VERIFY mode should only needed if there is a possibility that some application other than a Sunbelt application can change data in the data files being used for a transaction.
VERIFYREAD	Performs a read verification for file variables that are not included in the {file lock list}. Any data that has been read from a file is verified to insure that it has not been changed by another program. In this mode, an IO error occurs if any of the data associated with the cached read data has been changed after it has been read and before the commit is executed in the transaction. The verification mode does not occur when a file variable is included in the {file lock list} since other programs cannot change the data while the file variable is locked.

 

4. For a RESTORE {action}, the {options} parameter may be the LEVEL={dnumnvar} keyword. If not specified, the RESTORE {action} restores to the previous level. Otherwise, the RESTORE {action} restores to the specified level. The action restores the cached file data to its state after the last SAVE action.

5. For an INFO {action}, the {options} parameter may be the LEVEL={nvar} keyword. The current transaction level is placed in the specified variable. A level of zero (0) means no transaction is taking place.

6. For a SAVE {action}, the {options} parameter may be the LEVEL={nvar} keyword. The LEVEL keyword in this case is optional. If the {nvar} numeric variable is specified, it receives the current level value after the save action is completed. The SAVE action saves all cached data currently in use for a transaction. The RESTORE action resets the cached data files to the same state as after the last SAVE action.

7. A ROLLBACK or SAVE {action} has no {options} parameter. The ROLLBACK action discards all cached data generated for a transaction. The state of the physical disk data files specified in the {file lock list} remains unchanged and the file variables are restored to the original state before the transaction was started.

8. Any file variables opened in the READ only mode do not need inclusion in the {file lock list}. Any file IO operations for these files are executed and no resulting data for these files is maintained by the runtime for a transaction.

9. A transaction rollback is executed if an untrapped or untrappable error occurs. A U48 error is given for programmatic errors and an I27 error is given for transaction errors.

10. Any file variables opened in the EXCLUSIVE mode must be included in the {file lock list} to allow write operations under transaction control.

11. A transaction rollback is executed if an untrapped or untrappable error occurs. A U48 error is given for programmatic errors and an I27 error is given for transaction errors. An A06 error occurs when a file in the TRANSACTION START file list is not opened

12. A transaction supports both local files and managed files for multiple data managers.

13. A transaction locks all files in a manner consistent with FILEPI. Any IO operations for AAM and ISI files in a transaction that are not included in the TRANSACTION START file list cause an implied file lock to occur as normally expected. It should also be noted that a FILEPI statement cannot be executed when a TRANSACTION is active.

14. A transaction supports record locking. Only AFILE and IFILE files opened for record locking can be included in a transaction and used in write operations.

15. A transaction only allows use of files that are specified in the TRANSACTION START {file lock list} in write operations. An IO error occurs if a write operation is executed for a file variable that is not included in the {file lock list}.

16. Transaction support is implemented in PL/B using the ACID (Atomicity Consistency Isolation Durability) rules:

 

Atomicity	A transaction represents an atomic unit of work. All modifications within a transaction are performed or none of the modifications is performed.
Consistency	When committed, a transaction must preserve the integrity of the data within the system. If one part of the transaction fails, all of the pending changes are rolled back leaving the files in their original state.
Isolation	Modifications made by a transaction are isolated from the modifications made by other transactions.
Durability	After a transaction has been committed, all modifications are permanently in place in the system.

 

17. Only 250 concurrent SAVE points are allowed.

18. The following statements are not allowed under any TRANSACTION and will result in a U48 error: AAMDEX, ALERT, CLOSE, COPYFILE, CREATE, DISPLAY (*W only), ERASE, EVENTCHECK, EVENTWAIT, EXECUTE, EXTCALL, FILEPI, FORMLOAD, GETFNAME, INDEX, KEYIN, Object Methods, OPEN, PAGESETUP, PAUSE, PREP, PRINT, PRTCLOSE, PRTOPEN, PRTPAGE, PRTPLAY, RELEASE, RENAME, ROLLOUT, SETPROP (VISIBLE property for COLLECTION, PLFORM, WINDOW), SNDOPEN, SORT, SPLOPEN, SPLCLOSE, TRANSACTION START, and WEOF.

19. A TRANSACTION ROLLBACK is performed for the following instructions: CHAIN, DSCNCT, DETACH, SHUTDOWN, and STOP.

See Also: Disk I/O Instructions