Simplifying the Capturing, Evaluation, and Communication of Class-Based Exceptions

Transcription

1 Simplifying the Capturing, Evaluation, and Communication of Class-Based Exceptions Applies to: SAP Web AS 6.10 (and later releases). Summary As the number of calls to programs (or class-methods) that raise class-based exceptions increases, so can (highly likely) be the code to handle the exceptions expected from the called programs. This article presents an approach and utility to simplify capturing, evaluating and communicating class-based exceptions. Author(s): Chetanpal Singh Company: Computer Sciences Corporation (CSC) Created on: 22 November 2006 Author Bio Chetan has 16 years of IT industry experience, with last 9 years in architecting, developing, and implementing SAP applications. His expertise includes managing SDLC phases, designing common-services in SAP and Net Weaver environment, interfaces development, and data migration. Chetan is certified Project Management Professional (PMP), and is working with CSC SAP Federal Consulting Practice group SAP AG 1

2 Table of Contents Applies to:... 1 Summary... 1 Author Bio... 1 Introduction... 3 Utility Overview and Features... 3 What details (of class-based exception) does the utility retrieve?... 3 Execution Scenario (Raising and Handling of Class-Based Exceptions)... 4 Source Code: Utility... 6 Source code: Sample program (using the utility)... 8 Related Content Copyright SAP AG 2

3 Introduction Class-based exception handling is the way to move forward for handling errors and exceptions in SAP applications (programs). I would not get into details of what Class-based exception is, as SAP Online Help and search for articles by Thomas Weiss (SAP AG) available at SDN provide enough information on it. This article is applicable to development environments that already are using class-based exception handling approach as a means for handling exception situations encountered during processing. The article explains the custom developed utility that can be used to simplify handling of class-based exceptions and retrieving its context-specific details. Utility Overview and Features The article presents a generic approach about how, using a simple class-method call, SAP applications (programs) can: a) Handle multiple class-based exceptions conveniently at a single place in the program, b) Avoid having to specify all class-based exceptions explicitly for the purpose of handling them, c) Make program-code robust in the sense that it does not have to be changed even if there are changes in the exceptions raised by the class-method(s) it calls, and d) For any class-based exception caught at a higher level in hierarchy (e.g. using CATCH CX_ROOT statement), have the ability to identify context-specific information associated with it In non-object oriented environment, many SAP applications use standard structure BAPIRET2 (or table-type of the same structure) as a template to exchange informational, warning, or error messages between SAP and external interfaces (or even between two processes within SAP). BAPIRET2 structure has a number of placeholders to host message details, like message type (error, warning, etc), message ID, message number, message text, etc. Populating these fields when triggering an error (or warning) can help programmers find where in the program (main or the called programs) the error would have occurred. On the same lines, the utility described in this article provides a convenient way to catch any class-based exception, at any level of its super-class (e.g. CX_ROOT, CX_STATIC_CHECK, etc), retrieve its contextspecific (sub-class) details, and load results in same template as BAPIRET2. This enables programs to keep using same template (BAPIRET2) as means of exchanging the messages no matter how they were triggered (i.e. based on old SAP Message Class (SE91) approach, or new way of class-based exception). What details (of class-based exception) does the utility retrieve? For any given class-based exception object (no matter at what level of its super-class was it caught), the utility retrieves following context-specific information: 1) Exception-class name (the actual (sub)class based on which the exception originated) 2) Exception-class TEXTID that was used when triggering exception 3) Exception text (the detailed message/text associated with the exception) 4) Main program name (or ABAP Class name) in which the exception occurred 5) INCLUDE program (or ABAP Class-method name) where exception occurred, and 6) Line number (of the INCLUDE or ABAP Class-method) where exception occurred All these details of class-based exception can be stored in BAPIRET2 based structure (or table-type) and communicated to the caller applications (screen, external interfaces, other SAP program etc). Now as BAPIRET2 does not have true placeholders for exception class name, exception class TEXTID, etc, existing fields can be mapped to attributes of your choice depending upon what you want each of those 2006 SAP AG 3

4 fields to hold when storing details and thus interpret accordingly in receiving application. This example uses BAPIRET2 field mapping as follows: BAPIRET2 field TYPE ID NUMBER MESSAGE MESSAGE_V1 MESSAGE_V2 MESSAGE_V3 MESSAGE_V4 ROW Mapped to store To store exception type ( E : Error, W : Warning, I : Info, etc) Constant value CLASS-EXCEPTION, to indicate the message stored is for a class-based exception Constant value of 999 to indicate the message stored is for a class-based exception. (You can also leave it blank) Detailed message (exception text) Exception-class name Exception-class TEXTID Program name (or class name) where exception occurred INCLUDE (or class-method name) where exception occurred Line number at which the exception occurred Execution Scenario (Raising and Handling of Class-Based Exceptions) Following is a common scenario of how class-based exceptions propagate through the call chain and finally handled by the main program: Based on which exception gets raised, it would get handled by its corresponding CATCH statement in the main program. But above scenario can lead to two difficult situations: a) As the number of class-methods calls from the main program increases, so can the code to handle exceptions that can be expected from the called class-methods, and b) If a called class-method is later modified to raise a new exception, main program most likely would have to be changed to handle the newly introduced exception. Depending upon what function the main program performs, it may be required that each exception be caught and handled explicitly; especially in cases where different processing routes would be taken by the program for each type of error (exception) encountered SAP AG 4

5 But many times, especially in reports or large file processing programs, the programs usually go about validating data (by using existing functions and/or class-methods), process records that are valid, and discard those that contain erroneous data. Errors encountered, no matter of what type, are reported on the error-report; preferably with additional details to assist users (and programmers) in understanding the cause of error as well as finding where it occurred. If each class-based exception is to be handled explicitly, it can raise difficult situations as described above. And if all class-based exceptions are caught at the highest level using a single CATCH CX_ROOT (or CATCH CX_STATIC_CHECK) statement, we do get rid of specifying CATCH statement for each exception explicitly but then have no convenient way to retrieve context-specific info associated with the exception. This utility overcomes these hurdles by letting programs to code a single CATCH CX_ROOT (or CATCH CX_STATIC_CHECK statement, or any associated super-class) to catch any class-based exception and be able to retrieve its context-specific info (as mentioned in points 1 to 5). The results can finally be loaded in BAPIRET2 structure for sending to other programs, or evaluating within the program to steer process flow. Based on the new approach, here is how the coding of main program would look like. Note: vp_exception_obj can be defined as ABAP object with reference to exception-class CX_ROOT: All class-based exceptions are handled just once, using CATCH CX_ROOT. Calling the utility will retrieve the context-specific information associated with the exception that was caught. The retrieved details (BAPIRET2 record received from the class-method utility) can then be exported back to the main calling program or evaluated to take further action. As mentioned before, it may be so that each (or a number of possible exceptions) have to be handled explicitly to navigate the program processing through different routes (based on type of exception encountered). But on the contrary, there are many scenarios in dialog programs that as soon as an error is encountered, you abort processing and inform user with an error message (or in case of report programs, report error via a spool or exception report, skip the record in error, and continue processing next record) SAP AG 5

6 Source Code: Utility The utility is implemented via a static, public class method PROCESS_CB_EXCEPTION (Process Class- Based Exception) of custom class ZCL_CS_CB_EXCP_UTIL. Class-method signatures are: Import: IMP_CX_OBJECT_REF TYPE CX_ROOT (class based exception object reference) Export: EXP_ERROR_MSG_REC TYPE BAPIRET2 (error message) Exception: INVALID_UTIL_CALL (is raised if import parameter is initial/ not-supplied) * * * Process class-based exception object and retrieve context-specific * * information (associated with the exception that was caught) * * * METHOD process_cb_exception. CONSTANTS: c_active(1) TYPE n VALUE '1'. DATA: vp_descr_ref TYPE REF TO cl_abap_typedescr, v_ex_cls_tag(30) TYPE c, v_ex_cls_name TYPE seoclsname, v_textid_value TYPE seovalue, v_textid_name TYPE seocmpname, v_program_name TYPE syrepid, v_include_name TYPE syrepid, v_pgm_src_line TYPE int4. * Initialize export parameter (error message record) CLEAR: exp_error_msg_rec. * Get exception-class name (associated with the exception object) CALL METHOD cl_abap_classdescr=>describe_by_object_ref EXPORTING p_object_ref = imp_cx_object_ref RECEIVING p_descr_ref = vp_descr_ref EXCEPTIONS reference_is_initial = 1 OTHERS = 2. IF sy-subrc <> 0. RAISE invalid_util_call. EXIT. ENDIF. * Get exception-class tag and exception-class name SPLIT vp_descr_ref->absolute_name AT '=' INTO v_ex_cls_tag v_ex_cls_name. * Build TEXTID value for search CONCATENATE '''' imp_cx_object_ref->textid '''' INTO v_textid_value SAP AG 6

