The .4gl File - Interacting with the User

Your form can display options to the user using action views - buttons, dropdown menus (topmenus), toolbars, and other items on the window.

Defining Actions - the MENU statement

An action defined in the .4gl module, which identifies the program routine to be executed, can be associated with each action view shown on the form. You define the program logic to be executed for each action in the .4gl module.

In this BDL program, the MENU statement supplies the list of actions and the statements to be executed for each action. The actions are specified with ON ACTION clauses:
```
ON ACTION query
  CALL query_cust()
```
The ON ACTION clause defines the action name and the statements to be executed for the action. The presentation attributes - title, font, comment, etc. - for the graphical object that serves as the action view are defined in a separate action defaults file, or in the ACTION DEFAULTS section of the form file. This allows you to standardize the appearance of the views for common actions. Action Defaults are illustrated in Tutorial Chapter 5: Enhancing the Form.
You can also use ON ACTION clauses with some other interactive BDL statements, such as INPUT, INPUT ARRAY, DIALOG, and DISPLAY ARRAY.
When the MENU statement in your program is executed, the action views for the actions (query, in the example) that are listed in the interactive MENU statement are enabled. Only the action views for the actions in the specific MENU statement are enabled, so you must be sure to include a means of exiting the MENU statement. If there is no action view defined in your form specification file for a listed action, a simple push button action view is automatically displayed in the window. Control is turned over to the user, and the program waits until the user responds by selecting one of enabled action views or exiting the form. Once an action view is selected, the corresponding program routine (action) is executed.

See Ring menus (MENU) in the Genero Business Development Language User Guide for a complete discussion of the statement and all its options.

Displaying Messages and Errors

The MESSAGE and ERROR statements are used to display text containing a message to the user. The text is displayed in a specific area, depending on the front end configuration and window style. The MESSAGE text is displayed until it is replaced by another MESSAGE statement or field comment. You can specify any combination of variables and strings for the text. BDL generates the message to display by replacing any variables with their values and concatenating the strings:

MESSAGE "Customer " || l_custrec.store_num , || " retrieved."

The Localized Strings feature can be used to customize the messages for specific user communities. This is discussed in Tutorial Chapter 10: Localization.

Example: dispcust.4gl

This portion of the dispcust.4gl program connects to a database, opens a window and displays a form and a menu.

Program dispcust.4gl:

01 -- dispcust.4gl 
02 SCHEMA custdemo 
03 
04 MAIN
05 
06   CONNECT TO "custdemo"
07 
08   CLOSE WINDOW SCREEN
09   OPEN WINDOW custwin WITH FORM "custform"
10   MESSAGE "Program retrieves customer 101"
11
12   MENU "Customer" 
13     ON ACTION query 
14       CALL query_cust()
15     ON ACTION exit
16       EXIT MENU
17   END MENU
18
19   CLOSE WINDOW custwin 
20
21   DISCONNECT CURRENT
22
23 END MAIN

Note:

Line 02 The SCHEMA statement is required since variables are defined as LIKE a database table in the function query_cust.
Line 06opens the connection to the custdemo database.
Line 08 closes the default window named SCREEN, which is opened each time the runtime system starts a program containing interactive statements
Line 09 uses the WITH FORM syntax to open a window having the identifier custwin containing the form identified as custform. The window name must be unique among all windows defined in the program. Its scope is the entire program. You can use the window's name to reference any open window in other modules with other statements. Although there can be multiple open windows, only one window may be current at a given time. By default, the window that opens will be a normal application window. The form identifier is the name of the compiled .42f file (custform.42f). The form identifier must be unique among form names in the program. Its scope of reference is the entire program.
Line 10 displays a string as a MESSAGE to the user. The message will be displayed until it is replaced by a different string.
Lines 12 through 17 contain the interactive MENU statement. By default, the menu options query and exit are displayed as buttons in the window, with Customer as the menu title. When the MENU statement is executed, the buttons are enabled, and control is turned over to the user. If the user selects the query button, the function query_cust will be executed. Following execution of the function, the action views (buttons in this case) are re-enabled and the program waits for the user to select an action again. If the user selects the exit button, the MENU statement is terminated, and the program continues with line 19.
Line 19 The window custwin is closed which automatically closes the form, removing both objects from the application's memory.
Line 21 The program disconnects from the database; as there are no more statements in MAIN, the program terminates.