Relevant Methods of the System Service

Most of the components of system service class CL_OS_SYSTEM are used internally by the Object Services. Two methods must be used in an application program to be able to work explicitly with object-oriented transactions.

INIT_AND_SET_MODES

This static method initializes the entire Object Services and creates the necessary service objects. INIT_AND_SET_MODES is executed no more than once for each ABAP program. Every additional call causes an exception.

INIT_AND_SET_MODES is used in connection with the Transaction Service to set the transaction mode of the top level transaction. The constant OSCON_TRUE or OSCON_FALSE of type group OSCON must be passed to input parameter I_EXTERNAL_COMMIT. OSCON_TRUE sets the compatibility mode for which COMMIT WORK must be defined explicitly in the program, whereas OSCON_FALSE sets object-oriented transaction mode, for which an explicit COMMIT WORK is not allowed. Once the compatibility mode has been set, a top level transaction is implicitly created and started. All other transactions of the program are nested in this transaction.

Update mode is controlled with the other input parameter I_UPDATE_MODE of type OS_DMODE. Possible input parameters are: OSCON_DMODE_DEFAULT or OSCON_DMODE_UPDATE_TASK for asynchronous updates, OSCON_DMODE_DIRECT for direct updates, OSCON_DMODE_LOCAL for local updates, and OSCON_DMODE_UPDATE_TASK_SYNC for synchronous updates. OSCON_DMODE_LOCAL and OSCON_DMODE_UPDATE_TASK_SYNC are only allowed in object-oriented transaction mode since they can be set in compatibility mode using ABAP statements (COMMIT WORK AND WAIT and SET UPDATE TASK LOCAL). If you choose local or direct updating, the SET UPDATE TASK LOCAL statement is executed implicitly when you start the transaction.

INIT_AND_SET_MODES is executed implicitly the first time you access a class of the Object Services with default values (compatibility mode with asynchronous updating). If you want to execute INIT_AND_SET_MODES explicitly, you must do so before an implicit call in order for it to take effect (the implicit call will then not take place).

GET_TRANSACTION_MANAGER

This static method gives you the return parameter RESULT of type IF_OS_TRANSACTION_MANAGER containing a reference to the Transaction Manager. The Transaction Manager is created when you initialize the Object Services.

Methods of the Transaction Manager

The Transaction Manager manages the object-oriented transactions of the ABAP program and is executed from interface IF_OS_TRANSACTION_MANAGER.

IF_OS_TRANSACTION_MANAGER~CREATE_TRANSACTION

Creates a transaction and returns a reference to the transaction in return parameter RESULT of type IF_OS_TRANSACTION.

IF_OS_TRANSACTION_MANAGER~GET_CURRENT_TRANSACTION

Returns a reference to the current transaction in return parameter RESULT of type IF_OS_TRANSACTION.

IF_OS_TRANSACTION_MANAGER~GET_TOP_TRANSACTION

Returns a reference to the top level transaction in return parameter RESULT of type IF_OS_TRANSACTION.

Methods of a Transaction

Transactions are executed from interface IF_OS_TRANSACTION.

IF_OS_TRANSACTION~START

Starts the transaction. If a top level transaction does not yet exist, it becomes the top level transaction. Otherwise it becomes a subtransaction. A transaction must have status OSCON_TSTATUS_NEW in order to be started. Each transaction thus can only be started once per program. You cannot start a transaction again that was ended with END since that would invalidate the transaction object in the program. You have to create a new transaction, but you can use the same reference variable again.

The COMMIT WORK statement may not occur between the START and END methods.

IF_OS_TRANSACTION~END

Ends the transaction. Changes to persistent objects are stored until the COMMIT WORK or ROLLBACK WORK of the top level transaction. If the transaction is a top level transaction, COMMIT WORK is implicitly triggered upon encountering an END. This starts the update and invalidates the persistent objects. If you access a persistent object again, it is loaded from the database.

IF_OS_TRANSACTION~UNDO

Ends the transaction. The changes made to persistent objects in the transaction are canceled and the objects are returned to the state they had prior to the transaction. If the transaction is an object-oriented top level transaction, ROLLBACK WORK is implicitly triggered when you perform an UNDO.

IF_OS_TRANSACTION~END_AND_CHAIN

