The DISPLAY ARRAY Statement

The DISPLAY ARRAY statement lets the user view the contents of an array of records, scrolling through the display.

The example defines a program array of records, each record having members that correspond to the fields of the screen records defined in the form specification file. The DISPLAY ARRAY statement displays all the records in the program array into the rows of the screen array. Typically the program array has many more rows of data than will fit on the screen.

The COUNT attribute

When using a static array, the number of rows to be displayed is defined by the COUNT attribute. If you do not use the COUNT attribute, the runtime system cannot determine how much data to display, and so the screen array remains empty.

When using a dynamic array, the number of rows to be displayed is defined by the number of elements in the dynamic array; the COUNT attribute is ignored.

Example:

01  DISPLAY ARRAY cust_arr TO sa_cust.*

This statement will display the program array cust_arr to the form fields defined in the sa_cust screen array of the form.

By default, the DISPLAY ARRAY statement does not terminate until the user accepts or cancels the dialog; the Accept and Cancel actions are predefined and display on the form. Your program can accept the dialog instead, using the ACCEPT DISPLAY instruction.

The ARR_CURR function

When the user accepts or cancels a dialog, the ARR_CURR built-in function returns the index (subscript number) of the row in the program array that was selected (current).

Example Library module: cust_lib.4gl

The cust_lib.4gl module contains the library function display_custarr, that can be reused by other programs that reference the customer table.

Module cust_lib.4gl:
01 SCHEMA custdemo 
02
03 FUNCTION display_custarr()
04
05   DEFINE cust_arr DYNAMIC ARRAY OF RECORD
06          store_num    LIKE customer.store_num,
07          store_name   LIKE customer.store_name,
08          city         LIKE customer.city,
09          state        LIKE customer.state,
10          zip_code      LIKE customer.zip_code,
11          contact_name LIKE customer.contact_name,
12          phone        LIKE customer.phone 
13    END RECORD,
14          cust_rec RECORD
15          store_num    LIKE customer.store_num,
16          store_name   LIKE customer.store_name,
17          city         LIKE customer.city,
18          state        LIKE customer.state,
19          zip_code      LIKE customer.zip_code,
20          contact_name LIKE customer.contact_name,
21          phone        LIKE customer.phone 
22    END RECORD,
23    ret_num LIKE customer.store_num,
24    ret_name LIKE customer.store_name,
25    curr_pa SMALLINT
26  
27    OPEN WINDOW wcust WITH FORM "manycust"
28
29    DECLARE custlist_curs CURSOR FOR
30      SELECT store_num, 
31            store_name,
32            city, 
33            state, 
34            zip_code, 
35            contact_name, 
36            phone 
37        FROM customer 
38        ORDER BY store_num 
39
40  
41   CALL cust_arr.clear()
42   FOREACH custlist_curs INTO cust_rec.*
43      CALL cust_arr.appendElement()
44      LET cust_arr[cust_arr.getLength()].* = cust_rec.*
45   END FOREACH
46
47   LET ret_num = 0
48   LET ret_name = NULL
49
50   IF (cust_arr.getLength() > 0) THEN 
51      DISPLAY ARRAY cust_arr TO sa_cust.*
52      IF NOT INT_FLAG THEN
53         LET curr_pa = arr_curr()
54         LET ret_num = cust_arr[curr_pa].store_num 
55         LET ret_name = cust_arr[curr_pa].store_name 
56      END IF
57   END IF
58
59   CLOSE WINDOW wcust 
60   RETURN ret_num, ret_name 
61
62 END FUNCTION
Note:
  • Lines 05 thru 13 define a local program array, cust_arr.
  • Lines 14 thru 22 define a local program record, cust_rec. This record is used as temporary storage for the row data retrieved by the FOREACH loop in line 42.
  • Lines 23 and 24define local variables to hold the store number and name values to be returned to the calling function.
  • Line 25 defines a variable to store the value of the program array index.
  • Line 27 opens a window with the form containing the array.
  • Lines 29 thru 38 DECLARE the cursor custlist_curs to retrieve the rows from the customer table.
  • Line 40 sets the variable idx to 0, this variable will be incremented in the FOREACH loop.
  • Line 41 clear the dynamic array.
  • Line 42 uses FOREACH to retrieve each row from the result set into the program record, cust_rec.
  • Lines 43 thru 44 are executed for each row that is retrieved by the FOREACH. They append a new element to the array cust_arr, and transfer the data from the program record into the new element, using the method getLength to identify the index of the element. When the FOREACH statement has retrieved all the rows the cursor is closed and the FOREACH is exited.
  • Lines 47 and 48 Initialize the variables used to return the customer number and customer name.
  • Lines 50 thru 57 If the length of the cust_arr array is greater than 0, the FOREACH statement did retrieve some rows.
  • Line 52 DISPLAY ARRAY turns control over to the user, and waits for the user to accept or cancel the dialog.
  • Line 52 The INT_FLAG variable is tested to check if the user validated the dialog.
  • Line 53 If the user has validated the dialog, the built-in function ARR_CURR is used to store the index for the program array element the user had selected (corresponding to the highlighted row in the screen array) in the variable curr_pa.
  • Lines 54 and 55 The variable curr_pa is used to retrieve the current values of store_num and store_name from the program array and store them in the variables ret_num and ret_name.
  • Line 59 closes the window.
  • Line 60 returns ret_num and ret_name to the calling function.