|
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
.FIELD field_spec, [type] – [, ALLOW(valid[, ...])][, NOALLOW][, ARRIVE_METHOD(arrive_method)] – [, NOARRIVE_METHOD][, AUTOMATIC][, NOAUTOMATIC] – [, BLANK_IFZERO] [, NOBLANK_IFZERO][, BLINK][, NOBLINK] – [, BOLD][, NOBOLD][, BREAK([CHANGE|ALWAYS|RETURN])][, NOBREAK] – [, CHANGE_METHOD(change_method)][, NOCHANGE_METHOD][, CHECKBOX] – [, NOCHECKBOX][, COLOR (palette#)][, NOCOLOR][, COPY] – [, DATE([TODAY][, PERIOD][, SHORT])][, NODATE][, DECREMENT] – [, DEFAULT(default)][, NODEFAULT][, DISABLED][, NODISABLED ENABLED] – [, DSP_LENGTH(display_length)][, NODSP_LENGTH] – [, DISPLAY_METHOD(display_method)][, NODISPLAY_METHOD] – [, DRILL_METHOD(drill_method)][, NODRILL_METHOD] – [, EDITFMT_METHOD(editfmt_method)][, NOEDITFMT_METHOD] – [, ENUMERATED(display_length[, base][, step])][, NOENUMERATED] – [, FIELD_POSITION([CHANGE, ]row, column)] [, NOFIELD_POSITION]– [, FONT(palette_name)][, NOFONT] [, FORMAT(fmt_string)][, NOFORMAT]– [, HELP(help_id)][, NOHELP][, HIGHLIGHT][, NOHIGHLIGHT] – [, HYPERLINK_METHOD(hyperlink_method)][, NOHYPERLINK_METHOD] – [, INCREMENT][, INFORMATION(info_string)][, NOINFORMATION] – [, INPUT_LENGTH(input_length)][, NOINPUT_LENGTH][, ITALIC][, NOITALIC] – [, JUSTIFY(LEFT|RIGHT|CENTER)][, NOJUSTIFY] – [, LEAVE_METHOD(leave_method)] [, NOLEAVE_METHOD]– [, MATCH([CASE|NOCASE][, EXACT|NOEXACT])]– [, NEGATIVE(ALLOWED|ONLY|ORZERO)] [, NONEGATIVE]– [, NODECIMAL][, DECIMAL_REQUIRED]– [, NOECHO([display_character])][, ECHO][, NOTERM][, TERM] – [, PAINT(character)][, NOPAINT][, POSITION([CHANGE,]row, column)] – [, NOPOSITION][, PROMPT(prompt)][, NOPROMPT][, NOPROMPTFONT] – [, RADIO][, NORADIO][, RANGE(minimum, maximum)][, NORANGE][, READONLY] – [, NOREADONLY][, REQUIRED][, NOREQUIRED][, RETAIN_POSITION] – [, NORETAIN_POSITION][, REVERSE][, NOREVERSE] – [, SELECT(srow, scolumn, [height], entry[, ...])][, NOSELECT] – [, SELWND(srow, scolumn, window)][, NOSELWND [, TIME([AMPM][, NOW])] – [, NOTIME][, TIMESTAMP([AMPM][, SHORT])][, NOTIMESTAMP] – [, UNDERLINE][, NOUNDERLINE][, UPPER_CASE_ONLY|UC] – [, NOUPPER_CASE_ONLY|NOUC|>LOWER_CASE_ALLOWED] – [, USER([user_text][, user_type])][, NOUSER][, VIEW_LENGTH(view_length)] – [, NOVIEW_LENGTH][, WAIT(IMMEDIATE|FOREVER|GLOBAL|n)]
Arguments
field_spec
The field specification for the input window field. See Field specifications for information.
type
The data type and size, specified only for local fields, which must have one of the following formats:
- Asize. An alpha type of size.
- dimensionAsize. An alpha array of dimension elements of size.
- Dsize. A decimal type of size.
- Dsize.decimal. An implied-decimal type of size with decimal places.
- Isize. An integer type of size.
Where size is the size of the input field, dimension is the number of dimensions for the array (only single-dimension alpha arrays are supported), and decimal is the number of digits after the decimal point. (See the Discussion below for information on maximums.)
QUALIFIERS
See .FIELD qualifiers.
The .FIELD command defines a field to be included in the window’s input set. The maximum number of input fields in an input window or input set is 253.
Fields can be placed anywhere in the input window. On exit, the current window position is updated to the next horizontal character following the input field, including the display width.
Default values will be used for all options that are not specified.
A field with the form dimensionAsize (a single-dimension alpha array) is displayed as a multi-line text field. Dimension determines the number of lines in the field and size determines the width of the field. For example, 4a50 designates a four-line, 50-column text field, which is technically four 50-column alpha fields stacked vertically. (Note, however, that on Windows, these stacked fields are enclosed in a single frame and are a single Windows control.) Wrap mode is set automatically for input, and a text field can be edited with any editing function. Note that dimensionAsize is an array declaration (unlike an index specification, which merely references an element in an existing array defined in a repository).
On a decimal or implied-decimal field, the decimal point can either be explicitly entered or implied during input. If you specify that a field is of type d and has a decimal value of 2 (the number of decimal places), an input of 55 will yield “55.00”, while an input of 8.7 will yield “8.70”. If you specify the NODECIMAL qualifier, which means the user doesn’t need to type the decimal point (see NODECIMAL, DECIMAL_REQUIRED ), the entry of 55 will yield “.55”. (The entry 8.7 will still yield “8.70”.) Note that whether a decimal field is defined in Repository, with .FIELD, or with IB_FIELD, the field can have no more than nine digits after the decimal point.
Implied-decimal fields will always display their full precision unless the field is formatted otherwise. Any explicit spacing may be overwritten if the field needs it to display the full precision. (See the FORMAT option for information about formatting the field’s display.)
Alpha fields and single-dimension alpha arrayed fields can have a size of up to 65,535 characters. If you specify a size greater than 65,535, Toolkit will generate an error. Decimal fields (including implied decimal fields) have a maximum size of 28, and for implied-decimal fields, up to 28 digits can follow the decimal point. On any operating system, integer fields can have 1, 2, 4, or 8 digits, depending on the size of the integer field. Integer fields support all qualifiers that are valid for decimal fields without precision.
Using .FIELD with .REPOSITORY_STRUCTURE
If you specify a repository structure (using .REPOSITORY_STRUCTURE), note the following:
- You must call .REPOSITORY_STRUCTURE prior to the .FIELD commands so that fields can be drawn from that repository structure.
- All fields defined after a .REPOSITORY_STRUCTURE command must exist in that repository.
- Repository fields that have the “Excluded by Toolkit” flag set, will not be accessible by Script (or Composer or the IB_FIELD subroutine). By default, this flag is not set.
- You cannot specify type, size, dimension, or decimal places for fields drawn from a repository.
- For field qualifiers that are not explicitly specified, UI Toolkit uses the default values defined in the repository. If neither option from an option pair has been specified in the repository, the Toolkit default applies.
- If you wish to override the default values (whether they are repository defaults or Toolkit defaults), use the qualifiers. See .FIELD qualifiers.
- When you include time and date fields from the repository, you must specify any desired time and date formats in your script files. UI Toolkit does not import repository formatting for time and date fields. For timestamp fields, however, there is a default display format, which you can change or override,
- If you are drawing an input field’s allow list or selection list from a repository, any quoted entries (single or double quotes) will be unquoted, unless you have enclosed the entry and the quotes in the opposite type of quotes—for example, for “Allow” use “‘Allow’” (double quotes enclosing an entry with single quotes) in your repository definition, and for ‘Allow’ use ‘“Allow”’ (single quotes enclosing an entry with double quotes).
- Multiple repository structures can be combined together enabling access as one structure by using the implicit group feature of Repository. For more information, see Basic field information.
- For repository arrayed fields, use the index argument to access individual elements. See Field specifications below.
- For fields that are group members, you must use the group prefix unless the field name is unique within the structure. See Field specifications below.
- For fields that are members of a structfield, the field name must be unique within the repository structure.
Specifying the BLINK, BOLD, HIGHLIGHT, ITALIC, REVERSE, UNDERLINE, or COLOR qualifier for a field overrides the corresponding rendition set with .FILL for the window. Specifying NOBLINK, NOBOLD, NOHIGHLIGHT, NOITALIC, NOREVERSE, NOUNDERLINE, or NOCOLOR causes the corresponding window rendition that’s been set by .FILL to be used. (See .FILL for information on specifying these renditions for a window.)
Renditions specified with .FIELD override user-controlled renditions for the field (renditions set with Synergy UI Toolkit Control Panel or Windows Control Panel). If a rendition is overridden for a field, the default Toolkit behavior is no longer used for the field. This means that no rendition is applied when the field is being processed, displayed, or cleared, unless done so programmatically with I_FLDMOD, %IDISPLAY_METHOD, or %IEDIT_FMTMETHOD.
Note the following:
- For all edit controls, renditions set with .FIELD affect only text within the field’s frame.
- For check box fields on UNIX or OpenVMS, only the check box area is affected. On Windows, no area of a check box field is affected.
- For combo boxes on Windows, text within the field’s frame is affected. The actual list is affected only by UNDERLINE, ITALIC, and BOLD.
- For radio buttons on Windows, the area occupied by the entries’ text is affected. The buttons themselves are not.
- Disabled fields on Windows always have gray text. Specifying a foreground color for a disabled field has no effect.
- Modifying a rendition for a field affects only that rendition. Other renditions, including color, remain the same.
- For ActiveX® Toolkit lists, field attributes and color have precedence over any specified alternating background colors for the list.
- When using Toolkit lists (non-ActiveX lists) on Windows, the field’s rendition isn’t updated until the field is focused.
- It may be best to use different renditions for different platforms or when using different fonts.
See Customizing the look of your application for more rendition information.
Field specifications have the following form and cannot exceed 30 characters:
[struct_alias.]field_name[[index,...]]
where struct_alias is the alias for a structure (used only after the input window has been created), field_name is the name of the field (which may include a group prefix), and index is an index for a dimension of a repository arrayed field. (Index specifications must be enclosed in square brackets.) Struct_alias, index, and group prefixes are valid only for fields defined in a repository.
Struct_alias is necessary only after the input window has been created and must be followed by a period. (When using .FIELD, .SET, IB_FIELD, or IB_SET, the .REPOSITORY_STRUCTURE specification or the IB_RPS_STRUCTURE call determines the structure used for the field.)
Index specifications enable you to access individual elements of a repository arrayed field. For multi-dimensional arrays, pass the same number of index specifications as there are dimensions, and pass them in the same order as the corresponding dimensions. For example, for a two-dimensional array named total, specify the following to use the seventh field (second dimension) of the third element (in the first dimension):
.FIELD total[3,7]
The name of the resulting input field will include brackets, indices, and separating commas, but not spaces, tabs, or leading zeros. For the field definition above, for example, this would be total[3,7], so to use I_DISABLE for this field, you could pass something like the following:
xcall i_disable(wndid, "total[3,7]")
For single-dimension alpha arrays, you can use index to specify a particular field in the array, or you can omit index and the square brackets. (If you omit index, you must also omit the square brackets.) Omitting index instructs Toolkit to display the entire array as a text field. The number of elements determines the number of lines in the text field, and the field size for the array becomes the length of the text field. Wrap mode is set automatically during input, and a text field can be edited with any editing function.
Script will generate an error in the following circumstances:
- If an index value is less than 1 or greater than the number of elements specified for that dimension.
- If the number of index specifications does not match the number of dimensions. (The exception is single-dimension alpha arrays. For these, index is optional.)
For fields that are group members in a repository, use the group prefix (if one has been specified for the group) to make the field name unique—for example, if the group prefix is gr2 and the field name is lastname, you can use gr2lastname. (You can omit the group prefix only if the name is unique within the entire structure.)
For example, the following field_spec references the second element in address, a single-dimension array which is a member of a group with the prefix gr1:
.REPOSITORY_STRUCTURE customer .FIELD gr1address[2] .SET custset, customer, gr1address[2]
If the customer structure in the above example has the alias cust, you could use the following to disable the field after the input window had been created:
xcall i_disable(wndid, "cust.gr1address[2]")
Note that for arrayed groups, you can use a field name (with or without a group prefix) only to access a member from the first element in the array. You can use index specifications to access an arrayed group element as a whole, but you cannot use index to access individual members within an arrayed group element.
All .FIELD qualifiers are optional. Separate qualifiers with a comma. For all qualifiers, except ALLOW and SELECT, you can break a line only between qualifiers, not in the middle of a qualifier and its arguments.
In most cases, text for qualifier parameters must be enclosed in quotation marks, but there are some exceptions, which are noted. For example, the following includes two qualifiers (ALLOW, and ARRIVE_METHOD) with quoted parameter strings:
.field myfield, a3, allow("yes", "no"), arrive_method("mymethod")
ALLOW(valid[, ...])
NOALLOW
ALLOW specifies which entries are valid for the field. You can specify up to 100 entries with valid.
For example, if “yes” and “no” were the only possible entries, the syntax for the .FIELD command would be as follows:
.field yesno, a3, allow("yes", "no")
If you don’t specify the MATCH qualifier and the allowable entry is alpha, the input system will only look for a match for the shortest entry, and there will be no case sensitivity. You can change these match characteristics by specifying the MATCH qualifier. (See MATCH for more information.)
NOALLOW is the default state if neither ALLOW nor NOALLOW is specified in the script or in the repository. If ALLOW has been specified in the repository, NOALLOW will cancel the allow list associated with the field.
ARRIVE_METHOD, NOARRIVE_METHOD
ARRIVE_METHOD(arrive_method)
NOARRIVE_METHOD
ARRIVE_METHOD specifies a pre-input subroutine, where arrive_method is the name of the subroutine to invoke. Arrive_method is case insensitive and is valid with or without quotation marks.
For example,
.field field,...,arrive_method("mymethod")
If you specify ARRIVE_METHOD, the arrive_method subroutine will be called before the field is processed by I_INPUT. Up to 20 optional data arguments can be passed to I_INPUT. These optional data arguments are then, in turn, passed to the arrive_method subroutine.
The routine specified in arrive_method must be callable as a subroutine and must reside either in the program image itself or in an open ELB. In the latter case, on some systems a call to the OPENELB routine is required. See IARRIVE_METHOD for more information on writing the arrive_method subroutine.
NOARRIVE_METHOD is the default state if neither ARRIVE_METHOD nor NOARRIVE_METHOD is specified in the script or in the repository. If ARRIVE_METHOD has been specified in the repository, specifying NOARRIVE_METHOD will override this setting and the arrive method will not be invoked.
AUTOMATIC NOAUTOMATIC
AUTOMATIC specifies that when an empty field is processed, a return with no input is automatically assumed (i.e., the specified default action—DEFAULT, COPY, INCREMENT, or DECREMENT—will occur automatically). In the following example, the ordnum field automatically contains the default value (which happens to be 1).
.field ordnum, d4, automatic, default(1)
NOAUTOMATIC is the default state if neither AUTOMATIC nor NOAUTOMATIC is specified in the script or in the repository. If AUTOMATIC has been specified in the repository, NOAUTOMATIC cancels automatic entry of the field.
BLANK_IFZERO NOBLANK_IFZERO
BLANK_IFZERO (which may also be specified BZRO or BLANK_IF_ZERO) indicates that a numeric (d or i) field will be left blank if the user enters a value of 0. For example, the amount field below will be left blank if the user enters a 0 value.
.field amount, d5, bzro
NOBLANK_IFZERO (which may also be specified NOBZRO or NOBLANK_IF_ZERO) is the default state if neither BLANK_IFZERO, BZRO, nor BLANK_IF_ZERO is specified in the script or in the repository. If BLANK_IFZERO has been specified in the repository, specifying NOBLANK_IFZERO will override this setting and will display a zero on zero input.
BLINK, NOBLINK
BLINK NOBLINK
BLINK specifies italicized text on Windows and blinking text on UNIX and OpenVMS. It is synonymous with ITALIC. For detailed information on BLINK and other input field renditions, see Renditions.
In the following example, the contents of the field are italicized on Windows and blinking on UNIX and OpenVMS.
.field date_due, d8, blink
NOBLINK is the default state if neither BLINK nor NOBLINK is specified in the script or repository. If BLINK has been specified in the repository, NOBLINK cancels the blinking. NOBLINK is synonymous with NOITALIC.
BOLD NOBOLD
BOLD specifies bold text on Windows and highlighted text on UNIX and OpenVMS. It is synonymous with HIGHLIGHT. For detailed information on BOLD and other input field renditions, see Renditions.
In the following example, the contents of the field are bold.
.field balance, d18.2, bold
NOBOLD is the default state if neither BOLD nor NOBOLD is specified in the script or repository. If BOLD has been specified in the repository, NOBOLD cancels this attribute. NOBOLD is synonymous with NOHIGHLIGHT.
BREAK([CHANGE|ALWAYS|RETURN]) NOBREAK
BREAK triggers a break in input set processing on a field. Specify the type of break with one of the following:
CHANGE = Causes break processing to occur when the field is changed. (default)
ALWAYS = Causes break processing to occur on the field every time the user leaves the field.
RETURN = Causes break processing to occur on the field only when the field is changed or Enter is pressed.
Sometimes you’ll want to interrupt input set processing on a field, perform external operations, and then continue with the input set. The BREAK qualifier without an argument or with the CHANGE argument specifies that a break will occur after input to this field has been processed (that is, whenever the field’s data is changed). If the ALWAYS argument is present, a break will occur regardless of whether or not input has been processed (for instance, even if the user merely leaves the field with the I_NEXT or I_PREV menu entry). If the RETURN argument is present, a break will occur when Enter is pressed, but not when the field has been accessed with the I_NEXT or I_PREV menu entry (assuming the field was not modified).
The global variable g_fldnam specified in tools.def will contain the name of the field with the break specification.
The BREAK qualifier might be useful in specifying an inventory item in a sales transaction. You could break on the specification field, search for the item in inventory, display any pertinent information, and then continue with the rest of the input set.
In the following example, a break will occur after input from the custno has been processed:
.field custno, d6, break
NOBREAK is the default state if neither BREAK nor NOBREAK is specified in the script or in the repository. If BREAK has been specified in the repository, NOBREAK will cancel break processing for the field. To change to another form of break processing (ALWAYS, RETURN, or the default, CHANGE), specify BREAK with the desired optional qualifier.
On Windows, when used in conjunction with CHECKBOX, SELECT, SELWND, or RADIO, the BREAK qualifier will not trigger a return to the calling routine until you leave that field. For example, clearing a check box will not return from I_INPUT until another field is accessed. If, however, the E_STATE (D_VALSTCHG) option has been set, then a break occurs immediately on a change of state, and does not occur when leaving the field (unless the two are simultaneous).
CHANGE_METHOD, NOCHANGE_METHOD
CHANGE_METHOD(change_method)
NOCHANGE_METHOD
CHANGE_METHOD specifies a post-validation routine, where change_method is the name of the routine to invoke. Change_method is case sensitive and is valid with or without quotation marks. For example,
.field name,...,change_method("mymethod")
The specified routine will be called after the field is validated by I_INPUT, L_INPUT, I_INPFLD, or L_INPFLD. (By default, validation will not occur until focus on the field is lost. Immediate validation can be specified for check boxes, radio buttons, and combo boxes by using the D_VALSTCHG option in E_STATE.) Up to 20 optional data arguments can be passed to I_INPUT and L_INPUT. These optional data arguments are then, in turn, passed to the change_method routine.
The routine specified in change_method must be callable as a function and must reside either in the program image itself or in an open ELB. In the latter case, on some systems a call to the OPENELB routine is required. See %ICHANGE_METHOD for more information on writing the change_method routine.
NOCHANGE_METHOD is the default state if neither CHANGE_METHOD nor NOCHANGE_METHOD is specified in the script or in the repository. If CHANGE_METHOD has been specified in the repository, specifying NOCHANGE_METHOD will override this setting and the change method will not be invoked.
CHECKBOX NOCHECKBOX
CHECKBOX indicates that this field is to be displayed as a check box on Windows. On UNIX and OpenVMS, check boxes are one-character fields (“X” if non-zero, or space if zero).
On Windows, a check box is a small square that is either empty or has a check in it. Every check box displays one of these states, and the state is represented in the data area of input as a 1 or 0 for checked or unchecked, respectively.
At runtime, the spacebar can be used to toggle the state.
A numeric input window field can be designated a check box field by adding the script option “checkbox” to the .FIELD command. When this is done, a check box is created at the location of the field. Prompt text becomes the text associated with the check box and is always placed adjacent and to the right of the check box, regardless of any specified prompt position. You can use IB_FIELD with the D_FLD_CHECKBOX qualifier to create a check box field when creating windows at runtime, or you can create a check box using Composer (see Composer).
A check box is implicitly an enumerated field, and therefore cannot be defined with the ENUMERATED qualifier.
Toggling a check box does not, by default, cause the field to be immediately validated. Until the field loses focus, no Toolkit validation tests or change method occurs. Likewise, no leave and arrive methods will be invoked until focus is lost. In order for a field to be immediately validated, the D_VALSTCHG option of E_STATE needs to be set. See E_STATE for more information about this subroutine and the D_VALSTCHG option.
On Windows, if a check box has no prompt, there is no visual change when the check box gains focus. Focus is denoted by a dotted rectangle around the prompt and changes to the renditions for the prompt (if needed E_STATE options are set).
NOCHECKBOX is the default state if neither CHECKBOX nor NOCHECKBOX is specified in the script or in the repository. If CHECKBOX has been specified in the repository, specifying NOCHECKBOX will override this setting and the field will not be displayed as a check box.
COLOR(palette#) NOCOLOR
COLOR specifies the color palette entry to use for foreground and background colors for the text, where palette# is a palette number in the range 1 to 16. For example,
.field amount_due, d10.2, color(5)
For detailed information on COLOR and other input field renditions, see Renditions.
NOCOLOR is the default state if neither COLOR nor NOCOLOR is specified in the script or in the repository. If a color has been specified in the repository, NOCOLOR specifies that the window’s color be used, or color palette number 1 if not specified.
COPY
COPY copies the value from the data area that corresponds to this field (as defined by the structure) if the field is empty. For example,
.field cusnam, a30, copy
If you use COPY, you should not use DECREMENT, INCREMENT, or DEFAULT. These four qualifiers are mutually exclusive.
If COPY has been specified in the repository, specifying NODEFAULT will cancel it. (See DEFAULT, NODEFAULT for more information.)
DATE([TODAY][, PERIOD][, SHORT]) NODATE
DATE enables you to process dates by specifying one or more of the following:
TODAY = Defaults the date to the system date if the user presses Enter in a blank date field.
PERIOD = Specifies that the date is a period. (A period is a user-defined unit within the range 1 to 99, typically representing an accounting period.)
SHORT = Shortens the display of the date from the normal 11 characters. A short period date (one with both the SHORT and PERIOD arguments) will have a display length of 5 characters. All other short dates will have a display length of 8 characters.
You can use this qualifier only on d4 through d8 fields, or on i2 or i4 fields; fields of any other type or size will generate an error. The input for a date is either numeric or delimited. The size of the field defines the way the date is stored, as shown in the table below.
|
Date Formats for Field Sizes |
||
|---|---|---|
|
Size |
Date format |
Meaning |
|
d4 field |
YYPP |
Two-digit year, period |
|
d5 field |
YYJJJ |
Two-digit year, Julian day |
|
d6 field |
YYMMDD or YYYYPP |
Two-digit year, month, day or Four-digit year, period |
|
d7 field |
YYYYJJJ |
Four-digit year, Julian day |
|
d8 field |
YYYYMMDD |
Four-digit year, month, day |
|
i2 field |
YYPP |
Two-digit year, period |
|
i4 field |
YYYYMMDD |
Four-digit year, month, day |
Users don’t have to type just digits—they can type a three-letter abbreviation for the month, and UI Toolkit will convert what was typed to one of the storage formats shown in the table above. (The U_MONTHS subroutine determines the abbreviation for each month. The default is the first three letters of the month in English.)
Using the DATE qualifier, any value that is not specified defaults to the current date. If the user specifies /day/year, the month will default to the current month, and if the user enters a single value, it will be used as the day. For example, if the user specifies 5, the date will default to the fifth day of the current month and year. If the user enters a single value followed by the date separator, it will be used as the month. For example, the user can specify 10/, and the date will default to October and the current day and year.
Several global fields in tkctl.def affect date processing. The g_date_order global field affects date input and display as follows:
|
If g_date_order is… |
Input and display will have this order… |
|---|---|
|
0 |
month day year or period year (if PERIOD is specified) |
|
1 |
day month year or period year (if PERIOD is specified) |
|
2 |
year month day or year period (if PERIOD is specified) |
Additionally, the g_date_sep global field specifies the character that will separate parts of the date on redisplay. This is initialized to a slash (/). And the g_periods global field defines the maximum number of periods that are allowed on input. This is initialized to 12 if you don’t specify a value.
The following example defaults the date in the invdat field to today’s date if the user presses Enter without entering anything into the field. The date is stored in the format YYMMDD.
.field invdat, d6, date(today)
In the next example, if the user enters Dec 7, 12071994, 1207, 12/7, or 12/7/94 (assuming the current year is 1994), the date will be displayed as “12/07/94” and stored as 19941207.
.field birthdat, d8, date(short)
NODATE is the default state if neither DATE nor NODATE is specified in the script or in the repository. If DATE has been specified in the repository, NODATE will reset the field to a normal decimal field. To override any of the other date arguments, specify DATE without one or more of them.
DECREMENT
DECREMENT designates that if the user does not enter a value the first time a numeric (d or i) field is processed, the last value in the field minus one will be used. For example, the following script will decrement the last value in the quantity field by one (if the user doesn’t enter a value).
.field quantity, d4, decrement
If you use DECREMENT, you should not use COPY, INCREMENT, or DEFAULT. These four qualifiers are mutually exclusive.
If DECREMENT has been specified in the repository, NODEFAULT will cancel it.
DEFAULT(default)
NODEFAULT
DEFAULT defines a default value for the field, where default is a value up to 80 characters long. The default value is automatically displayed in the field if the user has not previously entered anything in the field. The user can accept the default by pressing Enter, edit the default, or type a new value. In the following example, the default value is 1.
.field quantity, d4, default(1)
If a selection window is associated with this field, the entry in the selection window that matches the default value will be the first highlighted entry, if found. Note that a default value specified here takes precedence over any default value specified in the .ITEM selection window building command or any call to the S_SELDFLT subroutine.
For date and time fields, the default value must be specified in field storage form, rather than field input or display form. For example, the default value for a six-digit period date should be specified in the form “199813.” If the field is a date field, the default value must match the date field’s storage format. For example, the default value for a six-digit period date should be specified as “199813.”
If you use DEFAULT, you should not use the COPY, INCREMENT, or DECREMENT qualifiers. These four qualifiers are mutually exclusive.
If you use DEFAULT with ENUMERATED, DEFAULT must be specified after ENUMERATED.
NODEFAULT is the default state if there is no specification for this qualifier in the script or in the repository. If DEFAULT has been specified in the repository, NODEFAULT cancels any default value specified. It also cancels any COPY, INCREMENT, or DECREMENT qualifier that has been specified for the field.
DISABLED, NODISABLED
DISABLED NODISABLED
DISABLED disables the field. A disabled field is unable to receive keyboard focus either by mouse click or by pressing one of the following: Tab, arrow key, or Enter. For example,
.field state, a2, disabled
On Windows, except within ActiveX Toolkit lists, disabled fields will be grayed out. (Disabled fields within an ActiveX Toolkit list are rendered the same as enabled fields.)
On UNIX and OpenVMS, disabled fields will use the “disabled field display” rendition. This rendition can be modified using U_REND but cannot be modified using U_MODREND. See U_REND for more information on processing display renditions.
NODISABLED (which may also be specified ENABLED) is the default state if there is no specification for this qualifier in the script or in the repository. If DISABLED has been specified in the repository, NODISABLED cancels it.
DSP_LENGTH(display_length)
NODSP_LENGTH
DSP_LENGTH specifies the maximum number of characters that can be displayed in a field, overriding Toolkit’s default display length. Valid values for display_length are 0 through 65,535. (Unless an explicit view length is set for the field, however, display_length cannot be set to a value that extends the field beyond the window border.) If display_length is set to 0, Toolkit uses the default.
This maximum includes any formatting characters and the negative sign (if a negative value is allowed for the field). Display lengths cannot be specified for check box fields, radio buttons, selection fields (including fields with selection windows), or text fields (multi-dimensional alpha fields).
If you don’t specify display_length, or if you set it to 0, it defaults to one of the following:
- For a field that’s an enumerated list, display length defaults to the display length set for the enumeration setting (for example, the display_length argument for the ENUMERATED qualifier).
- For a field with a format string, display length defaults to the length of the format string. (This does not apply to fields that are enumerated lists.)
- For a field that’s unformatted, display length defaults to the input length. (This does not apply to fields that are enumerated lists.)
For information on how display length works with other length settings for input fields, see Understanding display, input, and view lengths.
NODSP_LENGTH is the default state if neither DSP_LENGTH nor NODSP_LENGTH is specified in the script or in the repository. If DSP_LENGTH has been specified in the repository, NODSP_LENGTH cancels the display length setting, causing the default to be used.
DISPLAY_METHOD, NODISPLAY_METHOD
DISPLAY_METHOD(display_method)
NODISPLAY_METHOD
DISPLAY_METHOD defines a display method for the field, where display_method is the name of the subroutine to invoke. Display_method is case insensitive and is valid with or without quotation marks. For example,
.field field,..., display_method("mymethod")
The subroutine specified with display_method will be called whenever the field is about to be displayed, after Toolkit has formatted the display according to its rules. Up to 20 optional data arguments can be passed to I_INPUT. These optional data arguments are then, in turn, passed to the display_method subroutine.
Any field with a user-defined data type will not invoke the display_method subroutine. Instead, use the EDSPFLD_METHOD routine.
|
Display methods are not allowed for check box, selection list, selection window, or radio button fields. |
NODISPLAY_METHOD is the default state if neither DISPLAY_METHOD nor NODISPLAY_METHOD is specified in the script or in the repository. If DISPLAY_METHOD has been specified in the repository, specifying NODISPLAY_METHOD will override this setting and the display method will not be invoked.
DRILL_METHOD(drill_method)
NODRILL_METHOD
DRILL_METHOD defines a drill method for the field, where drill_method is the name of the method to invoke. Drill_method is case insensitive and is valid with or without quotation marks. For example,
.field field,..., drill_method("mymethod")
A drill method is generally used for some form of lookup or additional information. On Windows, if an input field has a drill method and is a member of an input set being processed by I_INPUT, a drilldown button (a small button with “…” on the face) is placed immediately to the right of the field. If you click this button, the drill method is invoked. On UNIX and OpenVMS, there is no drilldown button, but instead an I_DRILL menu entry will trigger UI Toolkit to invoke the specified drill method. Up to 20 optional data arguments can be passed to I_INPUT. These optional data arguments are then, in turn, passed to the drill_method subroutine.
NODRILL_METHOD is the default state if neither DRILL_METHOD nor NODRILL_METHOD is specified in the script or in the repository. If DRILL_METHOD has been specified in the repository, specifying NODRILL_METHOD will override this setting and the drill method will not be invoked.
EDITFMT_METHOD, NOEDITFMT_METHOD
EDITFMT_METHOD(editfmt_method)
NOEDITFMT_METHOD
EDITFMT_METHOD defines an edit format method for the field, where editfmt_method is the name of the subroutine to invoke. Editfmt_method is case insensitive and valid with or without quotation marks. For example,
.field field,..., editfmt_method("mymethod")
The editfmt_method subroutine will be called whenever data in a field is about to be edited, after Toolkit has formatted the display according to its rules. Up to 20 optional data arguments can be passed to I_INPUT. These optional data arguments are then, in turn, passed to the editfmt_method subroutine.
For fields with a user-defined data type, any EEDTDSP_METHOD subroutine is called prior to the editfmt_method subroutine.
|
|
Edit format methods are not allowed for check box, selection list, selection window, or radio button fields. |
NOEDITFMT_METHOD is the default state if neither EDITFMT_METHOD nor NOEDITFMT_METHOD is specified in the script or in the repository. If EDITFMT_METHOD has been specified in the repository, specifying NOEDITFMT_METHOD will override this setting and the edit format method will not be invoked.
ENUMERATED(display_length[, base][, step])
NOENUMERATED
ENUMERATED specifies an enumerated data field, which is a field that returns a decimal or integer value for the corresponding displayed text entry. This field type corresponds to the Repository “enumerated” field attribute used in conjunction with an allow list, selection list, or selection window. It does not correspond to the Synergy DBL or Repository enumeration data type.
ENUMERATED takes the following arguments:
display_length
The number of characters (from 0 to 65535) that can be displayed for each select or allow list item.
base
(optional) The return value of the first entry. If you don’t specify a base value, the default is 1.
step
(optional) The value added to each successive entry. If you don’t specify a step value, the default is 1.
The ENUMERATED qualifier must be used in conjunction with the SELECT, ALLOW, SELWND qualifiers, or with a selection window built “on-the-fly” using S_SELBLD. If used with SELECT or ALLOW, it must precede them. An enumerated data field must have a decimal (d) or integer (i) data type, and its size must be able to handle the largest number expected to be returned.
This example defines two enumerated input fields:
.input inp, 20, 70 .field fld1, d2, enum(6, 1, 1), sel(1, 2, 3, red, orange, yellow) .field fld2, d2, enum(6, 3, 2), sel(1, 2, 3, green, blue, violet)
The first input field, fld1, is two digits in size, and has three selection items: red, orange, and yellow. This field has a display length of 6 characters, a base value of 1, and a step value of 1. It will return the value 1 for red, 2 for orange, and 3 for yellow.
The second input field, fld2, is also two digits in size and has three selection items: green, blue, and violet. The display length is 6 characters, but the base value is 3 and the step value is 2. This means it returns the value 3 for green, 5 for blue, and 7 for violet.
When UI Toolkit processes an enumerated data field at runtime, the data area contains the enumerated field calculated as follows:
(entry_number-1)*step + base
where entry_number is the number of the entry specified by the SELECT, ALLOW, or SELWND qualifier for each field.
If there’s a field-level display length (set with the DSP_LENGTH qualifier, for example), it overrides the display_length setting for ENUMERATED.
For more information on display length, including default settings, and for information on how display length, input length, and view length interact, see Understanding display, input, and view lengths.
|
|
This setting may be used as the view length if no view length or field-level display length (specified with DSP_LENGTH, for example) is specified for the field. In this case, display_length is used to calculate the width of the field and must not be set to a value that causes the field to extend beyond the window’s borders. (See VIEW_LENGTH, NOVIEW_LENGTH for more information on the field width calculation.) |
If you use ENUMERATED with DEFAULT, ENUMERATED must precede DEFAULT.
NOENUMERATED is the default state if this category is not specified in the script or in the repository. If ENUMERATED has been specified in the repository, NOENUMERATED overrides this setting and resets the field to a non-enumerated field. If you only wish to override the field parameters for ENUMERATED, use ENUMERATED with the new parameters.
|
|
A check box is implicitly an enumerated field and therefore cannot be defined with the enumerated qualifier. |
FIELD_POSITION, NOFIELD_POSITION
FIELD_POSITION([CHANGE, ]row, column) NOFIELD_POSITION
FIELD_POSITION (which may be abbreviated FPOS) specifies the position of a field, independent of its prompt. It takes the following arguments:
CHANGE
(optional) Designates that FIELD_POSITION is a degree of movement rather than an actual position. This value can be negative or positive.
row
Either a row position or the number of rows that the current position will move.
column
Either a column position or the number of columns that the current position will move.
If you don’t specify the FIELD_POSITION qualifier on a .FIELD statement, the position of the field defaults to the current screen position if there isn’t a prompt, or immediately following the prompt if one exists. (See POSITION, NOPOSITION for more information.)
If the position of a field specified by FIELD_POSITION falls on or before any part of the prompt, a warning occurs but the command is still processed.
Any POSITION or PROMPT qualifier is processed first, and FIELD_POSITION will be relative to the next position after the prompt (or POSITION, if PROMPT is not specified).
If the CHANGE qualifier is absent, the specified row and column will be the absolute coordinates for the field relative to the input window.
The following example positions the “Name” prompt at the tenth row and first column (10,1) and the input field at the tenth row and tenth column (10,10). Thus, five spaces are between the end of the “Name” prompt and the beginning of the input field.
.field fld1, a10, position(10,1), prompt("Name"), fpos(10,10)
This second example has the same result as the previous example except that it specifies a change in position from the end of the prompt rather than specifying an absolute position for the input field.
.field fld1, a10, position(10,1), prompt("Name"), fpos(change, 0, 5)
NOFIELD_POSITION (which may be abbreviated NOFPOS) is the default state if this category has not been specified in the script or in the repository. If FIELD_POSITION has been specified in the repository, NOFIELD_POSITION resets the position of the input field to default to the next character after the prompt rather than the position specified in the repository.
FONT(palette_name)
NOFONT
FONT specifies the font for the field, where palette_name is the name of a font palette entry. Palette_name must be known at runtime or a default font will be used. See Using fonts on Windows for more information on font palettes.
|
|
Do not enclose palette_name in quotation marks; it will cause an error. |
Although FONT has no visual effect on UNIX and OpenVMS, it is preserved with the window definition so that the same window library can be used for both non-Windows and Windows systems.
Specifying a field font with the FONT qualifier overrides any default font that would have been used for the field. NOFONT indicates that the window’s font should be used. See also .FONT for more information about specifying a window’s font, and see PROMPTFONT, NOPROMPTFONT for more information about specifying a prompt’s font.
The following example specifies my_field_font for the field inpfld.
.field inpfld, a30, font(my_field_font)
NOFONT is the default state if neither FONT nor NOFONT is specified in the script or in the repository. If FONT has been specified in the repository, NOFONT cancels the field’s font and uses the window’s font instead.
FORMAT(fmt_string)
NOFORMAT
FORMAT (which may be abbreviated FMT) designates a redisplay format for the field. Fmt_string is a quoted format string that determines the format in which the field input will be displayed.
On numeric fields, format_string follows the rules for Synergy DBL formatting. If you don’t specify the FORMAT qualifier, numeric input is redisplayed, right-justified over blanks. When a redisplay format is defined and justification is not specified, the resulting format string is right-justified within the display field.
On alphanumeric fields, the FORMAT qualifier permits a special form, in which every “@” character is replaced by another character. This replacement is processed from left to right. For example, if the user enters ab and you have the format string
"The first two are @@"
you would get “The first two are ab”.
The system only looks at the leftmost characters and substitutes blanks. For example, if your field has a data type of a3, the fourth @ will be blank.
On both numeric and alpha fields, the size of the display field is the width of the input field or the maximum number of characters the format can generate, whichever is greater.
In the following example, the contents of the field will be displayed in the form $XX,XXX.
.field amount, d5, fmt("$XX,XXX")
Thus, if the user enters 1234, the resulting display would be “$01,234”.
If you specify any justification for the field, UI Toolkit will justify only within the display length. See also JUSTIFY, NOJUSTIFY.
UI Toolkit supports the Repository format justification specification. Format justification defines how a format is truncated before being applied to a field. See Defining field formats.
NOFORMAT (which may be abbreviated NOFMT) is the default state if neither FORMAT nor NOFORMAT is specified in the script or in the repository. If FORMAT has been specified in the repository, NOFORMAT cancels the field’s format string. If you only wish to specify a different format string, use FORMAT with the new string.
HELP(help_id)
NOHELP
HELP specifies a help identifier. Help_id is used as an argument to the EHELP_METHOD subroutine. If no EHELP_METHOD subroutine is registered, help_id will be passed to Toolkit’s default help subroutine. (See EHELP_METHOD for more information on help processing.)
In the following example, h_name is passed as an argument to the EHELP_METHOD subroutine, if registered; otherwise, it’s passed to UI Toolkit’s default help routine.
.field name, a30, help(h_name)
NOHELP is the default state if neither of these qualifiers is specified in the script or in the repository. If HELP has been specified in the repository, NOHELP cancels the help identifier. If you only wish to specify a different help identifier, use HELP with the new identifier.
HIGHLIGHT NOHIGHLIGHT
HIGHLIGHT specifies highlighted text on UNIX and OpenVMS and bolded text on Windows. It is synonymous with BOLD. For detailed information on HIGHLIGHT and other input field renditions, see Renditions.
In the following example, the contents of the field are highlighted/bolded.
.field balance, d18.2, highlight
NOHIGHLIGHT is the default state if neither HIGHLIGHT not NOHIGHLIGHT is specified in the script or the repository. IF HIGHLIGHT has been specified in the repository, NOHIGHLIGHT cancels the highlighting. NOHIGHLIGHT is synonymous with NOBOLD.
HYPERLINK_METHOD, NOHYPERLINK_METHOD
HYPERLINK_METHOD(hyperlink_method)
NOHYPERLINK_METHOD
HYPERLINK_METHOD specifies a hyperlink method for the field, where hyperlink_method is the name of the subroutine to invoke.
On Windows, if an input field has a hyperlink method, when it is a member of an input set being processed by I_INPUT, any prompt text associated with the field is highlighted. If you click the mouse button with the cursor on the highlighted text, the hyperlink prompt text method is invoked.
On UNIX and OpenVMS, there is no hyperlink text, but instead an I_HYPER menu entry triggers UI Toolkit to invoke the specified hyperlink_method. For example,
.field field,...,hyperlink_method("mymethod")
NOHYPERLINK_METHOD is the default state if neither HYPERLINK_METHOD nor NOHYPERLINK_METHOD is specified in the script or in the repository. If HYPERLINK_METHOD has been specified in the repository, specifying NOHYPERLINK_METHOD will override this setting and the hyperlink method will not be invoked.
INCREMENT
INCREMENT designates that if the user does not enter a value the first time a numeric (d or i) field is processed, the last value in the field plus one will be used. For example,
.field ordnum, d5, increment
If you use INCREMENT, you should not use COPY, DECREMENT, or DEFAULT. These four qualifiers are mutually exclusive.
If INCREMENT has been specified in the repository, specifying NODEFAULT will cancel it. (See DEFAULT, NODEFAULT for more information.)
INFORMATION(info_string)
NOINFORMATION
INFORMATION specifies a text string (info_string) that is displayed on the information line when input is being processed for that field. The information line will revert to the text it contained previously once input to the field is terminated. If info_string is absent, the information line will not be modified.
In the following example, “Please enter your name” is displayed on the information line while the name field is processed.
.field name, a30, information("Please enter your name")
NOINFORMATION is the default state if neither INFORMATION nor NOINFORMATION is specified in the script or in the repository. If INFORMATION has been specified in the repository, NOINFORMATION cancels the information string. If you only wish to specify a different information string, use INFORMATION with the new string.
INPUT_LENGTH(input_length)
NOINPUT_LENGTH
INPUT_LENGTH specifies the maximum number of characters the user can enter in an input field, overriding Toolkit’s default input length. Valid values for input_length are 0 to 65,535. If you set this to 0, the default input length is used.
If there is a change method for the field, the input length determines how many characters will be passed to the change method. If the input length is longer than the storage size, the additional characters may be ignored if there is no change method.
Input length cannot be specified for check box fields, radio buttons, selection fields (including fields with selection windows), or text fields (multi-dimensional alpha fields).
If you don’t specify input length, it defaults to one of the following:
- For an alphanumeric or user-defined field, the default input length is the storage size of the field.
- For a decimal field, the default input length is the storage size plus 1 if a decimal point is allowed. If a negative value is allowed, another character is added.
- For an integer field, the default input length is 3 for an i1, 5 for an i2, 10 for an i4, or 20 for an i8. If a negative value is allowed, the length is increased by 1.
- For a date field, the default input length is determined by the date format. Period dates are 8. Short period dates are 5. Calendar (non-period) dates are 11. Short calendar dates are 8.
- For a time field, the default input length is determined by the time format. HHMM is 5. HHMM AM|PM is 8. HHMMSS is 8. HHMMSS AM|PM is 11.
NOINPUT_LENGTH is the default state if neither INPUT_LENGTH nor NOINPUT_LENGTH is specified in the script or in the repository. If INPUT_LENGTH has been specified in the repository, NOINPUT_LENGTH cancels the input length setting, which causes the default input length to be used.
For information on how input length works with other length settings for input fields, see Understanding display, input, and view lengths.
ITALIC NOITALIC
ITALIC specifies italicized text on Windows and blinking text on UNIX and OpenVMS. It is synonymous with BLINK. For example,
.field date_due, d8, italic
For detailed information on ITALIC and other input field renditions, see Renditions.
NOITALIC is the default state if neither ITALIC nor NOITALIC is specified in the script or repository. If ITALIC has been specified in the repository, NOITALIC cancels the italics. NOITALIC is synonymous with NOBLINK.
JUSTIFY(LEFT|RIGHT|CENTER) NOJUSTIFY
JUSTIFY determines whether the text in the field will be displayed left-justified, right-justified, or centered. The field defined in the following example will display left-justified text.
.field custno, d5, justify(left)
Restrictions and defaults depend on the field type:
- Numeric fields accept only RIGHT (default) or LEFT alignment.
- Text fields accept only LEFT alignment.
- Alpha fields accept all three types. LEFT is the default. (Note that leading spaces are not stripped from the data.)
If you have formatted the display of the field (using the FORMAT qualifier), the justification is performed only within the length of the formatted display.
NOJUSTIFY is the default state if this category has not been specified in the script or in the repository. If JUSTIFY has been specified in the repository, NOJUSTIFY resets the justification to the field type default. If you wish to change the justification alignment, use JUSTIFY with the new alignment.
LEAVE_METHOD(leave_method)
NOLEAVE_METHOD
LEAVE_METHOD specifies a post-input subroutine for the field. Leave_method is the name of the subroutine to invoke. A leave method provides a much more reusable and encapsulated mechanism than break processing, which must be at each usage of a field. For example,
.field field_spec, field_qualifiers, leave_method("mymethod")
NOLEAVE_METHOD is the default state if neither LEAVE_METHOD nor NOLEAVE_METHOD is specified in the script or in the repository. If LEAVE_METHOD has been specified in the repository, specifying NOLEAVE_METHOD will override this setting and the LEAVE_METHOD will not be invoked.
MATCH([CASE|NOCASE] [, EXACT|NOEXACT])
MATCH specifies whether the alpha field input must match the case of a specified allowable entry and/or match all characters in the entry. Specify one or more of these options:
CASE = Match case as well as characters.
NOCASE = Do not match case as well as characters. (default)
EXACT = Match the characters in the entry exactly for the number of characters specified.
NOEXACT = Do not match the characters exactly. (default)
If CASE is set, the match will be case sensitive. The entry no will match with “no”, but will not match with “NO” or “No”. If the UPPER_CASE_ONLY or UC qualifier is specified, MATCH(CASE) is ignored.
If EXACT is not set, UI Toolkit will look for a match based on the shortest string. For example, if you are looking for a match with the entry Ann, a match will be acknowledged with “A”, “An”, and “Ann”. However, if the entry is longer than Ann (for example, “Anne”), it will not be recognized as a match. EXACT mode means that input must match the allowed qualifier exactly for the full length of the input. If MATCH(EXACT) mode is set, Ann will only match with “Ann”.
CASE/NOCASE and EXACT/NOEXACT are not mutually exclusive; you can use these four options together in any combination. For example, if MATCH(CASE, EXACT) mode is set, the entry no will only match with “no”, but if MATCH(CASE, NOEXACT) mode is set, “NO”, “n”, and “no way” will all match the entry no.
NOCASE is the default if neither CASE nor NOCASE is specified in the script or repository. If CASE has been specified in the repository, NOCASE cancels case sensitive matching for the field.
NOEXACT is the default state if neither EXACT nor NOEXACT is specified in the script or in the repository. If EXACT has been specified in the repository, NOEXACT cancels full-length matching for the field.
NEGATIVE(ALLOWED|ONLY|ORZERO) NONEGATIVE
NEGATIVE allows negative values on numeric type (d or i) fields. Specify one of the following:
ALLOWED = Allows negative entries. (default)
ONLY = Allows negative entries only.
ORZERO = Allows negative or zero entries only.
If you specify the NEGATIVE qualifier, a negative or minus sign (–) can be placed either before or after the numeric value. This qualifier causes the size of the input field to be one character larger than the size of the data field. For example, if negative were specified on a d8 field, nine input characters would be allowed.
In the following example, the credit field can contain a negative value and allows a total of eight input characters (seven digits and a minus sign):
.field credit, d7, negative
NONEGATIVE is the default state if neither NEGATIVE nor NONEGATIVE is specified in the script or in the repository. If NEGATIVE has been specified in the repository, NONEGATIVE will override it and enable the input of non-negative values only.
NODECIMAL DECIMAL_REQUIRED
NODECIMAL (which may also be specified as NODECIMAL_REQUIRED) indicates that the user does not need to type a decimal point when placing input in a d type field. The input is stored right-justified, with the number of decimal places inferred from the storage format. In the following example, an entry of 55 will be interpreted as “.55”:
.field amount, d7.2, nodecimal
By way of contrast, an entry of 55 in the following example (which does not specify the NODECIMAL qualifier) will be interpreted as “55.00”:
.field amount, d7.2
An explicit decimal point overrides the NODECIMAL qualifier. For example, an entry of 12.34 always yields a result of “12.34”, even if the NODECIMAL qualifier is present.
DECIMAL_REQUIRED is the default state if neither DECIMAL_REQUIRED nor NODECIMAL is specified in the script or in the repository. If NODECIMAL has been specified in the repository, specifying DECIMAL_REQUIRED cancels it and aligns the numeric value based on an entered decimal point only.
NOECHO([display_character])
ECHO
NOECHO prevents the text entered by the user from being displayed in the field. If specified, display_character will display for each character typed. This feature is commonly used for password fields. After the user presses Enter, the display_character fills in any remaining spaces at the end of the input so others can’t see how many characters were entered.
If no display_character is specified, the field simply remains blank and the cursor remains stationary as the user types.
NOECHO has the following restrictions:
- It can only be used for alpha fields.
- You cannot use “E_” entries (field editing menu entries) on fields that have NOECHO.
- REQUIRED is the only validation allowed. (See REQUIRED, NOREQUIRED .)
The following example defines a password field in which an asterisk (*) is displayed for every character the user types. The typed characters themselves are not echoed in the input field.
.field password, a10, noecho(*), pos(1,1), prompt("Password:")
ECHO is the default state if neither NOECHO nor ECHO has been specified in the script or in the repository. If NOECHO has been specified in the repository, ECHO will cancel it and leave echo on for field input. To change or cancel the character specified with NOECHO, use the NOECHO qualifier with another character or no character specified.
NOTERM TERM
NOTERM is not supported on Windows.
NOTERM automatically terminates the field when the field is full so the user doesn’t have to press Enter. For example, if you type 555-1079 into the acctnum field defined below, it would be equivalent to typing 555-1079 and pressing Enter without NOTERM. (You can still terminate a NOTERM field by pressing Enter before it is full.)
.field acctnum, a8, noterm
TERM requires the user to press Enter to terminate field input. If a field is full and the user tries to enter more characters, the terminal bell is rung for each extra character typed.
TERM is the default state if neither one of these qualifiers is specified in the script or in the repository. If NOTERM is specified in the repository, specifying TERM will override it, requiring the user to press Enter to end input.
PAINT(character)
NOPAINT
PAINT specifies a character that “paints” the empty field with character to indicate where the user should type input. This character overrides any paint character designated by the .PAINT command.
In the following example, when the field is empty, it will be painted with the “#” character to indicate where the user should type input. (When input processing begins, the field is blanked.)
.field amount, d7, paint(#)
NOPAINT is the default state if neither of these qualifiers is specified in the script or in the repository. If PAINT has been specified in the repository, NOPAINT resets the field to the default paint character (which is a space).
This qualifier is ignored on Windows.
POSITION([CHANGE, ]row, column) NOPOSITION
POSITION specifies either a specific position or the number of rows and columns that the current position will change. It supports the following arguments:
CHANGE
(optional) Designates that POSITION is a degree of movement rather than an actual position. This value can be positive or negative.
row
Either a row position or the number of rows that the current position will move.
column
Either a column position or the number of columns that the current position will move.
If explicit positioning is not specified, UI Toolkit will automatically update the position to follow any field or text that was specified immediately before this command.
If there is no prompt defined (see the PROMPT qualifier section), the input field begins at the specified position. If a prompt is defined, the prompt begins at the specified position.
In the following example, the prompt begins at row 12, column 10, and the name field immediately follows the prompt (at row 12, column 15).
.field name, a30, position(12, 10), prompt("Name ")
In the next example, the name field will move 2 rows down from its current position but will stay in its current column.
.field name, a30, position(change, 2, 0)
NOPOSITION is the default state if neither POSITION nor NOPOSITION is specified in the script or in the repository. If POSITION has been specified in the repository, NOPOSITION resets the position of the prompt to default to the next character available rather than the position specified in the repository.
PROMPT(prompt)
NOPROMPT
PROMPT provides a fixed (static) or variable (dynamic) prompt to the user for input:
- With a fixed prompt, prompt is a quoted string that must include any desired spacing between the prompt and the input. Fixed prompts may be modified at runtime using I_PROMPT.
- With a variable prompt, prompt is a number that specifies the length of the prompt. The I_PROMPT subroutine uses this length to set the variable prompt.
If you do not use the FIELD_POSITION qualifier, field input will immediately follow the prompt. Your prompt must include any desired spacing between the prompt and the input.
The following example defines a fixed prompt that prompts the user for a name:
.field name, a30, prompt("Name ")
The following example defines a variable prompt that can be up to 20 characters long:
.field name, a30, prompt(20)
NOPROMPT is the default state if this category is not specified in the script or in the repository. If PROMPT has been specified in the repository, NOPROMPT will cancel it. If you wish to specify a new input prompt, use PROMPT with the desired parameter.
PROMPTFONT(palette_name)
NOPROMPTFONT
PROMPTFONT specifies a font for a prompt, where palette_name is the name of a font palette entry. Palette_name must be known at runtime or a default font will be used. See Using fonts on Windows for more information on font palettes.
Although the PROMPTFONT qualifier has no visual effect on UNIX and OpenVMS, it is preserved with the window definition so that the same window library can be used for both non-Windows and Windows systems.
Specifying a font with PROMPTFONT overrides any default font that would have been used for the prompt. Specifying NOPROMPTFONT indicates that the default font for the prompt is to be used.
If a prompt is not specified for the field, PROMPTFONT will be ignored.
See also .FONT for more information about specifying a window’s font, and FONT, NOFONT for more information about specifying a prompt’s font.
The following example specifies “my_prompt_font” for field inpfld.
.field inpfld, a30, prompt("Name "), promptfont(my_prompt_font)
NOPROMPTFONT is the default state if neither PROMPTFONT nor NOPROMPTFONT is specified in the script or in the repository. If PROMPTFONT has been specified in the repository, NOPROMPTFONT cancels the field’s font and the uses window’s font instead.
RADIO NORADIO
The RADIO qualifier indicates that this field is to be displayed as a radio button group on Windows. (Specifying RADIO on UNIX or OpenVMS has no effect.) It must be used in conjunction with either SELWND or SELECT. Radio buttons are a form of selection window, where each entry becomes a radio button, and the text for each entry is displayed to the right of the radio button. Note the following:
- All radio buttons for a field receive focus as a single field. Pressing Tab, Shift+Tab, or Enter, or clicking on another field advances focus to the next field.
- If you use the SELECT qualifier with RADIO, radio buttons are placed vertically in a single column unless you pass the height argument for SELECT. If you pass height, this argument determines how many radio buttons a column can hold. For example, if you pass height as 3 and there are eight radio buttons, there will be three columns: the first and second columns will have three radio buttons, and the third column will have two radio buttons.
- If you use the SELWND qualifier with RADIO, the height of the associated selection window determines how many radio buttons can fit in a column. For example, if the selection window is only one row high, the buttons will be placed horizontally; there will be only one button per column. If the selection window is three rows high and there are five radio buttons, the first column will have three radio buttons, and the second will have two.
- If a font is not specified for the field, the default prompt font will be used for the radio button’s selection entry text.
- Make sure radio buttons do not overlap other controls or extend beyond the limits of the containing window. Toolkit does not limit radio button placement.
For information on creating an input window with radio buttons at runtime, see the IB_FIELD Discussion. For information on how radio button fields are validated, see SELECT, NOSELECT .
|
Composer can also be used to create radio buttons. See Composer for more information. |
You can use the selection subroutines with radio buttons to load new selections, get or set a default, and so forth. For example, to make a change to a radio button set (add a button, remove a button, etc.), use S_SELLD to reload the associated selection window with a different set of selections.
You can retrieve the selection window ID with I_FLDINF.
NORADIO is the default state if neither RADIO nor NORADIO is specified in the script or in the repository. If RADIO has been specified in the repository, specifying NORADIO will override this setting and the field will not be displayed as a group of radio buttons.
RANGE(minimum, maximum)
NORANGE
RANGE defines the minimum and maximum input values for a numeric (d or i) field.
For date and time fields, the minimum and maximum values must be specified in field storage format, rather than the field input or display format. Also note that the minimum and maximum values will not be validated for date and time fields; they will only be compared with the resulting value from the user’s input.
The following example defines a minimum value of 1 and a maximum value of 100.
.field amount, d3, range(1, 100)
NORANGE is the default state if neither of these qualifiers is specified in the script or in the repository. If RANGE has been specified in the repository, NORANGE cancels range checking for the field. If you only wish to specify new range parameters, use RANGE with the new parameters.
READONLY, NOREADONLY
READONLY NOREADONLY
READONLY renders the field read-only. Only edit controls can be rendered read-only. Selection window, radio button, and check box fields that specify the READONLY qualifier will generate an error when compiled by script or when read into Composer.
Like disabled fields, the contents of a read-only field cannot be modified. Unlike a disabled field, a read-only field is able to receive focus. On Windows, the field’s contents can be highlighted for the purpose of copying to the clipboard. On Windows, the field will use the “3D face” color for its background and “window text” color for the text. Typically, this is black on dark gray. This rendition can be modified by using U_REND but cannot be modified using U_MODREND. See U_REND for more information on processing display renditions.
Read-only fields within an ActiveX Toolkit list are rendered the same as disabled fields.
.field description, 3a50, readonly
NOREADONLY cancels the field from being read-only.
REQUIRED NOREQUIRED
REQUIRED specifies that a non-blank alpha or non-zero numeric entry is required in the field. For example, the custno field doesn’t allow an entry of 0.
.field custno, d6, required
You can enable the user to temporarily exit from a required field. If the first keystroke in the field is a menu entry that causes an exit from the field, no validation will be done by the input processor. However, the user will still be required to enter data into all required fields before completing the input set.
NOREQUIRED is the default state if neither REQUIRED nor NOREQUIRED is specified in the script or in the repository. If REQUIRED has been specified in the repository, specifying NOREQUIRED overrides it and enables the user to skip this field or enter a zero.
RETAIN_POSITION, NORETAIN_POSITION
RETAIN_POSITION NORETAIN_POSITION
RETAIN_POSITION enables the user to leave and then return to the text field, retaining the current position until the field is re-initialized or redisplayed. It is allowed only for text fields.
NORETAIN_POSITION is the default state if neither RETAIN_POSITION nor NORETAIN_POSITION is specified in the script or in the repository. If RETAIN_POSITION has been specified in the repository, specifying NORETAIN_POSITION overrides it.
REVERSE NOREVERSE
REVERSE specifies reverse video text. For detailed information on REVERSE and other input field renditions, see Renditions. In the following example, the contents of the field are in reverse video.
.field description, 4a60, reverse
NOREVERSE is the default state if neither REVERSE nor NOREVERSE is specified in the script or in the repository. If REVERSE has been specified in the repository, NOREVERSE cancels the reversing.
SELECT(srow, scolumn, [height], entry[, ...]) NOSELECT
SELECT defines a selection window by specifying the position where the window is placed on the screen and designating one or more text entries. Up to 100 text entries may be specified. SELECT takes the following arguments;
srow
The row at which the upper-left corner of the selection window will be placed, relative to the beginning of the field. Ignored on Windows.
scolumn
The column at which the upper-left corner of the selection window will be placed, relative to the beginning of the field. Ignored on Windows.
height
(optional) The maximum number of rows in the selection window (or the maximum number of radio buttons placed in a column if the RADIO qualifier is specified). A height of 0 is the same as omitting height.
entry
A text entry in the selection window.
Data on UNIX and OpenVMS and radio buttons on Windows are organized first by column, top to bottom, and then left to right. For example, if height is 3 and there are eight entries or radio buttons, the window will contain three columns with three entries or radio buttons in the first column, three in the second, and two in the third. If height is not specified, the height of the window is the number of entries or radio buttons in a column.
On Windows, fields associated with selection windows use native Windows combo boxes (unless you specify the RADIO qualifier; see below). Combo boxes combine the field edit control with an arrow box. Clicking on the arrow or anywhere within the field will drop down the combo box. The combo box arrow is only displayed when the input set containing the field is active. If the height of the selection window is less than the number of entries it contains, the drop-down list will display height number of entries and a scroll bar.
If you specify the RADIO qualifier (supported on Windows only) with SELECT, the field will be a group of radio buttons. These buttons are placed vertically in a single column unless you pass the height argument for SELECT. If you pass height, this argument determines how many radio buttons can fit in a single column. For example, if there are three radio buttons and height is passed as 1, there will be three columns with one radio button in each. (In other words, the buttons are placed horizontally.) If, however, there are eight radio buttons and height is passed as 3, there will be three radio buttons in the first column, three in the second, and two in the third. For more information on radio buttons, see RADIO, NORADIO .
On Windows, highlighting an entry in a combo box or selecting a radio button does not, by default, cause the field to be immediately validated. Until the field loses focus, no Toolkit validation tests or change method occurs. Likewise, no leave or arrive methods will be invoked until focus is lost. In order for a field to be immediately validated, the D_VALSTCHG option of E_STATE needs to be set. See E_STATE for more information on this subroutine and the D_VALSTCHG option.
If the user selects an entry by dropping down the combo box list, focus moves to the next field by default. If the user selects an entry without dropping down the combo box list, focus will remain on the combo box. To always maintain focus on the combo box set after a selection is made, turn off the D_CBADVANCE option of E_STATE.
The following example defines a selection window with a maximum height of two rows and the text entries “yes” and “no.” The upper-left corner of the selection window will be placed at row 1 and column 2, relative to the beginning of the field.
.field yesno, a3, select(1, 2, 2, yes, no)
NOSELECT is the default state if neither SELECT nor NOSELECT has been specified in the script or in the repository. If SELECT has been specified in the repository, NOSELECT cancels the selection window associated with the field. If you only wish to specify different parameters for the selection window, use SELECT with the new parameters.
You can use the selection subroutines to load new selections, get or set a default, and so forth. See Selection Routines for details.
SELWND(srow, scolumn, window)
NOSELWND
SELWND specifies a selection window to be placed on the screen. It is similar to SELECT, except the selection window already exists. SELWND takes the following arguments:
srow
The screen row at which the upper-left corner of the selection window will be placed, relative to the beginning of the field.
scolumn
The screen column at which the upper-left corner of the selection window will be placed, relative to the beginning of the field.
window
The name of a selection window. The window must either reside in the same window library or be created during runtime (using the S_SELBLD routine) before the input window is loaded.
If you use the SELWND qualifier on Windows, the field will be either a native Windows combo box or, if you also specify RADIO, a group of radio buttons. If you use SELWND and RADIO, the height of the selection window determines the maximum number of radio buttons that can fit in a column. For example, if the window is two rows high and there are five radio buttons, the first column will have two radio buttons, the second column will have two, and the third column will have one. You can control spacing between radio button columns by changing the column width for the selection window. This spacing is calculated by adding the width of the radio button to the width of a column in the selection window (which is equal to the number of characters times the character width for the font).
See the Windows-specific information in SELECT, NOSELECT for more information on native Windows combo boxes and radio buttons.
The following example specifies that the yesno selection window’s upper-left corner will be placed at row 1, column 2, relative to the beginning of the field.
.field yesno, a3, selwnd(1, 2, yesno)
NOSELWND is the default state if neither SELWND nor NOSELWND is specified in the script or in the repository. If SELWND has been specified in the repository, NOSELWND cancels the association between the pre-built selection window and the field. If you only want to specify different parameters for this category, use SELWND with the new parameters.
TIME([AMPM][, NOW]) NOTIME
TIME enables you to process times.
AMPM = Specifies that the display form will use a 12-hour clock with an AM/PM designation. AMPM is not case sensitive and may be abbreviated. These designators are set by DTK_AM and DTK_PM in syntxt.ism. If AMPM is not specified, a 24-hour clock is used.
NOW = Defaults the time to the current system time if the user presses Enter without entering a time.
You can use this qualifier only on d4, d6 (or greater), i2, or i4 fields; fields of any other size will generate an error. The input for a time is either numeric or delimited.
The size of the field defines the way the time is stored as the table below indicates. The size used for the hour will be extended if a field larger than d6 is used.
|
Time Formats for Field Sizes |
||
|---|---|---|
|
Size |
Time format |
Meaning |
|
d4 field |
HHMM |
Hour and minute |
|
d6 field |
HHMMSS |
Hour, minute, second |
|
i2 field |
HHMM |
Hour and minute |
|
i4 field |
HHMMSS |
Hour, minute, second |
For numeric input
- if one or two digits are entered, it is considered to be the hour.
- if three or four digits are entered, it is considered to be the hour and minute. The two rightmost digits will be the minute, and the leftmost one or two digits will be the hour.
- if five or more digits are entered, it is considered to be the hour, minute, and second. The two rightmost digits will be the second, the next two digits are the minute, and the leftmost one or two digits are the hour.
When the input string is delimited, if any component of the time is missing that part will be assumed to be zero. If one of the non-numeric components is the post-meridian indicator, twelve hours will be added to the time specified.
The global field g_time_sep in tkctl.def specifies the character that will separate parts of the time on redisplay. It is initialized to a colon (:) by U_START.
In the following example, if the user enters 1545, the time will be displayed as “3:45 PM”, and stored as 154500.
.field shiptime, d6, time(ampm)
In this example, the time in the ordtime field defaults to the current system time if the user presses Enter without entering anything into the field. The time is stored in the form HHMMSS.
.field ordtime, d6, time(now)
NOTIME is the default state if neither TIME nor NOTIME is specified in the script or in the repository. If TIME has been specified in the repository, NOTIME resets the repository field to a normal decimal field. To override either the AMPM or NOW argument, specify TIME without the one you want to override.
TIMESTAMP, NOTIMESTAMP
TIMESTAMP([AMPM][, SHORT]) NOTIMESTAMP
TIMESTAMP creates a read-only 8-byte integer field that corresponds to a timestamp key in an ISAM file. (See Keys in ISAM files.) It enables you to create a timestamp field without drawing it from a repository autotime or ctimestamp field.
AMPM = Sets the display format to use a 12-hour clock with an AM/PM designation preceded by a space. AMPM is not case sensitive and may be abbreviated. These designators are set by DTK_AM and DTK_PM in syntxt.ism. If AMPM is not specified, a 24-hour clock is used.
SHORT = Sets the display format to a short form that omits the following: the century portion of the year, the seconds value and its separator, and the milliseconds value and the period (.) that precedes it.
By default, fields drawn from repository autotime and ctimestamp fields become timestamp fields in the window library. If you do not want this behavior, you can use NOTIMESTAMP to create a standard integer field from a repository autotime or ctimestamp field. You can alter the default behavior by using AMPM and SHORT with TIMESTAMP to change the display format for a timestamp field drawn from a repository autotime or ctimestamp field.
An error will occur if you use TIMESTAMP with a field that is set to anything but a read-only 8-byte integer, or if the field is set to be a selection field, a radio button set, or a check box.
The default display format for a timestamp field consists of a date and a time separated by a space. For example:
12/31/2013 23:59:59.999999
The date portion consists of two-digit numbers for month and day and a four-digit number for year. (Two digits are used for the year if SHORT is specified.) The g_date_order setting defines the order of date components (month, day, year), and g_date_sep defines the separator for date components (see tkctl.def).
The time consists of an hour value (1 to 24, unless AMPM is specified), a minute value, a seconds value, and a six-digit microseconds value. The separator for hour, minutes, and seconds is defined by g_time_sep (see tkctl.def), and a period (.) precedes the microseconds value.
|
Qualifier(s) |
Default display length and view lengtha |
Example |
|---|---|---|
|
none |
26 |
12/31/2013 23:59:59.999999 |
|
AMPM |
29 |
12/31/2013 11:59:59.999999 PM |
|
SHORT |
14 |
12/31/13 23:59 |
|
AMPM and SHORT |
17 |
12/31/13 11:59 PM |
Timestamp fields are right-justified by default, though justification has an effect only if the month or hour requires one digit, or if the display length has been changed from the default.
You can change the display format by setting the view length, display length, or justification for the field, and you can use an IDISPLAY_METHOD method to set up a different display format.
UNDERLINE NOUNDERLINE
UNDERLINE specifies underlined text. For detailed information on UNDERLINE and other input field renditions, see Renditions.
In the following example, the contents of the field are underlined.
.field contact, a30, underline
NOUNDERLINE is the default state if neither UNDERLINE nor NOUNDERLINE is specified in the script or in the repository. If UNDERLINE has been specified in the repository, NOUNDERLINE cancels the underlining.
UPPER_CASE_ONLY, NOUPPER_CASE_ONLY
UPPER_CASE_ONLY NOUPPER_CASE_ONLY
UPPER_CASE_ONLY (which can be abbreviated UC) converts lowercase input characters to uppercase on alpha fields. All input will be displayed in uppercase. In the following example, all entries in the state field will be displayed in uppercase.
.field state, a2, uc
Note that only input is uppercased. If your program loads data directly into this field, you must uppercase that data.
NOUPPER_CASE_ONLY (which can be abbreviated NOUC or LOWER_CASE_ALLOWED) is the default state if neither of these qualifiers is specified in the script or in the repository. If UPPER_CASE_ONLY has been specified in the repository, NOUPPER_CASE_ONLY will cancel it and enable lowercase input.
USER([user_text][, user_type])
NOUSER
USER enables you to associate a user-defined text string with input fields and/or validate a data type that you’ve defined. User_text is the text to be stored, while user_type is a string that represents the user-defined data type. Either user_text or user_type (or both) must be specified.
The size of user_text is fixed by the size of the string used during the window’s compilation; writing data out to the string won’t change the size of the string. The maximum size of user_text is 80 characters. You can access user_text at runtime with the I_USER subroutine.
The user_type argument is available only on alpha fields. It flags the runtime input processor to call the ECHKFLD_METHOD (for extra input validation), EDSPFLD_METHOD (for display), and EEDTDSP_METHOD (for editing) subroutines. User_type is passed to EDSPFLD_METHOD, ECHKFLD_ METHOD, and EEDTDSP_METHOD to be used as a control code. The maximum size of user_type is 30 characters.
For example, you might want to define a zip code data type and a phone number data type. If the zip code type is “ZIP_TYPE”, then a user_type specified as “ZIP_TYPE” will indicate that you want to check the zip code. To check your user-defined data type, you must write the ECHKFLD_METHOD and EDSPFLD_METHOD subroutines. (If you choose to use the EEDTDSP_METHOD or %IEDITFMT_METHOD routines, you will need to write them as well.) If ECHKFLD_METHOD is not specified, your code will still run but UI Toolkit will bypass user-defined data type checking. (See Environment Routines for more information about ECHKFLD_METHOD, EDSPFLD_METHOD, and EEDTDSP_METHOD.)
In the following example, the string “This can contain whatever you want” is associated with the name field.
.field name, a30, user("This can contain whatever you want")
The following sample window script includes a user-defined zip code data type. It assumes that the subroutines ECHKFLD_METHOD and EDSPFLD_METHOD will control the zip code input validation and display format.
.input mail, 1, 17
.placement 5, 29
.title " Zip Test "
.field zip, a9, pos(1,2), prompt("Zip"), user(, "ZIP_TYPE"), uc
.end
NOUSER is the default state if neither USER nor NOUSER is specified in the script or in the repository. If USER has been specified in the repository, NOUSER cancels both the user-text and user-defined data type specified in the repository. To cancel only one, you must specify USER with the desired parameter.
VIEW_LENGTH(view_length)
NOVIEW_LENGTH
VIEW_LENGTH determines the width of the field (that is, the width of the area on the screen that will display data for the field), overriding Toolkit’s default view length. Valid values for view_length are 0 through 9,999. This value should not be so large that it would cause the field to extend beyond the window border. If you set view_length to 0, the default view length is used.
View length cannot be specified for check box fields or radio buttons.
On Windows, if the view length is less than the field’s display length, the field is scrollable. For text fields (multi-dimensional alpha fields), this doesn’t affect the number of lines, just the width of each line. You can scroll through all displayed characters and delete any displayed character, no matter what the input length. (However, you can enter a character only when there are fewer characters than the limit imposed by the input length.)
|
On UNIX and OpenVMS, if the view length is less than the field’s display length, the contents of a field will be truncated to the view length if you move the cursor in the field or modify the contents of the field. |
If you specify an explicit view length on Windows, the width of the field is computed by multiplying the view length value by the width of the sizing character for the font used by the field. (If the font is changed, the field’s width is adjusted.) On UNIX and OpenVMS, the width is set to the number of characters specified by view_length.
If you specify an explicit view length for a field in an ActiveX list, this setting overrides input and display lengths, but may be extended by the length of a header, a footer, or another field that occupies the same column in a multi-line item. A view length may also be overridden by dragging column borders or by a call to SetColumnWidth, a published method for ActiveX Toolkit lists.
If you don’t set an explicit view length, the default is the greater of display length or input length.
|
|
If no explicit view length is in effect, a value of 0 is returned in gs_viewlen. This is unlike gs_dsplen and gs_inplen, which always return display length and input length settings, whether you set them or the defaults are in effect. (Gs_viewlen, gs_dsplen, and gs_inplen are members of the gs_inpfld record returned by I_FLDINF.) |
For information on how view length works with other length settings for input fields, see Understanding display, input, and view lengths.
NOVIEW_LENGTH is the default state if neither VIEW_LENGTH nor NOVIEW_LENGTH is specified in the script or in the repository. If VIEW_LENGTH has been specified in the repository, NOVIEW_LENGTH cancels the view length setting, which causes the longer of the display length or input length to determine the field width.
WAIT(IMMEDIATE|FOREVER|GLOBAL|n)
WAIT specifies an input time-out, overriding the g_wait_time setting, which by default instructs Toolkit to wait until I/O processing is complete (i.e., no time-out) before returning to the calling routine. (See g_wait_time.) The wait time can be specified with one of the following:
IMMEDIATE = Time out immediately. When this is set the user will be unable to enter data in the field.
FOREVER = Wait until I/O processing is completed.
GLOBAL = Use the globally specified time-out (g_wait_time).
n = Wait up to n seconds (where n is a positive value) for I/O processing to be complete.
If a time-out is set and the user doesn’t complete input within the specified time, g_select is set to true and g_entnam is set to the entry name set with g_time_entry, which is defined in tkctl.def. The default value for g_time_entry is “O_TIMEOUT” (see g_time_entry).
Note the following platform differences:
- On UNIX and OpenVMS, the time-out is reset after the user presses the first keystroke in an input field. For instance, if you have a 60 second time-out on a field, and after 30 seconds the user presses a key, the user has an additional 60 seconds to complete input. Subsequent keystrokes, however, do not reset the time-out.
- On Windows, the time-out is not reset by keystrokes. Additionally, no time-out will occur while a menu is dropped down or when the application is otherwise suspended (as when a message window is open). When the application continues, the time-out occurs as soon as the application can process the message from the system.
