December 1999 487
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.
Test in Function Builder
Import parameters
Export parameters
Exceptions Function module
For more information about this, refer to Testing Function Modules [Extern] 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 = 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 <module> either as a literal or a variable. Each interface parameter <fi> is explicitly assigned to an actual parameter <ai>. You can assign a return value <ri> to each exception <ei>. 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.
Calling Function Modules
• 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 <ei> 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 <ei> is specified in the EXCEPTION option, the calling program handles the exception by assigning <ri> to SY-SUBRC. <ri> 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:
• 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 <ri> for several exceptions.
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.
Calling Function Modules
December 1999 489
CALL FUNCTION 'STRING_SPLIT_AT_POSITION' EXPORTING
STRING =
POS =
* LANGU = SY-LANGU
* IMPORTING
* STRING1 =
* STRING2 =
* POS_NEW =
EXCEPTIONS
STRING1_TOO_SMALL = 1 STRING2_TOO_SMALL = 2 POS_NOT_VALID = 3
OTHERS = 4.
IF SY-SUBRC <> 0.
* MESSAGE ID SY-MSGID TYPE SY-MSGTY NUMBER SY-MSGNO
* WITH SY-MSGV1 SY-MSGV2 SY-MSGV3 SY-MSGV4.
ENDIF.
STRING_SPLIT_AT_POSITION CALL FUNCTION
Insert Statement Insert Statement
Add values to actual parameters
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:
• 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
Calling Function Modules
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 STRING2 have the generic type C. The actual parameter must also have type C, but the length does not matter.
• POS and POS_NEW have the fully-specified type I. The actual parameter must also have type I.
• LANGU also 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:
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.
Calling Function Modules
December 1999 491