Tutorial Chapter 3: Record Display

Summary:

Interacting with the User
Working with Records and Forms
The Form Specification File
Compiling the program and form

This example program opens a WINDOW containing a FORM to display information to the user. The options to retrieve data or exit are defined in a MENU statement, and displayed as buttons on the form. When the user presses the "query" button, an SQL SELECT statement retrieves a single row from the customer table and displays it on the form.

A FORM can contain form fields for entering and displaying data; explanatory text; and buttons, dropdown menus, folders, tables, checkboxes, images, and other form objects (referred to as views).

Display on Windows platforms

Interacting with the User

Opening Windows and Forms

A program creates a window with the OPEN WINDOW instruction, and destroys a window with the CLOSE WINDOW instruction. The OPEN WINDOW ... WITH FORM instruction can be used to automatically open a window containing a specified form:

     OPEN WINDOW custwin WITH FORM "custform"

When you are using a graphical front end, windows are created as independent resizable windows. By default windows are displayed as normal application windows, but you can specify a Presentation Style. The standard window styles are defined in the default Presentation Style file (FGLDIR/lib/default.4st):

If the WITH FORM option is used in opening a window, the CLOSE WINDOW statement closes both the window and the form.

     CLOSE WINDOW custwin

When the runtime system starts a program, it creates a default window named SCREEN. This default window can be used as another window, but it can be closed if not needed.

     CLOSE WINDOW SCREEN

Note: The appropriate Genero front-end client must be running for the program to display the window and form.

Displaying Messages to the User

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 Chapter 10.

Using Menus

Your form can display options to the user as buttons, dropdown menus (top menus), toolbars, and other objects (action views) on the window. An action, which identifies the program routine to be executed, can be associated with each action view.

In your BDL program, you use the MENU statement to supply the list of actions and the statement, or block of statements, to be executed. The actions can be specified with ON ACTION or COMMAND clauses.

An 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. This is illustrated in chapter 5.

        ON ACTION query
          CALL query_cust()

A COMMAND clause allows you to define the label to be displayed, and an optional help comment, in addition to the statements to be executed, in the program itself.
```
   COMMAND "query" "Retrieve customer"
     CALL query_cust()
```

When the MENU statement in your program is executed, the action views for the actions that are listed in the interactive MENU statement are enabled. Only the action views in the specific MENU statement are enabled, so you must be sure to include a means of exiting the MENU statement. If there are no action views defined in your form specification file for the actions listed, simple push button action views for the actions are displayed in the window. Control is turned over to the user, and the program waits until one of the enabled action views is selected. Once the view is selected, the program routine (action) is executed.

You can also use ON ACTION clauses with some other interactive BDL statements, such as INPUT, INPUT ARRAY, and DISPLAY ARRAY.

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     COMMAND "query" "Retrieve customer"
14       CALL query_cust()
15     COMMAND "exit" "Quit now"
16        EXIT MENU
17   END MENU
18
19   CLOSE WINDOW custwin
20
21   DISCONNECT CURRENT
22
23 END MAIN

Notes:

Line 02 The SCHEMA statement is required since variables are defined as LIKE a database table in the function query_cust.
Line 06 opens 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 mouses over the query or exit buttons, the associated help text for the action view is displayed in a bubble.
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.

Working with Records and Forms

Defining a Record

In addition to defining individual variables, the DEFINE statement can define a record, a collection of variables each having its own data type and name. You put the variables in a record so you can treat them as a group. Then, you can access any member of a record by writing the name of the record, a dot (known as dot notation), and the name of the member.

    DEFINE custrec RECORD
            store_num  LIKE customer.store_num
            store_name LIKE customer.store_name
          END RECORD

    DISPLAY custrec.store_num

Your record can contain variables for the columns of a database table. At its simplest, you write RECORD LIKE tablename.* to define a record that includes members that match in data type all the columns in a database table. However, if your database schema changes often, it's best to list each member individually, so that a change in the structure of the database table won't break your code. Your record can also contain members that are not defined in terms of a database table.

Displaying a Record: DISPLAY BY NAME

A common technique is to use the names of database columns as the names of both the members of a program record and the fields in a form. Then, the DISPLAY BY NAME statement can be used to display the program variables. By default, a screen record consisting of the form fields associated with each database table is automatically created. BDL will match the variable name to the name of the form field, ignoring any record name prefix:

     DISPLAY BY NAME custrec.*

The program variables serve as the intermediary between the database and the form that is displayed to the user. Values from a row in the database table are retrieved into the program variables by an SQL SELECT statement, and are then displayed on the form. In Chapter 6 you will see how the user can change the values in the form, resulting in changes to the program variables, which could then be used in SQL statements to modify the data in the database.

