Anthony Cecchini is the President of Information Technology Partners (ITP), an SAP consulting company headquartered in Pennsylvania. ITP offers comprehensive planning, resource allocation, implementation, upgrade, and training assistance to companies. Anthony has over 17 years of experience in SAP R/3 business process analysis and SAP systems integration. His areas of expertise include SAP NetWeaver integration; ALE development; RFC, BAPI, IDoc, Dialog, and Web Dynpro development; and customized Workflow development. You can reach him at [email protected].
The Controls Technology Framework, Event and Error Handling
In this final blog of the series on the Controls Technology Framework, I will continue to take a look at the SAP Controls Technology and how we can use it in our development. I will focus on Events and their respective handling techniques along with errors.
Event Handling in the Controls Technology Framework
Events are used to implement user interaction within a program. The user triggers control events by performing specific actions (e.g., double-clicking).
For a complete list of events relevant to a particular control, refer to the control class documentation or the Object Navigator (transaction SE80).
There are two kinds of events:
System events: A system event is triggered before any automatic field checks (e.g., required fields) have taken place on the screen, and before any field transports. The PAI and PBO events are not triggered. By default, an event is a system event. The event handler method is called automatically before the PAI event.
Application events: An application event triggers the normal PAI event. Consequently, all field checks and field transports have taken place. If you want the event handler method to be called at a particular point in your application program, you must call the static method CL_GUI_CFW=>DISPATCH in a PAI module. The dispatch method calls the event handler method that is defined and registered for that event. After the event handler method is called, normal PAI event processing continues.
There are advantages and disadvantages to employing both types of events. Below is a summary………
For performance reasons, the frontend must not pass all events to the application server, and it must be clear at runtime whether an event must take place as a system or an application event. This is necessary so that the point of time at which the event handler is triggered (either before the PAI event and screen field transports, or after) can be determined. For this purpose, the information regarding events is stored in special internal tables, both on the application server and the presentation server. The table at the frontend is managed by the Automation Controller; the tables at the backend are administered by the Controls Technology Framework.
Loo at the diagram below to get an idea of how the Automation Controller and the Control Framework handle an event.
When an event is triggered by the user at the frontend, the Automation Controller checks whether the event is registered or not. If the event is not registered, the Automation Controller ignores it. Otherwise, it generates an OK_CODE that is passed to the Controls Technology Framework.
The Controls Technology Framework then calls the event handler method. For the system event, the handler method is called directly. In the case of an application event, you must call the static method CL_GUI_CFW=>DISPATCH within the PAI module. The event handling of controls involves three steps:
1. Register the events. You need to construct the event tables using a special ABAP Objects Controls Technology Framework method
(control-> set_registered_events). The table has a type based on the cntl_simple_events structure. Define an internal table (type cntl_simple_events) and a corresponding work area (type cntl_simple_event):
DATA events TYPE cntl_simple_events.
DATA event TYPE cntl_simple_event.
Now fill the event table with the relevant events. To do this, you need the event ID (event_id field). You can find this information in the Object Navigator by looking at the attributes of the control class — CL_GUI_SIMPLE_TREE.
You must also decide whether the event is to be a system event (appl_event = ‘ ‘) or an application event (appl_event = ‘X’):
event-eventid = event_id.
event-appl_event = appl_event.
APPEND event TO events.
Finally you must now send the event table to the frontend so that it knows which events it has to direct to the backend:
CALL METHOD my_control-> set_registered_events events = events.
2. Define the event handler methods. To react to the events of our control, we must now specify a handler method for it. This can be either an instance method or a static method. However, it must be defined in a local class. Suppose we want to catch the event NODE_DOUBLE_CLICK in a simple tree control. We would define a class whose definition is as follows:
Class handler_class definition.
Public-section.
Class-methods my_method
For event NODE_DOUBLE_CLICK of CL_GUI_SIMPLE_TREE
Importing node_key sender.
Endclass.
You can then implement the handler. The method’s sender parameter is always imported, which contains information regarding the control that fired the event. You can also import additional parameters — in our case, we have imported the node that fired the event.
3. Register the handler methods for the events. This is done via the following line of code.
SET HANDLER for
handler_class=>my_method for my_control.
The variable my_control is the reference variable of the tree object. In the case of a system event, the handler method that you define for the event is called automatically by the system. Since the PBO and PAI events are not called, you can use the method set_new_ok_code to set a new value for the OK_CODE field. This then triggers the PAI and PBO modules. Calling the method set_new_ok_code also carries out normal field transport. To process an application event, you must call the static method CL_GUI_CFW=>DISPATCH within a PAI module. You cannot trigger the handler method for a second time by calling the dispatch method twice.
Keep it simple. Use the application event when you use other screen components — e.g., input/output fields along with the controls — since only in this case will you want the event handler to access the latest values of the screen fields. If you use only the controls and no old screen components, a system event will suffice.
Error Handling (Debugging) in the Controls Technology Framework
The majority of errors in controls technology programming occur during synchronization of the Automation Queue. This raises the exception CNTL_ERROR. The exception only indicates that a method call was unsuccessful, and since there may be many control methods called from a program, it is difficult to figure out which method raised the exception. It is up to the developer to find out where the error occurred and which control fired the exception. When a method in the queue gives an exception, the methods that follow it are also not executed.
Let’s look at a simple example of the type of error that can occur. SAP offers the method CL_GUI_SIMPLE_TREE->add_nodes for adding nodes to the simple tree. If you attempt to add two nodes with the same node key (which has to be unique) to the tree structure, a CNTL_ERROR exception is triggered.
This error is not apparent until the Automation Queue is synchronized. The steps involved in error handling are:
1. Run the program in the ABAP Debugger by entering the name of the program in the ABAP Editor (transaction SE38) and selecting Program → Execute → Debugging.
2. In the debugger settings, select the option “Automation Controller: Always process requests synchronously.” Selecting this option synchronizes the Automation Queue after each method call.
3. Step through the individual methods. You will find that the value of SY-SUBRC has been set in the method(s) where an exception has been triggered. Otherwise a short dump occurs
Now that you have a basic technical understanding of controls technology framework, you are ready to take the next step and actually integrate a control — maybe a tree control — into an ABAP program.
Controls technology has become a valuable tool for ABAP developers. It provides a great deal of functionality, and an efficient way to build interactive and user-friendly interfaces that benefit your end users without requiring you to start from scratch, an advantage every time-strapped programmer can
appreciate.
To read part 1 of this series on the Advanced Control Technology Framework, use the following link. SAP Controls Technology Part 1
To read part 2 of this series on the Advanced Control Technology Framework, use the following link. SAP Controls Technology Part 2
