DISPLAY ARRAY

The DISPLAY ARRAY statement displays program array values in a screen array, so that the user can scroll through the screen array.

4GLREF00000136.gif

record array is the identifier of a program array of RECORD variables.

screen array is the identifier of a screen array.

To use the DISPLAY ARRAY statement, you must do the following:

  1. Define the screen array in the form specification file.

  2. Use DEFINE to declare an array of program records, whose members correspond in name, data type, and order to the screen array fields.

  3. Open and display the screen form with either of the following:

The OPEN FORM and DISPLAY FORM statements.

The OPEN WINDOW statement with the WITH FORM clause.

  1. Fill the program array with data to be displayed, counting the number of program records being filled with retrieved data.

  2. Call the SET_COUNT(x) function, with x the number of filled records.

  3. Use the DISPLAY ARRAY statement to display the program array values in the screen array fields.

The SET_COUNT( ) function sets the initial value of the ARR_COUNT( ) function. If you do not call SET_COUNT( ), then 4GL cannot determine how much data to display, and so the screen array remains empty.

The DISPLAY ARRAY statement binds the screen array fields to the member records of the program array. The number of variables in each record of the program array must be the same as the number of fields in each screen record (that is, in a single row of the screen array). Each mapped variable must have the same data type or a compatible data type as the corresponding field.

The size of the screen array (from the form specification file) determines the number of program records that 4GL displays at one time on the screen. The size of the program array determines how many retrieved rows of data the program can store. The size of the program array can exceed the size of the screen array. In this case, the user can scroll through the rows on the form.

When 4GL encounters a DISPLAY ARRAY statement, it does the following:

  1. Displays the program array values in the screen array fields.

  2. Moves the cursor to the first field in the first screen record.

  3. Waits for the user to press a scroll key (by default, F3 to scroll forward, or F4 to scroll backwards) or the Next Page or Previous Page keys or mouse buttons, or to choose Accept key.

Since the DISPLAY ARRAY statement does not terminate until the user presses the Accept or Interrupt key, you may want to display a message informing the user.

By default, 4GL displays variables and constants as follows:

Right-justifies number values in a screen field.

Left-justifies character values in a screen field.

Truncates the displayed value, if a character value is longer than the field.

Fills the field with asterisks ( * ) to indicate an overflow, if a number value is larger than the field can display.

If the field contains a BYTE value, displays <byte value> in the field.

The ON KEY Blocks

The ON KEY keywords specify a block of statements to be executed when the user selects one of the specified keys. This is the syntax of the ON KEY block:

4GLREF00000137.gif

key name is one or more of these keywords, in uppercase or lowercase letters, separated by commas, to specify a key:

ACCEPT
HELP
NEXT or
RETURN
DELETE
INSERT
NEXTPAGE
RIGHT
DOWN
INTERRUPT
PREVIOUS or
TAB
ESC or ESCAPE
LEFT
PREVPAGE
UP
F1 through F64

 
 
 
CONTROL-char (except A, D, H, I, J, L, M, R, or X)

 
 
 
statement is an SQL statement or some other 4GL statement.

For key name you can also substitute the NEXTPAGE keyword as a synonym for NEXT, and PREVPAGE as a synonym for PREVIOUS.

References

ATTRIBUTE

DISPLAY

INPUT ARRAY

OPEN WINDOW

OPTIONS

SCROLL