Screen records / arrays

Syntax

SCREEN RECORD record-name [ [ size ] ] ( field-list )

{ table.*
| field-name
| first-field [ {THROUGH|THRU} last-field ]
[,...] }

1. record-name is the name of an explicit screen record or screen array.
2. size is an integer representing the number of records in the screen array. If the size is not specified in the SCREEN RECORD definition, it is deduced from the corresponding list container in the form layout.
3. field-name is a field identifier as defined in the right operand of a field definition in the ATTRIBUTES section.
4. first-field and last-field are field identifiers like field-name. This notation instructs the form compiler to take all the fields defined between the first and last field (inclusive).
5. table is the name or alias of a table, synonym, or view, as declared in the TABLES section. This notation instructs the form compiler to build the screen record with all fields declared in the ATTRIBUTES section for the given table.

Usage

Screen records and screen arrays are defined with the SCREEN RECORD keywords in the INSTRUCTIONS section of a form specification file to name a group of fields.

Screen records

A screen record is a named group of fields that screen interaction statements of the program can reference as a single object.

A screen record is the form-counterpart of a RECORD variable in your program.

By establishing a correspondence between a set of screen fields (the screen record) and a set of program variables (typically a program record), you can pass values between the program and the fields of the screen record.

In many applications, it is convenient to define a screen record that corresponds to a row of a database table.

SCHEMA myshop
LAYOUT
...
    [f1        ]  <-----------+
...                           |
END                           |
TABLES                        |
customer                      |
END                           |
ATTRIBUTES                    |
...                           |
f1 = customer.cust_name;  ----+
...             ^-----------------+
END                               |
INSTRUCTIONS                      |
SCREEN RECORD sr_customer         |
(...                              |
 customer.cust_name,    ----------+
 ...);
END

Like the name of a screen field, the identifier of a screen record must be unique within the form, and its scope is restricted to when its form is open. Interactive statements can reference record-name only when the screen form that includes it is being displayed. The form compiler returns an error if record-name is the same as the name or alias of a table in the TABLES section.

SCHEMA myshop
LAYOUT
GRID
{
  Customer id: [f1     ]
  Name:        [f2                          ]
  Create date: [f3     ]
}
END
END

TABLES
customer
END

ATTRIBUTES
f1 = customer.cust_id;
f2 = customer.cust_name;
f3 = customer.cust_crea;
END

INSTRUCTIONS
SCREEN RECORD sr_customer
(
 customer.cust_id,
 customer.cust_name,
 customer.cust_crea
);
END

Default screen records

The form compiler builds default screen records that consist of all the screen fields linked to the same database table within a given form. A default screen record is automatically created for each table that is used to reference a field in the ATTRIBUTES section.

The components of the default record correspond to the set of display fields that are linked to columns in that table. The name of the default screen record is the table name (or the alias, if you have declared an alias for that table in the TABLES section).

For example, all the fields linked to columns of the "customer" table constitute a default screen record whose name is "customer".

If a form includes one or more FORMONLY fields, those fields constitute a default screen record with the name "formonly".

Screen arrays

A screen array is a screen record with a dimension, to handle a list of records in layout containers such as TABLE, TREE, SCROLLGRID, or static field lists.

A screen array is the form-counterpart of a DYNAMIC ARRAY OF RECORD variable in your program.

Each row of a screen array is a screen record. Each column of a screen array consists of fields with the same field tag ([f1 ]) in the LAYOUT section.

SCREEN RECORD sa_custlist[20]
(
 customer.cust_id,
 customer.cust_name,
 customer.cust_crea
);

If the size is specified, it must be equal to the number of lines of the list container in the layout of the form.

INPUT cust_record.* FROM sa_custlist[arr_curr()].*

LAYOUT
TABLE
{
[f1      |f2       |f3       ]
[f1      |f2       |f3       ]
[f1      |f2       |f3       ]
[f1      |f2       |f3       ]
}
END
END
...
ATTRIBUTES
f1 = customer.cust_id;
f2 = customer.cust_name;
f3 = customer.cust_crea;
END
...

With the above TABLE container, when specified, the screen array size must be 4:

SCREEN RECORD sa_custlist[4]
(
 customer.cust_id,
 customer.cust_name,
 customer.cust_crea
);

SCREEN RECORD sa_custlist
(
 customer.cust_id,
 customer.cust_name,
 customer.cust_crea
);

Using screen records and screen arrays in programs

Screen records and screen arrays can display program records. If the fields in the screen record have the same sequence of data types as the columns in a database table, you can use the screen record to simplify operations that pass values between program variables and rows of the database.

DEFINE cust_rec RECORD LIKE customer.*
...
INPUT BY NAME cust_rec.*
    ...

DEFINE cust_arr DYNAMIC ARRAY OF RECORD LIKE customer.*
...
DISPLAY ARRAY cust_arr TO sa_custlist.*
    ...