abap-cheat-sheets/17_SAP_LUW.md

SAP LUW

• SAP LUW
  • Introduction
  • Terms
  • SAP LUW Overview
    • Bundling Techniques
    • Related ABAP Statements
  • Concepts Related to the SAP LUW
  • Notes on the SAP LUW in ABAP Cloud and RAP
  • More Information
  • Executable Example

Introduction

⚠️ Most of the content of this cheat sheet is only relevant to classic ABAP.

This cheat sheet provides a high-level introduction to the SAP LUW concept that deals with data consistency with a focus on SAP LUW-related statements, supported by an executable example to check the syntax in action.

When you run an application, you typically change data in a transaction, which may be temporarily stored in transactional buffers. This data may be temporarily inconsistent in the buffers, but it is important that the data be in a consistent state at the end of the transaction so that it can be saved to the database.

Consider the following example of transactional consistency:

• A transaction consists of a money transfer from account A to account B, assuming the accounts are in the same bank and the data is stored in the same database.
• Such a transaction represents a logical unit. The transaction is successful when the money is debited from account A and credited to account B.
• This transaction may include other related tasks. Data may be loaded into a buffer, processed there, and become inconsistent during this time. It may also take a while for the whole process to be completed.
• However, at the end of the transaction, all data must be in a consistent state so that the database can be updated accordingly. Or, if errors occur during the transaction, it must be ensured that all changes can be reversed. It must not happen that money is credited to account B without also updating the totals of account A. In such a case, the previous consistent state must be restored.

💡 Note

• This cheat sheet focuses on classic ABAP. Hence, the links in this cheat sheet open topics in the ABAP Keyword Documentation for Standard ABAP.
• The SAP LUW concept is certainly relevant to ABAP Cloud, too. The ABAP RESTful Application Programming Model (RAP) is the transactional programming model for ABAP Cloud. It comes with a well-defined transactional model and follows the rules of the SAP LUW. Find out more in this blog.

Terms

The following terms are related to the concept of the SAP LUW and try to give you some context about it:

• Transaction

  • In a business context, a transaction describes a sequence of related and/or interdependent actions, such as retrieving or modifying data.
  • The result of the transaction is a consistent state of data in the database.

• Logical unit of work (LUW)

  • Describes the time interval at which one consistent state of the database is transitioned to another consistent state.
  • Follows an all-or-nothing approach: It ends either with a single and final commit, which saves the changed data in the database, or with a rollback, which undoes all changes and restores the consistent state before the changes (for example, in the case of an error during the LUW). Either all data changes are committed, or none at all.
  • For an Application Server ABAP (AS ABAP), two types of LUWs come into play to achieve data consistency: Database LUW and SAP LUW (which is covered below).

• Database LUW

  • Also called database transaction.
  • Is an SAP-independent mechanism for transactional consistency in the database.
  • Describes an indivisible sequence of database operations concluded by a database commit, that persists data to the database.
  • The database system either executes the database LUW completely or not at all. If an error is detected within a database LUW, a database rollback undoes all database changes made since the start of the database LUW.

• Database commit

  • Marks the end of a database LUW in which changed data records are written to the database.
  • An important question for developers is how and when database commits and rollbacks are triggered (especially implicitly).
  • In AS ABAP, database commits can be triggered implicitly as well as by means of explicit requests.
  • Find more information here.

• Implicit database commits. Among others, implicit database commits are triggered by:

  • Completing a dialog step in the context of dynpros
    • A dialog step describes the state of a user session between a user action on the user interface of a dynpro and the sending of a new screen layout, i.e. it covers logic implemented in the PAI of the current dynpro and PBO of the following dynpro
    • When the next screen is displayed, the program waits for a user action and does not occupy a work process during this time.
    • The next free work process is assigned to the program in the next dialog step.
    • A work process change requires and implicitly triggers a database commit.
  • Calling a function module in a synchronous (sRFC) or asynchronous remote function call (aRFC)
    • This is when the current work process passes control to another work process or system. Exception: Updates.
  • HTTP/HTTPS/SMTP communication executed using the Internet Communication Framework (ICF)
  • WAIT statements that interrupt the current work process
  • Sending messages (error messages, information message, and warning)

