Start of Content Area

Calling Function Modules  Locate the document in its SAP Library structure

This section describes calling function modules from the Function Builder.

Finding Function Modules

Before programming a new function or creating a new function module, you should look in the Function Builder to see whether there is an existing function module that already performs the same task.

For more information about this, refer to Finding Function Modules in the ABAP Workbench documentation. For example, you might look for function modules that process strings by entering *STRING* as a search criterion in the Repository Information System. This is an extract from the list of function modules found:

This graphic is explained in the accompanying text

The title CSTR is the function group. There is a main program SAPLCSTR that contains these function modules. If you select a function module, you can display its attributes in the Function Builder.

Important attributes:

The documentation describes the purpose of the function module, lists the parameters for passing data to and from the module, and the exceptions. It tells you how you can pass data to and from the function module, and which errors it handles.

This section provides further information about the interface parameters and exceptions, and how to use the function module. For further information, refer to Displaying Information about Interface Parameters in the ABAP Workbench documentation. Function modules can have the following interface parameters:

You can specify the types of the interface parameters, either by referring to ABAP Dictionary types or elementary ABAP types. When you call a function module, you must ensure that the actual parameter and the interface parameters are compatible.

Interface parameters are, by default, passed by value. However, they can also be passed by reference. Tables parameters can only be passed by reference. You can assign default values to optional importing and changing parameters. If an optional parameter is not passed in a function module call, it either has an initial value, or is set to the default value.

Exceptions are used to handle errors that occur in function modules. The calling program checks whether any errors have occurred and then takes action accordingly.

Testing Function Modules

Before you include a function module in a program, you can test it in the Function Builder.

This graphic is explained in the accompanying text

For more information about this, refer to Testing Function Modules in the ABAP Workbench documentation.

Calling Function Modules in ABAP

To call a function module, use the CALL FUNCTION statement:

CALL FUNCTION <module>
     [EXPORTING  f1 = a 1.... f n = a n]
     [IMPORTING  f1 = a 1.... f n = a n]
     [CHANGING   f1 = a 1.... f n = a n]
     [TABLES     f1 = a 1.... f n = a n]
     [EXCEPTIONS e1 = r 1.... e n = r n [ERROR_MESSAGE = r E]
                                     [OTHERS = ro]].

You can specify the name of the function module <module> either as a literal or a variable. Each interface parameter <fi> is explicitly assigned to an actual parameter <a i>. You can assign a return value <r i> to each exception <e i>. The assignment always takes the form <interface parameter> = <actual parameter>. The equals sign is not an assignment operator in this context.

You can use the EXCEPTIONS option to handle the exceptions of the function module. If an exception <e i > is raised while the function module is running, the system terminates the function module and does not pass any values from the function module to the program, except those that were passed by reference. If <e i > is specified in the EXCEPTION option, the calling program handles the exception by assigning <r i > to SY-SUBRC. <r i > must be a numeric literal.

If you specify of ERROR_MESSAGE in the exception list you can influence the message handling of function modules. Normally, you should only call messages in function modules using the MESSAGE ... RAISING statement. With ERROR_MESSAGE you can force the system to treat messages that are called without the RAISING option in a function module as follows:

If you specify OTHERS after EXCEPTIONS, the system assigns a single return code to all other exceptions that you have not specified explicitly in the list.

You can use the same number <r i > for several exceptions.

Example

The recommended and easiest way to call a function module is to use the Insert statement function in the ABAP Editor. If you select Call Function and specify the name of the function module (F4 help is available), the system inserts a CALL FUNCTION statements with all of the options of that function module in the source code.

This graphic is explained in the accompanying text

Optional parts of the function call are inserted as comments. In the above example, STRING and POS are obligatory parameters. LANGU, on the other hand, is optional. It has the default value SY-LANGU (the system field for the logon language). Handling export parameters is optional. Handling exceptions is also theoretically optional. However, you should always do so. That is why the EXCEPTIONS lines are not commented out.

You can trigger exceptions in the function module using either the RAISE or the MESSAGE ... RAISING statement. If the calling program handles the exception, both statements return control to the program. The MESSAGE ..... RAISING statement does not display a message in this case. Instead, it sets the following system fields:

You can use the system fields to trigger the message from the calling program.

To ensure that you use the right data types for the actual parameters, you must refer to the function module interface. If you double-click the name of a function module in the source code of your program, the system navigates to its source code in the Function Builder. You can then display the interface by choosing Goto Interface.

For example, in the above case

A complete call for the function module STRING_SPLIT_AT_POSITION might look like this:

PROGRAM CALL_FUNCTION.

DATA: TEXT(10) TYPE C VALUE '0123456789',
      TEXT1(6) TYPE C,
      TEXT2(6) TYPE C.

PARAMETERS POSITION TYPE I.

CALL FUNCTION 'STRING_SPLIT_AT_POSITION'
     EXPORTING
          STRING            =  TEXT
          POS               =  POSITION
     IMPORTING
          STRING1           =  TEXT1
          STRING2           =  TEXT2
     EXCEPTIONS
          STRING1_TOO_SMALL = 1
          STRING2_TOO_SMALL = 2
          POS_NOT_VALID     = 3
          OTHERS            = 4.

CASE SY-SUBRC.
  WHEN 0.
    WRITE: / TEXT, / TEXT1, / TEXT2.
  WHEN 1.
    WRITE 'Target field 1 too short!'.
  WHEN 2.
    WRITE 'Target field 2 too short!'.
  WHEN 3.
    WRITE 'Invalid split position!'.
  WHEN 4.
    WRITE 'Other errors!'.
ENDCASE.

The function module splits an input field at a particular position into two output fields. If the contents of POSITION are in the interval [4,6], the function module is executed without an exception being triggered. For the intervals [1,3] and [7,9], the system triggers the exceptions STRING2_TOO_SMALL and STRING2_TOO_SMALL respectively. For all other values of POSITION, the exception POS_NOT_VALID is triggered.