Back to Contents

Form Specification File Attributes

Summary:

• Attributes Summary

See also: Form Specification Files.

Attributes Summary

ACCELERATOR Attribute

Purpose:

The ACCELERATOR attribute defines the primary accelerator key of an action default item.

Syntax:

Notes:

1. key can be a function key (F11) or a letter (A, B).

ACCELERATOR2 Attribute

Purpose:

The ACCELERATOR2 attribute defines the secondary accelerator key of an action default item.

Syntax:

Notes:

1. key can be a function key (F11) or a letter (A, B).

ACCELERATOR3 Attribute

Purpose:

The ACCELERATOR3 attribute defines the third accelerator key of an action default item.

Syntax:

Notes:

1. key defines the accelerator key as described in Accelerators

ACTION Attribute

Purpose:

The ACTION attribute defines the name of the action to be sent to the program when the user activates the form item.

Syntax:

Notes:

1. action-name is an identifier that defines the name of the action to be sent.

Tips:

1. Try to use abstract action names instead of key identifiers.

Example:

01 BUTTONEDIT f001 = customer.state, ACTION = print;

AUTOSCALE Attribute

Purpose:

The AUTOSCALE attribute causes the form element contents to automatically scale to the size given to the item.

Syntax:

Notes:

1. For images, this attribute forces the image to be stretched to fit in the area reserved for the image.

AUTONEXT Attribute

Purpose:

The AUTONEXT attribute causes the cursor to automatically advance during input to the next field when the current field is full.

Syntax:

Notes:

1. If data values entered in the field do not meet the requirements of other field attributes like INCLUDE or PICTURE, the cursor does not automatically move to the next field but remains in the current field, with an error message.

Tips:

1. AUTONEXT is particularly useful with character fields in which the input data is of a standard length, such as numeric postal codes or the abbreviations in the state table. It is also useful if a character field has a length of 1 because only one keystroke is required to enter data and move to the next field.

CENTURY Attribute

Purpose:

The CENTURY attribute specifies how to expand abbreviated one- and two-digit year specifications in a DATE and DATETIME field. Expansion is based on this setting (and on the year value from the system clock at runtime).

Syntax:

Notes:

1. The CENTURY attribute can specify any of four algorithms to expand abbreviated years into four-digit year values that end with the same digits (or digit) that the user has entered.
2. CENTURY supports the same settings as the DBCENTURY environment variable but with a scope that is restricted to a single field.
3. If the CENTURY and DBCENTURY settings are different, CENTURY takes precedence.

Warnings:

1. Unlike DBCENTURY, the CENTURY attribute is not case sensitive. However, we recommend that you use uppercase letters in the attribute.

CLASS Attribute

Purpose:

The CLASS attribute is used to define the behavior of a field.

Syntax:

Notes:

1. identifier is a predefined keyword defining the class of the field.

Supported field classes:

Warnings:

1. It is not recommended that you use this attribute; use new form items instead.

COLOR Attribute

Purpose:

The COLOR attribute defines the foreground color of the text displayed by a form element.

Syntax:

Notes:

1. color-name can be: BLACK, BLUE, CYAN, GREEN, MAGENTA, RED, WHITE, and YELLOW.

Warnings:

1. For backward compatibility, in unqualified form fields (without an item type), color-name can be combined with an intensity keyword: REVERSE, LEFT, BLINK, and UNDERLINE. This is deprecated; you should use simple color names only, without video attributes.

Example:

01 EDIT f001 = customer.name, COLOR = RED;

COLOR WHERE Attribute

Purpose:

The COLOR WHERE attribute defines a condition to set the foreground color dynamically.

Syntax:

Notes:

1. color-name can be: BLACK, BLUE, CYAN, GREEN, MAGENTA, RED, WHITE, and YELLOW.
2. boolexpr defines a Boolean expression with a restricted syntax.
3. The Boolean expression is automatically evaluated at runtime to check when the color attribute must be set.

Warnings:

1. The condition in COLOR WHERE can only reference the field for which the attribute is set.
2. For backward compatibility, in unqualified form fields (without an item type), color-name can be combined with an intensity keyword: REVERSE, LEFT, BLINK, and UNDERLINE. This is deprecated; you should use simple color names only, without video attributes.
3. The COLOR WHERE attribute may not be supported in all situations. For example, it cannot be supported in TABLE columns.

Example:

01 EDIT f001 = item.price, COLOR = RED WHERE f001>100;

CONFIG Attribute

Purpose:

The CONFIG attribute is used with the WIDGET attribute to define the behavior and decoration of the field.

Syntax:

Notes:

1. The CONFIG attribute can only be used with the WIDGET attribute. It is ignored if WIDGET is not used.
2. parameter is the value of a configuration parameter.
3. Configuration parameters are separated by blanks.
4. If a configuration parameter holds blank characters, you must use {} curly braces to delimit the parameter value.
5. See the WIDGET attribute for more details about configuration.

COMMENT Attribute

Purpose:

The COMMENT attribute defines text that can be shown when the element becomes current.

Syntax:

Notes:

1. string is the text to be displayed.
2. string can be a localized string.
3. The screen location where the message is displayed depends on external configuration. It can be displayed in the COMMENT LINE, or in the STATUSBAR when using a graphical user interface.

Tips:

1. The most common use of the COMMENT attribute is to give information or instructions to the user. This is particularly appropriate when the field accepts only a limited set of values.

Warnings:

1. If the OPEN WINDOW statement specifies COMMENT LINE OFF, any output to the comment area is hidden even if the window displays a form that includes fields that include the COMMENT attribute.

Example:

01 EDIT f001 = customer.name, COMMENT = "The customer name";

DEFAULT Attribute

Purpose:

The DEFAULT attribute assigns a default value to a field during data entry.

Syntax:

Notes:

