Input length of form fields

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.

The field input length also matters when displaying a program variable to a form field with the DISPLAY TO or DISPLAY BY NAME instruction, that may truncate the text resulting from the data conversion.

The field input length is also used to define the input limit when using the AUTONEXT attribute.

For non-character types, if the resulting text does not fit into the input length, the field will show * stars to indicate an overflow.

Input length definition

Trailing blanks in input fields

When the user enters data in a form field, the runtime system automatically truncates the trailing blanks.

The resulting value in the corresponding program variable or in the field input buffer (DIALOG.getFieldBuffer()) is right-trimmed.

Length semantics and input length

Character string input limit depends also from the Byte Length Semantics (BLS) or Char Length Semantics (CLS) usage.

In this section, the term "character width" relates to the horizontal sizes of characters, especially in a fixed font size. This concept is also known as "fullwidth" versus "halfwidth" characters. Typically, the width of a Chinese logogram is twice the width of characters of occidental languages such as A,B,C. For more details, see Character size unit and length semantics.

Using Byte Length Semantics

When using BLS (the default), the input length represents the maximum number of bytes that the field can hold, in the current character set of the runtime system.

Using Char Length Semantics

When using character length semantics (FGL_LENGTH_SEMANTICS=CHAR), the input length is expressed in character width. The runtime system will truncate the entered text by computing the total width of the string. Trailing characters that do not fit into the field input length (interpreted as a maximum width) will be rejected by the runtime and an input error will be displayed to the user.

Field width definition

The input length is by default 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 brackets:

LAYOUT
GRID
{
   123
  [f1 ]    -- width = 3 cells
   123456
  [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, for a DATE data type, an EDIT 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 form field width. For example, if the form item tag defines a width of 5 cells and is bound to an INTEGER variable by the input dialog, even if the integer variable can hold larger values, the user can only enter 5 digits or the negative sign and 4 digits. As result, the value range will be -9999 to 99999.

If the program variable is defined with a DATE, DATETIME or INTERVAL data type, the input length is defined by the form field width. The user can potentially enter any kind of characters. However, when the date/time field is checked by the dialog instruction, it must represent a valid date/time value.

If the program variable is defined with character data type such as CHAR, VARCHAR, TEXT or STRING, by default, the input length is defined by the form field width, without exceeding the length of the character string program variable. The SCROLL attribute can be used to bypass this limit and force the input length to be as large as the program variable can hold. For example, when using a VARCHAR(20) variable with a form field defined with 6 cells, the maximum input length is by default a character width of 6 (= 6 Latin chars or 3 Chinese ideograms). When using SCROLL, the maximum input length will be 20 bytes or 20 chars, depending on FGL_LENGTH_SEMANTICS. Using the SCROLL attribute must be an exception: define form fields with a number of cells that can hold all possible characters, that can fit in the corresponding program variable. However, for some item types like TEXTEDIT, the SCROLL attribute behavior is implicit when the element is stretchable or allows scrollbars.

To compute the width of the form item in the AUI tree, specific rules apply for some kind of form item types like DATEEDIT, COMBOBOX and BUTTONEDIT, see Widget width inside hbox tags for more details.