The Customer List Module

The custlist.4gl module defines a 'zoom' module, to let the user select a customer from a list. The module could be reused for any application that requires the user to select a customer from a list.

This module uses the custlist.per form and is implemented with a DIALOG instruction defining a CONSTRUCT sub-dialog and a DISPLAY ARRAY sub-dialog. The display_custlist() function in this module returns the customer id and the name.

In the application illustrated in this chapter, the main module orders.4gl will call the display_custlist() function to retrieve a customer selected by the user.

01   ON ACTION zoom1
02     CALL display_custlist() RETURNING id, name 
03     IF (id > 0) THEN
04         ...

Here is the complete source code.

Module custlist.4gl:

001 SCHEMA custdemo 
002
003 TYPE cust_t RECORD
004            store_num     LIKE customer.store_num,
005            store_name    LIKE customer.store_name,
006            city          LIKE customer.city 
007        END RECORD
008 
009 DEFINE cust_arr DYNAMIC ARRAY OF cust_t 
010 
011 FUNCTION custlist_fill(where_clause)
012   DEFINE where_clause STRING
013   DEFINE idx SMALLINT
014   DEFINE cust_rec cust_t 
015 
016   DECLARE custlist_curs CURSOR FROM
017     "SELECT store_num, store_name, city "||
018     "  FROM customer"||
019     "  WHERE "||where_clause||
020     " ORDER BY store_num"
021 
022   LET idx = 0
023   CALL cust_arr.clear()
024   FOREACH custlist_curs INTO cust_rec.*
025     LET idx = idx + 1
026     LET cust_arr[idx].* = cust_rec.*
027   END FOREACH
028 
029 END FUNCTION
030   
031 FUNCTION display_custlist()
033   DEFINE ret_num LIKE customer.store_num 
034   DEFINE ret_name LIKE customer.store_name 
035   DEFINE where_clause STRING
036   DEFINE idx SMALLINT
037 
038   OPEN WINDOW wcust WITH FORM "custlist"
039 
040   LET ret_num = 0
041   LET ret_name = NULL
042 
043   DIALOG ATTRIBUTES(UNBUFFERED)
044 
045      CONSTRUCT BY NAME where_clause ON customer.store_name 
046      END CONSTRUCT
047 
048      DISPLAY ARRAY cust_arr TO sa_cust.* 
049      END DISPLAY
050 
051      BEFORE DIALOG
052         CALL custlist_fill("1 = 1")
053 
054      ON ACTION fetch 
055         CALL custlist_fill(where_clause)
056 
057      ON ACTION accept 
058         LET idx = DIALOG.getCurrentRow("sa_cust")
059         IF idx > 0 THEN
060            LET ret_num = cust_arr[idx].store_num 
061            LET ret_name = cust_arr[idx].store_name 
062            EXIT DIALOG
063         END IF
064 
065      ON ACTION cancel 
066         EXIT DIALOG
067 
068   END DIALOG
069   
070   CLOSE WINDOW wcust 
071 
072   RETURN ret_num, ret_name 
073 
074 END FUNCTION

Note:

Line 001 defines the database schema to be used by this module.
Lines 003 thru 007 define the cust_t TYPE as a RECORD with three members declared with a LIKE reference to the database column.
Line 009 defines the cust_arr program array with the type defined in previous lines.
Lines 011 thru 029 define the custlist_fill() function which fills cust_arr with the values of database rows.
- Lines 016 thru 020 declare the custlist_curs SQL cursor by using the where_clause condition passed as the parameter.
- Lines 022 thru 027 fetch the database rows into cust_arr.
Lines 031 thru 074 implement the display_custlist() function to be called by the main module.
- Lines 040 and 041 initialize the ret_num and ret_name variables. If the user cancels the dialog, the function will return these values to let the caller decide what to do.
- Lines 043 thru 068 define a DIALOG instruction implementing the controller of the form.
  - Lines 045 thru 046 define the CONSTRUCT sub-dialog controlling the customer.store_name query field.
  - Lines 048 thru 049 define the DISPLAY ARRAY sub-dialog controlling the sa_cust screen array.
  - Lines 051 thru 052 implement the BEFORE DIALOG trigger, to fill the list with an initial result set by passing the query criteria as "1 =1" to the cust_list_fill() function.
  - Lines 054 thru 055 implement the fetch ON ACTION trigger, executed when the user presses the fe button in the form, to fill the list with a result set by passing the query criteria in where_clause to the cust_list_fill function.
  - Lines 057 thru 063 implement the accept ON ACTION trigger, executed when the user validates the dialog with the OK button or with a double-click in a row of the list. The code initializes the return values ret_num and ret_name with the current row.
  - Lines 065 thru 066 implement the cancel ON ACTION trigger, to leave the dialog when the user hits the Cancel button.
- Line 072 returns the values of the ret_num and ret_name variables.