Ends the transaction and immediately starts a new one. If the transaction is an object-oriented top level transaction, changed persistent objects are written to the database but not invalidated. Return parameter RESULT of type IF_OS_TRANSACTION returns a reference to the current transaction.

IF_OS_TRANSACTION~UNDO_AND_CHAIN

Cancels the changes made to persistent objects in the transaction and starts a new transaction. Return parameter RESULT of type IF_OS_TRANSACTION returns a reference to the current transaction.

IF_OS_TRANSACTION~REGISTER_CHECK_AGENT

Registers an object as a checking agent, which is called by the transaction for checking purposes before the transaction ends. An interface reference to such an object is passed to input parameter I_CHECK_AGENT of type IF_OS_CHECK.

IF_OS_TRANSACTION~GET_STATUS

Returns the transaction status in the RESULT return value of type OS_STATUS. The following values (constants of type group OSCON) are possible:

IF_OS_TRANSACTION~SET_MODE_UNDO_RELEVANT

Can be used to deactivate the UNDO mechanism before a transaction is started, for example, to improve performance. This is done by transferring the value OSCON_FALSE to the optional input parameter I_UNDO_RELEVANT of the type OS_BOOLEAN. The default value is OSCON_TRUE. This removes the need to save the initial status of persistent objects before a change. In compatibility mode, the UNDO mechanism is deactivated in the top level transaction. Otherwise the UNDO mechanism is active, unless it was explicitly deactivated using this method.

If IF_OS_TRANSACTION~UNDO is called in a transaction with deactivated UNDO mechanism, the status of the transaction is OSCON_TSTATUS_FIN_ABORT.

IF_OS_TRANSACTION~SET_MODE_UPDATE

Can be used exactly once for the top level transaction before persistent objects are accessed in order to set the update mode. This is only necessary in compatibility mode, where the update mode is normally set implicitly the first time you access a persistent object with asynchronous updating (see Persistent Objects and COMMIT WORK). This method is not necessary for object-oriented transactions since the update mode of the top level transaction is set explicitly with CL_OS_SYSTEM=>INIT_AND_SET_MODES or when an object-oriented transaction is created in the ABAP Workbench.

The input parameter I_UPDATE_MODE of type OS_DMODE can take on the following values: OSCON_DMODE_DEFAULT or OSCON_DMODE_UPDATE_TASK for asynchronous updates, OSCON_DMODE_DIRECT for direct updates, OSCON_DMODE_LOCAL for local updates, and OSCON_DMODE_UPDATE_TASK_SYNC for synchronous updates. OSCON_DMODE_LOCAL and OSCON_DMODE_UPDATE_TASK_SYNC are only allowed in object-oriented transaction mode since they can be set in compatibility mode using ABAP statements (COMMIT WORK AND WAIT and SET UPDATE TASK LOCAL).

If you choose local or direct updating, the SET UPDATE TASK LOCAL statement is executed implicitly when you start the transaction.

IF_OS_TRANSACTION~GET_MODES

Provides the attributes of the current transaction in the output parameters: E_UNDO_RELEVANT of type OS_BOOLEAN, E_CHAINED of type OS_BOOLEAN, E_UPDATE_MODE_TYPE of type OS_DMODE, and E_EXTERNAL_COMMIT of type OS_BOOLEAN.

Events of a Transaction

IF_OS_TRANSACTION~SAVE_REQUESTED

The event is triggered when a top level transaction is ended with END before the class agents of the changed persistent objects record the changes. For class agents that implicitly use update modules, the event is triggered before the update modules are registered using CALL FUNCTION IN UPDATE TASK. The event defines the time when the changes to persistent objects should be recorded for class agents with self-programmed change methods.

IF_OS_TRANSACTION~SAVE_PREPARED

The event is triggered when a top level transaction ends with END after the class agents of the changed persistent objects have recorded the changes. For class agents that implicitly use update modules, the event is triggered after the update modules are registered using CALL FUNCTION IN UPDATE TASK. The event defines the time when the changes to database tables in the objects should be recorded for class agents with self-programmed change methods.

IF_OS_TRANSACTION~FINISHED

The event is triggered at the actual end of a transaction, regardless of whether it was ended with END or UNDO. An output parameter of type OS_STATUS tells you how the transaction was ended (see above method GET_STATUS).