ABAP Exception Class ZCX_RETURN3

[AlwinPut]

As an ABAP programmer we must program Object Oriented code (aka OO code). So for exception / error handling we need to use Exception classes instead of using the old procedural ways of error handling like SY-SUBRC and BAPIRETURN data.

However often we have to call BAPIs, or less favorite other function modules or FORM routines. In new OO code we have to handle the procedural errors and convert them to OO Exceptions.

Some years ago I started to create an exception class for handling all kind of procedural error messages (old procedural and new OO messages) and combining it with the good old SAP messages (T: SE91).

This class is called ZCX_RETURN3. It can handle all kind errors.

• Create exception class instance based on all kind of BAPI return structure and table types like BAPIRET2, BAPIRET1 and BAPIRETURN.


• Create exception class instance based on current message in SY-MSGID / SY-MSGNO.


• Create exception class instance based on BDC messages from a CALL TRANSACTION statement.


• Create exception class instance based on a plain OO exception class instance and combine it with a SAP SE91 message.


• NEW: ZCX_RETURN3 can be used in the ABAP 7.50 syntax for raising RAISE EXCEPTION with MESSAGE. Example:
  

  RAISE EXCEPTION TYPE zcx_return3
  
    MESSAGE e058
  
    WITH '1' '2' '3' '4'.​

  
  


• NEW: "ABSTRACT" statement in class definition can be activated to enforce inheritance of this class.

ZCX_RETURN2 was the previous version. Based on the comments on the blog post of ZCX_RETURN2 I have redesigned it into ZCX_RETURN3. Important change is, that it now supports the new RAISE EXCEPTION ... [USING] MESSAGE statement and that the static instance creation methods (factory methods) are removed to promote inheriting this class for specialized exception classes instead of using this class as generic exception class.

In this blog post is explained how it works. It also contains references to related blogs for code templates for quickly adding error handling code.

Examples

Probably most used exception class instantiations are for:

• BAPI errors


• SE91 message errors

Therefor the two examples below will show how this works.
The examples are based on instantiating ZCX_RETURN3, but creating a sub class of ZCX_RETURN3 is also possible.

Example 1: Raising BAPI errors

For example you call a BAPI function module routine which returns a BAPI return table of type BAPIRET2.

        DATA:

          lt_return TYPE bapiret2_t.



        CALL FUNCTION 'BAPI_USER_CREATE1'

          EXPORTING

            username  = 'DUMMY'

            logondata = ls_logondata

            password  = ls_password

            address   = ls_address

          TABLES

            return    = lt_return.



        DATA(lx_return) = NEW zcx_return3( ).

        lx_return->add_bapiret2_table( lt_return ).



        IF lx_return->has_messages( ) = abap_true.

          RAISE EXCEPTION lx_return.

        ENDIF.

The return table variable LT_RETURN will receive the error messages from the BAPI.

The class ZCX_RETURN3 will be instantiated or a subclass of ZCX_RETURN3.

Method ADD_BAPIRET2_TABLE will add the messages to the exception object.

If LT_RETURN contains one or more messages with type E, A or X, then method HAS_MESSAGES() will return ABAP_TRUE. And then RAISE EXCEPTION will raise it.

Example 2: Raising SAP and custom message

        SELECT SINGLE

            kunnr

          FROM kna1

          WHERE kunnr = @gv_kunnr

          INTO @DATA(ls_kna1).



        IF sy-subrc <> 0.



          RAISE EXCEPTION TYPE zcx_return3

            MESSAGE e001

              WITH gv_kunnr.



        ENDIF.

Function modules, FORM routines and ABAP statements can fill SY-SUBRC. If the value is <> 0, then an error occurred.

The new 7.50 syntax is used. RAISE EXCEPTION TYPE with MESSAGE will retrieve the message from table T100 and raise it as exception in one statement.

The essence of the ZCX_RETURN3

The class ZCX_RETURN3 has many ADD methods for adding different kind of error types and converting them to its own attribute internal table GT_RETURN of type BAPIRET2_T.



For retrieving the data use the GET-methods:

