Details Lists (SAP Library - ABAP Programming (BC-ABA))

Details Lists

When the system processes event blocks that are not assigned to interactive list events, and when processing dialog modules, the ABAP program writes its list output to the basic list.

The ABAP system field sy-lsindcontains the index of the list currently being created. While creating a basic list, sy-lsind equals zero.

By default, the basic list has a standard list status and a standard page header. The TOP-OF-PAGE and END-OF-PAGE events can occur while the basic list is being created. All output in these events is placed in the page header or footer of the basic list. In executable programs, the basic list is automatically sent to the list processor and displayed at the end of the END-OF-SELECTION event. Otherwise, it is displayed after the PAI processing block on the screen from which the LEAVE TO LIST-PROCESSING statement occurred.

Creating Detail Lists

Each time the user executes an action on a list, the runtime environment checks whether there is an event block defined that corresponds to the function code. If there is, sy-lsind is automatically increased by one, and the relevant event block is executed. Any output statements that are performed during execution of this event block place their data into a new list (list level) with the index sy-lsind. In order to create a new list level, the GUI status of the basic list must allow user actions, and the relevant event blocks must be defined in the program.

All lists created during an interactive list event are detail lists. Each interactive list event creates a new detail list. With one ABAP program, you can maintain one basic list and up to 20 detail lists. If the user creates a list on the next level (that is, SY-LSIND increases), the system stores the previous list and displays the new one. The user can interact with whichever list is currently displayed.

The system displays this list after processing the entire processing block of the event keyword or after leaving the processing block due to EXIT or CHECK. By default, the new list overlays the previous list completely. However, you can display a list in a dialog box. If no other dialog status is set in the event block for the detail list, the system uses the status from the previous list level. However, there is no standard page header for detail lists (see below).

Consequences of Event Control

The fact that you program detail lists in event blocks has important consequences. You cannot nest processing blocks (see Structure of the Processing Logic). Therefore, you cannot process other events within the processing blocks of interactive lists.

Especially, you cannot

· use separate processing blocks to process further interactive events. A certain user action always triggers the same processing block in your program. You must use control statements (IF, CASE) within the processing block to make sure that the system processes the desired statements. There is a range of system field that you can use for this.

· use the event TOP-OF-PAGE to influence the list structure of secondary lists. For the layout of the page headers of the secondary lists, you must use the event TOP-OF-PAGE DURING LINE-SELECTION (see below). However, the event END-OF-PAGE occurs also in secondary lists.

· use events such as GET and GET LATE to retrieve data for secondary lists, but must use ABAP statements. You can use the logical database linked to the executable program only for the layout of the basic list through events. If you want to use a logical database during interactive events, you must call another executable program using submit or (better) call the logical database using a function module.

Navigating in Lists

To return from a high list level to the next-lower level, the user can choose Back from a detail list. The system releases the last list to have been displayed, and returns to the previous list level. The system deletes the contents of the released list.

To determine the list level in which the output from an event block will be displayed, you can change the value of the system fields sy-lsind. This is one of the few exceptions to the rule that states that you must never overwrite ABAP system fields. The system accepts only index values which correspond to existing list levels. It then deletes all existing list levels whose index is greater or equal to the index you specify. For example, if you set sy-lsind to 0, the system deletes all secondary lists and overwrites the basic list with the current secondary list.

When you change sy-lsind, the change only takes effect at the end of the corresponding event. If you work with statements in the processing block that access the list with the index sy-lsind using the INDEXaddition (for example, SCROLL), you should set the new value of sy-lsind after these statements. The best place to set it is in the last statement of the event block.

System Fields for Details Lists

After each user action on a list, the following ABAP system fields will be set in the corresponding event block:

System Field	Information
sy-lsind	Index of the list created during the current event (basic list = 0)
sy-listi	Index of the list level from which the event was triggered
sy-lilli	Absolute number of the line from which the event was triggered
sy-lisel	Contents of the line from which the event was triggered
sy-curow	Position of the line in the window from which the event was triggered (counting starts with 1)
sy-cucol	Position of the column in the window from which the event was triggered (counting starts with 2)
sy-cpage	Page number of the first displayed page of the list from which the event was triggered
sy-staro	Number of the first line of the first page displayed of the list from which the event was triggered (counting starts with 1). This line may contain the page header.
sy-staco	Number of the first column displayed in the list from which the event was triggered (counting starts with 1)
sy-ucomm	Function code that triggered the event
sy-pfkey	Status of the list currently being displayed.

Page Headers for Detail Lists

On detail lists, the system does not display a standard page header and it does not trigger the event TOP-OF-PAGE. To create page headers for detail list, you must use a different TOP-OF-PAGE event:

TOP-OF-PAGE DURING LINE-SELECTION.

The system triggers this event for each detail list. If you want to create different page headers for different list levels, you must program the processing block of this event accordingly, for example by using system fields such as sy-lsind or sy-pfkey in control statements.

As on the basic list, the page header of a detail list remains displayed even when you scroll vertically.

Messages on Detail Lists

ABAP allows you to react through the MESSAGEstatement to incorrect or possibly-incorrect user input by displaying messages. The seriousness of the error determines how program processing continues.

