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

Gray-blue
Bright gray
Yellow (Yellow)
Blue-green
Green
Red
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.