Skip to content

ABAP Keyword Documentation →  ABAP − Reference →  Processing External Data →  ABAP Database Access →  ABAP SQL →  ABAP SQL - System Classes 

CL_OSQL_REPLACE - Replacement Service

The system class CL_OSQL_REPLACE implements a replacement service that can be used to redirect access to data sources in ABAP SQL statements during the execution of unit tests ABAP Unit. The system class CL_OSQL_REPLACE can only be used in test classes by ABAP Unit.

Other versions: 7.31 | 7.40 | 7.54

Defining Replacement Rules

The static method ACTIVATE_REPLACEMENT of the system class CL_OSQL_REPLACE is used to define replacement rules.

  • A three-column internal table is passed to the parameter REPLACEMENT_TABLE:
  • The first column, SOURCE, contains the name of a data source defined in ABAP Dictionary, namely a database table, a classic view, or a non-abstract CDS entity.
  • The second column, TARGET, contains the name of a database object in the current database to which an ABAP SQL access to the data source named in the first column is redirected.
  • The third column, SCHEMA, contains the name of a database schema to be searched to find the database object from the second column. If the third column is empty, the ABAP database schema is used.
  • An ID can be passed to the parameter FLG_DML to define whether the redirection also applies to write ABAP SQL statements:
  • If the value abap_false is passed to the parameter FLG_DML, the redirection only applies to queries, that is, to the main queries of reads and for the subqueries of all accesses.
  • If the value abap_true is passed to the parameter FLG_DML, the redirection also applies to the database tables to be changed by writes.
  • An ID can be passed to the parameter FLG_SURVIVE_SUBMIT to define whether the redirection also applies to called programs:
  • If the value of abap_false is passed to the parameter FLG_SURVIVE_SUBMIT, the redirection applies only to the current program.
  • If the value of abap_true is passed to the parameter FLG_SURVIVE_SUBMIT, the redirection also applies to programs called using SUBMIT, CALL TRANSACTION, and CALL DIALOG.

The redirection can be made to any database objects, in particular variants of the database tables or views defined in the ABAP Dictionary. The database objects that are redirected to must have the same structure as the object that is redirected from, otherwise the result is database specific and exceptions may arise.

A successful redirection applies for the entire execution of a module test until the internal session is ended or there is another redirection. A redirection is ended explicitly if an empty internal table is passed to the method ACTIVATE_REPLACEMENT.


  • From a technical perspective, a redirection replaces the names of the database objects in the platform-specific SQL statements, which the database interface generates from the ABAP SQL statements and passes to the database system.

  • Redirection of the data sources used by ABAP SQL is used during module tests so that test tables and test data can be processed instead of the actual tables and their data. In particular, this enables testing of system programs that access system tables.

  • In the case of redirections in called programs using the parameter FLG_SURVIVE_SUBMIT, program calls using SUBMIT without the addition AND RETURN are pointless.

Additional Methods

As well as the method ACTIVATE_REPLACEMENT, CL_OSQL_REPLACE has the following methods:

  • The methods IS_REPLACEMENT_ACTIVE and IS_REPLACEMENT_ACTIVE_DML are used to check whether a redirection is active and whether it also applies to writes.
  • The methods SET_ACTIVE_FOR_DML and TOGGLE_ACTIVE_FOR_DML are used to set or change the setting for writes for an existing redirection.

Restrictions and Special Features

Data Sources of Reads

The following applies to data sources of reads:

  • The data source of a read can only be redirected to an object defined in ABAP Dictionary if the object appears in the database with the name that it is defined with in ABAP Dictionary.
  • To redirect a read from a projection view to another data source, the underlying database table can be redirected.
  • It is not possible to redirect to the following:
  • If the data source of a subquery in the WHERE condition of a write statement is redirected to the target of the write, the behavior is undefined and unexpected errors may occur.
  • If a read is redirected to a CDS view or a CDS table function for which one or more CDS roles are defined as part of CDS access control, the associated access conditions are evaluated independently of the target of the redirection. CDS roles that are defined for the target of a redirection are ignored.
  • If a read of a data source is redirected to an AMDP table function that is known in the current AS ABAP, the AMDP framework creates the associated variant in the database if necessary, and the static constructor of the associated AMDP class is executed.
  • If the source or target of a redirection is a database table of the ABAP database schema defined in ABAP Dictionary, for which a replacement object is defined, the redirection is evaluated first and then the replacement object.
  • If a data source of a read is redirected to a database table for which a replacement object is defined, a redirect to the replacement object is made.
  • If a database table is redirected for which a replacement object is defined, the redirection is applied. The replacement object is ignored.
  • If a replacement object is defined for a database table and the replacement object is redirected, the redirection is ignored. The replacement object is accessed here.

Targets of Writes

The same restrictions apply to the target of a write as to the data sources of reads, if applicable. In addition, targets of writes cannot be redirected to the following objects defined in ABAP Dictionary:

  • Database tables with active logging

Writes to a projection view cannot be redirected if the rows to be changed are defined by a work area or an internal table. Therefore, it is only possible to redirect accesses to the database table of a projection view if there are no writes to the view (except with the statements DELETE with a WHERE condition or UPDATE with the addition SET). Otherwise, a runtime error occurs.


See the program DEMO_CL_OSQL_REPLACE.

  • A production class prod reads data from the database table SCARR in the method select, and deletes a row from this table in the method delete.
  • The test class test_prod tests the methods of the production class.
  • In the method setup, access to SCARR is redirected for read and write ABAP SQL statements with cl_osql_replace=>activate_replacement to a test table DEMO_TEST_SCARR, which was defined in ABAP Dictionary as a copy of SCARR. The database schema of DEMO_TEST_SCARR is passed here explicitly for demonstration purposes, but this is not necessary for database objects from the ABAP database schema.
  • In the method setup, the test table DEMO_TEST_SCARR is supplied with two rows of test data from an internal table testdata.
  • In the method test, the method select is called and the return value is compared with the internal table testdata. Calling the method delete deletes a row of test data from the test table and checks that the deleted row no longer exists.
  • In the method teardown, the test data is deleted from the test table.
Execution of the module test should always be successful, regardless of the content of SCARR.