Include programs and Macros in SAP ABAP
Include Programs Locate the document in its SAP Library structure
Include programs are global R/3 Repository objects. They are solely for modularizing source code, and have no parameter interface.
They have the following functions:
Library: Include programs allow you to use the same source code in different programs. For example, this can be useful if you have lengthy data declarations that you want to use in different programs.
Order. Include programs allow you to manage complex programs in an orderly way. Function groups and module pools use include programs to store parts of the program that belong together. The ABAP Workbench supports you extensively when you create such complex programs by creating the include programs automatically and by assigning them unique names. A special include is the TOP include of a program. If you name it according to the naming convention, it is always included in program navigation and in the syntax check.
Creating Your Own Include Programs
If you create an include program yourself, you must assign it the type I in its program attributes. You can also create or change an include program by double-clicking on the name of the program after the INCLUDE statement in your ABAP program. If the program exists, the ABAP Workbench navigates to it. If it does not exist, the system creates it for you.
An include program cannot run independently, but must be built into other programs. Include programs can contain other includes.
The only restrictions for writing the source code of include programs are:
Include programs cannot call themselves.
Include programs must contain complete statements.
You must ensure that the statements of your include program fit logically into the source code of the programs from which it is called. Choosing Check while editing an include program in the ABAP Editor is normally not sufficient for this.
Example
***INCLUDE INCL_TST.
TEXT = 'Hello!'.
Here, the syntax check reports an error because the field TEXT is not declared. However, you can include INCL_TST in any program in which a field called TEXT with the correct type has been declared.
For the syntax check to produce valid results, you must check the program in which the include occurs. The exception to this is the TOP include, the contents of which are always included when you check the syntax of another include.
Using Include Programs
To use an include program in another program, enter the statement
INCLUDE <incl>.
The INCLUDE statement has the same effect as copying the source code of the include program <incl> into the program. In the syntax check, the contents of the include program are also analyzed. Include programs are not loaded at runtime, but are expanded when the program is generated. Once the program has been generated, the load version contains static versions of all of its includes. If you subsequently change an include program, the programs that use it are automatically regenerated.
The INCLUDE statement must be the only statement on a line and cannot extend over several lines.
Example
Suppose we have the following program:
***INCLUDE STARTTXT.
WRITE: / 'Program started by', SY-UNAME,
/ 'on host', SY-HOST,
'date:', SY-DATUM, 'time:', SY-UZEIT.
ULINE.
We can then include this program in any other ABAP program to display a standard list header.
PROGRAM SAPMZTST.
INCLUDE STARTTXT.
............
This could produce the following output:
Program started by KELLERH
on host ds0025 date: 03/19/1998 time: 09:00:39
Macros Locate the document in its SAP Library structure
If you want to reuse the same set of statements more than once in a program, you can include them in a macro. For example, this can be useful for long calculations or complex WRITE statements. You can only use a macro within the program in which it is defined, and it can only be called in lines of the program following its definition.
The following statement block defines a macro <macro>:
DEFINE <macro>.
<statements>
END-OF-DEFINITION.
You must specify complete statements between DEFINE and END-OF-DEFINITION. These statements can contain up to nine placeholders (&1, &2, ..., &9). You must define the macro before the point in the program at which you want to use it.
Macros do not belong to the definition part of the program. This means that the DEFINE...END-OF-DEFINITION block is not interpreted before the processing blocks in the program. At the same time, however, macros are not operational statements that are executed within a processing block at runtime. When the program is generated, macro definitions are not taken into account at the point at which they are defined. For this reason, they do not appear in the overview of the structure of ABAP programs.
A macro definition inserts a form of shortcut at any point in a program and can be used at any subsequent point in the program. As the programmer, you must ensure that the macro definition occurs in the program before the macro itself is used. Particular care is required if you use both macros and include programs, since not all include programs are included in the syntax check (exception: TOP include).
To use a macro, use the following form:
<macro> [<p1> <p2> ... <p9>].
When the program is generated, the system replaces <macro> by the defined statements and each placeholder &i by the parameter <p i >. You can use macros within macros. However, a macro cannot call itself.
Include programs are global R/3 Repository objects. They are solely for modularizing source code, and have no parameter interface.
They have the following functions:
Library: Include programs allow you to use the same source code in different programs. For example, this can be useful if you have lengthy data declarations that you want to use in different programs.
Order. Include programs allow you to manage complex programs in an orderly way. Function groups and module pools use include programs to store parts of the program that belong together. The ABAP Workbench supports you extensively when you create such complex programs by creating the include programs automatically and by assigning them unique names. A special include is the TOP include of a program. If you name it according to the naming convention, it is always included in program navigation and in the syntax check.
Creating Your Own Include Programs
If you create an include program yourself, you must assign it the type I in its program attributes. You can also create or change an include program by double-clicking on the name of the program after the INCLUDE statement in your ABAP program. If the program exists, the ABAP Workbench navigates to it. If it does not exist, the system creates it for you.
An include program cannot run independently, but must be built into other programs. Include programs can contain other includes.
The only restrictions for writing the source code of include programs are:
Include programs cannot call themselves.
Include programs must contain complete statements.
You must ensure that the statements of your include program fit logically into the source code of the programs from which it is called. Choosing Check while editing an include program in the ABAP Editor is normally not sufficient for this.
Example
***INCLUDE INCL_TST.
TEXT = 'Hello!'.
Here, the syntax check reports an error because the field TEXT is not declared. However, you can include INCL_TST in any program in which a field called TEXT with the correct type has been declared.
For the syntax check to produce valid results, you must check the program in which the include occurs. The exception to this is the TOP include, the contents of which are always included when you check the syntax of another include.
Using Include Programs
To use an include program in another program, enter the statement
INCLUDE <incl>.
The INCLUDE statement has the same effect as copying the source code of the include program <incl> into the program. In the syntax check, the contents of the include program are also analyzed. Include programs are not loaded at runtime, but are expanded when the program is generated. Once the program has been generated, the load version contains static versions of all of its includes. If you subsequently change an include program, the programs that use it are automatically regenerated.
The INCLUDE statement must be the only statement on a line and cannot extend over several lines.
Example
Suppose we have the following program:
***INCLUDE STARTTXT.
WRITE: / 'Program started by', SY-UNAME,
/ 'on host', SY-HOST,
'date:', SY-DATUM, 'time:', SY-UZEIT.
ULINE.
We can then include this program in any other ABAP program to display a standard list header.
PROGRAM SAPMZTST.
INCLUDE STARTTXT.
............
This could produce the following output:
Program started by KELLERH
on host ds0025 date: 03/19/1998 time: 09:00:39
Macros Locate the document in its SAP Library structure
If you want to reuse the same set of statements more than once in a program, you can include them in a macro. For example, this can be useful for long calculations or complex WRITE statements. You can only use a macro within the program in which it is defined, and it can only be called in lines of the program following its definition.
The following statement block defines a macro <macro>:
DEFINE <macro>.
<statements>
END-OF-DEFINITION.
You must specify complete statements between DEFINE and END-OF-DEFINITION. These statements can contain up to nine placeholders (&1, &2, ..., &9). You must define the macro before the point in the program at which you want to use it.
Macros do not belong to the definition part of the program. This means that the DEFINE...END-OF-DEFINITION block is not interpreted before the processing blocks in the program. At the same time, however, macros are not operational statements that are executed within a processing block at runtime. When the program is generated, macro definitions are not taken into account at the point at which they are defined. For this reason, they do not appear in the overview of the structure of ABAP programs.
A macro definition inserts a form of shortcut at any point in a program and can be used at any subsequent point in the program. As the programmer, you must ensure that the macro definition occurs in the program before the macro itself is used. Particular care is required if you use both macros and include programs, since not all include programs are included in the syntax check (exception: TOP include).
To use a macro, use the following form:
<macro> [<p1> <p2> ... <p9>].
When the program is generated, the system replaces <macro> by the defined statements and each placeholder &i by the parameter <p i >. You can use macros within macros. However, a macro cannot call itself.
