英文原文：SAP-samples · 上游版本 d43eb13c4c7c · 原始 Markdown

SAP LUW

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

Introduction

[!NOTE] The concept is relevant to both ABAP Cloud and classic ABAP, but some of the statements covered in the cheat sheet and the executable example are only relevant to classic ABAP.

This cheat sheet provides a high-level overview of 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 and the unrestricted ABAP language version Standard ABAP. Hence, the links in this cheat sheet open topics in the ABAP Keyword Documentation for Standard ABAP.
• The SAP LUW concept is also relevant to ABAP Cloud. 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 in Standard 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 function module that has an importing parameter (a structure that is used to modify a database table). It simply shows a database modifying statement contained in a function module. The code alone does not distinguish it as an update function module. For example, check the example function modules from the imported repository that are used in the executable example. In ADT, right-click a function module and choose Open with → SAP GUI. In SAP GUI, choose the Attributes tab. The Update Module checkbox is selected.

  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. This is true 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 no matter if you use the COMMIT WORK 
    "statement with or without the addition AND WAIT.
    COMMIT WORK.
    "COMMIT WORK AND WAIT.
    

[!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 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
  • Note the background processing framework (bgPF) as a successor technology

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 an 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]

• COMMIT WORK vs. COMMIT WORK AND WAIT in ABAP Cloud
  • Both COMMIT WORK and COMMIT WORK AND WAIT are valid syntax options in ABAP for Cloud Development.
  • However, the functionality of COMMIT WORK and COMMIT WORK AND WAIT - and also SET UPDATE TASK LOCAL - is primarily applicable in classic ABAP, where update function modules, among others, are available. These function modules are not applicable in ABAP Cloud.
  • In ABAP Cloud, local updates are always enforced implicitly and automatically, meaning that updates occur in the same work process and are always synchronous.
  • Consequently, in ABAP Cloud, COMMIT WORK and COMMIT WORK AND WAIT behave identically, rendering the choice between the two irrelevant.
  • Typically, COMMIT WORK in ABAP Cloud returns a value of 0 for sy-subrc, while other values would result in a runtime error.
  • In the context of RAP, when committing in a RAP transaction, refer to the notes about COMMIT ENTITIES here.
• 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 the information on the CL_ABAP_LOCK_OBJECT_FACTORY class that is related to this context here.

[!NOTE] For more information about related topics in RAP, see the sections Authorization Control and Concurrency Control in the Development guide for the ABAP RESTful Application Programming Model.

⬆️ back to top

The SAP LUW in ABAP Cloud and RAP

