ABAP Geek 10 - Everything FUNCTIONs – But How?

ref: https://www.sdn.sap.com/irj/sdn/weblogs?blog=/pub/wlg/1741

During my never ending quest for the holy grail of perfect keyword documentation this astonishing language named ABAP offers nearly daily some surprises for me. Especially the ABAP language hotline service that is offered by our group for internal as well as for external customers (the so called development support) must often handle requests that lead to some smaller improvements in the documentation.

And sometimes I even stumble over (or fall into?) one or the other larger gap. One of these gaps was a missing detailed description of a function module’s parameter interface!

Everybody working with ABAP knows function modules: Either you are publishing functional services via function modules or you are using them. And of course, you define interface parameters for your modules or you are supplying actual parameters when calling them. And well, everything works fine – but as I asked above, do you know how?

Defining the Parameter Interface

You define a function module’s parameter interface in the Function Builder. There you can enter names for the well known IMPORTING, EXPORTING, CHANGING, and TABLES (L) parameters and you can type them with TYPE, TYPE REF TO ( J ) or LIKE ( L ). Furthermore, you can either define old fashioned non-class based exceptions ( L ) or you can enter a list of modern exception classes ( J ) for exceptions that can be triggered by a function module. This Weblog is about the meaning what you are doing there.

Interface Representation in the Source Code of a Function Module

You know that a function module is implemented between

*"---------------------------------------------------------
*" Local Interface:
*" [IMPORTING parameters]
*" [EXPORTING parameters]
*" [CHANGING   parameters]
*" [TABLES    table_parameters]
*" [{RAISING|EXCEPTIONS} exc1 exc2 ...]  
*"---------------------------------------------------------

Where the syntax of parameters is:

... { VALUE(p1) | p1 }
         {TYPE [REF TO] type} | {LIKE struc-comp} | {STRUCTURE struc}          [OPTIONAL |{DEFAULT def1}]
    { VALUE(p2) | p2 }
         {TYPE [REF TO] type} | {LIKE struc-comp} | {STRUCTURE struc}
         [OPTIONAL|{DEFAULT def2}]
    ...

and the syntax of table_parameters is:

... p1  {TYPE itab_type} | {STRUCTURE struc} [OPTIONAL]
    p2  {TYPE itab_type} | {STRUCTURE struc} [OPTIONAL]
    ...

Quiet familiar from defining local methods, isn’t it? But there are some differences …

Interface parameters

The interface parameters are defined on the relevant tab pages in the Function Builder.

 

• IMPORTING parameters are input parameters. When the function module is called, a suitable actual parameter must be specified for every non-optional input parameter. The content of the actual parameter is passed to the input parameter when the call is made. The content of an input parameter for which 'pass by reference' is defined cannot be changed in the function module. This is the same as for methods.
• EXPORTING parameters are output parameters. When the function module is called, a suitable actual parameter can be specified for every output parameter. The content of an output parameter that is defined for 'pass by value' is transferred to the actual parameter if the function module is completed without errors. An output parameter that is defined for pass by reference is not initialized when the function module is called. This is the same as for methods.
• CHANGING parameters are input and output parameters. When the function module is called, a suitable actual parameter must be specified for every non-optional input/output parameter. When the function module is called, the content of the actual parameter is passed to the input/output parameter, and when the function module is completed, the content of the input/output parameter is passed to the actual parameter. This is the same as for methods.
• TABLES parameters are table parameters. Table parameters are obsolete CHANGING parameters that are typed as standard tables with a header line (L ). If an internal table without a header line or a table body is passed as an actual parameter to a formal parameter of this type, an empty local header line is generated in the function module. If an internal table with a header line is used as an actual parameter, both the table body and the header line are passed to the function module. Pass by value is not possible in formal parameters defined using TABLES. Table parameters are not allowed in methods and you should not define them for function modules any more. Formal parameters defined with TABLES can be replaced by formal parameters defined with CHANGING. A local work area can easily be created for the internal table in the function module by using the addition LIKE LINE OF itab of the DATA statement.

Type of Parameter Passing

There are two ways in which parameters can be passed: pass by reference and pass by value. Pass by value is selected in the Function Builder by selecting pass by value, and in the above syntax, differs from pass by reference by the specification of VALUE( ) .

 

• With pass by reference, the formal parameter points directly to the actual parameter, so that changes to the formal parameters have an immediate effect on the actual parameter.
• With pass by value, when the function module is called, the formal parameter is created as a copy of the actual parameter (for IMPORTING and CHANGING parameters), or initial (for EXPORTING parameters). For CHANGING and EXPORTING parameters, the formal parameter is copied to the actual parameter when returning from the function module (via ENDFUNCTION or RETURN ( J ) or EXIT , CHECK ( L )).

Note the following for the different types of parameter:

 

• In IMPORTING , EXPORTING , and CHANGING parameters, pass by reference and pass by value are possible, in TABLES parameters, only pass by reference is possible.
• IMPORTING parameters passed by reference cannot be overwritten in the function module.
• EXPORTING parameters passed by reference are not initialized when the function module is called. For this reason, no read access to these parameters should be carried out before the first write access.

Typing of Interface Parameters

The parameter interface of a function module is public across the system. Interface parameters can therefore only be typed with reference to data types from the ABAP Dictionary or from the public section of global classes. In the Function Builder, interface parameters can be typed by the selection of either TYPE, TYPE REF TO or LIKE. While typing with TYPE is also displayed as TYPE in the above syntax, typing with LIKE is not only represented by LIKE , but also by STRUCTURE !

 

• Typing with TYPE [REF TO] is the recommended typing for interface parameters of function modules. It takes place when TYPE or TYPE REF TO is selected in the Function Builder. For IMPORTING , EXPORTING , and CHANGING parameters, any predefined ABAP type (complete or generic), or any data type from the ABAP Dictionary or from the public section of a global class can be specified after TYPE . After TYPE REF TO , the generic data type data , a non-generic data type, or an object type can be specified. Then, the interface parameter is typed as a reference variable. In TABLES parameters, only a table type itab_type can be specified, where itab_type is a 'standard table' with a flat line type from the ABAP Dictionary. When calling the function module, the typing check is performed in the same way as for methods.
• Typing with LIKE is obsolete. It takes place if an elementary component of a flat structure (or database table) struc-comp from the ABAP Dictionary is specified after LIKE in the Function Builder. The typing check is the same as for the specification of components after TYPE , with the exception that the fractional portion is not taken into account for packed numbers. And some more weird stuff: If a component of a global program structure in the function group of a function module has exactly the same identity (structure name struc and component comp) as the component of a structure in the ABAP Dictionary specified after LIKE , LIKE refers to the component of the structure defined in the function group! Fortunately, this leads to a warning during syntax check. In contrast, TYPE always refers to types in the ABAP Dictionary.
• Typing with STRUCTURE is obsolete. It takes place if a flat structure (or database table) struc from the ABAP Dictionary is specified after LIKE in the Function Builder. The formal parameter is then casted with this structure, and it is possible to access the individual components. For a formal parameter typed with STRUCTURE , a connected actual parameter must be a structure. In non-Unicode programs, the actual parameter must be suitably aligned (for pass by reference) and its length must exactly match the length of the structure struc , with the exception of table parameters. For table parameters, the length of the actual parameter must only be at least the length of the structure. In Unicode programs, the Unicode fragment view of a structured actual parameter must match that of struc . For an elementary actual parameter this must be character-type and flat. Everything clear now? Seems better not to use that …

From the last two points you see that choosing LIKE in the Function Builder is by far not the same as using the language element LIKE with DATA or for typing method parameters or field symbols. Good reasons, not to use LIKE any more!

Optional parameters

IMPORTING , CHANGING , and TABLES parameters can be made optional by the selection of optional in the Function Builder. EXPORTING parameters are always optional. IMPORTING and CHANGING parameters can be assigned a replacement parameter (default value in the Function Builder). In the above syntax, this is expressed using the additions OPTIONAL or DEFAULT . For an optional parameter, no actual parameter must be entered when the function module is called. While a formal parameter with the addition OPTIONAL is then initialized according to its type, a formal parameter with the addition DEFAULT takes over the value and type of the replacement parameter def1 def2 ... . Within a function module, the logical expression IS SUPPLIED can be used to check if an optional formal parameter was assigned an actual parameter when the module was called.

Exceptions

The exceptions of a function module are defined on the Exceptions tab page in the Function Builder. Here you can select exception classes to define whether class-based exceptions are declared or non-class-based exceptions are defined. Class-based exceptions are represented in the above syntax by RAISING , and non-class-based exceptions are represented by EXCEPTIONS. This is the same as for methods.

 

• The addition RAISING is used to denote class-based exceptions that can be propagated from the function module to the caller. Exceptions in the categories CX_STATIC_CHECK and CX_DYNAMIC_CHECK must be explicitly declared, otherwise a propagation can lead to an interface violation. A violation of the interface leads to the treatable exception CX_SY_NO_HANDLER. Exceptions of the category CX_NO_CHECK are implicitly always declared. The declaration of exceptions of the category CX_STATIC_CHECK is statically checked in the syntax check. For exceptions of the category CX_DYNAMIC_CHECK, the check is not performed until runtime. In a function module in which class-based exceptions are declared with the RAISING addition, the statement CATCH SYSTEM-EXCEPTIONS cannot be used. Instead, the relevant exceptions should be handled in a TRY control structure.
• The addition EXCEPTIONS is used to define a list of non-class-based exceptions that can be triggered in the function module using the statements RAISE or MESSAGE RAISING. Exceptions defined in this way - as with formal parameters - are bound to the function module and cannot be propagated. If an exception of this type is triggered in a function module, and no return value has been assigned to it with the homonymous addition EXCEPTIONS of the CALL FUNCTION statement where the call was made, this leads to a runtime error.

For new developments after release 6.10, I strongly recommend that you work with class-based exceptions that are independent of the function module.

Global Parameters

Finally, as another relict of ABAP’s long history, you might find the attribute Global checked for older function modules. What the heck is this?

The parameters of a function module can be declared as “global” by choosing   Edit → Interface → Globalize Parameters in the Function Builder. Then the parameters are treated as follows:

 

• All parameters, that are completely typed and defined for pass by value, are handled in a way as they were declared as global data objects in the top include of the function group: They are visible throughout the function group and their values are preserved when the function module is left. When calling a function module the global parameters are initialized or a replacement parameter (default) is assigned.
• All other parameters are handled in a way as they were declared as global data objects in the top include of the function group, that can be used only during the execution of the function module: They are visible throughout the function group but you can access them only while the function module is active. If you access such a parameter and the respective function module is not executed, you get the runtime error GETWA_NOT_ASSIGNED (Why? Well, technically thos guys are represented via field symbols which are valid only during the runtime of the function module).

In a function group you cannot declare global data objects that have the same names as global parameters. If a parameter name occurs in several function modules with global interfaces, the parameter must be defined with exactly the same properties.

Needless to say, that you never define such global parameters in new function modules …