SET HANDLER

Basic form 19

SET HANDLER FOR ... .

Variants:

1. SET HANDLER h1 ... hn FOR ref.

2. SET HANDLER h1 ... hn FOR ALL INSTANCES.

3. SET HANDLER h1 ... hn.

Effect

Registers and deregisters event handler methods dynamically at runtime. The statement is part of ABAP Objects. For dynamic registration, or to deregister event handlers, use the ACTIVATION addition.

The variant that you should use depends on the declaration of the event handler method. They can be declared as

Instance events, using
METHODS meth FOR evt OF cif, or as
Static events, using
CLASS-METHODS meth FOR evt OF cif.

There are also four possible combinations for evt and cif:

e OF class

e is an instance event of class class, declared using the EVENTS statement. In this case, use the addition FOR. In variant 1, the event hander methods are set for a single triggering instance of the class class or one of its subclasses. In variant 2, they are registered for all triggering events of the class class or its subclasses. In variant 1, the triggering instance must exist when the SET HANDLER statement occurs. In variant 2, on the other hand, the registration applies not only to all instances that exist when the SET HANDLER statement occurs, but also to those that are created later.
e OF intf

e is an instance event of interface intf that you declare using the EVENTS statement. In this case, use the FOR addition. In variant 1, the event handler methods are registered for a single triggering instance of a class or its subclasses that implements the interface intf. In variant 2, the event handler methods are registered for all triggering instances of the classes or subclasses that implement interface intf. In variant 1, the triggering instance must exist when the SET HANDLER statement ooccurs. In variant 2, on the other hand, the registration applies not only to all instances that already exist when the SET HANDLER statement occrs, but also to those that are created later.
ce OF class

ce is a static event of the class class that you declare using the CLASS-EVENTS statement. In this case, you cannot use the FOR addition. Variant 3 registers the event handler methods for the triggering class class.
ce OF intf

ce is a static event of the interface intf that you declare using the CLASS-EVENTS statement. In this case, you cannot use the FOR addition. Variant 3 registers the event handler methods for all triggering classes that implement the interface intf. The registration does not only apply to classes that are known when the SET HANDLER statement occurs, but also for all classes that are loaded subsequently.

Variant 1

SET HANDLER h1 ... hn FOR ref.

Effect

Registers static event handler methods for instance events of a single instance (object). ref is a reference variable, which must contain a reference to an object. The class of the object must contain the events to be handled by the methods h1 ... hn as instance events (see EVENTS).

The events to be handled can either be components of the class to which the object referred to in ref belongs, or components of an interface that is implemented by this class. For interface events, ref can be a class reference or an interface reference.

You can use the ACTIVATION addition to deregister handler methods or register them dynamically (see below).

Note

A syntax or runtime error occurs if you attempt to register unsuitable handler methods. The type of ref must be the same class or a subclass of the class specified in the declaration of the event handler methods after FOR EVENT evt OF. This means you cannot register objects of superclasses even if they inherit the event from one of these. If an interface is specified after FOR EVENT evt OF, the type of the reference variable must be the interface itself, a class or subclass implementing the interface, or another interface containing the interface as a component.

Example

Events in classes:

CLASS c1 DEFINITION.
PUBLIC SECTION.
  EVENTS: e1, e2.
  METHODS m1.
ENDCLASS.

CLASS c2 DEFINITION.
PUBLIC SECTION.
  METHODS m2 FOR EVENT e1 OF c1.
ENDCLASS.

CLASS c3 DEFINITION.
PUBLIC SECTION.
  METHODS m3 FOR EVENT e2 OF c1.
ENDCLASS.

DATA: cref1 TYPE REF TO c1,
      cref2 TYPE REF TO c2,
      cref3 TYPE REF TO c3.

CREATE OBJECT: cref1, cref2, cref3.

SET HANDLER cref2->m2 cref3->m3 FOR cref1.

cref1->m1( ).

CLASS c1 IMPLEMENTATION.
METHOD m1.
   RAISE EVENT e1.
   RAISE EVENT e2.
ENDMETHOD.
ENDCLASS.

CLASS c2 IMPLEMENTATION.
METHOD m2.
   WRITE / 'M2 handling event'.
ENDMETHOD.
ENDCLASS.

CLASS c3 IMPLEMENTATION.
METHOD m3.
   WRITE / 'M3 handling event'.
ENDMETHOD.
ENDCLASS.

This example registers two handler methods, each for one instance event of the instance of class c1 to which the class reference in cref1 is pointing.

Example

Events in interfaces:

INTERFACE i1.
  EVENTS e1.
  METHODS m1.
ENDINTERFACE.

CLASS c1 DEFINITION.
  PUBLIC SECTION.
    INTERFACES i1.
ENDCLASS.

CLASS c2 DEFINITION.
  PUBLIC SECTION.
    METHODS m2 FOR EVENT e1 OF i1.
ENDCLASS.

DATA: cref  TYPE REF TO c1,
      iref  TYPE REF TO i1,
      cref1 TYPE REF TO c2,
      cref2 LIKE cref1.

CREATE OBJECT: cref, cref1, cref2.

iref = cref.

SET HANDLER cref1->m2 cref2->m2 FOR iref.

iref->m1( ).

CLASS c1 IMPLEMENTATION.
  METHOD i1~m1.
    RAISE EVENT i1~e1.
  ENDMETHOD.
ENDCLASS.

CLASS c2 IMPLEMENTATION.
  METHOD m2.
    WRITE / 'M2 handling event'.
  ENDMETHOD.
ENDCLASS.

This example registers a handler method for an instance event of the instance of class c1 to which the interface reference in iref is pointing.

Variant 2

SET HANDLER h1 ... hn FOR ALL INSTANCES.

Addition:

...ACTIVATION f

Effect

Registers multiple event handler methods for the instance events of all instances that can trigger the events for which the handlers h1 ... hn are declared. The registration applies equally to all triggering instances that are generated after the SET HANDLER statement.

The events for handling can be declared either in classes or in interfaces. Class events can be triggered by all instances of the corresponding class. Interface events can be triggered by all instances of the classes that implement the interface and their subclasses.

Note

When you register event handler methods for all triggering instances, the addition ACTIVATION only allows you to deregister all triggering instances simultaneously. It is not possible to deregister individual triggering instances separately after a mass registration using the addition ACTIVATION. The reason is that mass registrations are internally stored in a central handler table while single registrations are stored in a handler table for each triggering instance.

Example

Events in classes and interfaces:

INTERFACE i1.
  EVENTS e1.
ENDINTERFACE.

CLASS c1 DEFINITION.
  PUBLIC SECTION.
    INTERFACES i1.
    EVENTS e1.
    METHODS m1.
ENDCLASS.

CLASS c2 DEFINITION.
  PUBLIC SECTION.
    METHODS m2 FOR EVENT e1 OF i1.
ENDCLASS.

CLASS c3 DEFINITION.
  PUBLIC SECTION.
    METHODS m3 FOR EVENT e1 OF c1.
ENDCLASS.

DATA: cref11 TYPE REF TO c1,
      cref12 TYPE REF TO c1,
      cref2  TYPE REF TO c2,
      cref3  TYPE REF TO c3.

CREATE OBJECT: cref2, cref3.

SET HANDLER cref2->m2 cref3->m3 FOR ALL INSTANCES.

CREATE OBJECT: cref11, cref12.

cref11->m1( ).
cref12->m1( ).

CLASS c1 IMPLEMENTATION.
  METHOD m1.
    RAISE EVENT: i1~e1, e1.
  ENDMETHOD.
ENDCLASS.

CLASS c2 IMPLEMENTATION.
  METHOD m2.
    WRITE / 'M2 handling event'.
  ENDMETHOD.
ENDCLASS.

CLASS c3 IMPLEMENTATION.
  METHOD m3.
    WRITE / 'M3 handling event'.
  ENDMETHOD.
ENDCLASS.

This example registers the event handler method m2 for all instances of the classes that implement the interface i1. The event handler method m3 is registered for all instances of the class c1. The triggering instances can also by generated after the SET HANDLER statement.

Variant 3

SET HANDLER h1 ... hn.

Addition:

... ACTIVATION f

Effect

Registers event handler methods for static events. The event handlers h1 ... hn are methods that have been defined as handlers for static events.

The events for handling can be declared either in classes or in interfaces. If they are declared in classes, the event handler methods are registered for the corresponding class. If they are declared in interfaces, the event handler methods are registered for all of the classes that implement the interface. The classes do not already have to be loaded when the SET HANDLER statement occurs - you can also load them later.

You can use the ACTIVATION addition to deregister handler methods and to register them dynamically.

Example

Events in classes and interfaces:

INTERFACE i1.
  CLASS-EVENTS ce1.
ENDINTERFACE.

CLASS c1 DEFINITION.
  PUBLIC SECTION.
    INTERFACES i1.
    CLASS-EVENTS ce1.
    CLASS-METHODS cm1.
ENDCLASS.

CLASS c2 DEFINITION.
  PUBLIC SECTION.
    INTERFACES i1.
    CLASS-METHODS cm2.
ENDCLASS.

CLASS c3 DEFINITION.
  PUBLIC SECTION.
    METHODS: m31 FOR EVENT ce1 OF i1,
             m32 FOR EVENT ce1 OF c1.
ENDCLASS.

DATA: cref3 TYPE REF TO c3.

CREATE OBJECT cref3.

SET HANDLER: cref3->m31, cref3->m32.

c1=>cm1( ).
c2=>cm2( ).