A limited set of ABAP language features is available in ABAP for Cloud Development (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.

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.
• Find more information in the ABAP cheat sheet about EML.

⬆️ back to top

Controlled SAP LUW

• The controlled SAP LUW is an enhancement to the SAP LUW concept, available in both ABAP Cloud and classic ABAP.
• It introduces a check mechanism to detect violations of transactional contracts to guarantee transactional consistency.
• Such contracts specify which ABAP statements and operations are allowed and which are not allowed in a transactional phase.
• In this way, applications can be made more robust and the SAP LUW can be made more tangible.
• Violations that are detected result in a runtime error (or are logged).
• There are mainly two transactional phases: modify and save.
• In RAP, these two phases are set implicitly, and they are subdivided as follows (see more information in the EML cheat sheet and the RAP guide):
  • modify
    • RAP interaction phase
    • RAP early save phase
  • save
    • RAP late save phase
• Using the static methods modify and save of the CL_ABAP_TX class, you can activate the transactional phases explicitly.
• The controlled SAP LUW is automatically and implicitly supported by newer ABAP concepts such as RAP (i.e. the transactional phases are implicitly active when RAP handler methods are called), background Processing Framework (bgPF), and local consumption of RAP business events.
• Furthermore, transactional contracts define where (i. e. in which transactional phase) a classified API, such as a method of a class, can be used. The classifications start with IF_ABAP_TX_..., for example, IF_ABAP_TX_SAVE, and are, in the case of methods, typcially included as types in the local types of the class (CCDEF include, Class-Relevant Local Types tab in ADT). The classifications detail out and restrict the scope of use, so as not to use a classified API in phases where not allowed. Follow the links below for more information.
  • Example of a classified API: Open the class CL_BCS_MAIL_MESSAGE (which is used for sending emails). In ADT, go to the Class-Relevant Local Types tab, and find classifications for methods, for example, the send_async method. Calling this method in the modify transactional phase results in a violation. You can also get information about the transactional contract using the F2 information in ADT. In the case of the method mentioned, choose F2 on send_async (... cl_bcs_mail_message=>create_instance( ... )->send_async( ). ...) to view the transactional contract information.
• Regarding the concrete restrictions and for more information, follow the links.
• Examples for violations, such as database modifications. They are only allowed in the save transactional phase because the data being processed in the modify phase may be inconsistent:
  • Database modification (e.g. MODIFY dbtab FROM @row.) performed when the modify transactional phase is active.
  • Database modifcation in a RAP handler method implementation. Here, the modify transactional phase is active by default.
  • Database modifcation in a RAP event handler method implementation when the save transactional phase has not been activated explicitly. Note: When RAP event handler methods are called, they are started in the modify transactional phase. Modifying a database right away there, without the activation of the save phase, means a violation.
  • Calling a classified API in a phase where not allowed, such as ... cl_bcs_mail_message=>create_instance( ... )->send_async( ). ... (classified with IF_ABAP_TX_SAVE) in the modify transactional phase.
• More information:
  • Controlled SAP LUW in the SAP Help Portal
  • ABAP Keyword Documentation (Standard ABAP):
    • Restrictions in Transactional Phases
    • API Classifications
    • Restrictions in RAP Handler and Saver Methods

Example using CL_ABAP_TX:

...

*&---------------------------------------------------------------------*
*& Activating the modify transactional phase
*&---------------------------------------------------------------------*

cl_abap_tx=>modify( ).

"The following database modification statement is not allowed in the
"modify transactional phase. In certain contexts, e.g. in ABAP Cloud,
"the runtime error BEHAVIOR_ILLEGAL_STMT_IN_CALL occurs.
MODIFY zdemo_abap_carr FROM TABLE @( VALUE #(
    ( carrid = 'XY'
      carrname = 'XY Airlines'
      currcode = 'EUR'
      url =  'some_url' ) ) ).

...

*&---------------------------------------------------------------------*
*& Activating the save transactional phase
*&---------------------------------------------------------------------*

cl_abap_tx=>save( ).

"In this phase, database modifications are allowed.
MODIFY zdemo_abap_carr FROM TABLE @( VALUE #(
    ( carrid = 'XY'
      carrname = 'XY Airlines'
      currcode = 'EUR'
      url =  'some_url' ) ) ).
...

⬆️ back to top

More Information

• The RAP Transactional Model and the SAP LUW (Development guide for the ABAP RESTful Application Programming Model)
• SAP LUW in the ABAP Keyword Documentation
• Controlled SAP LUW as an enhancement of the SAP LUW concept

⬆️ back to top

Executable Example

After the import of the repository, proceed as follows:

• Find the program in ADT using the search by choosing CTRL + SHIFT + A.
• Enter zdemo_abap_sap_luw and open the program.
• Run the program by choosing F8.

[!NOTE]

• The examples in the main branch of the ABAP cheat sheet repository are designed to be imported into the SAP Business AI Platform, ABAP environment. For Standard ABAP, you can find examples (such as zdemo_abap_sap_luw) in the other branches of the repository.
• The executable example ...
  • demonstrates the SAP LUW using classic dynpros to provide a self-contained and simple example that highlights the considerations regarding implicit database commits, without putting the spotlight on dynpros. Note that classic dynpros are outdated for application programs. New developments should use web-based UIs, such as SAP Fiori UIs.
  • covers the following topics in simple contexts:
    • Demonstrating synchronous update, asynchronous update, and local update triggered by COMMIT WORK, COMMIT WORK AND WAIT, and SET UPDATE TASK LOCAL using update function modules.
    • Demonstrating the statements PERFORM ... ON COMMIT and PERFORM ... ON ROLLBACK using subroutines.
  • does not claim to include meaningful dynpros with meaningful dynpro sequences and is not intended to be a role model for proper dynpro design.
  • is not intended to solve concrete programming tasks. You should always work out your own solution for each individual case.
  • is only intended to demonstrate a selection of keywords and visualize SAP LUW-related syntax in action on a high level.
  • is explained in more detail in the expandable section below. Click to view the details.
• Dynpros cannot be created in ABAP Cloud. As mentioned earlier, 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. See the links in the More Information section.
• The steps to import and run the code are outlined here.
• Disclaimer