Example: dispcust.4gl (function query_cust)

This function retrieves a row from the customer table and displays it in a form.

Function query_cust

01 FUNCTION query_cust()      -- displays one row
02   DEFINE  l_custrec RECORD
03      store_num    LIKE customer.store_num,
04      store_name   LIKE customer.store_name,
05      addr         LIKE customer.addr,
06      addr2        LIKE customer.addr2,
07      city         LIKE customer.city,
08      state        LIKE customer.state,
09      zipcode      LIKE customer.zipcode,
10      contact_name LIKE customer.contact_name,
11      phone        LIKE customer.phone
12     END RECORD
13
14   SELECT store_num, store_name, addr,
15         addr2, city, state, zipcode,
16         contact_name, phone  
17     INTO l_custrec.* 
18     FROM customer 
19     WHERE store_num = 101
20     
21   DISPLAY BY NAME l_custrec.* 
22   MESSAGE "Customer ", l_custrec.store_num,
23          " displayed."
24 END FUNCTION

Notes:

Line 01 is the beginning of the function query_cust. No variables are passed to the function.
Lines 02 thru 12 DEFINE a record l_custrec as LIKE columns in the customer database table, listing each variable separately.
Line 14 thru 19 SELECT .. INTO can be used, since the statement will retrieve only one row from the database. The SELECT statement lists each column name to be retrieved, rather than using SELECT *. This allows for the possibility that additional columns might be added to a table at a future date. Since the SELECT list retrieves values for all the variables in the program record, in the order listed in the DEFINE statement, the shorthand INTO l_custrec.* can be used.
Line 21 The names in the program record l_custrec match the names of screen fields on the form, so DISPLAY BY NAME can be used. l_custrec.* indicates that all of the members of the program record are to be displayed.
Lines 22 and 23 A string for the MESSAGE statement is concatenated together using the double pipe ( || ) operator and displayed. The message consists of the string "Customer ", the value of l_custrec.store_num, and " displayed".

There are no additional statements in the function, so the program returns to the MENU statement, awaiting the user's next action.

The Form Specification File

You can specify the layout of a form in a form specification file, which is compiled separately from your program. The form specification file defines the initial settings for the form, which can be changed programmatically at runtime.

Form specification files have a file extension of .per . The structure of the form is independent of the use of the form. For example, one function can use a form to display a database row, another can let the user enter a new database row, and still another can let the user enter criteria for selecting database rows.

A basic form specification consists of the following sections:

The SCHEMA section (optional)

This specifies the database schema file to be used when the form is compiled. It is required if any form items are defined as data types based on a column of a database table.

     SCHEMA custdemo

The ACTION DEFAULTS, TOPMENU, and TOOLBAR sections (optional)

These sections are provided to allow you to define the decoration for action views (action defaults), as well as to define Topmenus and Toolbars for the form. In this case, the definitions are specific to the form. If your definitions are in external XML files instead, they can be applied to any form.

This is discussed in chapter 5.

The LAYOUT section

This section defines the appearance of a form using a layout tree of containers, which can hold other containers or can define a screen area. Some of the available containers are GRID, VBOX, HBOX, GROUP, FOLDER, and PAGE.

The simplest layout tree could have only a GRID container defining the dimensions and the position of the logical elements of a screen:

LAYOUT
  GRID
    grid-area
  END
END

The END keyword is mandatory to define the end of a container block.

The grid-area is delimited by curly braces. Within this area, you can specify the position of form items or interactive objects such as BUTTON, COMBOBOX, CHECKBOX, RADIOGROUP, PROGRESSBAR, etc.

Simple form fields, delimited by square brackets ( [ ] ), are form items into which the program can display data and take input. Generally, the number of characters in the space between the brackets defines the width of the region to be used by the item. For example, in the grid-area, the following field could be defined:

     [f01            ]

This form field has an item tag of f01, which will be used to link the field to its definition in the ATTRIBUTES section of the form specification.

Interactive form items, such as COMBOBOX, CHECKBOX, and RADIOGROUP, can be used instead of simple form fields to represent the values in the underlying formfield. Special width calculations are done for some of these form items, such as COMBOBOX, BUTTONEDIT, and DATEEDIT. If the default width generated by the form compiler does not fit, the - dash symbol can be used to define the real width of the item.

Text in the grid-area that is outside brackets is display-only text, as in the word Company below:

     Company [f01            ]

The TABLES section (optional)

If a database table or database view is referenced elsewhere in the form specification file, in the ATTRIBUTES section for example, the table or view must be listed in the TABLES section:

    TABLES 
      customer 
    END

A default screen record is automatically created for the form fields associated with each table listed in this section.

The ATTRIBUTES section

The ATTRIBUTES section defines properties of the items used in the form.

Formfields

For form fields (items that can be used to display data or take input) the definition is:

    <item-type> <item-tag> = <field-name>, <attribute-list> ;

Examples:

    EDIT f01 = customer.cust_num, REQUIRED;
    COMBOBOX f03 = customer.state;
    CHECKBOX f04 = formonly.propcheck;

The item-type defines the kind of graphical object which must be used to display the form element. The most commonly used item-type, EDIT, defines a simple line edit box for data input or display.

The item- tag identifies the form field in the display area.

The field-name must specify a database column as the name of the display field, or must be FORMONLY (fields defined as FORMONLY are discussed in chapter 11.) Fields are associated with database columns only during the compilation of the form specification file. After the form compiler identifies data types from the schema file, the association between fields and database columns is broken, and the field-name is associated with the screen record.

Form field and form item definitions can optionally include an attribute-list to specify the appearance and behavior of the item. For example, you can define acceptable input values, on-screen comments, and default values for fields; you can insure that a value is entered in the field during the input of a new row (REQUIRED); columns in a table can be specified as sortable or non-sortable; numbers and dates can be formatted for display; data entry patterns can be defined and input data can be upshifted or downshifted.

A form field can be a BUTTONEDIT, CHECKBOX, COMBOBOX, DATEEDIT, EDIT, IMAGE, LABEL, PROGRESSBAR, RADIOGROUP, or TEXTEDIT.

Other form items

For form items that are not form fields (BUTTON, CANVAS, GROUP, static IMAGE, static LABEL, SCROLLGRID, and TABLE) the definition is:

    <item-type> <item-tag> : <item-name> , <attribute-list> ;

Examples:

    BUTTON btn1: print, TEXT = "Print Report";
    LABEL lab1 : label1, TEXT ="Customer";

The item-type defines the kind of graphical object which must be used to display the form element.

The item-tag identifies the form item in the display area.

The item-name provides the name of the form item.

The optional attribute-list defines the aspect and behavior of the form item.

The INSTRUCTIONS section (optional)

The INSTRUCTIONS section is used to define explicit screen records or screen arrays. This is discussed in Chapter 7.

Example: Form Specification File custform.per

This form specification file is used with the dispcust.4gl program to display program variables to the user. This form uses a layout with a simple GRID to define the display area.

custform.per

01 SCHEMA custdemo
02
03 LAYOUT
04   GRID
05   {
06    Store #:[f01  ] Name:[f02                 ]
07    Address:[f03                 ]
08            [f04                 ]
09       City:[f05             ]State:[f6]Zip:[f07   ] 
10    Contact:[f08                           ]
11      Phone:[f09                ]       
12
13   }   
14   END   --grid
15 END  -- layout
16
17 TABLES 
18     customer
19 END
20
21 ATTRIBUTES
22 EDIT f01 = customer.store_num, REQUIRED;
23 EDIT f02 = customer.store_name, COMMENT="Customer name";
24 EDIT f03 = customer.addr;
25 EDIT f04 = customer.addr2;
26 EDIT f05 = customer.city;
27 EDIT f6  = customer.state;
28 EDIT f07 = customer.zipcode;
29 EDIT f08 = customer.contact_name;
30 EDIT f09 = customer.phone;
31 END

Notes:

Line 01 lists the database schema file from which the form field data types will be obtained.
Lines 03 through 15 delimit the LAYOUT section of the form.
Lines 04 thru 14 delimit the GRID area, indicating what will be displayed to the user between the curly brackets on lines 05 and 13.
Line 17 The TABLES statement is required since the field descriptions reference the columns of the database table customer.
Within the grid area, the form fields have item tags linking them to descriptions in the ATTRIBUTES section, in lines 20 thru 28. As an example, f01 is the display area for a program variable having the same data type definition as the store_num column in the customer table of the custdemo database.
Line 22 All of the item-tags in the form layout section are listed in the ATTRIBUTES section. For example, the item-tag f01 is listed as having an item-type of EDIT. This field will be used for display only in this program, but the same form will be used for input in a later program. An additional attribute, REQUIRED, indicates that when this form is used for input, an entry in the field f01 must be made. This prevents the user from trying to add a row with a NULL store_num to the customer table, and later getting an ERROR message from the database.
Line 23 The second field is defined with the attribute COMMENT, which defines a text to be displayed when that field gets the focus, or as a tooltip when the mouse goes over the field.

Compiling the Program and Form

When this form is compiled (translated) using the fglform tool, an XML file is generated that has a file extension of .42f. The runtime system uses this file along with your programs to define the Abstract User Interface.

Compile the form:

     fglform custform.per

Compile the single module program:

fglcomp dispcust.4gl

Execute the program:

fglrun dispcust.42m