In list processing, the message processing for the individual message types is as follows:

· A (=Abend): Termination

The system displays the message in a dialog box. The entire transaction (for example, SA38) is terminated after the user confirms the message using ENTER.

· E (=Error) or W (=Warning):

The system displays the message in the status bar. Once the user has confirmed the error by pressing ENTER, the current event block is terminated and the previous list level remains displayed. If you use an error or warning message while creating the basic list, the entire program is terminated.

· I (=Information):

The system displays the message in a dialog box. Once the user has confirmed the message by pressing ENTER, the program continues processing after the MESSAGE statement.

· S (= status)

The system displays the message in the status bar of the current list.

· X (= Exit) Runtime error:

This message type triggers a runtime error and generates a short dump.

Using Detail Lists

A program that creates a single list – that is, the program is started first and must issue all the required detailed information on the generated list - can lead to very extensive lists from which the user has to extract the required data. For background processing, this is the only possible method. After starting a background job, there is no way of influencing the program. The desired selections must be made beforehand and the list must provide detailed information.

For dialog sessions, there are no such restrictions. The user is present during the execution of the program and can control and manipulate the program flow directly. To be able to use all advantages of the online environment, classical reporting was developed into interactive reporting.

Interactive reporting allows the user to participate actively in retrieving and presenting data during the session. Instead of one extensive and detailed list, with interactive reporting you create a condensed basic list from which the user can call detailed information by positioning the cursor and entering commands. Interactive reporting thus reduces information retrieval to the data actually required. Detailed information is presented in detail lists.

Apart from creating detail lists, interactive reporting also allows you to call transactions or other executable programs from lists. These programs then use values displayed in the list as input values. The user can, for example, call a transaction from within a list to change the database table whose data is displayed in the list.

Examples

Example

Creating Detail Lists

REPORT demo_list_interactive_1.

START-OF-SELECTION.
WRITE: 'Basic List, sy-lsind =', sy-lsind.

AT LINE-SELECTION.
WRITE: 'Secondary List, sy-lsind =', sy-lsind.

When you run the program, the basic list appears. The GUI status automatically permits the function Choose (F2). When you choose a list line, the system triggers the AT LINE-SELECTION event, and the first detail list overlays the basic list. This list has no standard page header. It also inherits the GUI status of the basic list. By choosing Choose, the user can now create up to 19 of these lists. Trying to produce more than 19 lists results in a runtime error. Using Back , the user can return to previous lists.

Example

Navigation in detail lists.

REPORT demo_list_interactive_2.

START-OF-SELECTION.
WRITE: 'Basic List, sy-lsind =', sy-lsind.

AT LINE-SELECTION.
  IF sy-lsind = 3.
    sy-lsind = 0.
  ENDIF.
  WRITE: 'Secondary List, sy-lsind =', sy-lsind.

When you run the program, the basic list appears:

Basic List, sy-lsind = 0

The GUI status automatically permits the function Choose . If the user positions the cursor on the list line and chooses Choose to trigger the AT LINE-SELECTION event, the system displays a detail list that contains the following line:

Secondary List, sy-lsind = 1

Choosing Choose again produces:

Secondary List, sy-lsind = 2

Back leads to the previous list level. Choosing Choose, on the other hand, produces a detail list that contains the following line (because of the IF condition):

Secondary List, sy-lsind = 0

The system deletes list levels 1 and 2. Choosing Back returns to the point at which the list processing started. If you choose Choose, the system creates a detail list with index 1. However, the list on level 0 is no longer a basic list (no page header), but is itself a detail list.

Example

Page Headers for Detail Lists

REPORT demo_list_interactive_3.

START-OF-SELECTION.
WRITE 'Basic List'.

AT LINE-SELECTION.
WRITE 'Secondary List'.

TOP-OF-PAGE DURING LINE-SELECTION.
  CASE sy-lsind.
    WHEN 1.
      WRITE 'First Secondary List'.
    WHEN 2.
      WRITE 'Second Secondary List'.
    WHEN OTHERS.
      WRITE: 'Secondary List, Level:', sy-lsind.
  ENDCASE.
  ULINE.

When you run the program, the basic list appears. The user can choose Choose to create detail lists. The details lists have page headers that are set according to the value of sy-lsind.

Example

Messages on Detail Lists

REPORT demo_list_interactive_4 NO STANDARD PAGE HEADING.

AT LINE-SELECTION.
WRITE 'Basic List'.
MESSAGE s888(sabapdocu) WITH text-001.

AT LINE-SELECTION.
  IF sy-lsind = 1.
    MESSAGE i888(sabapdocu) WITH text-002.
  ENDIF.
  IF sy-lsind = 2.
    MESSAGE e888(sabapdocu) WITH text-003 sy-lsind text-004.
  ENDIF.
  WRITE: 'Secondary List, sy-lsind:', sy-lsind.

When the program runs, the system displays the basic list and the success message 100 in the status line. A single click triggers the AT LINE-SELECTION event. When the system creates the first detail list, it displays a dialog box with the information message 100. You cannot create the second detail list, because the message 200 has message type E: