ABAP/4 Programming Quickstart

Note This chapter was written to be Chapter One - "Quick-start" - of a book for
accomplished programmers who wish to transition to ABAP/4. The remainder of
the book wasn't written.

Startup
Log onto SAP. Type "SE38" into the command field as Figure 1.1 shows, and press . You
are "going into SE38", the ABAP editor.

Figure 1.1 The SAP R/3 main screen

Type in the new program name "ZHELLO1", select *Attributes then click
on [Create as Figure 1.2 illustrates. If that name is already taken, choose
another name.

Note The opening square brace on [Create is an example of the York-Mills Notation,
 which we will use throughout the book to describe your navigation through menus,
buttons and fields. See Appendix F for a complete description. In this case, the
square brace is a prefix that indicates the "Create" is a button. Similarly, "{"
indicates a menu item, "*" a radiobutton and "<" a field entry. We'll use italics for
the labels on those navigation objects.

Figure 1.2 ABAP/4 Program Development: Initial Screen

Fill in a title like "Test program for ABAP programming book". Enter "1"
in Type and "S" in Application, select Upper/lower case as you can see in
Figure 1.3 and click on "Save" (the file-folder icon on the task bar).
Select [Local private object as shown in Figure 1.4, then click on [Source
code.

Note We'll explain in later chapters all the things we're racing through so quickly here
such as values for "Type" and "Application". In this chapter we're going to just
blast ahead to demonstrate some of what you can do in ABAP/4, and how to do it.
Figure 1.3 ABAP/4: Program ZHELLO1 Attributes
 Figure 1.4 Selecting a development class

Your first program

You're now in the editor; it opens with the statement
REPORT ZHELLO1 .
The ABAP editor in Release 3.0 has three ways of presenting the code;
you select one in the menu item {Settings {Editor mode. Release 2.2
offers only the "Command Mode" presentation, so we'll assume you're
using that mode.
Type in the second line of the program:
WRITE 'Hello World'.

Note We'll create several versions of this program as we work through the chapter. You
can view each intact program when it appears in the text by clicking on the
"source code" icon
 and you can download it by right-clicking on the "disk drive" icon.

Notice the single-quote (') delimiters and the terminating period. Save
your work by clicking on the file-folder icon on the task bar, and select
the menu items {Program {Execute, or click on [Execute, or in Release
3.0 press F8. Behold! You have followed time-honored tradition with your
first programming task, as Figure 1.5 shows.

Figure 1.5 Output of first program

This output is called a report (and often a list) in SAP. When you've tired
of admiring your success, return to the source code by pressing F3 or by
clicking on "Back" (the left-pointing green arrow icon on the task bar).

A simple two-level list

One of the unusual and powerful capabilities in SAP is to "drill-down" through data. We'll
gradually build this example to illustrate how you can write programs to drill down, and in
the process learn some of the nature and capability of ABAP/4. Add two more lines to your
program so it reads like ZHELLO2:

Save and execute it again, and it looks the same. However, if you place the cursor on "Hello
World" (or almost anywhere else on the report) and double-click or press F2, you'll see the
next level of the report as shown in Figure 1.6:

Figure 1.6 List of Continents

From here you can march back up the report levels with "Back" (the left-
pointing green arrow icon) or you can Exit all the way back to the source
code by pressing Shift-F3 or clicking on the up-pointing yellow arrow.
While you're in the list of continents, double-click on one of them. It'll
look as if nothing happened but you must go Back twice to return to the
"Hello World" level. The continents have been listed twice, and the two
lists of continents have the same contents but they are in distinct levels
of the report. R/3 will allow you to go as many as nine levels deep.
 AT LINE-SELECTION is an event in ABAP/4 that's triggered when you
"select" (double-click or F2) a line in the current report. The code block
following the event statement is executed whenever the event is
triggered. If the event's code block writes output, then it will force
another list level. ABAP/4 recognizes several events; a few of which we'll
use in this chapter.
Notice the colon (:) on the second WRITE. This allows you to follow the
keyword with any number of comma-separated parameters; each
parameter will be processed by the keyword independently. In this case,
the statement acts as three separate WRITE statements to print out the
three different strings. The forward slash forces a newline, and the
number 12 offsets the string to start in the 12th column.

Adding variables
User-variables must be declared and typed in ABAP/4. In addition to user variables, R/3
provides quite a few system variables that contain the state of the program and the report.
Rewrite your program to read like ZHELLO3:

Save and execute this version of your program and watch the list level increment as you
"Select", and decrement as you go "Back". March down to list level nine and see that
indeed, you may not go any deeper. Remember that at any level you can return immediately
to the source code with "Exit" (Shift-F3 or the Yellow arrow). "Exit" is a tricky command
however; sometimes it'll take you all the way back to the SAP main screen. You have a new
way to climb back out by selecting (double-clicking) on the line that reads "Return". Figure
1.7 shows the list of continents selected while you're already in the ninth level.
 Figure 1.7 Lists are limited to nine levels
The DATA statement declares variables and establishes their types. The
default type is C (Character), so it is optional for string variables. The
variable's length is specified in the parentheses immediately following
the variable name. You can optionally assign an initial value to the
variable at declaration.
SY-xxxxx is the naming convention for system variables; SY-LSIND
contains the current list index (level); we added it so you can see where
you are. SY-LISEL contains the list selection (the contents of the line you
selected), so the program can test where it is. SET USER-COMMAND
simulates in code a user action, in this case the "Back"(F3 or green-
arrow) command. SKIP, of course, skips a line on the screen.

Note The system variables are often mnemonic. SY-LISEL is mnemonic for LIne
SELection. SY-SUBRC for SUBroutine Return Code. Most of these mnemonics
are in English and contrast with the mnemonics for data fields that are mostly in
German.
Notice that every command is terminated by a period (even ELSE!), that
a command can span multiple lines (DATA and the second WRITE), and
that a line can contain more than one command (SKIP...). ABAP/4 is case-
insensitive except in some string comparisons, so keywords can be
upper, lower or proper (mixed) case as you choose. We like UPPER
keywords, lower variable and table names, and Proper Subroutine and
Function Module names. White space (spaces, tabs, newlines) count for
very little in ABAP/4. We like to indent structured commands and leave
blank lines to make code easier to read. You can insert comment lines by
placing an asterisk (*) in the first column, and in-line comments with the
double-quote ("); comments are terminated by a newline.

Note The only virtue that we know of for using the asterisk is that the system editors
highlight asterisk-indicated comment lines in red. You can use the double quote as
your sole comment indicator, thereby simplifying your life.

Using internal tables

One data structure you can declare is the internal table (itab) which exists only while this
program runs. Once again, import or rewrite your program to read like ZHELLO4:

Save and execute it again, and now you have a third defined list level: some of the nations
in the selected continent as you see in Figure 1.8. The content of the third level depends on
what you selected at the second level. Neat! Also, the program no longer continues to
deeper levels; it stops where it's "supposed to".
 Figure 1.8 Output showing list of countries
The BEGIN OF... END OF... construction creates a "structure" - a complex
data type that may contain several fields. Adding the OCCURS... option
expands that structure into an internal table. The OCCURS value should
be somewhat near the number of records you expect, but the program
will work fine with zero or a very large number; a larger or smaller
number of records affects processing speed and memory utilization, but
will work regardless. You refer to fields in a table using the format
tablename-fieldname.

Note The hyphen is commonly used to qualify field names to tables, similar to the
period in many other languages. It is a legal character in field names, but we like
to avoid them so that any hyphenated string obviously refers to a table or structure
field.

The BEGIN OF...OCCURS...END OF... commands not only create itabs, but
also create separate "header lines" or "work areas" that have the same
structure as the itab and HAVE THE SAME NAME! Many commands, such
as the assignments, actually affect only the header line. The information
doesn't get into the itab until you APPEND the header line to the itab. It'll
take you a while to get used to this: when you see a table name, it may
refer to the table or to its header line.
LOOP AT itabname loops through the named itab from the first record to
the last, executing for each record the commands between the LOOP
and ENDLOOP statements. At each iteration, the LOOP command
populates the header line with the values in that itab record, so the
WRITE statements are actually writing the contents of the header line,
not the itab entry.
The CASE statement compares the variable in the first line to the values
(variable or literal) in the following WHEN statements. It executes the
commands starting at the first matching WHEN and stopping at the next
WHEN or the ENDCASE. Finally, it will execute the commands following
WHEN OTHERS if no other WHEN matches.

FORM subroutines
As the program gets longer and does more things, it's harder to follow. Sometimes we need
to have the program do the same thing in several places. We make the program flow easier
to follow and eliminate duplicate code by moving blocks into subroutines which the
program calls as needed. One type of subroutine in ABAP/4 is the FORM, which is called
with the PERFORM command. Import or rewrite your program to read like ZHELLO5:

Save and execute it yet again, and you see that we have a fourth level which shows the
capital city of the country you've selected, shown in Figure 1.9. The "Return" button is now
a little more prominent and has a permanent location on the screen. Other than that, the
output doesn't look any different. The code has changed a lot though.
 Figure 1.9 Output showing selected Capital city
We've added the event START-OF-SELECTION which is triggered after
the program is initialized, so it contains essentially the "main program".
The code block for any event is terminated by the next event statement
(in this case, the AT LINE-SELECTION statement), by the first FORM
definition, or by the end of the program. In this version, the main
program consists of calling the FORM (subroutine) "build_loc", then
calling "level0". It's easier to follow when logical blocks are defined
elsewhere, named sensibly, and simply called in order. Since we need
the return button in several places, it's a natural for a subroutine.

Note ABAP/4 event blocks may appear in any order within a program. An event block
is terminated by the start of the next event block, the first FORM definition or the
end of the program. However, it is good programming practice to standardize on
an ordering. We follow the ordering shown in Appendix E.
Since we've seen enough of the list levels, we removed them from the
screens.
The new "Return" function is truly a button now, not just a line in the
report. The command GET CURSOR FIELD returns the name of the field
you selected. We wanted a big button, and the ability to select anywhere
on it, so we used one variable to paint its top and bottom lines and a
second variable to paint its label and ends; the variables are called
ret_button1 and ret_button2. The comparison operator CS returns TRUE
if cfield ContainsString 'ret_button', so the IF statement is satisfied if
either variable is selected.
The CASE statement is easier to read when each branch simply calls a
subroutine rather than containing all the code. We've removed the
WHEN OTHERS option because we don't want anything to happen if the
user double-clicks in level 4 or below. The "Return" button or "Back" are
the only ways out of that level.
The FORM definition for build_loc illustrates again the distinction
between an itab and its header line. The subfields in the header line are
independent, so the value of "continent" remains the same until you
assign another string to it. Again, you are assigning values to the header
line; only with APPEND do they appear in the itab.
Now that we have one flat table, we must write list level 1 in a new way.
We don't have a simple table of continents, and we don't want "North
America" to appear three times in the list. AT NEW fieldname is a
conditional statement that's true every time the value of fieldname
changes, as well as in the first record if it differs from the header line.
We CLEAR the header line so we know it will not be the same as record
one at the start, then LOOP.
Note This technique works only when the table is sorted by continent. Because we built
the table this way, though, we know that it will work here. If the internal table is
built from a non-sorted source, it must be sorted before using LOOP AT and AT
NEW in this way.

To write list level 2 from our single flat table, we need to select those
records whose continents match the one you chose in level 1. The
WHERE option (optional command clauses are called "additions" in SAP-
talk) will limit the execution of the code block to those records that
match the WHERE condition, in this case those records for which the
value of loc-continent equals the contents of "sel_cont". We assign to
sel_cont the value of SY-LISEL (the selected line, remember), offset by 11
characters. In other words, sel_cont equals the selected line, starting at
the 12th character; since we wrote the continent to the screen starting
in column 12, sel_cont now contains the continent without any leading
spaces.
In addition to writing names of countries in the selected continent, we're
also using HIDE to store their capital city names. Hidden fields aren't
visible, but they are associated with the current line. When a line is
selected the hidden field values are assigned to their header line fields,
so we can use that information for later displays or tests.
List level 3 differs from the others; it writes a single text statement
based on your earlier choices. We must assemble the string to write
because R/3 writes the full declared width of the text field, regardless of
the length of its contents, and we want a nice-looking sentence. We
must concatenate some literal strings and some variables, most
separated by spaces, and one (the terminating period) with no leading
space. Release 3.0 has a CONCATENATE command that can do it all, but
Release 2.2 does not, so we'll do this the old way.
First we stick a period on the end of the capital city name using the
function STRING_CONCATENATE. A function is a library subroutine
accessible from any program. Our program "exports" parameters to the
function and "imports" return values from it; the function also returns the
listed error codes if appropriate in the system variable SY-SUBRC
(SUBroutine Return Code). Then we start building our string with the
start of the sentence "The capital of ". We assign to the string, starting
at offset 18, the contents of the selected line, starting at its offset 14.
Then we add " is " at offset 38 and the capital name-plus-period at offset
42. Since we don't know how long the country or capital names are, we
assemble them with lots of room, then CONDENSE the entire string; that
command shifts all the substrings leftwards until they are each
separated by one space. Now we can write it out.

Tuning up the report

Now that we're approaching a useful report, let's add some color and clean up some loose
ends. We will:

Use cfield to require selecting the "Hello World" string itself to go to the second
level.
Reset cfield and the loc header line after we create each screen so old values can't
confuse us.
Write headers on each list, and paint the "Return" button as part of the page setup.
HIDE the continents in the level 1 list, and test for them in level 2. That way you
write the next level only when you select a valid line on the screen.
HIDE the nation's name in level 2 so we don't have to extract it from a substring of
SY-LISEL in level 3.
Only write out level 3 if we selected a valid screen line in level 2.
Write the "Return" button and "The capital of..." in colors.

Here's ZHELLO6:
Save and execute this version and select all over the screens; it now responds only when it
makes sense. The colored "Return" button is more obvious, and the colored level-3
statement clearly differs from the other lists.
The TOP-OF-PAGE events are triggered whenever R/3 automatically
generates a new page. The first one only works on level 0 screens, and
the DURING LINE-SELECTION version works on all the other levels.
We discussed the return_button earlier, but we want to point out one
more thing in its FORM definition. List level zero, the first output screen,
includes a couple of title lines that don't show up on lower (or is that
higher?) levels. So we restore the cursor to line five after painting the
button if we're in level zero, and to line three in any other level.
Subsequent writing will start on the line we move it to.
We like to use "IF cfield CS 'greeting'" instead of "IF cfield = 'greeting'"
because R/3 returns the field name capitalized, and we like to keep our
lower-case convention for the variable name. The CS operator is case-
insensitive, whereas the equality operator is case-sensitive.
The condition IS INITIAL is true if the variable is reset (in its initial state).
The initial state for character type variables is a space; that is, a reset
character variable contains one space.
Valid color numbers and the colors they display in a typical SAP
installation are shown in Table 1-1.
Table 1-1 Valid Color Numbers

1. Gray-blue
2. Bright gray
3. Yellow (Yellow)
4. Blue-green
5. Green
6. Red
7. Violet

User's initial choices

We can offer the user choices that affect how the program runs; inviting (or requiring) him
or her to enter a single value or a range or list of values. We can also send out error
messages if the user fails to properly complete the choices.
Reports in R/3 consist of quite a bit more than their code. So far the
examples have been limited to code; this time we'll use some of the
other capabilities. And we'll look at our first database table.
The final version of our sample program is ZHELLO7:

Before you execute it, you must provide the content of TEXT-001 that we
specified in the SELECTION-SCREEN COMMENT line near the beginning of
the program. Double-click on the "TEXT-001", select [Yes to create it as
shown in Figure 1.10, then type in the label "Color for Capital city display
(1-7)" as shown in Figure 1.11. Save it and go back (green arrow) to the
source code. This text element is the first example of a program element
that is somewhere other than in the code. It's stored in a table
associated with the program. You could also have gotten to the table
using the path {Goto {Text elements *Numbered texts [Edit.

Figure 1.10 Dialog box to create a Text element

 Figure 1.11 Maintaining Text elements
SAP stores most system data, owner's "Master" (lookup) data and
business transaction data in database tables. The TABLES statement
hooks in the named tables, making them available to the program, and
creates a header line for each. In this example, T005T is SAP's table of
country codes, their names and what we call their citizens. Double-click
on the "T005T' in the TABLES statement. You'll see a brief description of
the table and a list of its fields with their descriptions as shown in Figure
1.12. This illustrates the amazingly integrated nature of R/3: everything
seems to connect to everything else, and you can drill down to get there
from almost anywhere. "Green arrow" back to the source code.
 Figure 1.12 Table and Fields of T005T
Save and execute this last version and see the selection screen shown
in Figure 1.13. Click on [Execute or press F8. R/3 returns the cursor to
the empty Color parameter field and sends you a message that you
must enter a valid number. Type in a number between 1 and 7 then
[Execute again. This time it places the cursor in the first "s_land1" field
(whatever that is) and insists you enter a country code. Type in "a*" in
the first field and [Execute again. Now you're in familiar territory. Try the
"Country list" choice in level 1 and see what happens. You see every
country in the SAP database whose code matches your "s_land1"
choices; and you can drill down to see what that country's residents are
called.
 Figure 1.13 Initial selection screen
We placed the range selection option on the entry screen with the
SELECT-OPTIONS command. It expects you to enter a single value or a
wildcard pattern in the "From" field, or the beginning and ending values
of one or more ranges in the "From" and "To" fields. You can look up
possible values for those fields: press F4 or click on the down-pointing
arrow at the right of the field when the cursor is in the field. Choose [No,
you don't want more selection criteria as shown in Figure 1.14, to see
the list shown in Figure 1.15. In this case, the values are country codes
found in the T005T table.
Figure 1.14 "Restrict values ranges" dialog box
 Figure 1.15 "Possible values" pull-down list
If you click on the right-pointing arrow to the right of the "To" field, a
new screen appears in which you can enter as many ranges as you
need, as shown in Figure 1.16.
 Figure 1.16 Multiple-ranges selection screen
The "s_land1" label on the selection screen doesn't mean anything to
the user (and is pretty ugly), so let's change it. That label is another text
element. You reach that one by {Goto {Text elements *Selection texts
[Edit to see the table shown in Figure 1.17. In the "s_land1" record, you
can change the second field from "?...(S_LAND1)" to whatever you want
that will fit. In our example, we'll use " Range of Countries." Tinker with
the leading spaces to align it with the "Color for Capital city display (1-
7)" label as shown in Figure 1.18.
Figure 1.17 Maintaining Selection texts
 Figure 1.18 Improved Selection screen
The various SELECTION-SCREEN commands place text on the screen.
User choices are invoked by the PARAMETERS (single-value) and SELECT-
OPTIONS (ranges) commands. The PARAMETERS label would have been
determined by the selection text elements like the SELECT-OPTIONS was
if we hadn't painted a COMMENT on the same screen line.
We've added two new events to filter the screen entries. AT SELECTION-
SCREEN ON color and AT SELECTION-SCREEN ON s_land1 are triggered
when you [Execute out of the selection screen. In these cases, we just
test for valid entries. A type "E" (error) message tells R/3 to return to the
selection screen with the cursor in the subject field, and to display the
message (number 208 in this case) from the message set 00 (notice the
MESSAGE-ID 00 option in the REPORT ZHELLO7 line). Double-click on the
"00" in the top line and select [Messages to see all the messages
available in that set as shown in Figure 1.19. Message 208 is simply "&"
which R/3 expands into the contents of the WITH option. If neither IF is
satisfied, then the selection screen is accepted and the program
proceeds.
 Figure 1.19 List of messages in set 00
We extract selected records from database tables using the SQL-like
SELECT command. The selection conditions we chose are (1) the
language (Spras from the German Sprache) is the same as the user's
login language, and (2) the country code (Land1; Land is German for
country, nation or state) is in the list you selected at the selection
screen. All the commands between SELECT and ENDSELECT will be
processed for each selected record.
And finally, the string 'We don''t know about the people from ' shows
how to include an apostrophe in a string, and USING string2 shows how
to pass parameters to the color_write subroutine.

Summary
We have developed an example of interactive list processing in ABAP/4 from the classic,
very simple "Hello World" to a rather complete multi-level illustration of the "drill-down"
capability. We showed the use of several of the commands available in ABAP/4, and
glimpsed a couple areas beyond the code that contain program elements.
The remainder of this book will expand on every command shown and
every point illustrated in this example. We'll explain a lot of things that
we touched lightly or just leaped over in this chapter, and we'll provide
examples of the other two main uses of ABAP/4 in an R/3 installation:
creating batch data communications (BDC's), and creating reports.