Field input length

Input length basics

The field input length is used by interactive instructions to limit the size of the data that can be entered by the user. Additionally, when displaying a program variable to a form field with the DISPLAY TO or DISPLAY BY NAME instruction, the field input length is used to truncate the text resulting from the data conversion. For non-character values, if the resulting text does not fit into the input length, the field will show * stars to indicate an overflow.

Length semantics for character fields

When using byte length semantics (the default), the input length represents the number of bytes in the current character set. In other words, it is the number of bytes used by the character string in the character set used by the runtime system. For example, when using a Chinese BIG5 encoding, Latin characters (a,b,c) use one byte each, while Chinese ideograms use 2 bytes: If the input length is 6, the user can enter 6 Latin characters like "abcdef", or 4 Latin characters and one Chinese ideogram, or 3 Chinese ideograms.

When using character length semantics (FGL_LENGTH_SEMANTICS=CHAR environment variable), the unit for the input length is in characters. For example, in a UTF-8 character set, if the form field has a width of 6 cells, the field can hold 6 characters, from any alphabet. There is no limitation regarding the number of bytes the UTF-8 encoded string will use.

Input length control

The field input length is defined according to:

The type of layout (grid-based or stack-based layout)
The data type of the program variable bound to field by the interactive instruction.
In grid-based layout, the usage of the SCROLL attribute for CHAR/VARCHAR/STRING types.

Field width definition in grid-based containers

In a grid-based container, by default the input length is defined by the width of the field item tag in the LAYOUT section. The width of a field item tag is defined by the number of cell positions used between the square braces:

LAYOUT
GRID
{
  [f1 ]    -- width = 3 cells
  [f2    ] -- width = 6 cells
  ...

As a general rule, forms must define fields that can hold all possible values that the corresponding program variable can contain. For example, a DATE field must be defined with 10 cells, to hold date values in the format DD/MM/YYYY.

If the program variable is defined with a numeric data type like INTEGER or DECIMAL, the input length is defined by the width of the field defined in the form.

If the program variable is defined with character data type such as CHAR, VARCHAR or STRING, by default, the input length is defined by the width of the field defined in the form. The SCROLL attribute can be used to bypass this limit and force the input length to be as large as the program variable. For example, when using a CHAR(20) variable with a form field defined with width of 3 characters, the input length will be 20 characters instead of 3.

Note: Using the SCROLL attribute must be an exception: Form fields should be large enough to hold all possible characters that fit in the corresponding program variable. Note also that for specific item types like TEXTEDIT, the SCROLL attribute behavior is implicit when the element is stretchable or allows scrollbars.

If the program variable is defined with a DATE, DATETIME or INTERVAL data type, the input length is defined by the data type. For example. a DATE field will allow 10 characters.

Field width definition in stack-based containers

In a stack-based layout, the input length is defined by the data type of the program variable.

In the next example, the cust_id field will allow numeric input length in the range of the INTEGER data type, and the cust_name field will allow up to 50 characters:

-- Form file
LAYOUT
 STACK
   EDIT customer.cust_id;
   EDIT customer.cust_name;
 ...

-- Program
MAIN
   DEFINE cust_rec RECORD
              cust_id INTEGER,
              cust_name VARCHAR(50)
          END RECORD
   ...
   INPUT BY NAME cust_rec.*
      ...

If the program variable is defined with a numeric data type like INTEGER or DECIMAL or a character data type such as CHAR, VARCHAR or STRING, the input length is defined by the value range of the program variable. For numeric values, you can use the INCLUDE attribute to define the range of possible values.

If the program variable is defined with a DATE, DATETIME or INTERVAL data type, the input length is defined by the data type. For example. a DATE field will allow 10 characters.