• IF_MESSAGE~GET_TEXT
  Get the message text of the first error.


• IF_MESSAGE~GET_LONGTEXT
  Get the long text of T:SE91 of the first error.


• GET_BAPIRET2_STRUC
  Get the first error of GT_RETURN.


• GET_BAPIRET2_TABLE
  Get all errors from table GT_RETURN.

Raising the ZCX_RETURN3 exception

Raising can be done with the new 7.50 RAISE EXCEPTION with MESSAGE and also by adding BAPI return data and other messages.

See the code templates in:

Blog post: ABAP Exception Class ZCX_RETURN3 – Raise code templates

Catching the ZCX_RETURN3 exception

This can be done for different purposes like ABAP programs / reports, ABAP Gateway, ABAP Proxy, IDocs and RFC function modules.

Blog post: ABAP Exception Class ZCX_RETURN3 – Catch code templates

Download and install ZCX_RETURN3

Download

• Download file ZCX_RETURN3.abap from github:
  https://github.com/alwinvandeput/zcx_return3


• Create or determine an ABAP package for the class ZCX_RETURN3.

Install ZCX_RETURN3 class

Option 1: with Eclipse (this is the preferred way)

This is the preferred way, because in Eclipse all code can be copied and pasted at once.

• Determine or create an ABAP package for the class ZCX_RETURN3.


• Create a new class: ZCX_RETURN3.


• Copy and paste the code of the ZCX_RETURN3_750.abap file.
  For ABAP < 7.50, use the file ZCX_RETURN3.abap.

Option 2: with ABAP workbench (not the preferred way)

• Determine or create an ABAP package for the class ZCX_RETURN3.


• Create in SE80 class: ZCX_RETURN3.
  Super class: CX_STATIC_CHECK
  Description: RETURN3 exception class
  Inst. Generation: PublicClass type: Exception class
  With messages of message classes as exception texts: OFF
  Final: OFFPackage: ZCA_DOMAIN


• Activate the class.


• Menu: Goto -> Sections -> Public section.


• Definition part
  
  
  
  • Copy and paste the Definition part of the file ZCX_RETURN3 into SE80 editor
  
  
  
  


• Implementation part.
  
  
  
  • Double click on every method and copy and paste the ABAP code.
    Use the Panel on the left (Explorer view) to navigate to the next method.
  
  
  
  

Appendix: Raising exceptions from procedural routines

Creating new procedural routines is not allowed anymore unless you need it for technical reasons. For example.

• Function module might be needed for tRFC, qRFC, remote enabled or update task.


• New FORM routines are not allowed.


• New Macros are not allowed.


• ABAP program events are allowed, because they are needed for technical reasons.

In the procedural routine only calling methods is allowed and catching OO exceptions for these methods. It is not allowed to raise OO exceptions.

Appendix: ZCX_RETURN3 versioning

It is already version 3, therefor the 3 in the name. In comparison the version 1, the naming of the methods have been improved and the coding is refactored by consistency of doing creating the instance and as a result it is simplified. In comparison the version 2 the static factory methods are removed and it has been made applicable for 7.50 RAISE EXCEPTION with MESSAGE.

ABAP BAPI BO Class Generator still uses an older version named ZCX_RETURN.

Appendix: SAP messages (T:SE91) advantages and tips

Advantages

1. By using the Where-used list in T: SE91, you can find the ABAP code location.


2. They have a name / number combination which identify each message uniquely.


3. They can be translated.


4. They can handle 4 variables.


5. They can be added to the Application log (T: SLG1 / SLG0).


6. They are used by all BAPI RETURN structure types and table types.

Tips

1. Make a Message class per ABAP class.
   Reason for this is that the messages belong to Business Object, Business Subobject or other type of class.
   By keeping the messages grouped together by ABAP class, it is easier to copy specific ABAP classes with their messages to another system.


2. Do not reuse messages on multiple code locations.
   Reason for this is that the goal is that the where-used list from SE91 will only return one code location.
   That's why you should not use or create generic SE91 messages like '&1 &2 &3 &4' with only variables and without any text.