Day 15

Formatting Techniques, Part 1

• Chapter Objectives
• Graphical Formatting with the write Statement
  • Syntax for the Graphical Additions to the write Statement
  • Using the as symbol Addition
  • Using the as icon Addition
  • Using the as line Addition
  • Displaying the Available Symbols, Icons, and line-draw Characters
• Report Formatting and Printing
  • Controlling Page Size
  • Creating Page Headers and Footers
• Summary
• Q&A
  
• Workshop
  • Quiz
  • Exercise 1

Chapter Objectives

After you have completed this chapter, you will be able to

• Use the graphical formatting options of the write statement (as symbols, icons, and lines).
• Print list output and manipulate the output on the spool.
• Create headers and footers (no standard page heading, top-of-page, end-of-page).
• Use the reserve statement to keep groups of lines together in the output list.

Graphical Formatting with the write Statement

To write simple graphics you can use the three additions shown in Table 15.1.

Syntax for the Graphical Additions to the write Statement

write n1 (a) as symbol.
         (b) as icon.
         (c) as line.

where:

• Additions (a), (b), and (c) are mutually exclusive.
• n1 is the name of a symbol, icon, or line-draw character.

Using the as symbol Addition

A symbol is a simple two-color picture of a common symbol such as a square, circle, folder, or document. Most symbols take the place of a single character in the output list, although some can take two spaces, for example, the symbol of a fist pointing left (sym_left_hand). A sample statement would be write sym_left_hand as symbol.

In order to write a symbol, you must include one of the two following statements at the top of your program:

include <symbol>.

or

include <list>.

All symbols are printable. This means that if you send your output to the printer, they will appear on paper exactly as you see them online.

The name between angle brackets is an include program. It contains a set of statements that define the names of the symbols you can use. The <symbol> include contains only the symbol definitions. The <list> include contains symbols, icons, line-draw characters, and color definitions. Listing 15.1 contains a sample program using symbols.

Listing 15.1  Display Symbols

1  report ztx1501.
2  include <symbol>.
3  tables ztxlfa1.
4  write: /  sym_plus_box as symbol, 'Vendor Master Tables',
5         /4 sym_filled_circle as symbol, 'LFA1',
6         /4 sym_filled_circle as symbol, 'LFB1',
7         /4 sym_filled_circle as symbol, 'LFC1',
8         /  sym_plus_box as symbol, 'Customer Master Tables',
9         /4 sym_filled_square as symbol, 'KNA1',
10        /4 sym_filled_square as symbol, 'KNB1',
11        /4 sym_filled_square as symbol, 'KNC1'.
12 skip.
13 uline.
14 select * up to 5 rows from ztxlfa1.
15     write: / ztxlfa1-lifnr,
16              ztxlfa1-name1,
17              sym_phone as symbol,
18              ztxlfa1-telf1.
19     endselect.

The code in Listing 15.1 produces the output shown in Figure 15.1.

Figure 15.1 : This is a sample of list output containing symbols.

• Lines 4 through 11 write out a list of hard-coded table names in bullet form.
• Lines 14 through 19 write out vendor numbers, names, and telephone numbers preceded by the telephone symbol.

Using the as icon Addition

An icon is similar to a symbol, but is a multi-colored picture that can appear in the output list. Most icons take two spaces in the output list, although a few take more. An example of a write statement that writes an icon would be write icon_led_red as icon.

To write an icon, you must include one of the two following statements at the top of your program:

include <icon>.

or

include <list>.

Not all icons are printable. The procedure to determine which ones can be printed follows later in this chapter.

Listing 15.2 writes out a few sample icons.

Listing 15.2  How to Write Icons to the List

1  report ztx1502.
2  include <icon>.
3  tables: ztxmara, ztxmgef.
4  data ico like icon_generate.
5 
6  write: / 'checkmark',   15 icon_checked as icon,
7         / 'red x',       15 icon_incomplete as icon,
8         / 'overview',    15 icon_overview as icon,
9         / 'time period', 15 icon_period as icon.
10 skip.
11 uline.
12 skip.
13 write: / 'List of Materials with Radioactive Indicators'.
14 uline.
15 select * from ztxmara.
16     clear ico.
17     if not ztxmara-stoff is initial.
18         select single * from ztxmgef where stoff = ztxmara-stoff.
19         if ztxmgef-lagkl = 7.
20             ico = icon_generate.
21             endif.
22         endif.
23     write: / ico as icon,
24              ztxmara-matnr,
25              ztxmara-mtart,
26              ztxmara-matkl,
27              ztxmara-brgew,
28              ztxmara-ntgew,
29              ztxmara-gewei.
30     endselect.

