Screen records

Syntax

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

where field-list is:

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

record-name is the name of an explicit screen record or screen array.
size is an integer representing the number of records in the screen array.
field-name is a field identifier as defined in the right operand of a field definition in the ATTRIBUTES section.
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).
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. 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.

Like the name of a screen field, the identifier of a screen record must be unique within the form, and it has a scope that 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 videoshop
LAYOUT
GRID
{
  Customer id: [f001     ]
  Name:        [f002                          ]
  Create date: [f003     ]
}
END
END
TABLES
customer
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 called "formonly".

Screen arrays

A screen array is similar to a screen record, except that it defines a additional size. Screen arrays are typically used to reference rows in a static list of fields defined in the LAYOUT section. Each row of a screen array is a screen record. Each column of a screen array consists of fields with the same field tag in the LAYOUT section.

The size value must be equal to the number of lines of the static list of field tags in the layout of the form. For example, a GRID container might represent a set fields organized in columns like this:

LAYOUT
GRID
{
  OrdId      Date        Total Price 
 [f001      |f002       |f003       ]
 [f001      |f002       |f003       ]
 [f001      |f002       |f003       ]
 [f001      |f002       |f003       ]
}
END
END

This example requires a size of 4 when defining the corresponding screen array:

INSTRUCTIONS
SCREEN RECORD sr_orders[4]
(
 order.ord_id,
 order.ord_date,
 order.ord_total
);
END

You cannot define multiple screen arrays for the same TABLE definition. Only one SCREEN RECORD specification is allowed.

Screen arrays must specify a size when referencing fields that define a static list in the layout. When referencing the columns of a variable-size record list container such as a TABLE or a TREE, the corresponding screen array must be defined without a size:

LAYOUT
TABLE
{
  OrdId      Date        Total Price 
 [f001      |f002       |f003       ]
 [f001      |f002       |f003       ]
 [f001      |f002       |f003       ]
 [f001      |f002       |f003       ]
}
END
END

This TABLE layout does not require a size specification when defining the corresponding screen array:

INSTRUCTIONS
SCREEN RECORD sr_orders
(
 order.ord_id,
 order.ord_date,
 order.ord_total
);
END

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.

Screen records are usually not referenced in programs within single record input statements, because program variable to form field binding is typically done by name with the INPUT BY NAME instruction.

Screen array names are typicaly referenced in programs within interactive dialog controlling a list of records such as DISPLAY ARRAY and INPUT ARRAY. The current form must include that named screen array.