1. value can be any literal expression supported by the form compiler.
2. value can be TODAY to specify the current system date as default.
3. value can be CURRENT to specify the current system datetime as default.
4. Default values have no effect when you execute the INPUT statement using the WITHOUT DEFAULTS option. In this case, the runtime system displays the values in the program variables list on the screen. The situation is the same for the INPUT ARRAY statement, except that the default values are displayed when the user inserts a new row.
5. If the field is FORMONLY, you must also specify a data type when you assign the DEFAULT attribute to a field.
6. If both the DEFAULT attribute and the REQUIRED attribute are assigned to the same field, the REQUIRED attribute is ignored.
7. If you do not use the WITHOUT NULL INPUT option in the DATABASE section, all fields default to null values unless you have specified a DEFAULT attribute.

Warnings:

1. DATETIME and INTERVAL literals are not supported.

Example:

01 EDIT f001 = order.orderdate, DEFAULT = TODAY;

DEFAULTVIEW Attribute

Purpose:

The DEFAULTVIEW attribute defines if the default view (button) must be displayed for an action.

Syntax:

Notes:

1. AUTO means that the view must be displayed if no explicit action view is used for that action. This is the default.
2. YES indicates that no default action view must be displayed for this action.
3. NO indicates that a default action view must be always displayed for this action.

DISPLAY LIKE Attribute

Purpose:

The DISPLAY LIKE attribute takes column attributes defined in the database schema files and applies them to a field.

Syntax:

Notes:

1. table is the optional table name to qualify the column.
2. column is the name of the column to be used to search for display attributes.
3. Specifying this attribute is equivalent to listing all the attributes that are assigned to table.column in the database schema file generated from the syscolatt table.
4. Display attributes are automatically taken from the schema file if the field is linked to table.column in the field name specification.

Warnings:

1. The DISPLAY LIKE clause is evaluated at compile time, not at runtime. If the database schema file changes, you might need to recompile a program that uses the LIKE clause. Even if all of the fields in the form are FORMONLY, this attribute requires the form compiler to access the database schema file that contains the description of table.

Example:

01 EDIT f001 = FORMONLY.fullname, DISPLAY LIKE customer.custname;

HIDDEN Attribute

Purpose:

The HIDDEN attribute indicates that the element should not be displayed.

Syntax:

Notes:

1. HIDDEN set the underlying item attribute to 1.
2. HIDDEN=USER set the underlying item attribute to 2.

Warnings:

1. When you set a hidden attribute for a form field, the model node gets the hidden attribute, not the view node.

Usage:

By default all elements are visible. You can use the HIDDEN attribute to hide an element, for example a form field or a groupbox. The runtime system handles hidden form fields. If you write an INPUT statement using a hidden field, the field is ignored as if it was declared as NOENTRY. Programs may change the visibility of form fields dynamically with the ui.Form built-in class.

When using the HIDDEN keyword only, the underlying item attribute is set to 1. The value 1 indicates that the element is hidden to the user without the possibility of showing the element, for example with the context menu of table headers. In this hidden mode, the UNHIDABLE attribute is ignored by the front end.

When using HIDDEN=USER, the underlying item attribute is set to 2. The value 2 indicates that the element is hidden by default, but the user can show/hide the element as needed.

Example:

01 EDIT f001 = FORMONLY.field1, HIDDEN;
02 EDIT col1 = FORMONLY.column1, HIDDEN=USER;

HEIGHT Attribute

Purpose:

The HEIGHT attribute defines an explicit height of a form element.

Syntax:

Notes:

1. integer defines the height of the element.

Usage:

By default, the size of an element is defined in characters and automatically computed by the form compiler according to the size of the form element in the layout.

For tables, the default height is defined by the number of lines used in the table layout. You can overwrite this default by specifying the HEIGHT attribute.

See also: WIDTH.

Example:

01 TABLE t1 ( HEIGHT = 20 )

BUTTONTEXTHIDDEN Attribute

Purpose:

The BUTTONTEXTHIDDEN attribute indicates that the labels of the buttons of this element should not be displayed.

Syntax:

Notes:

1. Use in a TOOLBAR definition, for example, to hide the labels of buttons.

DOWNSHIFT Attribute

Purpose:

Assign the DOWNSHIFT attribute to a character field when you want the runtime system to convert uppercase letters entered by the user to lowercase letters, both on the screen and in the corresponding program variable.

Syntax:

Notes:

1. Because uppercase and lowercase letters have different values, storing character strings in one or the other format can simplify sorting and querying a database.
2. Characters entered by the user are converted in INPUT, INPUT ARRAY and CONSTRUCT instructions.
3. When using single byte runners, the conversion of ASCII characters >127 is controlled by the LC_CTYPE environment variable.
4. The results of conversions between uppercase and lowercase letters are based on the locale settings (LANG).

FORMAT Attribute

Purpose:

You can use the FORMAT attribute with numeric and date time fields to control the format of output displays.

Syntax:

Notes:

