Search on this Website

Saturday, February 16, 2008

Using the raise Statement in Function Module

Normally, after returning from a function module, the system automatically sets the value of sy-subrc to zero. Use one of the following two statements to set sy-subrc to a non-zero value:

* raise
* message ... raising

Using the raise Statement

Use the raise statement to exit the function module and set the value of sy-subrc on return.
Syntax for the raise Statement

The following is the syntax for the raise statement.

raise xname.


* xname is the name of the exception to be raised.

The following points apply:

* xname can be any name that you make up. It does not have to be previously defined anywhere. It can be up to 30 characters in length. All characters are allowed except " ' . , and :.
* Do not enclose xname within quotes.
* xname cannot be a variable.

When the raise statement is executed, control returns immediately to the call function statement and a value is assigned to sy-subrc based on the exceptions you have listed there. Values assigned to export parameters are not copied back to the calling program. Listings 1.7 and 1.8 and Figure 1.9 illustrate how this happens.

Listing 1.7 How to Set the Value of SY-SUBRC from Within a Function Module

1 report ztx2007.
2 parameters parm_in default 'A'.
3 data vout(4) value 'INIT'.
4 call function 'Z_TX_2008'
5 exporting
6 exname = parm_in
7 importing
8 pout = vout
9 exceptions
10 error_a = 1
11 error_b = 4
12 error_c = 4
13 others = 99.
14 write: / 'sy-subrc =', sy-subrc,
15 / 'vout =', vout.

Listing 1.8 This Is the Function Module Called from Listing 1.7

1 function z_tx_2008.
2 *"------------------------------------------------------------
3 *"*"Local interface:
9 *" ERROR_A
10 *" ERROR_B
11 *" ERROR_C
12 *" ERROR_X
13 *"------------------------------------------------------------
14 pout = 'XXX'.
15 case exname.
16 when 'A'. raise error_a.
17 when 'B'. raise error_b.
18 when 'C'. raise error_c.
19 when 'X'. raise error_x.
20 endcase.
21 endfunction.

The code in Listings 1.7 and 1.8 produce this output, if you specify a value of A for parm_in:

sy-subrc = 1
vout = INIT

* In Listing 1.7, line 4 takes the value from parm_in and passes it to the function module z_tx_2007. Control transfers to line 1 of Listing 1.8.
* In Listing 1.8, line 14 assigns a value to the pout parameter. This parameter is passed by value, so the change is only to the local definition of pout. The original has not yet been modified.
* In Listing 1.8, line 15 examines the value passed via parameter exname. The value is B, so line 17-raise error_b-is executed. Control transfers to line 9 of Listing 1.7. Because the raise statement has been executed, the value of pout is not copied back to the calling program, thus the value of vout will be unchanged.
* In Listing 1.7, the system scans lines 10 through 13 until it finds a match for the exception named by the just-executed raise statement. In this case, it's looking for error_b. Line 11 matches.
* On line 11, the value on the right-hand side of the equals operator is assigned to sy-subrc. Control then transfers to line 20.

The special name others on line 13 of Listing 1.7 will match all exceptions not explicitly named on the exceptions addition. For example, if line 7 of Listing 20.8 were executed, exception error_x would be raised. This exception is not named in Listing 1.7, so others will match and the value of sy-subrc will be set to 99. You can code any numbers you want for exception return codes.

If an export parameter is passed by value, after a raise its value remains unchanged in the calling program even if a value was assigned within the function module before the raise statement was executed. If the parameter was passed by reference, it will be changed in the caller (it has the Reference flag turned on in the Export/Import Parameters screen). This effect is shown in Listing 20.7. The value of pout is changed in the function module and, if a raise statement is executed, the changed value is not copied back into the calling program.

No comments: