Skip to content

Transactions and Data-Dictionaries

This discussion applies to the Data-Dictionaries and their predecessor, Data sets. The term Data-Dictionary or DDO will be used to refer to both technologies.

DDOs alter tables using two methods, Request_Save and Request_Delete. Both methods use transactions (in fact, they require that your tables support transactions) and fully support all of the ACID property requirements. These methods operate as follows:

  1. Method starts (Request_Save or Request_Delete).
  2. A Begin_Transaction is executed (unless a transaction is already started).
  3. Table data is reread and locked as needed. If table locking is used, all tables that participate in the save or delete are locked. If row (record) locking is used, rows are locked as they are reread.
  4. Data is validated, processed, and table columns are updated.
  5. If any error occurs at any time, the error is handled as follows:
  6. Execution of the current method is stopped.
  7. The transaction is rolled back and aborted.
  8. All tables and rows are unlocked, and the transaction is ended.
  9. The error is reported (after the unlock).
  10. The Err indicator is set to True.
  11. Control is returned to the method that called the request method or, if a transaction was already started, to the line following the End_Transaction.

Note that this applies to all errors. If the runtime encounters any unexpected error, this process is triggered. If the developer generates an explicit error with the Error command (typically done within the events Validate_Save or Validate_Delete), the process is triggered.

  1. If no errors occur:
  2. The save or delete is completed.
  3. The transaction is committed (unless the request was already within a transaction).
  4. All tables and rows are unlocked, and the transaction is successfully ended (unless the request was already within a transaction).
  5. Control is returned to the method that called the request method.

Errors in a DDO Transaction

The error rollback is a very simple process. If an error occurs, execution stops, the transaction is rolled back, and the request method is completed. While this is simple, it is powerful and has the following implications:

  • A Request_Save or a Request_Delete may change many rows from many tables. For example, a delete cascades and deletes rows in descendant tables, causing hundreds of rows to be deleted and hundreds of parent rows to be altered. If an error occurs, all of these changes are rolled back.
  • If you wish to stop a transaction inside of a DDO, use the Error command. It is not expected that you will ever use the Abort_Transaction command within a DDO.
  • The event methods Validate_Save and Validate_Delete were created to provide a place for a developer to check for any errors and to generate errors as needed. There is nothing stopping you from declaring an error in any DDO event (e.g., Update, Backout, Save_Main_File). Any error generated at any time within the transaction will properly abort the transaction.
  • Once an error is encountered within a method, none of the other commands within that method (or the methods that called this method) are executed. The rollback occurs, the error is generated, and control is returned to the method that made the request. For example, in the sample below, the code in the function that occurs after the Error command can never be executed.
Function Validate_Save Returns Integer
    Error 300 "Sorry, no save"
    // If an error occurred, this code never is executed
    Showln "You will never see me"
    // We don’t need to return a value, the error triggers the stop
End_Function // Validate_Save
  • Error reporting is always deferred until the transaction is rolled back and all locks are removed. You can, therefore, execute an error within a DDO transaction without worrying that the error will be reported when tables are locked.

Grouping Multiple DDO Saves or Deletes

If you wish to group several DDO Request_Save or Request_Delete operations within a single transaction, you can group them using Begin_Transaction and End_Transaction as follows:

Begin_Transaction
    Send Request_Save Of hMyDDO1
    Send Request_Save Of hMyDDO2
End_Transaction

If an error occurs in either DDO transaction, both transactions are rolled back, and execution resumes at the line following the End_Transaction.

Note that you should never use a Lock, Reread, or Unlock command to group DDO transactions.

See Also