1. format-string is a string of characters that specifies a data display format.
2. You must enclose format-string within quotation marks ( " ).
3. Use the PICTURE attribute to format data entered in the field by the user.
4. When using FORMAT the data is right-aligned in the field.
5. If format-string is smaller than the field width, you get a compile-time warning, but the form is usable.
6. When this attribute is not used, environment variable settings define the default format.

Warnings:

1. To follow abstract user interface programming and support internationalization, it is not recommended that you use this attribute.

Numeric formats:

For DECIMAL, SMALLFLOAT, and FLOAT data types, format-string consists of pound signs (#) that represent digits and a decimal point. For example, "###.##" produces at least three places to the left of the decimal point and exactly two to the right.

If the actual number displayed requires fewer characters than format-string specifies, numbers are right-aligned and padded on the left with blanks.

If necessary to satisfy the format-string specification, the number values are rounded before display.

Date formats:

For DATE data types, the runtime system recognizes these symbols as special in format-string:

The form compiler interprets any other characters as literals and displays them wherever you place them within format-string.

These format-string examples and their corresponding display formats for DATE fields display the twenty-third day of September 1999:

Example:

01 EDIT f001 = order.thedate, FORMAT = "mm/dd/yyyy";

FONTPITCH Attribute

Purpose:

This attribute defines the character font type as fixed or variable.

Syntax:

Notes:

1. When using FIXED, you force the characters to have a fixed size.
2. When using VARIABLE, you allow the characters to have a variable size.

Usage:

By default, most front ends use variable width character fonts, but in some cases you might need to use a fixed font. Use this attribute to specify the font pitch for a specific field.

GRIDCHILDRENINPARENT Attribute

Purpose:

This attribute is used for a container to align its children to the parent container.

Syntax:

Usage:

By default, child elements of a container are aligned locally inside the container layout cells. With this attribute, you can force children to be aligned according to the layout cells of the parent container of the container to which you assign this attribute.

This is useful, for example, when you want to align fields across groupboxes defined with Layout Tags inside a GRID:

01 LAYOUT
02   GRID
03   {
04    <G g1                             >
05     Field1 [f1                      ]
06     Field2 [f2                      ]
07     Field3 [f3                      ]
08 
09    <G g2                             >
10     F4     [f4                  ]
11     F5     [f5                  ]
12 
13   }
14   END
15 END
16 ATTRIBUTES
17 GROUP g1 : GRIDCHILDRENINPARENT;
18 GROUP g2 : GRIDCHILDRENINPARENT;
19 EDIT f1 = FORMONLY.field1;
20 EDIT f2 = FORMONLY.field2;
21 EDIT f3 = FORMONLY.field3;
22 EDIT f4 = FORMONLY.field4;
23 EDIT f5 = FORMONLY.field5;
24 END

INCLUDE Attribute

Purpose:

The INCLUDE attribute specifies acceptable values for a field and causes the runtime system to check the data before accepting an input value.

Syntax:

Notes:

1. literal can be any literal expression supported by the form compiler.
2. If the field is FORMONLY, you must also specify a data type when you assign the INCLUDE attribute to a field.

Warnings:

1. DATETIME and INTERVAL literals are not supported.

Example:

01 EDIT f001 = compute.rate, INCLUDE = ( 1 TO 100, 200, NULL);
02 EDIT f002 = customer.state, INCLUDE = ( "AL" TO "GA", "IA" TO "WY" );

INVISIBLE Attribute

Purpose:

The INVISIBLE attribute prevents user-entered data from being echoed on the screen during an interactive statement.

Syntax:

Notes:

1. Characters that the user enters in a field with this attribute are not displayed during data entry. Depending on the front end type, the typed characters are displayed using the blank, star, underscore or dot characters.

Warnings:

1. This attribute does not prevent display instructions like DISPLAY, DISPLAY ARRAY from explicitly displaying data in the field.

IMAGE Attribute

Purpose:

The IMAGE attribute defines the image file to be associated with the form item.

Syntax:

Notes:

1. name can be a simple file name, a path, or an URL to an image server.

Usage:

This attribute is used, for example, to define the image file containing the icon to be displayed in a button or the picture of an image form item.

The name can be a simple file name, a complete or relative path, or an URL ( Uniform Resource Locator) path to an image server.

You can give a complete path with file extension, but it is recommended that you use a simple name or a relative path without file extension so that the system can automatically search for the image file using the specific extension (bmp, gif, ...).

If the image specification is a simple file name, the file is first sought in the pictures directory on the client workstation; if the file is not found, the front-end automatically sends an image request to the runtime system, in order to search for an image on the application server. The runtime system searches for server-side images by using the FGLIMAGEPATH environment variable.

To simplify deployment, you should use server-side images to centralize all images on the application server.

Example:

01 BUTTONEDIT f001 = FORMONLY.field01, IMAGE = "zoom";

KEY Attribute

Purpose:

The KEY attribute is used to define the labels of keys when the field is made current.

Syntax:

Notes:

1. keyname is the name of a key ( like F10, Control-z ).
2. label is the text to be displayed in the button corresponding to the key.
3. See also the KEYS section to define key labels for the whole form.

Example:

01 EDIT f001 = customer.city, KEY F10 = "City list";

NOT NULL Attribute

Purpose:

The NOT NULL attribute indicates that the field does not accept NULL values.

Syntax:

Notes:

1. NOT NULL keywords can also be used in the type definition of FORMONLY fields.

Usage:

This attribute requires only that the field contains a value. If the field contains a default value, the NOT NULL attribute satisfied. To insist on a data entry from the user, combine NOT NULL with the REQUIRED attribute in the field definition, or make sure the corresponding column is defined as REQUIRED in the database schema file.

See also REQUIRED attribute.

Example:

01 EDIT f001 = customer.city, NOT NULL;

NOENTRY Attribute

Purpose:

The NOENTRY attribute prevents data entry in the field during an INPUT or INPUT ARRAY statement.

Syntax:

Notes:

1. The NOENTRY attribute does not prevent data entry into a field during a CONSTRUCT statement (for a Query By Example).

Example:

01 EDIT f001 = order.totamount, NOENTRY;

ORIENTATION Attribute

Purpose:

The ORIENTATION attribute defines if an element is displayed vertically or horizontally.

Syntax:

Example:

01 RADIOGROUP f001 = customer.status, ORIENTATION=HORIZONTAL;

PICTURE Attribute

Purpose:

The PICTURE attribute specifies a character pattern for data entry in a text field and prevents entry of values that conflict with the specified pattern.

Syntax:

Notes:

1. format-string defines the data input pattern of the field.
2. format-string can be any combination of characters, where the characters "A", "#" and "X" have a special meaning.
3. The character "A" specifies any letter (alpha-numeric) character at a given position.
4. The character "#" specifies any digit character at a given position.
5. The character "X" specifies any character at a given position.
6. Any character different from "A", "X" and "#" is treated as a literal. Such characters automatically appear in the field and do not have to be entered by the user.
7. The PICTURE attribute does not require data entry into the entire field. It only requires that whatever characters are entered conform to format-string.
8. When PICTURE specifies input formats for DATETIME or INTERVAL fields, the form compiler does not check the syntax of format-string, but your form will work if the syntax is correct. Any error in format-string, however, such as an incorrect field separator, produces a runtime error.

Example:

01 EDIT f001 = carinfo.number, PICTURE = "AA####-AA(X)";

PIXELWIDTH Attribute

Purpose:

The PIXELWIDTH attribute specifies the initial width of an IMAGE form item in number of pixels.

Syntax:

Notes:

1. pixels is an integer literal defining a number of pixels.

Example:

01 IMAGE i001 = carinfo.picture, PIXELWIDTH = 200;

PIXELHEIGHT Attribute

Purpose:

The PIXELHEIGHT attribute specifies the initial height of an IMAGE form item in a number of pixels.

Syntax:

Notes:

1. pixels is an integer literal defining a number of pixels.

Example:

01 IMAGE i001 = carinfo.picture, PIXELHEIGHT = 200;

PROGRAM Attribute Console Only!

Purpose:

The PROGRAM attribute can specify an external application program to work with screen fields of data type TEXT or BYTE.

Syntax:

Notes:

1. editor is the name of the program that must be used to edit the special field data.
2. You can assign the PROGRAM attribute to a TEXT or BYTE field to call an external program to work with the BYTE or TEXT values.
3. Users can invoke the external program by pressing the exclamation point ( ! ) key while the screen cursor is in the field.
4. The external program then takes over control of the screen. When the user exits from the external program, the form is redisplayed with any display attributes besides PROGRAM in effect.
5. When no PROGRAM attribute is used, the DBEDIT environment variable defines the default editor.

QUERYEDITABLE Attribute

Purpose:

The QUERYEDITABLE attribute makes a combobox field editable during a CONSTRUCT instruction.

Syntax:

Notes:

1. The QUERYEDITABLE attribute is effective only during a CONSTRUCT instruction.
2. This attribute is useful when the display values match the real values in the ITEMS attribute.

REQUIRED Attribute

Purpose:

The REQUIRED attribute forces the user to enter data in the field during an INPUT or INPUT ARRAY statement.

Syntax:

Notes:

1. The REQUIRED attribute is effective only when the field name appears in the list of screen fields of an INPUT or INPUT ARRAY statement.
2. If both the REQUIRED and DEFAULT attributes are assigned to the same field, the runtime system assumes that the default value satisfies the REQUIRED attribute.

Warnings:

1. If the dialog instruction uses the WITHOUT DEFAULTS clause, the current value of the variable linked to the REQUIRED field is considered as a default value; the runtime system assumes that the field satisfies the REQUIRED attribute, even if the variable value is NULL. 

Usage:

This attribute requires only that the user enter a printable character in the field. If the user subsequently erases the entry during the same input, the runtime system considers the REQUIRED attribute satisfied. To insist on a non-null entry, combine REQUIRED with the NOT NULL attribute in the field definition or make sure the corresponding column is defined as NOT NULL in the database schema file.

See also NOT NULL attribute.

REVERSE Attribute

Purpose:

On character terminals, the REVERSE attribute displays any value in the field in reverse video (dark characters in a bright field).

Syntax:

Notes:

1. With character-based terminals, the REVERSE video escape sequences must be defined in the TERMINFO or TERMCAP databases.

SAMPLE Attribute

Purpose:

The SAMPLE attribute defines a text to be used to compute the width of a form field.

Syntax:

Notes:

1. text is the sample string that will be used to compute the width of the field.

Warnings:

1. By default the physical width of the fields is:
   if the width is smaller than 6 chars, the pixel width of the character 'M', multiplied by the number of characters the field is designed for,
   if the width is bigger than 6 chars, the pixel width of 6 characters 'M' plus the pixel width of the character '0' , multiplied by the number of characters the field is designed for minus 6.
   The default sample looks like "MMMMMM0000"...

Usage:

By default, form fields are rendered by the client with a size determined by the current font and the number of characters used in the layout grid. The field width is computed so that the largest value can fit in the widget.

Sometimes the default computed width is too wide for the typical values displayed in the field. For example, numeric fields usually need less space as alphanumeric fields. If the values are always smaller, you can use the SAMPLE attribute to provide a hint for the front end to compute the best width for that form field.

You can define a default sample for all fields used in the form, by specifying a DEFAULT SAMPLE option in the INSTRUCTIONS section.

See also: DEFAULT SAMPLE.

Example:

01 EDIT cid = customer.custid, SAMPLE="0000";
02 EDIT ccode = customer.ucode, SAMPLE="MMMMMM";
03 DATEEDIT be01 = customer.created, SAMPLE="00-00-0000";

SCROLL Attribute

Purpose:

The SCROLL attribute can be used to enable horizontal scrolling in the field.

Syntax:

Warnings:

1. Applies only to fields with character data input.

Usage:

By default the input fields do not allow scrolling in the value with the edit cursor. The maximum input length is defined by the graphical size of the field. For example, if you define an character field in the form with a length of 3 characters, users can only enter a maximum of 3 characters. If you want to let the user input more characters, use this attribute.

STRETCH Attribute

Purpose:

The STRETCH attribute specifies how a widget must resize when the parent container is resized.

Syntax:

Usage:

This attribute is typically used with form items that can be resized like IMAGE or TEXTEDIT fields. By default such form items have a fixed width and height, but in some cases you may want to force the widget to resize vertically, horizontally, or in both directions.

Example:

01 IMAGE i01 = FORMONLY.image01, STRETCH=BOTH;

TEXT Attribute

Purpose:

The TEXT attribute defines the label associated with a form item, for example the text of a checkbox item.

Syntax:

Notes:

1. string defines the label to be associated with the form item.
2. string can be a localized string.

Example:

01 CHECKBOX cb01 = FORMONLY.checkbox01, TEXT="OK", VALUECHECKED=1, VALUEUNCHECKED=0;

TITLE Attribute

Purpose:

The TITLE attribute defines the title of a form item, for example the title of a table column.

Syntax:

Notes:

1. string defines the title to be associated with the form item.
2. string can be a localized string.

Example:

01 EDIT col1 = FORMONLY.column1, TITLE="Num";

VALUEMIN Attribute

Purpose:

The VALUEMIN attribute defines a lower limit of values displayed in widgets such as progress bars.

Syntax:

Notes:

1. integer is a integer literal.

VALUEMAX Attribute

Purpose:

The VALUEMAX attribute defines a upper limit of values displayed in widgets such as progress bars.

Syntax:

Notes:

1. integer is an integer literal.

VALUECHECKED Attribute

Purpose:

The VALUECHECKED attribute defines the value associated with a checkbox item when it is checked.

Syntax:

Notes:

1. value is a numeric or string literal.

Example:

01 CHECKBOX cb01 = FORMONLY.checkbox01, TEXT="OK", VALUECHECKED=TRUE, VALUEUNCHECKED=FALSE;

VALUEUNCHECKED Attribute

Purpose:

The VALUEUNCHECKED attribute defines the value associated with a checkbox item when it is not checked.

Syntax:

Notes:

1. value is a numeric or string literal.

Example:

01 CHECKBOX cb01 = FORMONLY.checkbox01, TEXT="OK", VALUECHECKED="Y", VALUEUNCHECKED="N";

UNSORTABLE Attribute

Purpose:

Indicates that the element cannot be selected by the user for sorts.

Syntax:

Notes:

1. Makes sense only for a field that is used for the definition of a column in a TABLE container.

Usage:

By default, a TABLE container allows the user to sort the columns by a left-click on the column header. Use this attribute to prevent a sort on a specific column.

Example:

01 EDIT c01 = item.comment, UNSORTABLE;

UNSORTABLECOLUMNS Attribute

Purpose:

Indicates that the columns of the table cannot be selected by the user for sorting.

Syntax:

Usage

Same effect as UNSORTABLE, but at the TABLE level, to make all columns not sortable.

Example:

01 TABLE t1 ( UNSORTABLECOLUMNS )

UNSIZABLE Attribute

Purpose:

Indicates that the element cannot be resized by the user.

Syntax:

Notes:

1. Makes sense only for a field that is used for the definition of a column in a TABLE container.

Usage:

By default, a TABLE container allows the user to resize the columns by a drag-click on the column header. Use this attribute to prevent a resize on a specific column.

Example:

01 EDIT c01 = item.comment, UNSIZABLE;

UNSIZABLECOLUMNS Attribute

Purpose:

Indicates that the columns of the table cannot be resized by the user.

Syntax:

Usage

Same effect as UNSIZABLE, but at the TABLE level, to make all columns not resizable.

Example:

01 TABLE t1 ( UNSIZABLECOLUMNS )

UNHIDABLE Attribute

Purpose:

Indicates that the element cannot be hidden or shown by the user with the context menu.

Syntax:

Notes:

1. Makes sense only for a field that is used for the definition of a column in a TABLE container.

Usage:

By default, a TABLE container allows the user to hide the columns by a right-click on the column header. Use this attribute to prevent the user from hiding a specific column.

Example:

01 EDIT c01 = item.comment, UNHIDABLE;

UNHIDABLECOLUMNS Attribute

Purpose:

Indicates that the columns of the table cannot be hidden or shown by the user with the context menu.

Syntax:

Usage

Same effect as UNHIDABLE, but at the TABLE level, to make all columns not hidable.

Example:

01 TABLE t1 ( UNHIDABLECOLUMNS )

UNMOVABLE Attribute

Purpose:

The UNMOVABLE attribute prevents the user from moving a defined column of a table.

Syntax:

Usage:

By default, a TABLE container allows the user to move the columns by dragging and dropping the column header. Use this attribute to prevent the user from changing the order of a specific column. Typically, UNMOVABLE is used on at least two columns to prevent the user from changing the order of the input on these columns.

UNMOVABLECOLUMNS Attribute

Purpose:

The UNMOVABLECOLUMNS attribute prevents the user from moving columns of a table.

Syntax:

Usage:

By default, a TABLE container allows the user to move the columns by dragging and dropping the column header. Use this attribute to prevent the user from changing the order of columns.

UPSHIFT Attribute

Purpose:

Assign the UPSHIFT attribute to a character field when you want the runtime system to convert lowercase letters entered by the user to uppercase letters, both on the screen and in the corresponding program variable.

Syntax:

Notes:

1. Because uppercase and lowercase letters have different values, storing character strings in one or the other format can simplify sorting and querying a database.
2. Characters entered by the user are converted in INPUT, INPUT ARRAY and CONSTRUCT instructions.
3. When using single byte runners, the conversion of ASCII characters >127 is controlled by the locale settings (the LC_CTYPE environment variable).
4. The results of conversions between uppercase and lowercase letters are based on the locale settings (LANG).

Example:

01 EDIT f001 = FORMONLY.thetitle, UPSHIFT;

VALIDATE LIKE Attribute

Purpose:

The VALIDATE LIKE attribute instructs the runtime system to validate the data entered in the field by using the validation rules defined in the database schema file for the column associated with the field.

Syntax:

Notes:

1. table is the optional table name to qualify the column.
2. column is the name of the column used to search for validation rules.
3. Specifying this attribute is equivalent to listing all the attributes that are assigned to table.column in the database schema file generated from the syscolval table.
4. Validation rules are taken automatically from the schema file if the field is linked to table.column in the field name specification.

Warnings:

1. The VALIDATE LIKE clause is evaluated at compile time, not at runtime. If the database schema file changes, you might need to recompile a program that uses the LIKE clause. Even if all of the fields in the form are FORMONLY, this attribute requires the form compiler to access the database schema file that contains the description of table.

Example:

01 EDIT f001 = FORMONLY.fullname, VALIDATE LIKE customer.custname;

INITIALIZER Attribute

Purpose:

The INITIALIZER attribute allows you to specify an initialization function that will be automatically called by the runtime system to set up the form item.

Syntax:

Notes:

1. function is an identifier defining the program function to be called.

Usage:

The initialization function must exist in the program using the form file and must be defined with a parameter of the type of the built-in class corresponding to the form item.

Example:

In the form file:

01 COMBOBOX f001 = FORMONLY.state, INITIALIZER = initcombo, TAG = "state";

Program code:

01 FUNCTION initcombo(cb)
02    DEFINE cb ui.ComboBox
03    IF cb.getTag()="state" THEN
04       CALL cb.addItem(101,"Alabama")
05       CALL cb.addItem(102,"Nevada")
06       CALL cb.addItem(103,"Florida")
07       CALL cb.addItem(104,"California")
08    END IF
09 END FUNCTION

ITEMS Attribute

Purpose:

The ITEMS attribute defines a list of possible values that can be used by the form item.

Syntax:

where value-list is:

( { value | value-list } [,...] )

Notes:

1. value is a numeric or string literal.
2. value-list is a comma-separated list of values within parentheses.

Warnings:

1. Item labels can be defined with Localized Strings, but only if you specify the key and the label for each element of the list. See usage for an example.

Usage:

The list must be delimited by parentheses, and each element of the list can be a simple literal value or a pair of literal values delimited by parentheses.

The following example defines a list of simple values:

ITEMS = ("Paris", "London", "New York")

The next example defines a list of pairs:

ITEMS = ((1,"Paris"),(2,"London"),(3,"New York"))

This attribute can be used, for example, to define the list of a COMBOBOX form item:

01 COMBOBOX cb01 = FORMONLY.combobox01, ITEMS = ((1,"Paris"),(2,"London"),(3,"New York"));

In this case, the first value of a pair (1,2,3) defines the data values of the form field and the second value of a pair ("Paris", "London", "New York") defines the value to be displayed in the selection list.

When used in a RADIOGROUP form item, this attribute defines the list of radio buttons:

01 RADIOGROUP rg01 = FORMONLY.radiogroup01, ITEMS = ((1,"Paris"),(2,"London"),(3,"New York"));

In this case, the first value of a pair (1,2,3) defines the data values of the form field and the second value of a pair ("Paris", "London", "New York") defines the value to be displayed as the radio button label.

You can specify item labels with Localized Strings, but this is only possible when you specify a key and a label:

ITEMS = ((1,%"item1"),(2,%"item2"),(3,%"item3"))

JUSTIFY Attribute

Purpose:

The JUSTIFY attribute defines text justification.

Syntax:

Usage:

Default text justification depends on the dialog type, the field data type and the FORMAT attribute. For example, a numeric field value is right aligned, while a string field is left aligned. The type of dialog also defines the default justification. In a CONSTRUCT, all input fields are left aligned, for search criteria input.

With the JUSTIFY attribute, you define the display text justification of a field, as LEFT, CENTER or RIGHT. This attribute is ignored for input: Only the default text justification rule applies when a field has the focus.

The JUSTIFY attribute can only be used for widgets displaying a value as text, like a LABEL, EDIT or BUTTONEDIT.

Example:

01 LABEL t01 : TEXT="Hello!", JUSTIFY=RIGHT;
02 EDIT f01 = order.value, JUSTIFY=CENTER;

SCROLLBARS Attribute

Purpose:

The SCROLLBARS attribute can be used to specify scrollbars for a form item.

Syntax:

Usage:

This attribute defines scrollbars for the form item, such as a TEXTEDIT.

Example:

01 TEXTEDIT f001 = customer.fname, SCROLLBARS=BOTH;

SIZEPOLICY Attribute

Purpose:

The SIZEPOLICY  attribute is a sizing directive to display form elements.

Syntax:

Usage:

This attribute defines the initial size of some form elements. The default value of SIZEPOLICY is INITIAL.

When the SIZEPOLICY is FIXED, the form elements size is exactly the one defined in the Form Specification File. The width of the element is computed from the defined width and the font used.

For some elements such as COMBOBOX or RADIOGROUP, you may want the size of the widget to fit exactly to its content: When SIZEPOLICY is DYNAMIC, the width of the element grows and shrinks according to the width of the wider item.

When a form element is created from a database (for instance populating a COMBOBOX item list), the width of each element is not known when designing the form. When SIZEPOLICY is INITIAL, the width is computed to display the element correctly the first time it appears on the screen. Once it is displayed, its width is frozen. This behavior is also very useful when using Internationalization.

When SIZEPOLICY is INITIAL, the client behaves differently depending on the form element type:

• DateEdits: "DateEdit" is special, because INITIAL for the DateEdit means "inspect the width attribute of the field, if the width matches the DBDATE definition, and make the Edit field part of the DateEdit exactly as large as a sample string using the current date". 
• Buttons: The width defined in the form is a minimum width. If the text is bigger, the size grows. 
• ComboBoxes: The width defined in the form is a minimum width. If one of the items in the value list is bigger, the size grows in order for the combobox to display the largest item fully .
• Labels, Checkboxes and Radio Groups: The width defined in the form is ignored. The fields are sized according to their text.

The following table shows the effect of the SIZEPOLICY attribute according to the type of form item:

Keep in mind that INITIAL always corresponds to the first content, DYNAMIC to the content at anytime.

Example:

01 COMBOBOX f001 = customer.city, ITEMS=((1,"Paris"),(2,"Madrid"),(3,"London")), SIZEPOLICY=DYNAMIC;

SPACING Attribute

Purpose:

The SPACING attribute is a spacing directive to display form elements.

Syntax:

Usage:

This attribute defines the global distance between two neighboring form elements. By default, forms are displayed with NORMAL spacing. In this mode the front end displays form elements consistent with the desktop spacing, which is, for example, 6 and 10 pixels on Microsoft Windows platforms. Some overcrowded forms may need to be displayed with less space between elements, to let them fit to the screen. In this case you can use the COMPACT mode.

Example:

01 LAYOUT ( SPACING=COMPACT )

STYLE Attribute

Purpose:

The STYLE attribute is used to specify a presentation style for a form element.

Syntax:

Notes:

1. string is a user-defined style.

Usage:

This attribute specifies a presentation style to be applied to a form element. The presentation style can define decoration attributes such as a background color, a font type, etc.

TAG Attribute

Purpose:

The TAG attribute can be used to identify the form item with a specific string.

Syntax:

Notes:

1. tag-string is free text.

Usage:

This attribute is used to identify form items with a specific string. It can be queried in the program to perform specific processing.

You are free to use this attribute as you need. For example, you can define a numeric identifier for each field in the form in order to show context help, or group fields for specific input verification.

If you need to handle multiple data, you can format the text, for example, by using a pipe separator.

Example:

01 EDIT f001 = customer.fname, TAG = "name";
02 EDIT f002 = customer.lname, TAG = "name|optional";

TABINDEX Attribute

Purpose:

The TABINDEX attribute defines the tab order for a form item.

Syntax:

Notes:

1. integer defines the order of the item in the tab sequence.

Usage:

This attribute can be used to define the order in which the form items are selected as the user "tabs" from field to field when the program is using the form field order option.

It can also be used to define which field must get the focus when a folder page is selected.

By default, form items get a tab index according to the order in which they appear in the LAYOUT section.

Example:

01 EDIT f001 = customer.fname, TABINDEX = 1;
02 EDIT f002 = customer.lname, TABINDEX = 2;

VERIFY Attribute

Purpose:

The VERIFY attribute requires users to enter data in the field twice to reduce the probability of erroneous data entry.

Syntax:

Notes:

1. Because some data is critical, this attribute supplies an additional step in data entry to ensure the integrity of your data. After the user enters a value into a VERIFY field and presses RETURN, the runtime system erases the field and requests reentry of the value. The user must enter exactly the same data each time, character for character: 15000 is not exactly the same as 15000.00.
2. The VERIFY attribute takes effect while INPUT or INPUT ARRAY statements are executing. It has no effect on CONSTRUCT statements.

VERSION Attribute

Purpose:

The VERSION attribute is used to specify a user version string for an element.

Syntax:

Notes:

1. string is a user-defined version string.

Warnings:

1. Use the TIMESTAMP only during development.

Usage:

This attribute specifies a version string to distinguish different versions of a form element. You can specify an explicit version string or use the TIMESTAMP keyword to force the form compiler to write a timestamp string into the 42f file.

Typical usage is to specify a version of the form to indicate if the form content has changed. This attribute is used by the front-end to distinguish different form versions and to avoid reloading window/form settings into a new version of a form.

Example:

01 LAYOUT ( TEXT="Orders", VERSION = "1.23" )

OPTIONS Attribute

Purpose:

The OPTION attribute specifies widget options for the field.

Syntax:

Notes:

1. option can be one of: -nolist (to indicate that the column should appear as an independent field).

WANTTABS Attribute

Purpose:

The WANTTABS attribute forces a text field to insert TAB characters in the text when the user presses the TAB key.

Syntax:

Usage:

By default, text fields  like TEXTEDIT do not insert a TAB character in the text when the user presses the TAB key, since the TAB key is used to move to the next field. You can force the field to consume TAB keys with this attribute.  

WANTNORETURNS Attribute

Purpose:

The WANTNORETURNS attribute forces a text field to reject NewLine characters when the user presses the RETURN key.

Syntax:

Usage:

By default, text fields like TEXTEDIT insert a NewLine (ASCII 10) character in the text when the user presses the RETURN key. As the RETURN key is used to validate the dialog, you can force the field to reject RETURN keys with this attribute.

WANTFIXEDPAGESIZE Attribute

Purpose:

The WANTFIXEDPAGESIZE attribute gives a fixed height to a TABLE container.

Syntax:

Usage:

By default, the height of a TABLE container is resizable. Use this attribute to freeze the number of rows to the number of screen lines defined by the form file.

WIDTH Attribute

Purpose:

The WIDTH attribute defines an explicit width of a form element.

Syntax:

Notes:

1. integer defines the width of the element.

Usage:

By default, the size of an element is defined in characters and automatically computed by the form compiler according to the size of the form element in the layout.

For tables, the default width is defined by the columns used in the table layout. You can overwrite this default by specifying the WIDTH attribute. You typically give a number of columns as shown in the example below. This allows you to use tables with a large number of columns, but a small initial width.

See also: HEIGHT.

Example:

01 TABLE t1 ( WIDTH = 5 COLUMNS )

WIDGET Attribute

Purpose:

The WIDGET attribute specifies the type of graphical widget to be used for the field.

Syntax:

Notes:

1. identifier defines the type of widget, it can be one of the keywords listed in the table below.
2. The WIDGET attribute is used with CONFIG to parameter the field widget.

Warnings:

1. This attribute is supported for backward compatibility.
   • Instead of WIDGET="IMAGE", you should now use a IMAGE form item.
   • Instead of WIDGET="CANVAS", you should now use a CANVAS form item.
   • Instead of WIDGET="CHECK", you should now use a CHECKBOX form item.
   • Instead of WIDGET="COMBO", you should now use a COMBOBOX form item.
   • Instead of WIDGET="BMP", you should now use a BUTTON form item.
   • Instead of WIDGET="FIELD_BMP", you should now use a BUTTONEDIT form item.
   • Instead of WIDGET="RADIO", you should now use a RADIOGROUP form item.
   • The identifier widget type is case sensitive, only uppercase letters are recognized. 
   • When using the WIDGET attribute, the form cannot be properly displayed on character based terminals, it should only be displayed with graphical front ends.

Supported widgets:

Controlling V3 widgets activation:

The following list of widgets can be enabled or disabled from programs with a DISPLAY TO instruction:

• Text buttons (WIDGET="BUTTON") 
• Image buttons (WIDGET="BMP")
• Checkboxes of class "KEY" (WIDGET="CHECK", CLASS="KEY")
• Radio buttons of class "KEY" (WIDGET="RADIO", CLASS="KEY")

If you display an exclamation mark in such fields, the button is enabled, but if you display a star (*), it is disabled:

01 DISPLAY "*" TO button1 # disables the button
02 DISPLAY "!" TO button1 # enables the button

Changing the text of V3 buttons:

Text buttons (WIDGET="BUTTON") can be changed from programs with the DISPLAY TO instruction:

01 DISPLAY "Click me" TO button1 # Sets text and enables the button

Changing the image of V3 buttons:

Image buttons (WIDGET="BMP") can be changed from programs with the DISPLAY TO instruction:

01 DISPLAY "smiley.bmp" TO button1 # Sets image and enables the button

Warning: Image files are not centralized on the machine where the program is executed; image files must be present on the Workstation. See front end specific documentation for more details. 

Changing the text of V3 labels:

The text if label fields (WIDGET="LABEL") can be changed from programs with the DISPLAY TO instruction:

01 DISPLAY "Firstname" TO l_firstname # Sets text of the label field

Using V3 canvas areas:

The fields declared with the WIDGET="Canvas" attribute can be used by the program as drawing areas. Canvas fields must be defined in the LAYOUT section. A set of drawing functions are provided to fill CANVAS fields with graphical elements.

WINDOWSTYLE Attribute

Purpose:

The WINDOWSTYLE attribute defines the style to be used by the parent window of a form.

Syntax:

Notes:

1. string is a user defined style.

Usage:

The WINDOWSTYLE attribute can be used to specify the style of the parent window that will hold the form. This attribute is specific to the LAYOUT element. Do not confuse with the STYLE attribute, which is used to specify decoration style of the form elements.

When a form is loaded by the OPEN WINDOW or DISPLAY FORM instructions, the runtime system assigns automatically the WINDOWSTYLE to the 'style' attribute of the parent window element.

See also: STYLE, Windows and Forms.

Example:

01 LAYOUT ( STYLE="BigFont", WINDOWSTYLE="dialog" )

WORDWRAP Attribute

Purpose:

The WORDWRAP attribute enables a multiple-line editor.

Syntax:

Notes:

1. During input and display, the runtime system treats all segments that have that field tag as segments of a single field.
2. With character based terminals:
• The multi-line editor can wrap long character strings to the next line of a multiple-segment field for data entry, data editing, and data display.
• The COMPRESS option prevents blanks produced by the editor from being included in the program variable. COMPRESS is applied by default and can cause truncation to occur if the sum of intentional characters exceeds the field or column size. Because of editing blanks in the WORDWRAP field, the stored value might not correspond exactly to its multiple-line display.
• Specifying NONCOMPRESS after the WORDWRAP keyword causes any editor blanks to be saved when the string value is saved in a database column, in a variable, or in a file.
3. With graphical based terminals:
• The COMPRESS / NONCOMPRESS options are ignored, because text input and display is managed by the text editor widget.
• The text data is NOT automatically modified by the editor by adding blanks to put words on the next line.

Warnings:

1. This attribute is provided for backward compatibility with character-based forms; you should use a TEXTEDIT form item instead in graphical forms.
2. Using WORDWRAP fields with character-based terminals results in quite different behavior than with graphical front ends. With character-based terminals, the text input and display is modified by the multi-line editor. This editor can automatically modify the text data by adding blanks to put words to the next line in order to make the text fit into the form field. In graphical mode, the text input and display is managed by a multi-line edit control.

The maximum number of bytes a user can enter is the width of the form-field multiplied by the height of the form-field. Blank characters may be intentional blanks or fill blanks. Intentional blanks are initially stored in the target variable ore entered by the user. Fill blanks are inserted at the end of a line by the editor when the new-line or a  word-alignment forces a line-break. It is not possible to set the cursor at a fill blank. Intentional blanks are always displayed (even on the beginning of a line; the word-wrapping method used in reports with PRINT WORDWRAP works differently).

When entering characters with Japanese locales, special characters are prohibited from being the first or the last character on a line. If the last character is prohibited from ending a line, this character is wrapped down to the next line. If the first character is prohibited from beginning a line, the preceding character will also wrap down to the next line. This method is called kinsoku. The test for prohibited characters will be done only once for the first and the last character on each line.

Word-wrapping is disabled on the last row of a WORDWRAP field. The last word on the last row may by truncated. The WORDWRAP COMPRESS attribute instructs the editor to remove fill blanks before assigning the field-buffer to the target variable. The WORDWRAP NONCOMPRESS attribute instructs the editor to store fill blanks to the target variable. The WORDWRAP and WORDWRAP NONCOMPRESS attributes are equivalent.