Calling a Logical Database Using a Function Module

The subroutines in the logical database are called in the following sequence when you call the function module LDB_PROCESS:

1. LDB_PROCESS_INIT
2. INIT
3. LDB_PROCESS_CHECK_SELECTIONS
4. PUT_node.

None of the subroutines used to process the selection screen when you link the logical database to an executable program are called, neither does the runtime environment trigger any reporting events in the calling program. Instead, the PUT statements in the logical database trigger actions in the function module that call callback routines in the calling program. In other words, the function module catches the events that are otherwise processed by the runtime environment.

The function module has the following import parameters:

• LDBNAME

  Name of the logical database you want to call.

• VARIANT

  Name of a variant to fill the selection screen of the logical database. The variant must already be assigned to the database program of the logical database. The data is passed in the same way as when you use the WITH SELECTION-TABLE addition in a SUBMIT statement.

• EXPRESSIONS

  In this parameter, you can pass extra selections for the nodes of the logical database for which dynamic selections are allowed. The data type of the parameter RSDS_TEXPR is defined in the type group RSDS. The data is passed in the same way as when you use theWITH FREE SELECTIONaddition in a SUBMIT statement.

• FIELD_SELECTION

  You can use this parameter to pass a list of the required fields for the nodes of the logical database for which dynamic selections are allowed. The data type of the parameter is the deep internal table RSFS_FIELDS, defined in the type group RSFS. The component TABLENAME contains the name of the node and the deep component FIELDS contains the names of the fields that you want to read.

The function module has the following tables parameters:

• CALLBACK

  You use this parameter to assign callback routines to the names of nodes and events. The parameter determines the nodes of the logical database for which data is read, and when the data is passed back to the program and in which callback routine.

• SELECTIONS

  You can use this parameter to pass input values for the fields of the selection screen of the logical database. The data type of the parameter corresponds to the structure RSPARAMS in the ABAP Dictionary. The data is passed in the same way as when you use the WITH SELECTION-TABLE addition in a SUBMIT statement.

If you pass selections using more than one of the interface parameters, values passed in SELECTIONS and EXPRESSIONS overwrite values for the same field in VARIANT.

When you link a logical database with an executable program, the GET statements determine the depth to which the logical database is read. When you call the function module LDB_PROCESS, you determine the depth by specifying a node name in the CALLBACK parameter. For each node for which you request data, a callback routine can be executed at two points. These correspond to the GET and GET LATE events in executable programs. In the table parameter CALLBACK, you specify the name of the callback routine and the required execution point for each node. A callback routine is a subroutine in the calling program or another program that is to be executed at the required point.

For the GET event, the callback routine is executed directly after the data has been read for the node, and before the subordinate nodes are processed. For the GET_LATE event, the callback routine is processed after the subordinate nodes have been processed.

The line type of the table parameter CALLBACK is the flat structure LDBCB from the ABAP Dictionary. It has the following components:

• LDBNODE

  Name of the node of the logical database to be read.

• GET

  A flag (contents X or SPACE), to call the corresponding callback routine at the GETevent.

• GET_LATE

  A flag (contents X or SPACE), to call the corresponding callback routine at the GET LATEevent.

• CB_PROG

  Name of the ABAP program in which the callback routine is defined.

• CB_FORM

  Name of the callback routine.

If you pass an internal table to the CALLBACK parameter, you must fill at least one of the GET or GET_LATE columns with X for each node (you may also fill both with X). 

A callback routine is a subroutine that must be defined with the following parameter interface:

FORM subr USING node LIKE LDBCB-LDBNODE                 wa   [TYPE t]                evt                check.

The parameters are filled by the function module LDB_PROCESS. They have the following meaning:

• node contains the name of the node.
• wa is the work area of the data read for the node. The program that calls the function module LDB_PROCESS and the program containing the callback routine do not have to declare interface work areas using NODES or TABLES. If the callback routine is only used for one node, you can use a TYPE reference to refer to the data type of the node in the ABAP Dictionary. Only then can you address the individual components of structured nodes directly in the subroutine. If you use the callback routine for more than one node, you cannot use aTYPE reference. In this case, you would have to address the components of structured nodes by assigning them one by one to a field symbol.
• evt contains G or L, for GET or GET LATErespectively. This means that the subroutine can direct the program flow using the contents of evt.
• check allows the callback routine to influence how the program is processed further (but only if evt contains the value G). The value X is assigned to the parameter when the subroutine is called. If it has the value SPACE when the subroutine ends, this flags that the subordinate nodes of the logical database should not be processed in the function module LDB_PROCESS. This is the same as leaving a GET event block using CHECK in an executable program. If this prevents unnecessary data from being read, it will improve the performance of your program.

• LDB_ALREADY_RUNNING

  A logical database may not be called if it is still processing a previous call. If this occurs, the exception LDB_ALREADY_RUNNING is triggered.

• LDB_NOT_REENTRANT

  A logical database may only be called repeatedly if its database program contains the subroutine LDB_PROCESS_INIT , otherwise, this exception is triggered.

• LDB_SELECTIONS_NOT_ACCEPTED

  Error handling in the subroutine LDB_PROCESS_CHECK_SELECTIONS of the database program can trigger this exception. The error message is provided in the usual system fields SY-MSG... .

For details of further exceptions, refer to the function module documentation in the Function Builder.