Field input length

The input length is used by interactive instructions to limit the size of the data that can be entered by the user. Additionally, when you display a program variable to a form field with the DISPLAY TO or DISPLAY BY NAME instruction, the 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.

The input length is defined by the width of the form item tag in the form, and the data type of the program variable bound to the form field. The width of the item tag is defined by the number of cell positions used between the square braces:

     [f01 ]    -- width = 4 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, or a character data type such as CHAR or VARCHAR, by default, the input length is defined by the width of the form field. This means, the maximum number of characters a user can input is defined by the size of the item-tag in the form. For character data types, the SCROLL attribute can be used to bypass this limitation 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 an item-tag large as 3 characters, the input length will be 20 characters instead of 3. 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.

If the program variable is defined with a DATE, DATETIME or INTERVAL data type, the input length is the maximum of the format length and the width of the form field defined by its item tag. For DATETIME and INTERVAL fields, the format length is defined by the FORMAT attribute, or by default the format of the value. For DATE fields, the format length is defined by the DBDATE environment variable when the FORMAT attribute is not used.

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, a field having a width of 6 cells in the form file, represents a maximum input length of 6 bytes. In BIG5, Latin characters (a,b,c) use one byte each, while Chinese ideograms use 2 bytes. So, 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.