To control the interplay between online user and the ABAP program, the graphics function modules offer the following mechanisms:

• STAT: status with which function module called

• GRAPH_RECEIVE: waits for user input

• GET_xxxx_PARAM: returns the export parameters needed by the graphics program to respond to user input

• PWDID: parent window for the window being opened

• WINID: ID of current window (existing or to be created)

• SUPER: marks current window as "exit window"

STAT, the central parameter, tells the function module which task to perform on a given call:

• open a window and start the graphics program in it

• transfer data to the graphic window

The GRAPH_RECEIVE function module lets you wait for user input. The graphics program running in a given window reports back user activity (mouse clicks, menu selections, keyboard input, or window closure) as a message to GRAPH_RECEIVE. The ABAP program must then call the relevant GET_xxxx_PARAM module to activate the return parameter information for the given graphic program.

The most common pattern for programs allowing multiple windows is to place the various function module calls in a loop. A pass through the loop is made each time GRAPH_RECEIVE reports new input from the user. (See the example scheme in "Waiting for user input.")

Every ABAP program that uses graphics function modules must call the GRAPH_RECEIVE utility function module to perform waiting. Even if your program does not respond to user input, waiting is important because it "realizes" actions requested with the STAT parameter:

• Newly-created windows do not appear on the screen until the call to GRAPH_RECEIVE takes place.

• Data sent to existing windows are not actually displayed until GRAPH_RECEIVE is called.

Messages from the graphics program report user actions (keyboard and mouse input) that select graph objects, choose menu options, press functions keys, and so on.

GRAPH_RECEIVE receives messages from all graphics programs running on the user's workstation. The function module does not return until it has received an input message, even if the message only reports that a graphic window has been closed.

The ABAP program uses GRAPH_RECEIVE together with the GET_xxxx_PARAM function modules. These are a collection of function modules, one for each graphic program. (The letters xxxx stand for graphics program acronyms: BMAT, BUSG, GANTT, HIER, HPGL, PORT, or STAT).

The following table contains a list of all possible parameters you can use with this function module.

Note: ** denotes a dialog parameter

When GRAPH_RECEIVE reports that a message has been received, the ABAP program calls the relevant GET_xxxx_PARAM module to get the details on that message. For each graphics program, GRAPH_xxxx_PARAM returns the export parameters needed to respond to the user input.

To learn which graphics program sent the message received, the ABAP program must check the RWNID parameter returned by GRAPH_RECEIVE. The RWNID parameter provides the window ID for the window where the user input occurred. This window ID also identifies the graphics program running in the window. (For more information on window ID's, see the WINID parameter description.)

As in previous releases of SAP Graphics, it is possible to wait without using GRAPH_RECEIVE or the GET_xxxx_PARAM functions.

Function modules that actually call the graphics program can perform waiting and thus return their own export parameters.

(This requires using the RWNID and M_TYP parameter, and more values for STAT, when calling any graphics function module.)

This method is still available for compatibility with older programs, but is not recommended for new programs. Instead, use GRAPH_RECEIVE as described here. The function modules that call the graphics program should be viewed as "output-only" functions, while the GET_xxxx_PARAM functions serve as "input-only".

The following example is a possible scheme for combining multiple calls to function modules in a program. Here the programmer wanted to open several windows simultaneously, but not take input from the user until the last one is open. The windows created in the first calls do not appear on the screen until GRAPH_RECEIVE has been called. Similarly, newly-transferred data does not appear in the display until GRAPH_RECEIVE has been called.