Input length of form fields

Field input length defines the amount of characters the user can type in a form field.

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.

Note: 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

The field input length is defined from:

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

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.

Note: In this section, the term "character width" relates to the horizontal sizes of characters, especially in a fixed font size. Typically, the width of an Chinese character is 2, while characters of occidental languages usually have a width of 1. 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.

For example:

When using a Single Byte Character Set (SBCS) like ISO-8859-15 (and BLS): Each characters of this codeset uses one byte (and has a width of 1). A field with an input length of 5 cells can hold 5 characters of this codeset.
When using a Chinese BIG5 encoding (and BLS): Latin characters (a,b,c) use one byte each, while Chinese characters use 2 bytes. A field with an input length of 5 cells can hold:
- 5 Latin characters (5x1B=5B),
- 3 Latin characters and 1 Chinese character (3x1B+1x2B=5B),
- 1 Latin charater and 2 Chinese characters (1x1B+2x2B=5B),
- it cannot hold 3 Chinese characters (3x2B=6B > 5B).
When using UTF-8 and BLS (not recommended, use CLS with UTF-8): ASCII characters (like "e") use one byte, Latin acute characters (like "é") use 2 bytes and Chinese characters use 3 bytes. A field with an input length of 5 cells can hold:
- 5 ASCII characters (5x1B=5B),
- 1 ASCII character and 2 Latin acute characters (1x1B+2x2B=5B),
- 2 ASCII characters and 1 Chinese character (2x1B+1x3B=5B),
- it cannot hold 3 Chinese characters (3x3B=9B > 5B).

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 truncated when moving to another field or when validating the dialog instruction.

For example:

When using UTF-8 and CLS: ASCII characters (like "e") use one byte, Latin acute characters (like "é") use 2 bytes and Chinese characters use 3 bytes. A field with an input length of 5 cells can hold:
- 5 Latin characters (5x1W=5W),
- 3 Latin characters and one Chinese character (3x1W+1x2W=5W),
- 2 Chinese characters (2x2W=4W < 5),
- it cannot hold 3 Chinese characters (3x2W=6W > 5).

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 brackets:

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 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 or STRING, by default, the input length is defined by the form field width. 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 6, the maximum input length will be a width of 20 instead of 6.

Note: Using the SCROLL attribute must be an exception: it is recommended to allow a size for form fields 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.

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 this 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 allows 10 characters.