The code in Listing 15.2 produces the output shown in Figure 15.2.

Figure 15.2 : This is a sample of list output containing icons.

• Lines 6 through 9 write out a sample of four different icons.
• Line 4 defines a variable named ico to contain an icon to be written out. Any icon name can appear after like.
• Line 15 selects records from the materials table ztxmara.
• For each record, line 17 looks up the hazardous material number in ztxmgef.
• Line 19 determines if the material is radioactive. If so, the icon named icon_generate is assigned to variable ico.
• Line 23 writes the value of ico using as icon to cause the value to be interpreted as an icon. Additional fields from ztxmara are also written.

Using the as line Addition

A line-draw character is a character that can be used to draw lines on a list. You can use them to create horizontal or vertical lines, a box, a grid, or a tree-like structure.

Typically, to create a horizontal line you would use sy-uline. Simply write it out and specify the length needed. For example, to write a horizontal line beginning at position 5 for a length of 10, you would code write 5(10) sy-uline. To create a vertical line use sy-vline; for example, write: sy-vline, 'X', sy-vline would write a vertical line on either side of an X. If lines intersect in the output, the system will insert the appropriate connecting character. For example, where the edge of a horizontal line and vertical line meet, a box corner will be drawn. To provide absolute control of the line drawing there are additional line-draw characters available.

Listing 15.3  Symbols and line-draw Characters

1  report ztx1503.
2  include <list>.
3  tables: ztxlfa1, ztxlfb1, ztxlfc3.
4  data: line1 like line_horizontal_line,
5        line2 like line_horizontal_line.
6 
7  select * from ztxlfa1.
8      select single * from ztxlfb1 where lifnr = ztxlfa1-lifnr.
9      if sy-subrc = 0.
10         write: / sy-vline, sym_open_folder as symbol.
11     else.
12         write: / sy-vline, sym_folder as symbol.
13         endif.
14     write: ztxlfa1-lifnr, 30 sy-vline.
15     select * from ztxlfb1 where lifnr = ztxlfa1-lifnr.
16         select single lifnr from ztxlfb1 into (ztxlfb1-lifnr)
17                                    where lifnr = ztxlfb1-lifnr
18                                      and bukrs > ztxlfb1-bukrs.
19         if sy-subrc = 0.
20             line1 = line_left_middle_corner.
21             line2 = line_vertical_line.
22         else.
23             line1 = line_bottom_left_corner.
24             clear line2.
25             endif.
26         write: /   sy-vline,
27                  4 line1 as line,
28                    ztxlfb1-bukrs,
29                 30 sy-vline.
30         select * from ztxlfc3 where lifnr = ztxlfb1-lifnr
31                                 and bukrs = ztxlfb1-bukrs.
32             write: /   sy-vline,
33                     4  line2 as line,
34                     8  line_left_middle_corner as line,
35                        ztxlfc3-gjahr, ztxlfc3-shbkz,
36                     30 sy-vline.
37             endselect.
38         if sy-subrc = 0.
39             write 8(2) line_bottom_left_corner as line.
40             endif.
41         endselect.
42         write: /(30) sy-uline.
43     endselect.

The code in Listing 15.3 produces the output shown in Figure 15.3.

Figure 15.3 : This is a sample of list output containing line-draw characters.

• Line 2 includes the definitions for all symbols and line-draw characters so they can be used in this program.
• Line 4 defines two variables that can hold line-draw characters.
• Line 7 reads all rows from ztxlfa1.
• Line 8 reads ztxlfb1 to see if there are any child records for the current ztxlfa1 record.
• If child records exist, line 10 writes a vertical line and an open folder symbol. If none are found, a vertical line and closed folder are written.
• Line 14 writes the vendor number on the same line, and then a vertical line at position 30.
• Line 15 reads the child records from ztxlfb1.
• Line 16 performs a look-ahead to determine if this is the last child record or if there are more.
• If there are more child records, line 19 sets the line1 variable to hold a left middle corner line-draw character, and line2 to hold a vertical line. Sy-vline could have been used here instead of line_vertical_line.
• Line 26 writes out the line1 variable using the as line addition so that the value is interpreted as a line-draw character.
• Lines 30 through 37 write out the children of the current ztxlfb1 record using appropriate line-draw characters.
• Line 42 writes an underline having a length of 30 characters.

Displaying the Available Symbols, Icons, and line-draw Characters

Use steps 1 through 8 of the following procedure to display the available symbols, icons, and line-draw characters. Following all steps causes a write statement to be generated that writes the selected item to the list.

1. Begin by editing any program in the ABAP/4 Editor. You should be on the ABAP/4 Editor: Edit Program XXXXX screen.
2. Place your cursor on a blank line.
3. Click the Pattern button, or choose the menu path Edit->Insert Statement. The system displays the Insert Statement screen.
4. Select the Write radio button.
5. Click the Continue button. The system displays the Assemble a Write Statement screen.
6. Choose Symbol, Icon, or Line.
7. Place your cursor in the input field to the right of the radio button you chose.
8. Press the F4 key. The system displays a list of the available items.
9. Double-click one to choose it. You are returned to the Assemble A Write Statement screen.
10. Click the Copy button. You are returned to the ABAP/4 Editor: Edit Program XXXXX screen, and a write statement is inserted that will write the item out.

Listing 15.4   Symbols, Icons, and line-draw Characters

1  report ztx1504.
2  include <list>.           "definitions for icons, symbols + line-draw
3  tables: ztxlfa1, ztxlfc3.
4 data: it like ztxlfc3 occurs 100 with header line,
5       ico_l like icon_green_light.
6 select * from ztxlfc3 into table it.
7 sort it by lifnr bukrs gjahr shbkz.
8 loop at it.
9     if it-saldv < 1000.
10         ico_l = icon_green_light.
11     elseif it-saldv between 1000 and 3000.
12         ico_l = icon_yellow_light.
13     else.
14         ico_l = icon_red_light.
15         endif.
16     at new lifnr.
17        if sy-tabix > 1.
18            write: /5(82) sy-uline,
19                   19 line_bottom_middle_corner as line,
20                   21 line_bottom_middle_corner as line.
21            skip.
22            endif.
23        write: /5(15) sy-uline,
24               /5 sy-vline, sym_documents as symbol,
25                  it-lifnr, 19 sy-vline,
26               /5(82) sy-uline,
27               19 line_cross as line,
28               21 line_top_middle_corner as line.
29        endat.
30    write: / ico_l as icon,
31             5 sy-vline, it-bukrs, sy-vline,
32             it-gjahr, line_left_middle_corner as line no-gap,
33             it-shbkz no-gap, line_right_middle_corner as line,
34             it-saldv,
35             it-solll,
36             it-habnl, sy-vline.
37    at last.
38        write /5(84) sy-uline.
39        endat.
40    endloop.

The code in Listing 15.4 produces the output shown in Figure 15.4.

Figure 15.4 : This is a sample of list output containing symbols, icons, and line-draw characters.

Report Formatting and Printing

This section covers the following report formatting techniques:

• Controlling page size
• Report titles, headers, and footers
• Common position and formatting statements

Controlling Page Size

To control the size of the output page, use the following additions on the report statement:

• line-size
• line-count

The line-size addition controls the width of the output list; line-count controls the number of lines per page.

Syntax for the line-size and line-count Additions to the report Statement

The syntax for the line-size and line-count additions to the report statement is as follows:

report line-size i line-count j(k).

where:

• i, j, and k are numeric constants. Variables are not allowed.
• i specifies the width of the output list (in characters).
• j specifies the number of lines per page in the output list.
• k specifies the number of lines reserved for a footer at the bottom of each page.
• Do not enclose i, j, or k in quotes.

Using line-size and line-count

By default, the width of the output list is equal to the maximized window width. For example, if your window is maximized before you execute a report, the system will use that width as the output width of your program. If your window has been resized to be less than the maximum, the system will still use the maximized size. A scroll bar will appear at the bottom of the window to allow you to scroll right and see the rest of the report.

To override this behavior, specify the list output width by using line-size. Valid values are 2 through 255.

The page number is printed in the top-right corner of the list. The default number of lines per page is 60,000-the maximum allowed. You can use line-count to override this number. For example, to specify 55 lines per page, enter report line-count 55. Specifying line-count 0 means use the maximum (60,000).

The user can specify the number of lines per page that is appropriate for the printer when he or she prints the report.

line-count is not usually used with reports that are viewed online. For example, suppose R/3 incremented the page number each time you pressed the page down key. If the user generates a report, scrolls to page 3, and then resizes the window, will he still be on page 3? Obviously, the ability to resize the window makes it difficult to make rules about page numbers online. You could try making the page size equal to the window height when the report was run. But if the user resizes the window after the report has been generated, the page breaks will no longer match the window height. The user will see gaps in the output and the beginning of pages in the middle of the window. To avoid these problems in online reports, use the default value for line-count.

Listing 15.5 shows a sample program that illustrates the use of line-count and line-size.

Listing 15.5  line-count and line-size

1  report ztx1505 line-size 132 line-count 55.
2  tables ztxlfc3.
3  select * from ztxlfc3 order by lifnr bukrs gjahr shbkz.
4      on change of ztxlfc3-lifnr.
5          write / ztxlfc3-lifnr.
6          endon.
7      on change of ztxlfc3-gjahr.
8          write /10 ztxlfc3-bukrs.
9          endon.
10     write: /20 ztxlfc3-gjahr,
11                ztxlfc3-shbkz,
12                ztxlfc3-saldv,
13                ztxlfc3-solll,
14                ztxlfc3-habnl.
15     endselect.

The code in Listing 15.5 produces the output shown in Figure 15.5.

Figure 15.5 : This is the effect of the line-count addition.

• On line 1, line-size sets the number of output columns to 132. This sets a fixed number of output columns independent of the output window width. The user can use the scroll bar at the bottom of the window to view the output off to the right.
• On line 1, line-count sets the number of lines per page to 55. This causes a problem when the user scrolls down. This would not occur if the default value for line-count had been used. Another problem can occur when the user prints the list. If the printer does not print exactly 55 lines per page, the page breaks will be incorrect in the printed output. Again, by using the default line-count this problem can be avoided, because the user specifies the number of lines per page when he or she selects a printer.

Printing List Output

Start the ScreenCam "How to Print List Output" now.

To print the output from Listing 15.5, first run the report, and then follow this procedure:

1. From the output list, click the Print button on the application toolbar. If it is not available, choose the menu path System->List->Print. The Print Screen List screen will be displayed.
2. In the Output Device field, type your printer ID. You can obtain a list of all printers defined to your system by placing your cursor in this field and then pressing F4.
3. Place a tickmark in the Print Immed check box.
4. Click the Print button on the application toolbar. You are returned to the list, and the message Spool request (number nnnnn) created appears at the bottom of the window.

Default printer settings are specified in your user profile. Use the menu path System->User Profile->User Defaults to change them. These settings will be used each time you print a report.

Working with the Spool

When you click the Print button, your output is sent first to the R/3 spool, and then to the operating system's spool. If you didn't tickmark Print Immed, the list output is held in the R/3 spool-it is not sent to the operating system spool. It remains there until you delete it, or print it with the delete option turned on (the Delete After Print check box on the Print Screen List screen), or until it ages enough for a cleanup job to delete it. Cleanup jobs are scheduled by the Basis Consultant; they usually delete spool files older than 2 weeks. For the exact length of time in your shop, contact your Basis Consultant.

To view output on the spool, use the following procedure.

Start the ScreenCam "Working with the Spool" now.

1. From any screen, choose the menu path System->Services->Print Requests. The Spool: Request Screen is displayed.
2. Enter criteria to find your output. Your user Id (entered in the User Name field), Client, and a From Date are usually sufficient.
3. Press Enter. The Spool: Requests screen is displayed. It contains a list of the matching entries on the spool.
4. To display the output for one entry, place a tickmark beside it, and then click the Display button.
5. To display the output for multiple entries, place tickmarks beside Multiple Entries or use the menu path Edit->Choose All. Then click the Display button. The first entry is displayed. To view the next entry, click the Next Spool Request button on the application toolbar. To view the preview entry, click the Prev. Spool Request button.
6. To print an entry, Click the Print button.

If you didn't tickmark Delete After Print on the Print Screen List screen, the output remains in the spool. This allows you to reprint it later. This is useful if your printer has a lot of personality.

Creating Page Headers and Footers

By default, the Title from the Program Attributes screen appears as the title at the top of your report. You can create your own titles by using one of two methods:

• Standard page headers
• The top-of-page event

Creating Standard Page Headers

Using standard page headers is the easiest way to create report headers. The following procedure describes the easiest way to create them.

Start the ScreenCam "How to Create Standard Report Headers from the List" now.

