get-transaction-state

This procedure returns the current database transaction state for the agent as the procedure's RETURN-VALUE. The six possible values are: ‘NONE', ‘ACTIVE', ‘START-PENDING', ‘UNDO-PENDING', ‘RETRY-PENDING', and ‘COMMIT-PENDING'.

Location

Parameters

Returns

Notes

Valid entries for the transaction state are checked in set-transaction-state. The value returned is one of the six valid values: ‘NONE', ‘ACTIVE', ‘START-PENDING', ‘UNDO-PENDING', ‘RETRY-PENDING', and ‘COMMIT-PENDING'. This is true even if you use the shorthand abbreviations for the states (for example, ‘START' or ‘UNDO').

When the state is ‘START-PENDING', it means that there is no active database transaction for the agent. ‘NONE' and ‘START-PENDING' only occur when there is no transaction.

‘UNDO-PENDING', ‘RETRY-PENDING', and ‘COMMIT-PENDING' all imply that there is an ‘ACTIVE' transaction. These values can only be set in Web requests where the transaction state is ‘ACTIVE'. None of these actions has any impact until the current request is complete.

If the state is ‘UNDO-PENDING' or ‘RETRY-PENDING', do not set any undo-able variables or tables, unless their values after the current request completes is unimportant. All changes to these variables and tables are lost at the end of the current Web request, when the current database transaction is undone.

Examples

The first example checks the transaction state before a database transaction starts. In this case, the Web object starts a new transaction whether or not one already exists, as shown:

RUN get-transaction-state IN web-utilities-hdl.
IF RETURN-VALUE eq 'NONE':U THEN
RUN set-transaction-state IN web-utilities-hdl (‘START':U).
ELSE IF RETURN-VALUE eq ‘ACTIVE':U THEN
RUN set-transaction-state IN web-utilities-hdl (‘RETRY':U).

The second example shows how to avoid running two Web objects, where both rely on database transactions. If there already is a transaction, an error message is generated. This is an important test because all requests to a WebSpeed agent run within the same transaction. A single UNDO button will undo the work done by all Web objects running on the same agent, as shown:

\* Report an error message if there is already an ACTIVE transaction. *\
RUN get-transaction-state IN web-utilities-hdl.
IF RETURN-VALUE eq 'UNDO':U THEN DO:
  \* OK to turn this object into a state-aware object
     using a DB TRANSACTION. *\
  setWebState(20.0).
  RUN set-transaction-state IN web-utilities-hdl (‘START':U).
END.
ELSE DO:
  \* Don't allow this object to start up
     because a DB TRANSACTION is active. *\
  RUN HtmlError IN web-utilities-hdl
  ('Close the current database transaction before starting this web object.').
  RETURN.
END.