Start of Content Area

The Parameter Interface  Locate the document in its SAP Library structure

The USING and CHANGING additions in the FORM statement 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:

Parameters Passed by Reference

You list these parameters after USING or CHANGING without the VALUE addition:

FORM <subr> USING    ... <pi> [TYPE <t>|LIKE <f>] ...
            CHANGING ... <pi> [TYPE <t>|LIKE <f>] ...

The formal parameter occupies 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.

Input Parameters That Pass Values

You list these parameters after USING with the VALUE addition:

FORM <subr> USING    ... VALUE(<pi>) [TYPE <t>|LIKE <f>] ...

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.

Output Parameters That Pass Values

You list these parameters after CHANGING with the VALUE addition:

FORM <subr> CHANGING ... VALUE(<pi>) [TYPE <t>|LIKE <f>] ...

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 EXIT statement, 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.

Specifying the Type of Formal Parameters

Formal parameters can have any valid ABAP data type. You can specify the type of a formal parameter, either generically or fully, using the TYPE or LIKE addition. 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.

Specifying Generic Types

The following types allow you more freedom when using actual parameters. 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.

Type specification

Check for actual parameters

No type specification

TYPE ANY

The subroutine accepts actual parameters of any type. The formal parameter inherits all of the technical attributes of the actual parameter.

TYPE C, N, P, or X

The subroutine only accepts actual parameters with the type C, N, P, or X. The formal parameter inherits the field length and DECIMALS specification (for type P) from the actual parameter.

TYPE TABLE

The system checks whether the actual parameter is a standard internal table. This is a shortened form of TYPE STANDARD TABLE (see below).

TYPE ANY TABLE

The system checks whether the actual parameter is an internal table. The formal parameter inherits all of the attributes (line type, table type, key) from the actual parameter.

TYPE INDEX TABLE

The system checks whether the actual parameter is an index table (standard or sorted table). The formal parameter inherits all of the attributes (line type, table type, key) from the actual parameter.

TYPE STANDARD TABLE

The system checks whether the actual parameter is a standard internal table. The formal parameter inherits all of the attributes (line type, key) from the actual parameter.

TYPE SORTED TABLE

The system checks whether the actual parameter is a sorted table. The formal parameter inherits all of the attributes (line type, key) from the actual parameter.

TYPE HASHED TABLE

The system checks whether the actual parameter is a hashed table. The formal parameter inherits all of the attributes (line type, key) 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.

Example

TYPES: BEGIN OF LINE,
        COL1,
        COL2,
      END OF LINE.

DATA: WA TYPE LINE,
      ITAB TYPE HASHED TABLE OF LINE WITH UNIQUE KEY COL1,
      KEY(4) 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 Full Types

When you use the following types, the technical attributes of the formal parameters are fully specified. The technical attributes of the actual parameter must correspond to those of the formal parameter.

Type specification

Technical attributes of the formal parameter

TYPE D, F, I, or T

The formal parameter has the technical attributes of the predefined elementary type

TYPE <type>

The formal parameter has the type <type> This is a data type defined within the program using the TYPES statement, or a type from the ABAP Dictionary

TYPE REF TO <cif>

The formal parameter is a reference variable (ABAP Objects) for the class or interface <cif>

TYPE LINE OF <itab>

The formal parameter has the same type as a line of the internal table <itab> defined using a TYPES statement or defined in the ABAP Dictionary

LIKE <f>

The formal parameter has the same type as an internal data object <f> or structure, or a database table from the ABAP Dictionary

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.

Structured Formal Parameters

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>.

Example

DATA: BEGIN OF LINE,
        COL1 VALUE 'X',
        COL2 VALUE 'Y',
      END OF LINE.

DATA COMP(4) VALUE 'COL1'.

PERFORM DEMO USING LINE.

FORM DEMO USING P TYPE ANY.
  FIELD-SYMBOLS <FS>.
  ASSIGN COMPONENT COMP OF STRUCTURE P TO <FS>.
  WRITE <FS>.
  ASSIGN COMPONENT 2 OF STRUCTURE P TO <FS>.
  WRITE <FS>.
ENDFORM.

The 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, you can specify the type of a structure as follows:

... <pi> [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 formal parameter 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. STRUCTURE therefore allows you to force a structured view of any actual parameter.

Example

DATA: BEGIN OF LINE,
        COL1,
        COL2,
      END OF LINE.

DATA TEXT(2) VALUE 'XY'.

PERFORM DEMO USING TEXT.

FORM DEMO USING P STRUCTURE LINE.
  WRITE: P-COL1, P-COL2.
ENDFORM.

The output is:

X Y

The string TEXT is fitted into the structure LINE.

The TABLES Addition

To ensure compatibility with previous releases, the following addition is still allowed before the USING and CHANGING additions:

FORM <subr> TABLES   ... <itabi> [TYPE <t>|LIKE <f>] ...

The formal parameters <itabi> 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 TABLES addition for internal tables, although for performance reasons, you should not pass them by value.