1. Start from the ABAP/4 Editor: Edit Program screen.
2. If you have made any changes, save your report. As mentioned in the last Caution, you must do this for the following steps to work.
3. Execute the report. You then see the list output.
4. Choose the menu path System->List->List Header. Input fields appear at the top of the report-one for the header and four for column headers.
5. Type a list and column headers in the white input fields.
6. Click the Save button on the application toolbar. The message Changed texts active from next start of xxxxx in language E appears. This means you will see the new headers the next time you run this program.
7. Click the Back button twice. You are returned to the ABAP/4 Editor: Edit Program screen.
8. Execute the report again. You will see your new headers at the top of the output.

You may be asking yourself, where are these headers stored? Then again, you may not be asking yourself this, but you're about to find out anyway.

The headers you just entered are stored with your program as text elements. A text element is any character string that is displayed in the list output. It might appear at the top as a header, in the middle (as a character string that does not come from the database), or at the bottom as a footer. SAP likes to provide multi-lingual capabilities in its programs, so anything that might need to be translated, for example report headers, are stored separately from the source code as text elements. These elements can be translated without changing the source code. In this section we deal specifically with text elements for the report and column headers, but there are others as well that will be dealt with later.

Since the standard headers are stored as text elements, you can see them and modify them by accessing the text elements of the program. These are contained in the ABAP/4 Text Elements: Change Title and Heading screen, shown in Figure 15.6.

Figure 15.6 : This screen contains the standard Titles and Headers text elements.

Use the following procedure to view, change, or create standard headers.

Start the ScreenCam "How to Create Standard Report Headers Via Text Elements" now.

1. From the ABAP/4 Editor: Edit Program screen, choose the menu path Goto->Text Elements. The ABAP/4 Text Elements screen is displayed.
2. Choose the Titles and Headers radio button.
3. Click the Change button. The ABAP/4 Text Elements: Change Title And Heading screen is displayed. The Title field contains the title text you entered in the ABAP/4: Program xxxxx Attributes screen. If the List Header field is blank, the Title is displayed at the top of the list. The List Header field allows you to override the Title and specify a header that is different from the report title. Enter a List Header, and enter column headers at the bottom of the screen in the Column Header fields. Click the buttons at the bottom right of the screen to scroll left and right, to maximum of 255 characters.
4. Press the Save button to save your changes.
5. Press the Back button. The ABAP/4 Editor: Edit Program screen is displayed.
6. Execute your program. Your new title and headers appear at the top of your report.

To review, on the ABAP/4 Text Elements: Change Title And Heading screen, if the List Header field is non-blank, it is used as the header. If it is blank, the Title field is used as the header.

Translating Text Elements

Creating titles and headers as text elements allows them to be translated into foreign languages, usually by an someone who specializes in the translation of technical or industry-specific phrases. In this section you can try this yourself to get a feel for the process.

Start the ScreenCam "Translating Titles and Headers" now.

1. From the ABAP/4 Text Elements: Change Title and Heading screen, choose the menu path Goto->Translation. The Target Language For Translation screen is shown.
2. In the Target Language field, choose the language into which you want to translate your text elements. The language you choose must have been previously installed on your system by the Basis Consultant. Deutsch (German) is installed on every system, because it is the master language for all R/3 systems. Therefore, choose D (Deutsch).
3. Click the Translate button. The Translate Title And Headers For Program xxxxx screen is displayed. On this screen is the name of the field, a Remark field into which the translator can enter comments, followed by the original text and an input field for the translation. When blank, this input field contains an underscore.
4. In the fields containing an underscore, type your German translations. If you don't know German, just substitute Ks for all of your Cs, and use lots of phrases ending with schnitzel or containing the name Wolfgang.
5. Click the Save button on the standard toolbar. If you have more translations to do, you will remain on the same screen. Click the Back button to see the next set. When there is no more text to be translated, you will be returned to the ABAP/4 Text Elements: Change Title and Heading screen.
6. Now log on again, but this time enter D in the Language field in the log on screen.
7. Run your program. The translated titles will appear. If you display the program attributes, you will see the translated title on the ABAP/4: Program attribute xxxxx screen.

All translations are stored in a proposal pool from which you can retrieve previous translations of a word or phrase. If you enter a translation that differs from those stored in the pool, the system will automatically prompt you with the previous translations. You must then either save the new one or select a previous one.

Using Variables in Standard Page Headers

