Entering content frame

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 Structure linkFinding 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. Therefore, there is a function group SAPLCSTR that contains these function modules. If you select a function module, you can display its attributes in the Function Builder.

Important attributes:

        Documentation

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 the input and output parameters of the function module, and which errors it handles.

        Interface parameters and exceptions

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

         IMPORTparameters. These must be supplied with data when you call the function module, unless they are flagged as optional. You cannot change them in the function module.

         EXPORTparameters. These pass data from the function module back to the calling program. EXPORT parameters are always optional. You do not have to receive them in your program.

         CHANGING parameters. These must be supplied with data when you call the function module, unless they are flagged as optional. They can be changed in the function module. The changed values are then returned to the calling program.

         Tables parameters. You use these to pass internal tables. They are treated like CHANGING parameters. However, you can also pass internal tables with other parameters if you specify the parameter type appropriately.

The interface parameters can be typed. You can do so 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 Structure linkTesting Function Modules  in the ABAP Workbench documentation.

Calling Function Modules in ABAP

To call a function module, use the CALL FUNCTIONstatement:

CALL FUNCTION module
     [EXPORTING  f1 = a1 ... fn = an]
     [IMPORTING  f1 = a1 ... fn = an]
     [CHANGING   f1 = a1 ... fn = an]
     [TABLES     f1 = a1 ... fn = an]
     [EXCEPTIONS e1 = r1 ... en = rn [ERROR_MESSAGE = rE]
                                    [OTHERS = ro]].

You can specify the name of the function module moduleeither as a literal or a variable. An actual parameter a1, a2 … is explicitly assigned to every interface parameter f1, f2 … used. A return value r1, r2 … can be assigned to each exception e1, e2 … The assignment always takes the form interface parameter = actual parameter. The equals sign (=) is not an assignment operator in this context.

        After EXPORTING, you must supply all non-optional import parameters with values appropriate to their type. You can supply values to optional import parameters if you wish.

        After IMPORTING, you can receive the export parameters from the function module by assigning them to variables of the appropriate type.

        After CHANGING or TABLES, you must supply values to all of the non-optional CHANGING or tables parameters. When the function module has finished running, the changed values are passed back to the actual parameters. You can supply values to optional CHANGING or tables parameters if you wish.

You can use the EXCEPTIONS option to handle the exceptions of the function module. If an exception e1, e2 … 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 e1, e2 … is specified after the option EXCEPTION, the calling program handles the exception by assigning the value r1, r2 … to sy-subrc. You must specify r1, r2 … as 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....RAISINGstatement. With ERROR_MESSAGE you can force the system to treat messages that are called without the RAISING option in a function module as follows:

        Messages of classes S, I, and W are ignored (but written to the log in a background job).

        Messages of classes E and A stop the function module as if the exception ERROR_MESSAGE had occurred (sy-subrc is set to rE).

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 r1, r2 … 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 POSare 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:

         Message class sy-msgid

         Message type sy-msgty

         Message number sy-msgno

         sy-msgv1 to sy-msgv4 (contents of fields f1 to f4, included in a message).

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

         STRING, STRING1, and STRING2have the generic type c. The actual parameter must also have type c, but the length does not matter.

         POSand POS_NEW have the fully-specified type i. The actual parameter must also have type i.

         LANGUalso has a fully-defined type, since it is defined with reference to the ABAP Dictionary field SY-LANGU. The actual parameter must have the same type.

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

REPORT demo_mod_tech_fb_string_split.

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 into two output fields at a specified position. If the content of position is in the interval [4,6], the function module is executed without any exceptions being raised. For the intervals [1,3] and [7,9], the system triggers the exceptions string1_too_small and string2_too_small respectively. For all other values of position, the exception pos_not_valid is triggered.

 

Leaving content frame