• Explicit database commits. For example, database commits can be triggered explicitly in ABAP programs in the following ways:

  • Using the relevant database-specific Native SQL statement
  • Using the ABAP SQL statement COMMIT CONNECTION
  • Calling the function module DB_COMMIT, which encapsulates the corresponding Native SQL statement.
  • Using the ABAP SQL statement COMMIT WORK. Note that the statement is particularly relevant to the SAP LUW as shown below. It also ends the SAP LUW.

• Database rollback

  • Like a database commit, ...
    • a database rollback marks the end of a database LUW. Here, all modifying database operations are undone until the beginning of the LUW.
    • are triggered implicitly, as well as by explicit requests.
  • They are implicitly triggered, for example, by a runtime error or a termination message (message of type A).
  • For example, explicit rollbacks are triggered by:
    • Using the relevant database-specific Native SQL statement
    • Using the ABAP SQL statement ROLLBACK CONNECTION
    • Calling the function module DB_ROLLBACK, which encapsulates the corresponding Native SQL statement.
    • Using the ABAP SQL statement ROLLBACK WORK. Note that the statement is particularly relevant to the SAP LUW as shown below. It also ends the SAP LUW.

• Work process

  • As a component of an AS ABAP AS instance, work processes execute ABAP applications. Each ABAP program that is currently active requires a work process.
  • AS ABAP uses its own work processes to log on to the database system. Different types of work processes are available for applications, including dialog, enqueue, background, spool, and update work processes.
  • As mentioned earlier, in dialog processing, a work process is assigned to an ABAP program for the duration of a dialog step. An application program can be divided into several program sections and, in the case of dynpros, into several dialog steps that are processed sequentially by different work processes.
  • For example, in the context of a dynpro, when a dialog step that is waiting for user interaction completes, the work process is released (for another workload) and a new work process is assigned. The current workload is persisted and resources are released. This approach requires an (implicit) database commit that ends the database LUW.
  • A work process can execute only a single database LUW. It cannot interfere with the database LUWs of other work processes.

(⬆️ back to top)

SAP LUW Overview

For an SAP LUW, the following aspects come into play:

• Usually, an SAP LUW is started by opening a new internal session. The execution of programming units can be distributed among several work processes.
• Database commits persist data in the database (especially implicit database commits when work processes are switched).
• The all-or-nothing rule applies: All database changes that occur during a transaction constitute a logical unit of work. They must be committed together, or rolled back together in the event of an error.
• This means that all database changes must be deferred and made in a final database commit (that is, in a single database LUW) at the end of a transaction - not in between.
• To ensure data consistency, all database changes are bundled, for example, in temporary tables or transactional buffers, and then, at the end of the transaction, all changes are written to the database together in a single work process, that is, in a single database LUW with a single database commit. This can be done directly using ABAP SQL statements at this stage, or using bundling techniques - special ABAP programming techniques.

Using the above bank transfer as an example:

• At the end of the transaction, the new totals of both accounts are updated (money is debited from account A and credited to B).
• You cannot debit account A in one work process and then credit account B in a separate work process. When the work process changes, new totals would be available in one account, but not in the other. Consider the consequences if an error occurs and the new totals for account B cannot be updated, and so on. You would no longer be able to easily roll back the changes.
• Consider prematurely updating the database and notifying the users or processing the data while the logical unit has not been successfully completed.

(⬆️ back to top)

Bundling Techniques

The following bundling techniques are available for classic ABAP. This means that programming units are registered in different work processes, but are executed by a single work process. All database changes are put into one database LUW, and all changes are committed in one final database commit.

Using update function modules

• Are specially marked, i.e. the update module property is marked

• Can be given specific attributes to determine the priority with which they are processed in the update work process

• Usually contain database modification operations/statements

• CALL FUNCTION ... IN UPDATE TASK statements are used to register the update function modules for later execution; the actual execution is triggered by a COMMIT WORK statement

• Example of a simple update function module that has an importing parameter (a structure that is used to modify a database table)

  FUNCTION zsome_update_fu_mod
    IMPORTING
      VALUE(values) TYPE some_dbtab.
  
    MODIFY some_dbtab FROM values.
  
  ENDFUNCTION.
  