You can use up to 10 variables in the standard page headings for one program. In your program, assign values to the variables named sy-tvar0 through sy-tvar9. In your headings, use the variable names &0 through &9 to correspond to the sy variables within your program. For example, if in your program you code sy-tvar0 = 'AA' and sy-tvar1 = 'BB', &0 will be replaced by AA and &1 will be replaced by BB in the header.

Although each sy-tvar variable can hold a value up to 20 characters long, the variable output length is 2 by default. This means that for example, wherever &0 appears in the header, exactly two spaces are reserved for the value of sy-tvar0. If the value in sy-tvar0 is 'A', 'A' appears. If the value is 'AA', 'AA' appears. If the value is 'AAA', 'AA' appears.

The output length can be increased by appending periods to the end of the output variable. For example, to increase the output length of &0 from 2 to 4, code &0.. (two periods have been appended). To increase the output length to 7 append 5 periods (&0.....).

Listing 15.6 contains a program that uses standard page headings containing variables. Figure 15.7 shows how to code these variables on the ABAP/4 Text Elements: Change Title and Heading screen.
Figure 15.7 : The ABAP/4 Text Elements: Change Title And Heading screen for program ztx1506.

Listing 15.6  Variables in Standard Page Headers

1  report ztx1506.
2  tables ztxlfa1.
3  parameters: p_land1 like ztxlfa1-land1 default 'US'.
4  sy-tvar0 = sy-uname.
5  write: sy-datum to sy-tvar1,
6         sy-uzeit to sy-tvar2.
7  sy-tvar3 = p_land1.
8  select * from ztxlfa1 where land1 = p_land1.
9      write: / ztxlfa1-lifnr, ztxlfa1-name1.
10     endselect.

The code in Listing 15.6 produces this output:

KENGREENWOOD    1998/05/05 19:40:38          
------------------------------------------------
Country Code: US                          
------------------------------------------------
1040       Motherboards Inc.              
1080       Silicon Sandwich Ltd.          
1090       Consume Inc.                   
2000       Monitors and More Ltd.         
V1         Quantity First Ltd.            
V2         OverPriced Goods Inc.          
V3         Fluffy Bunnies Ltd.            
V4         Moo like a Cow Inc.            
V5         Wolfman Sport Accessories Inc. 
V7         The Breakfast Club Inc.        

• Line 3 defines p_land1 and prompts the user for a value.
• Line 4 assigns the current user Id to sy-tvar0.
• The write statement on line 5 moves the value of sy-datum to sy-tvar1. An ordinary assignment statement (using =) would have moved the value without formatting it. Using write causes the field to be formatted with separators according to the user's profile.
• Line 6 formats the current time and moves it to sy-tvar2.
• Line 7 assigns the value that was entered by the user to sy-tvar3.
• Lines 8 through 10 write out a simple vendor report.
• In Figure 15.7, &0.......... indicates where the value of sy-tvar0 will appear. The periods increase the output length of the variable from 2 to 12. &1........ indicates where the value of sy-tvar1 will appear, &2...... indicates where the value of sy-tvar2 will appear, and &3. the value of sy-tvar3. The periods increase the output lengths to 10, 8, and 3, respectively.

Creating Manual Page Headers

Standard page headers are easy to create, but they have some limitations too. They are limited to one line for the page header and four lines for the column headers. A maximum of 10 variables can be used, each with a minimum length of two characters. The header is always left justified, and the colors are standard and cannot be changed. Manual headings, however, have no such limitations.

To create manual headings, you need to

• Turn off standard page headers.
• Use the top-of-page event to create custom headings.

To turn off the standard page headings, add no standard page heading to the end of the report statement.

An event in ABAP/4 is like a subroutine in other languages. It is an independent section of code; it performs a task and then returns to the point of invocation. However, unlike subroutines, you do not code the call to an event. Instead, the system triggers the event for you when a specific condition arises.

The top-of-page event is triggered when the first write statement is executed. Before any values are written to the list, the system branches to the code following top-of-page and executes it. It then returns to the write statement and writes out the values. Listing 15.7 and Figure 15.8 illustrate this process.

Listing 15.7  The top-of-page Event

1  report ztx1507 no standard page heading.
2  data f1(5) value 'Init'.
3  f1 = 'Title'.
4  write: / 'Hi'.
5 
6  top-of-page.
7    write: / 'My', f1.
8    uline.

Figure 15.8 shows the output for Listing 15.7.

Figure 15.8 : Output of Listing 15.7.

• On line 1, the report statement contains the no standard page heading addition, so standard headers are not written.
• Line 2 defines f1 as character length 5 and gives it an initial value of 'Init'.
• Line 3 assigns the value 'Title' to f1.
• The write statement on line 4 triggers the top-of-page event on line 6. Lines 7 and 8 are then executed, causing My Title to be written to the first line of the list, followed by an underline (written by the uline statement on line 8). Processing then returns to the write statement on line 4 and Hi is written to line 3 of the output list.
• After line 4 has been executed, the program ends and the output is shown.

Notice that the value of f1 written out at the top of the page is the value at the time the first write statement is issued, not the value at the beginning of the program.

Creating Page Footers

As discussed earlier, after an online report has been generated, the user can change his window size. To avoid mid-page breaks, online reports always consist of a single very long virtual page, so having footers doesn't make much sense because there would be only one.

Batch reports are usually printed, and thus will have a definite page size that doesn't change after the report is created, so they can have page footers.

To create page footers you need

• To reserve space for the footer at the bottom of the page using the line-count addition on the report statement.
• The end-of-page event.

To reserve space for your footer, you can code line-count n(m) on the report statement, where n is the number of lines per page, and m is the number of lines to reserve for the footer. You don't want to hard-code n, because the user should be able to specify the number of lines per page when printing the report. Therefore simply leave it off, and enter report zxx line-count (m).

During report processing, sy-pagno contains the current page number and sy-linno contains the current line number being written to.

Code end-of-page at the bottom of your program, as shown in Listing 12.8. The statements following end-of-page are executed before each new page is begun. A new page is begun when a write statement is executed and if the output will not fit on the current page. For example, you may have coded report zxx line-count (3) leaving three rows for the footer, and the user may have specified 60 lines per page. The footer area is therefore contained within lines 58 through 60. If you have just written to the 57th line, the next write statement to a new line will trigger the end-of-page event, followed by a page break, the top-of-page event, and then write output to the next page.

Listing 15.8  top-of-page and end-of-page Events

1  report ztx1508 line-count 20(3) no standard page heading.
2  do 80 times.
3      write: / 'Please kick me', sy-index, 'times'.
4      enddo.
5 
6  top-of-page.
7    write: / 'CONFIDENTIAL',
8           / 'This page begins with number', sy-index.
9    uline.
10
11 end-of-page.
12   write: / sy-uline,
13          / 'The number of kicks at the top of the next page will be',
14             sy-index,
15          / 'Copyright 1998 by the ALA (Abuse Lovers Of America)'.

The first part of the output for Listing 15.8 appears as follows:

CONFIDENTIAL                                                            
This page begins with number          1
------------------------------------------------------------------
Please kick me          1  times                                        
Please kick me          2  times                                        
Please kick me          3  times                                        
Please kick me          4  times                                        
Please kick me          5  times                                        
Please kick me          6  times                                        
Please kick me          7  times                                        
Please kick me          8  times                                        
Please kick me          9  times                                        
Please kick me         10  times                                        
Please kick me         11  times                                        
Please kick me         12  times                                        
Please kick me         13  times                                        
Please kick me         14  times                                        
------------------------------------------------------------------
The number of kicks at the top of the next page will be         15      
Copyright 1998 by the ALA (Abuse Lovers Of America)
CONFIDENTIAL                                                            
This page begins with number         15
------------------------------------------------------------------
Please kick me         15  times
Please kick me         16  times
Please kick me         17  times
Please kick me         18  times

• Line 1 suppresses the use of standard page headers because we only want the manual page headers to be shown. It also sets the number of lines in the footer area to 3. The number of lines per page is set to 20 so we can test the page footer code online. Normally an online report does not specify the number of lines per page.
• The first time through the loop, line 2 triggers the top-of-page event on line 6, causing lines 7 through 9 to write two header lines followed by an underline. Control returns to line 3 and the write statement writes to the fourth line in the output list.
• After looping 14 times, the 15th write statement triggers the end-of-page statement on line 11. Lines 12 through 15 are executed, writing out the footer. The top-of-page statement on line 6 is then executed, and lines 7 through 9 write the page heading at the top of the next page. Then control returns to line 3 and the write statement writes to the fourth line on page 2.
• No page footer is written at the bottom of the last page.

Using the reserve Statement

Sometimes you may need to write out information that belongs together, but spread over multiple lines. For example, you may write the vendor number and name on one line, followed by the address on the next line, and the telephone numbers on the line after that. It would make sense to keep these lines together as a group in the output, and prevent them from being spread across two pages.

Use the reserve statement to keep a group of lines together in the output list.

Syntax for the reserve Statement

reserve n lines.

where:

• n is a numeric literal or variable.

When the reserve statement is executed, the system checks to see if there are n lines available on the current page. If there are fewer than n lines left on the current page, a page break is generated. This triggers the end-of-page event (if it exists), followed by the top-of-page event (if it exists). The next write statement begins at the top of the new page.

If at least n lines are available when the reserve statement is executed, it does nothing.

Listing 15.9 shows a sample program that uses the reserve statement.

Listing 15.9  The reserve Statement

1  report ztx1509 line-count 18(2) no standard page heading.
2  tables ztxlfa1.
3 
4  select * from ztxlfa1.
5      reserve 3 lines.
6      write: / ztxlfa1-lifnr, ztxlfa1-name1,
7             / ztxlfa1-stras, ztxlfa1-regio, ztxlfa1-land1,
8             / ztxlfa1-telf1.
9      skip.
10     endselect.
11
12 top-of-page.
13     write / 'Vendor Report'.
14     uline.
15
16 end-of-page.
17     uline.
18     write: / 'Report', sy-repid, ' Created by', sy-uname.

The code in Listing 15.9 produces the following output:

Vendor Report                                         
-----------------------------------------------
1000       Parts Unlimited                            
111 Queen St.                       ON  CA            
416-255-1212                                          
                                                      
1010       Industrial Pumps Inc.                      
1520 Avenue Rd.                     ON  CA            
416-535-2341                                          
                                                      
1020       Chemical Nation Ltd.                       
123 River Ave.                      ON  CA            
416-451-7787                                          
                                                      
                                                      
                                                      
-----------------------------------------------
Report ZTX1209   Created by KENGREENWOOD              

Vendor Report                                         
-----------------------------------------------
1030       ChickenFeed Ltd.                           
8718 Wishbone Lane                  AB  CA            
393-565-2340                                          
                                                      
1040       Motherboards Inc.                          
64 BitBus Blvd.                     MA  US            
617-535-0198                                          

Line 5 determines if there is space for three more lines on the current page. If there is, it does nothing and line 6 writes out vendor information over the next lines. If there isn't, it triggers the end-of-page event (lines 15 through 17), and then issues a page break. It then triggers the top-of-page event (lines 11 through 13). Then the write statement on line 6 is executed and the lines are written at the top of the new page.

Summary

• You can create simple graphical output in the list using the as symbol, as icon, and as line additions on the write statement. When using these additions, you must use the include statement to bring the symbol, icon and line-draw character definitions into your program.
• Use the line-size addition on the report statement to set the width of the output list. Use the line-count addition to set the number of lines per page in the output list. You can also use it to specify the number of lines reserved for the footer. You cannot use variables on the report statement, so use the new-page statement for these additions if you want to set these attributes at run time.
• To create page headers you can use either standard page headers or the top-of-page statement.
• Up to 10 variables can be used in standard page headers. Values assigned to sy-tvar0 through sy-tvar9 replace &0 through &9 in the list. Use periods to extend the output length of these replacement variables.
• To suppress output of the standard page header, use the no standard page heading addition on the report statement.
• If you include the top-of-page event in your program, it is triggered when the first write statement is executed. The statements following it are executed, then control returns to the write statement.
• Use the end-of-page event to create footers. You must also use line-count on the report or new-page statement to specify the number of lines per page and reserve space for the footer.
• Use the reserve statement to keep a group of lines together in the list.

Q&A

Workshop

The Workshop provides two ways for you to affirm what you've learned in this chapter. The Quiz section poses questions to help you solidify your understanding of the material covered and the Exercise section provides you with experience in using what you have learned. You can find answers to the quiz questions and exercises in Appendix B, "Answers to Quiz Questions and Exercises."

Quiz

1. What are the three graphical additions that are used with the write statement? What statement must also be included in order to write the graphical additions? Give an example of an include statement.
2. What are the two additions that are used with report statement to control size of the output page? Can the variable used for the two additions be variable?

Exercise 1

Write out a program that will display the following symbols: square, diamond, circle, glasses, pencil, phone, note, and folder.

---

© Copyright, Macmillan Computer Publishing. All rights reserved.