7 * Get program source-code line number where exception occurred CALL METHOD imp_cx_object_ref->get_source_position IMPORTING program_name = v_program_name include_name = v_include_name source_line = v_pgm_src_line. * Get TEXTID name SELECT cmpname INTO v_textid_name FROM seocompodf WHERE clsname = v_ex_cls_name AND version = c_active AND attvalue = v_textid_value. IF NOT sy-subrc IS INITIAL. v_textid_name = 'TEXTID name not found'. ENDIF. EXIT. " max one record would exist ENDSELECT. * Load export parameter (that is based on BAPIRET2 structure) exp_error_msg_rec-id = 'CLASS-EXCEPTION'. * Load exception text exp_error_msg_rec-message = imp_cx_object_ref->get_text( ). * Load exception-class name (based on which the exception was raised) exp_error_msg_rec-message_v1 = v_ex_cls_name. * Load TEXTID "name" associated with the exception-class object exp_error_msg_rec-message_v2 = v_textid_name. * Load program name (in which the error/exception occurred) exp_error_msg_rec-message_v3 = v_program_name. * Load INCLUDE filename (would contain class-method name ID * where the error occurred) exp_error_msg_rec-message_v4 = v_include_name. * Move source-code line number where the error occurred exp_error_msg_rec-row = v_pgm_src_line. * If the message type has to be specified as Error, Informational, * Warning, etc, the class-method signature can be modified to * include one more parameter to accept MESSAGE-TYPE value from * the caller application, which can be moved to the following field ***** exp_error_msg_rec-type = i_msg_type. * NUMBER field of BAPIRET2 structure (which is used to hold message * number from the SAP Message Class) can be populated with any * generic number (say, 999) to indicate that the message stored in * the template corresponds to class-based exception and is not of * a SAP Message Class message-number ***** exp_error_msg_rec-number = '999'. ENDMETHOD SAP AG 7

8 Source code: Sample program (using the utility) Following is a sample program that demonstrates using the utility and writing the context specific information associated with the exception. TEST_METHOD_M1 and TEST_METHOD_M2 are temporary class-methods created for testing purpose only. You can replace them with your own class-methods (that raise class-based exception(s)), and then run the test. *& * *& Report ZCS_EXCP_UTIL_TEST_PROG *& * REPORT zcs_excp_util_test_prog. DATA: l_error_msg_rec TYPE bapiret2, lp_sample_obj TYPE REF TO zcl_cs_cb_excp_util_suppl, vp_exception_obj TYPE REF TO cx_root. TRY. * Call static method test_method_m1 CALL METHOD zcl_cs_cb_excp_util_suppl=>test_method_m1. * Call instance method test_method_m2 CREATE OBJECT lp_sample_obj. CALL METHOD lp_sample_obj->test_method_m2. * Additional method calls can be placed here, no matter what * all exceptions they raise * Handle all exceptions here by catching CX_ROOT. No need to * specify each exception explicitly; and no need to worry about * if called method (and new methods) raise new exceptions in future CATCH cx_root INTO vp_exception_obj. * Call utility method to process the exception-class object CALL METHOD zcl_cs_cb_excp_util=>process_cb_exception EXPORTING imp_cx_object_ref = vp_exception_obj IMPORTING exp_error_msg_rec = l_error_msg_rec EXCEPTIONS invalid_util_call = 1 OTHERS = 2. IF sy-subrc <> 0. WRITE: / 'Error encountered in calling Class-Based', ' exception handling utility'. ENDIF. ENDTRY. * Write exception-class object details (for testing only). * Any field value can be evaluated to take any specific action * or the entire message can be transferred as-is to caller program WRITE: / 'Following are the details of error message:', / 'ID:', 55 l_error_msg_rec-id, / 'Exception Class:', 55 l_error_msg_rec-message_v1, / 'TEXTID (that was used when raising exception):', 55 l_error_msg_rec-message_v2, / 'Exception Message/ Text:', 55 l_error_msg_rec-message, / 'Program name (in which error occurred):', 55 l_error_msg_rec-message_v3, / 'INCLUDE name (where error occurred):', 55 l_error_msg_rec-message_v4, 2006 SAP AG 8

9 / 'Line number (where error occurred):', 55 l_error_msg_rec-row. *********************** END OF PROGRAM ******************************* 2006 SAP AG 9

10 Related Content ABAP Objects Class-Based Exceptions (at SAP Help) Class-Based Exception Handling in ABAP Part 1 (of 5) at SDN 2006 SAP AG 10

11 Copyright Copyright 2006 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iseries, pseries, xseries, zseries, z/os, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, i5/os, POWER, POWER5, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MaxDB is a trademark of MySQL AB, Sweden. SAP, R/3, mysap, mysap.com, xapps, xapp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. These materials are provided as is without a warranty of any kind, either express or implied, including but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. SAP shall not be liable for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials. SAP does not warrant the accuracy or completeness of the information, text, graphics, links or other items contained within these materials. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third party web pages nor provide any warranty whatsoever relating to third party web pages. Any software coding and/or code lines/strings ( Code ) included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP intentionally or grossly negligent SAP AG 11