• Depending on your use case, you can run the update work process in several ways:

  • Synchronous update: The calling program waits until the update work process has finished. The COMMIT WORK statement with the AND WAIT addition triggers a synchronous update in a separate update work process.

  • Asynchronous update: The calling program does not wait for the update work process to finish. The COMMIT WORK statement triggers an asynchronous update in a separate update work process.

  • Local update: The update is performed immediately in the current work process in a separate internal session and not in a separate update work process, so that a synchronous update is always performed (regardless of whether COMMIT WORK is used with AND WAIT or not). By default, the local update is deactivated at the start of each SAP LUW. If required, you can activate local update for an SAP LUW using the SET UPDATE TASK LOCAL statement before registering the update function modules.

    "Synchronous update
    
    DATA(st_a) = VALUE some_type( ... ).
    
    ... 
    
    "Registering the update function module specified in uppercase letters
    CALL FUNCTION 'ZSOME_UPDATE_FU_MOD' IN UPDATE TASK 
        EXPORTING values = st_a.
    
    ...
    
    "Triggering the synchronous update
    COMMIT WORK AND WAIT.                              
    
    ***********************************************************************
    "Asynchronous update
    
    DATA(st_b) = VALUE some_type( ... ).
    
    ... 
    
    CALL FUNCTION 'ZSOME_UPDATE_FU_MOD' IN UPDATE TASK 
        EXPORTING values = st_b.
    
    ...
    
    "Triggering the asynchronous update
    COMMIT WORK.
    
    ***********************************************************************
    "Local update
    
    "Before update function modules are registered.
    SET UPDATE TASK LOCAL.
    
    DATA(st_c) = VALUE some_type( ... ).
    
    ... 
    
    CALL FUNCTION 'ZSOME_UPDATE_FU_MOD' IN UPDATE TASK 
        EXPORTING values = st_c.
    
    ...
    
    "The update will be synchronous.
    COMMIT WORK.
    

💡 Note
If a runtime error occurs during the update, the update work process executes a database rollback, and notifies the user whose program created the entries.

Using remote-enabled function modules

• Also in this case, the bundling is done through function modules.
• They are also specially marked as remote-enabled function modules.
• For example, you can use register them for later asynchronous execution in the background and through the RFC interface (background Remote Function Call (bgRFC)). With this technology, you can make calls in the same or different ABAP systems.
• More information:
  • SAP Help Portal documentation about RFC
  • CALL FUNCTION ... IN BACKGROUND UNIT

Using subroutines

• Subroutines that are no longer recommended for use can be registered for later execution.

• They are registered with the PERFORM ... ON COMMIT statement. These subroutines are executed when a COMMIT WORK statement is called.

• An addition is available to control the order of execution.

• Similarly, a subroutine can be registered "on rollback" with PERFORM ... ON ROLLBACK. These subroutines are executed when a ROLLBACK WORK statement is called.

• When executed:

  • In the current work process, before update function modules.
  • When they are registered in an update function module with ON COMMIT, they are executed at the end of the update. This happens in the update work process for non-local updates, and in the current work process for local updates.

(⬆️ back to top)

Related ABAP Statements

An SAP LUW is usually started by opening a new internal session. The statements to end an SAP LUW have already been mentioned above: COMMIT WORK [AND WAIT] and ROLLBACK WORK.

COMMIT WORK [AND WAIT]

• Closes the current SAP LUW and opens a new one.
• Commits all change requests in the current SAP LUW.
• Among other things, this statement triggers ...
  • the processing of all registered update function modules.
  • the update work process and the local updates in the current work process.
  • a database commit for all currently open database connections, which also terminates the current database LUW.
• Note that COMMIT WORK triggers an asynchronous, COMMIT WORK AND WAIT a synchronous update.

ROLLBACK WORK

• Similar to COMMIT WORK statements, this statement closes the current SAP LUW and opens a new one.
• Among other things, this statement ...
  • causes all changes within a SAP LUW to be undone, that is, all previous registrations for the current SAP LUW are removed.
  • triggers a database rollback on all currently open database connections, which also terminates the current database LUW.

💡 Note
Notes on database connections:

• The database interface uses the standard connection of the current work process to access the standard database by default.
• Optionally, database accesses can also be made by using secondary connections to secondary databases or by using service connections to the standard database. The secondary connections are usually used by technical components. For example, they are used for caches, traces, logs, and so on.
• The implicit database rollback is performed on all database connections that are currently open.
• Within the SAP LUW, database changes and commits are allowed on service connections or through secondary database connections.

(⬆️ back to top)

Concepts Related to the SAP LUW

The following concepts are related to the SAP LUW to ensure transactional consistency. They are not discussed in detail here. For more information, see the links.

Authorization concept

• In an SAP system, you need to protect data from unauthorized access by making sure that only those authorized to access it can see and modify it.
• Authorization to access data can be set. Before a user can perform certain operations in your application, you need to implement authorization checks.
• Since ABAP SQL statements do not trigger any authorization checks in the database system, this is even more important. Database tables may be accessed without restriction using these statements. Conversely, not all users in a system are authorized to access all data available to ABAP SQL statements.
• Thus, it is up to the programmer to ensure that each user who can call the program is authorized to access the data it handles.
• More information:
  • Authorizations
  • AUTHORITY-CHECK

Lock concept

• The database system automatically sets database locks when ABAP SQL statements are called to modify database table entries.
• These locks are implemented by automatically setting a lock flag, which can only be set for existing database table entries.
• After a database commit, these flags are removed.
• As a result, database locks are not available for more than one database LUW, which must be considered in the context of an SAP LUW, since multiple database LUWs may be involved. Therefore, the lock flags that are set in a transaction are not sufficient. For the duration of an entire SAP LUW, a lock on database entries must remain set.
• This is where the SAP lock concept comes into play, which is independent of the automatic database locks. It is based on lock objects.
• Lock objects ...
  • are repository objects that are defined in the ABAP Dictionary.
  • specify the database tables in which records are to be locked with a lock request.
  • contain the key fields on which a lock is to be set.
• When a lock object is created, two lock function modules (ENQUEUE_... and DEQUEUE_...) are automatically generated. They are executed in a special enqueue work process. When a record is locked during a transaction (by the enqueue function module), a central lock table is filled with the table name and key field information. Unlike database locks, a locked entry in a lock object does not necessarily have to exist in a database table. Also, the locking must be done proactively, i. e. there is no automatic locking. You must make sure that the application implementation checks the lock entries.
• At the end of an SAP LUW, all locks should be released, either automatically during the database update or explicitly when you call the corresponding dequeue function module.
• More information: SAP Locks

💡 Note
RAP comes with its own implementation features to cover these concepts. See the topics Authorization Control and Concurrency Control in the Development guide for the ABAP RESTful Application Programming Model.

(⬆️ back to top)

Notes on the SAP LUW in ABAP Cloud and RAP

A limited set of ABAP language features is available in ABAP Cloud (restricted ABAP language version). The limitations include the fact that the above bundling techniques are not available. Note that the local update is enabled by default in ABAP Cloud. Find more information in this blog.

In fact, RAP is the transactional programming model for ABAP Cloud. And RAP comes with a well-defined transactional model and follows the rules of the SAP LUW. At the end of an SAP LUW in RAP, database modification operations should be performed in a final step in the RAP late save phase by persisting the consistent data in the RAP transactional buffer to the database.

There are RAP-specific, ABAP EML statements for commit and rollback:

• COMMIT ENTITIES implicitly triggers COMMIT WORK. Furthermore, COMMIT ENTITIES provides RAP-specific functionality with various additions. These EML statements implicitly enforce local updates with COMMIT WORK, or COMMIT WORK AND WAIT if the local update fails. Therefore, the update is either a local update or a synchronous update, but never an asynchronous update.
• ROLLBACK ENTITIES: Resets all changes of the current transaction and clears the transactional buffer. The statement triggers ROLLBACK WORK.

More Information

• The RAP Transactional Model and the SAP LUW (Development guide for the ABAP RESTful Application Programming Model)
• The SAP LUW in ABAP Cloud (blog)
• Cheat sheet about ABAP EML

(⬆️ back to top)

Executable Example

Coming soon ...