CLASS c1 IMPLEMENTATION.
  METHOD cm1.
    RAISE EVENT: i1~ce1, ce1.
  ENDMETHOD.
ENDCLASS.

CLASS c2 IMPLEMENTATION.
  METHOD cm2.
    RAISE EVENT i1~ce1.
  ENDMETHOD.
ENDCLASS.

CLASS c3 IMPLEMENTATION.
  METHOD m31.
    WRITE / 'M31 handling event'.
  ENDMETHOD.
  METHOD m32.
    WRITE / 'M32 handling event'.
  ENDMETHOD.
ENDCLASS.

This example registers the event handler method M31 for all triggering classes that implement the interface i1, that is, c1 and c2. The event handler method M32 is only registered for the class c1.

Example

Events in global interfaces:

,,INTERFACE if_docu_1 LOAD.

CLASS c1 DEFINITION.
  PUBLIC SECTION.
    METHODS: m1 FOR EVENT ce1 OF if_docu_1.
ENDCLASS.

DATA: cref1 TYPE REF TO c1.

CREATE OBJECT cref1.

SET HANDLER: cref1->m1.

CLASS cl_docu_2 DEFINITION LOAD.

cl_docu_2=>cm1( ).

CLASS c1 IMPLEMENTATION.
  METHOD m1.
    WRITE / 'M1 handling event'.
  ENDMETHOD.
ENDCLASS.

This example registers the event handler method m1 for all triggering classes that implement the global interface if_docu_1. The global class cl_docu_2 implements if_docu_1 and triggers the event if_docu_1~CE1 in its static method cm1. The class is not loaded until after the SET HANDLER statement, but the call cl_docu_2=>cm1 still triggers m1.

Addition

... ACTIVATION f

Effect

The optional ACTIVATION addition allows you to undo existing registrations or register new handlers dynamically using a variable. The argument f in the addition must be a field with type C and length 1. If f contains the value SPACE, the event handler method is deregistered. If f contains the value X, the event handler is registered. You do not need the ACTIVATION addition for static registrations.

Note

If an instance triggers an event, the registration is implicitly deleted if the triggering instance is deleted by the automatic memory management (garbage collection).
The addition ACTIVATION SPACE only allows you to delete those registrations set using ACTIVATION 'X'. A single registration cannot be deleted by means of a mass deregistration using FOR ALL INSTANCES ACTIVATION SPACE. Vice versa, individual triggering instances cannot be excluded from registration after a mass registration. The internal handler tables for single and mass registrations are completely independent of each other.

Example

CLASS C1 DEFINITION.
  PUBLIC SECTION.
    EVENTS E.
    ...
ENDCLASS.

CLASS C2 DEFINITION.
  PUBLIC SECTION.
    METHODS M2 FOR EVENT E OF C1.
ENDCLASS.

DATA: S         TYPE REF TO C1,
      H         TYPE REF TO C2,
      ACTIVE(1) TYPE C VALUE 'X'.
CREATE OBJECT: S, H.

SET HANDLER H->M2 FOR S.
...
SET HANDLER H->M2 FOR S ACTIVATION SPACE.
...
SET HANDLER H->M2 FOR S ACTIVATION ACTIVE.
...

CLASS C2 IMPLEMENTATION.
  METHOD M2.
    ...
  ENDMETHOD.
ENDCLASS.

In this example, the method H->M2 is deregistered and then set dynamically.

Note for all variants:

Note

When you register instance methods as event handlers, note that the registration refers to the current instance and not to the reference variable that is used for registration. Even when the reference variable takes another value after SET HANDLER, the registration of the object remains unchanged. This also affects to the lifetime of objects - an object exists for as long as it is registered as an event handler, even if no more reference variables point to it. The object is either explicitly deregistered using the ACTIVATION addition, or implicitly when the triggering instance no longer exists.

Note

Your event handler methods must be identifiable. If you use an initial reference variable in the SET HANDLER statement to specify an event handler method, a runtime error occurs.

Note

The Return Code is set as follows:

SY-SUBRC = 0:: All event handler methods have been properly registered.

SY-SUBRC = 4:: You tried to register the same combination of triggering event, event handling method, and handler more than once.

SY-SUBRC = 8:: You tried to deregister an event handler that was not registered.

Exceptions

Non-Catchable Exceptions

Cause: Unable to register any more handlers.
Runtime Error: SET_HANDLER_DISP_OVERFLOW
Cause: Handlers of instance methods need the FOR addition.
Runtime Error: SET_HANDLER_E_NO_FOR
Cause: Event handler registered for a static event.
Runtime Error: SET_HANDLER_FOR_CE
Cause: An event may not be triggered using NULL.
Runtime Error: SET_HANDLER_FOR_NULL
Cause: The handler of an event may not be NULL.
Runtime Error: SET_HANDLER_HOBJ_NULL