The Parameter Interface
The USING and CHANGING additions in the FORMstatement define the formal parameters of a subroutine. The sequence of the additions is fixed. Each addition can be followed by a list of any number of formal parameters. When you call a subroutine, you must fill all formal parameters with the values from the actual parameters. At the end of the subroutine, the formal parameters are passed back to the corresponding actual parameters.
Within a subroutine, formal parameters behave like dynamic local data. You can use them in the same way as normal local data objects that you would declare with the DATA statement. They mask global data objects with the same name. The value of the parameters at the start of the subroutine is the value passed from the corresponding actual parameter.
Subroutines can have the following formal parameters:
You list these parameters after USING or CHANGING without the VALUEaddition:
FORM subr USING p1 [{TYPE type}|{LIKE field}]
p2 [{TYPE type}|{LIKE field}]
... CHANGING p1 [{TYPE type}|{LIKE field}]
p2 [{TYPE type}|{LIKE field}]
...
The formal parameter has no memory of its own. During a subroutine call, only the address of the actual parameter is transferred to the formal parameter. The subroutine works with the field from the calling program. If the value of the formal parameter changes, the contents of the actual parameter in the calling program also change.
For calling by reference, USING and CHANGING are equivalent. For documentation purposes, you should use USING for input parameters which are not changed in the subroutine, and CHANGING for output parameters which are changed in the subroutine.
To avoid the value of an actual parameter being changed automatically, you must pass it by value.
You list these parameters after USING with the VALUEaddition:
FORM subr USING VALUE(p1) [{TYPE type}|{LIKE field}]
VALUE(p2) [{TYPE type}|{LIKE field}]
...
The formal parameter occupies its own memory space. When you call the subroutine, the value of the actual parameter is passed to the formal parameter. If the value of the formal parameter changes, this has no effect on the actual parameter.
You list these parameters after CHANGING with the VALUEaddition:
FORM subr CHANGING VALUE(p1) [{TYPE type}|{LIKE field}]
VALUE(p2) [{TYPE type}|{LIKE field}]
...
The formal parameter occupies its own memory space. When you call the subroutine, the value of the actual parameter is passed to the formal parameter. If the subroutine concludes successfully, that is, when the ENDFORM statement occurs, or when the subroutine is terminated through a CHECK or EXITstatement, the current value of the formal parameter is copied into the actual parameter.
If the subroutine terminates prematurely due to an error message, no value is passed. It only makes sense to terminate a subroutine through an error message in the PAI processing of a screen, that is, in a PAI module, in the AT SELECTION-SCREEN event, or after an interactive list event.
Formal parameters can have any valid ABAP data type. You can specify the type of a formal parameter using the TYPE or LIKEaddition. You can specify the type either generically or in full. If you specify a generic type, the type of the formal parameter is either partially specified or not specified at all. Any attributes that are not specified are inherited from the corresponding actual parameter when the subroutine is called. If you specify the type fully, all of the technical attributes of the formal parameter are defined with the subroutine definition.
The following remarks about specifying the types of parameters also apply to the parameters of other procedures (function modules and methods).
If you have specified the type of the formal parameters, the system checks that the corresponding actual parameters are compatible when the subroutine is called. For internal subroutines, the system checks this in the syntax check. For external subroutines, the check cannot occur until runtime.
By specifying the type, you ensure that a subroutine always works with the correct data type. Generic formal parameters allow a large degree of freedom when you call subroutines, since you can pass data of any type. This restricts accordingly the options for processing data in the subroutine, since the operations must be valid for all data types. For example, assigning one data object to another may not even be possible for all data types. If you specify the types of subroutine parameters, you can perform a much wider range of operations, since only the data appropriate to those operations can be passed in the call. If you want to process structured data objects component by component in a subroutine, you must specify the type of the parameter.
You can specify the type of formal parameters either generically or in full.
Generic Type Specification
When the type is specified generically, one of the generic data types listed in the keyword documentation, such as any, c, numeric, or index table, is specified. The actual parameter need only have the selection of attributes possessed by the formal parameter. The formal parameter adopts its remaining unnamed attributes from the actual parameter.
Note that formal parameters inherit the attributes of their corresponding actual parameters dynamically at runtime, and so they cannot be identified in the program code. For example, you cannot address an inherited table key statically in a subroutine, but you probably can dynamically.
TYPES: BEGIN OF line, col1(1) TYPE c, col2(1) TYPE c, END OF line.
DATA: wa TYPE line, itab TYPE HASHED TABLE OF line WITH UNIQUE KEY col1, key(4) TYPE c VALUE 'col1'.
wa-col1 = 'X'.INSERT wa INTO TABLE itab.wa-col1 = 'Y'. INSERT wa INTO TABLE itab.
PERFORM demo USING itab.
FORM demo USING p TYPE ANY TABLE. ... READ TABLE p WITH TABLE KEY (key) = 'X' INTO wa. ...ENDFORM.
The table key is addressed dynamically in the subroutine. However, the static address
READ TABLE p WITH TABLE KEY col1 = 'X' INTO wa.
is syntactically incorrect, since the formal parameter P does not adopt the key of table itab until runtime.
Specifying the Type Fully
When you use the following type assignments, the technical attributes of the formal parameters are fully specified. After TYPE, you can specify any non-generic data type from the ABAP Dictionary, a non-generic local type already defined with TYPES, or a non-generic built-in ABAP type (d, f, i, string, t, xstring) When you specify a previously declared data object dobj after LIKE, you are also specifying the type in full.
The technical attributes of the actual parameter must match the attributes of the formal parameter.
When you use a formal parameter that is fully typed, you can address its attributes statically in the program, since they are recognized in the source code.
Since formal parameters can take any valid ABAP data type, they can also take structures and internal tables with a structured line type, as long as the type of the formal parameter is fully specified. You can address the components of the structure statically in the subroutine.
Generic structures
If you pass a structured actual parameter generically to a formal parameter whose type is not correctly specified, you cannot address the components of the structure statically in the subroutine. For internal tables, this means that only line operations are possible.
To access the components of a generically passed structure, you must use field symbols, and the assignment
ASSIGN COMPONENT idx|name OF STRUCTURE s TO <fs>.
idx is interpreted as the component number and the contents of name are interpreted as a component name in the generic structure s.
REPORT demo_mod_tech_assign_component.
DATA: BEGIN OF line, col1 TYPE c VALUE 'X', col2 TYPE c VALUE 'Y', END OF line.
DATA comp(4) TYPE c VALUE 'COL1'.
PERFORM demo USING line.
FORM demo USING p TYPE any. FIELD-SYMBOLS <fs> TYPE ANY. ASSIGN COMPONENT comp OF STRUCTURE p TO <fs>. WRITE <fs>. ASSIGN COMPONENT 2 OF STRUCTURE p TO <fs>. WRITE <fs>.ENDFORM.
The list output is:
X Y
The components col1 and col2 of the structure of p (passed generically) are assigned to the field symbol <fs>. You cannot address the components directly either statically or dynamically.
Fitting Parameters into Structures
Instead of using TYPE or LIKE, for reasons of compatibility you can also specify the type of a structure as follows:
... p 1 [STRUCTURE s] ...
... p 2 [STRUCTURE s] ...
where s is a local structure in the program (data object, not a type) or a flat structure from the ABAP Dictionary. The appropriate formal parameter p 1 p 2 … is structured according to s, and you can address its individual components in the subroutine. When the actual parameter is passed, the system only checks to ensure that the actual parameter is at least as long as the structure. STRUCTUREtherefore allows you to force a structured view of any actual parameter.
REPORT demo_mod_tech_structure.
DATA: BEGIN OF line, col1(1) TYPE c, col2(1) TYPE c, END OF line.
DATA text(2) TYPE c VALUE 'XY'.
PERFORM demo USING text.
FORM demo USING p STRUCTURE text. WRITE: p-col1, p-col2.ENDFORM.
The list output is:
X Y
The string text is fitted into the structure line.
To ensure compatibility with previous releases, the following addition is still allowed before the USING and CHANGINGadditions:
FORM subr TABLES ... itab 1 [TYPE t|LIKE f] ...
... itab 2 [TYPE t|LIKE f] ...
The formal parameters itab 1 itab 2 … are defined as standard internal tables with header lines. If you use an internal table without header line as the corresponding actual parameter for a formal parameter of this type, the system creates a local header line in the subroutine for the formal parameter. If you pass an internal table with a header line, the table body and the table work area are passed to the subroutine. Formal parameters defined using TABLES cannot be passed by reference. If you want to address the components of structured lines, you must specify the type of the TABLES parameter accordingly.
From Release 3.0, you should use USING or CHANGING instead of the TABLESaddition for internal tables, although for performance reasons, you should not pass them by value.