FORM

Basic form

FORM form.

Additions

1. ... TABLES itab1 ... itabn
2. ... USING p1 ... pn
3. ... CHANGING p1 ... pn

Effect

Defines a subroutine called by PERFORM

Example


PERFORM WELCOME.

FORM WELCOME.
  WRITE / 'Hello world'.
ENDFORM.

The subroutine WELCOME called by the PERFORM statement outputs 'Hello world'

Notes

Subroutines defined by FORM can have parameters and local fields. These parameters and local fields shadow global fields. Any local fields you declare with DATA after a FORM statement are recreated and initialized for each PERFORM call. When the call has finished, the memory for local fields is released again. FORM statements are not allowed within FORM ... ENDFORM structures (i.e. no nested definitions). Nested and recursive calls are possible. The optional parameters must always be specified in the order TABLES , USING and CHANGING .

Addition 1

... TABLES itab1 ... itabn

Effect

TABLES allows you to pass internal tables with or without header lines to subroutines. For information about assigning types TABLES parameters, see Type assignment . TABLES parameters are passed by reference.

Example


DATA: BEGIN OF X.
        INCLUDE STRUCTURE SFLIGHT.
DATA:   ADDITION(8) TYPE C,
      END OF X.
...
PERFORM U USING X.
...
FORM U USING X STRUCTURE SFLIGHT.
  WRITE: X-FLDATE.
ENDFORM.

Example


TYPES: BEGIN OF FLIGHT_STRUC,
         FLCARRID LIKE SFLIGHT-CARRID,
         PRICE    LIKE  SFLIGHT-FLDATE,
       END   OF FLIGHT_STRUC.

DATA: MY_FLIGHT TYPE FLIGHT_STRUC OCCURS 0 WITH HEADER LINE,
      IBOOK1    LIKE SBOOK        OCCURS 0 WITH HEADER LINE,
      IBOOK2    LIKE IBOOK1       OCCURS 0,
      STRUC     LIKE SBOOK.

PERFORM DISPLAY TABLES MY_FLIGHT IBOOK1 IBOOK2 USING STRUC.

FORM DISPLAY TABLES P_ITAB  LIKE      MY_FLIGHT[]
                    P_BOOK1 LIKE      IBOOK1[]
                    P_BOOK2 LIKE      IBOOK2[]
             USING  P_STRU  LIKE      STRUC.
  DATA L_CARRID  LIKE P_ITAB-FLCARRID.
  ...
  WRITE: / P_STRU-CARRID, P_STRU-CONNID.
  ...
  LOOP AT P_ITAB WHERE FLCARRID = L_CARRID.
    ...
  ENDLOOP.
  ...
ENDFORM.

Addition 2

... USING p1 ... pn

Effect

Defines the formal parameters p1 ,... pn which are replaced by actual parameters when you call the subroutine.
The formal parameters p1 ,... pn can have a particular type (see Type assignment ). You can also specify the transfer type (i.e. how you want to pass them).

Note

Transfer types: USING ... p ...
Transfer is by reference. This means you can change the transferred field continually in the subroutine.
USING ... VALUE(p) ...

When you specify VALUE(...) , transfer is by value, i.e. the field contents are passed to the relevant local field. VALUES parameters thus behave in the same way as local fields.

Addition 3

... CHANGING p1 ... pn

Effect

The parameters after CHANGING can accept the same specifications as those after USING .
To link the VALUE specification with the change of a parameter value, you can use the addition CHANGING ... . Then, all the formal parameters specified by VALUE(...) are transported back to the actual parameters at the end of the subroutine (i.e. after ENDFORM ). If the subroutine is terminated by a dialog message, none of the parameters referenced by CHANGING VALUE ... changes.
Otherwise, the effect of USING and CHANGING is identical.

Example


DATA: NUMBER_1 TYPE I VALUE 1,
      NUMBER_2 TYPE I VALUE 2,
      TEXT_1(10)      VALUE 'one',
      TEXT_2(10)      VALUE 'two'.

PERFORM CONFUSE USING NUMBER_1
                      NUMBER_2
                      TEXT_1
                      NUMBER_1
                      TEXT_2.

FORM CONFUSE USING PAR_NUMBER_1 TYPE I
                   PAR_NUMBER_2 TYPE I
                   PAR_TEXT_1   TYPE C
                   VALUE(PAR_V_NUMBER_1) TYPE I
                   VALUE(PAR_V_TEXT_2) TYPE C.
  ADD 3 TO PAR_V_NUMBER_1.
  ADD 4 TO PAR_NUMBER_1.
  ADD NUMBER_1 TO PAR_NUMBER_2.
  TEXT_2 = 'three'.
  PAR_TEXT_1 = PAR_V_TEXT_2.
  PAR_V_TEXT_2 = 'four'.
ENDFORM.

Field contents after the PERFORM call:

NUMBER_1 = 5
NUMBER_2 = 7
TEXT_1 = 'two'
TEXT_2 = 'three'

Note

In subroutines, you are recommended to use the following procedure:
Pass input parameters as USING parameters and output parameters as CHANGING parameters. If in doubt, pass the parameter by VALUE . You should be particularly careful with passed SY fields. For performance reasons, data objects which contain tables should not be passed by VALUE if at all possible. You can protect TABLES parameters whose heasder lines must remain unchanged with LOCAL . STATICS allows you to create global fields with a local visibility area. In the case of local fields which are initialized on each call, you can replace DATA by STATICS . With frequently called FORM routines, this can lead to a noticeable improvement in performance. To avoid shadowing problems with parameters, you are recommended to keep to the naming convnetion for fields in subroutines. You should, for instance, always start FORM parameters with the prefix 'P_' and local fields with the prefix 'L_' .

Index
� SAP AG 1996