ConsoleField properties and fields

The following properties are required in a variable of type ConsoleField:

The name field is also required, although not in a constant ConsoleField.

The properties of ConsoleField are as follows:
fieldLen
Specifies the number of positions needed to display the largest value of interest. For constant consoleFields, you do not set this property: fieldLen is the number of characters occupied by the displayed value, as included in the value property.
  • Type: INT
  • Example: fieldLen = 20
  • Default: none
position
The location of the console field within the form. The property contains an array of two positive integers: the line number followed by the column number. The line number is calculated from the top of the form. Similarly, the column number is calculated from the left of the form.
  • Type: INT[]
  • Example: position = [2, 3]
  • Default: [1,1]
segments
Specifies the row, column, and length of each field segment, which is a consoleField subsection that can have delimiters. To create the appearance of a multiline text box, you stack one field segment on successive lines at the same form column, and the collection of segments acts as one field.
  • Type: INT[3][]
  • Example: segments = [[5,1,10],[6,1,10]]
  • Default: none

If a value is specified for segments, the value for position is ignored, and fieldLen should be set to the length of all segments combined.

If you specify multiple segments, the behavior of the ConsoleField is also affected by the value of the lineWrap field.

validValues
Specifies the list of values that are valid for user input.
  • Type: Array literal of singular and two-value elements
  • Example: validValues = [ [1,3], 5, 12 ]
  • Default: none

For details, see validValues.

The properties of a consoleField array include the previous ones (except for segments), as well as these:
columns
Specifies the number of columns in which to display the elements in an array of type ConsoleField. If the array has five elements and the value of the columns property is two, for example, the first line of the form shows two elements; the second line shows two elements; and the third line shows one element.
  • Type: INT
  • Example: columns = 3
  • Default: 1

This property is meaningful only for arrays of type ConsoleField. The distribution of array elements on screen (whether across or up and down) is affected by the property orientIndexAcross.

linesBetweenRows
Specifies the number of blank lines between each line that contains an array element.
  • Type: INT
  • Example: linesBetweenRows = 3
  • Default: 0

This property is meaningful only for arrays of type ConsoleField.

orientIndexAcross
Indicates whether the distribution of array elements is across the screen, as shown in a later example.
  • Type: Boolean
  • Example: orientIndexAcross = yes
  • Default: yes

This property is meaningful only for arrays of type consoleField.

If the property orientIndexAcross is set to yes, successive elements of the array are displayed from left to right. In the following, 2-column example, each successive element displays an integer that is equivalent to the element index:
  1   2
  3   4
  5
If the property orientIndexAcross is set to no, the successive elements are displayed from top to bottom:
  1   4
  2   5
  3
spacesBetweenColumns
Specifies the number of spaces separating each column of fields.
  • Type: INT
  • Example: spacesBetweenColumns = 3
  • Default: 1

This property is valid only for arrays of type consoleField.

The fields of ConsoleField are as follows:
align
The align field specifies the position of data in a variable field when the length of the data is smaller than the length of the field.
  • Type: AlignKind
  • Example: align = left
  • Default: left for character or timestamp data, right for numeric
  • Updatable at run time? Yes
Values are as follows:
left
Place the data at the left of the field. Initial spaces are stripped and placed at the end of the field.
none
Do not justify the data. This setting is valid only for character data.
right
Place the data at the right of the field. Trailing spaces are stripped and placed at the beginning of the field.
autonext
Indicates whether, after the user fills the current ConsoleField, the cursor goes to the next field.
  • Type: Boolean
  • Example: autonext = yes
  • Default: None
  • Updatable at run time? Yes

The tab order determines which ConsoleField is next, as described in ConsoleUI parts and related variables.

binding
Specifies the name of the variable to which the ConsoleField is bound by default.
  • Type: String
  • Example: binding = "myVar"
  • Default: None
  • Updatable at run time? No.

For on overview of binding, see ConsoleUI parts and related variables.

caseFormat
Specifies how to treat input and output in relation to case sensitivity.
  • Type: CaseFormatKind
  • Example: caseFormat = lowerCase
  • Default: defaultCase
  • Updatable at run time? Yes
Values are as follows:
defaultCase (the default)
Has no effect on case
lowerCase
Transforms characters to lowercase, as possible
upperCase
Transforms characters to uppercase, as possible
color
Specifies the color of the text in the ConsoleField.
  • Type: ColorKind
  • Example: color = red
  • Default: white
  • Updatable at run time? Yes, but the update has a visual effect only if the ConsoleField is displayed (or obtains focus) after the field is updated
Values are as follows:
defaultColor or white (the default)
White
black
Black
blue
Blue
cyan
Cyan
green
Green
magenta
Magenta
red
Red
yellow
Yellow
comment
Specifies the comment, which is the text displayed in the Window-specific comment line (if any) when the cursor is in the ConsoleField.
  • Type: String
  • Example: "Employee name"
  • Default: Empty string
  • Updatable at run time? No
commentKey
Specifies a key used to search the resource bundle that includes the comment, which is the text displayed in the Window-specific comment line (if any) when the cursor is in the ConsoleField. If you specify both comment and commentKey, comment is used.
  • Type: String
  • Example: commentKey = "myKey"
  • Default: Empty string
  • Updatable at run time? No

The resource bundle is identified by the system variable ConsoleLib.messageResource, as described in messageResource.

dataType
Specifies a string to identify a data type. The value is used to validate that user input (such as = 1.5) is compatible with a particular kind of SQL column. The field is meaningful only when the openUI statement for the ConsoleField (or related ConsoleForm) includes the statement property isConstruct.
  • Type: String
  • Example: dataType = "NUMBER"
  • Default: Empty string
  • Updatable at run time? No

In relation to numeric input, specify the value "NUMBER" if you allow the user to specify a floating point value (in which case, > 1.5 is valid user input); otherwise, specify the string equivalent of an integer; for example, "INT".

dateFormat
Indicates how to format output; but specify dateFormat only if the ConsoleField accepts a date.
  • Type: a String or date-related system constant
  • Example: dateFormat = isoDateFormat
  • Default: none
  • Updatable at run time? No
Valid values are as follows:
"pattern"
The value of pattern consists of a set of characters, as described in Date, time, and timestamp format specifiers.

Characters may be dropped from the beginning or end of a complete date specification, but not from the middle.

defaultDateFormat
The date format given in the runtime Java™ locale.
isoDateFormat
The pattern "yyyy-MM-dd", which is the date format specified by the International Standards Organization (ISO).
usaDateFormat
The pattern "MM/dd/yyyy", which is the IBM® USA standard date format.
eurDateFormat
The pattern "dd.MM.yyyy", which is the IBM European standard date format.
jisDateFormat
The pattern "yyyy-MM-dd", which is the Japanese Industrial Standard date format.
systemGregorianDateFormat
An 8- or 10-character pattern that includes dd (for numeric day of the month), MM (for numeric month), and yy or yyyy (for numeric year), with characters other than d, M, y, or digits used as separators.
The format is in this Java runtime property:
  vgj.datemask.gregorian.long.NLS
NLS
The NLS (national language support) code that is specified in the Java runtime property vgj.nls.code. The code is one of those listed in targetNLS. Uppercase English (code ENP) is not supported.

For additional details on vgj.nls.code, see Java runtime properties (details).

systemJulianDateFormat
A 6- or 8-character pattern that includes DDD (for numeric day of the year) and yy or yyyy (for numeric year), with characters other than D, y, or digits used as separators.
The format is in this Java runtime property:
  vgj.datemask.julian.long.NLS
NLS
The NLS (national language support) code that is specified in the Java runtime property vgj.nls.code. The code is one of those listed in targetNLS. Uppercase English (code ENP) is not supported.

For additional details on vgj.nls.code, see Java runtime properties (details).

editor
Specifies the program for user interaction with the data; but is meaningful only if the ConsoleField is bound to a variable of type LOB.
  • Type: String
  • Example: editor = "/bin/vi"
  • Default: none
  • Updatable at run time? Yes

You can specify the name of an executable found in the PATH or LIBPATH; alternatively, you can specify the fully qualified path of that executable.

help
Specifies the text to display when the following situation is in effect:
  • The cursor is in the ConsoleField; and
  • The user presses the key identified in ConsoleLib.key_help.
  • Type: String
  • Example: help = "Update the value"
  • Default: Empty string
  • Updatable at run time? Yes
helpKey
Specifies an access key for searching the resource bundle that contains text for display when the following situation is in effect:
  • The cursor is in the ConsoleField; and
  • The user presses the key identified in ConsoleLib.key_help.
If you specify both help and helpKey, help is used.
  • Type: String
  • Example: helpKey = "myKey"
  • Default: Empty string
  • Updatable at run time? Yes

The resource bundle is identified by the system variable ConsoleLib.messageResource, as described in messageResource.

highlight
Specifies the special effects (if any) that are used when displaying the ConsoleField.
  • Type: HighlightKind[]
  • Example: highlight = [reverse, underline]
  • Default: [noHighLight]
  • Updatable at run time? Yes, but the update has a visual effect only if the ConsoleField is displayed (or obtains focus) after the highlight field is updated
Values are as follows:
noHighlight (the default)
Causes no special effect. Use of this value overrides any other.
blink
Has no effect.
reverse
Reverses the text and background colors so that (for example) if the display has a black background with white letters, the background becomes white and the text becomes black.
underline
Places an underline under the affected areas. The color of the underline is the color of the text, even if the value reverse is also specified.
initialValue
Specifies the initial value for display. If you specify both initialValue and initialValueKey, initialValue is used.
  • Type: String
  • Example: initialValue = "200"
  • Default: Empty string
  • Updatable at run time? Yes

If the setInitial property in the openUI statement is set to true, the value of the initialValue property in the consoleField is used. If that openUI property is false, however, current values of bound variables are shown instead, and the value of the initialValue property is ignored.

initialValueKey
Specifies an access key for searching the resource bundle that contains the initial value for display. If you specify both initialValue and initialValueKey, initialValue is used.
  • Type: String
  • Example: initialValueKey = "myKey"
  • Default: Empty string
  • Updatable at run time? Yes

The resource bundle is identified by the system variable ConsoleLib.messageResource, as described in messageResource.

inputRequired
Indicates whether the user will be prevented from navigating away from the field without entering a value.
  • Type: Boolean
  • Example: inputRequired = yes
  • Default: no
  • Updatable at run time? No
intensity
Specifies the strength of the displayed font.
  • Type: IntensityKind[]
  • Example: intensity = [bold]
  • Default: [normalIntensity]
  • Updatable at run time? Yes, but the update has a visual effect only if the ConsoleField is displayed (or obtains focus) after the intensity field is updated
Values are as follows:
normalIntensity (the default)
Causes no special effect. Use of this value overrides any other.
bold
Causes the text to appear in a bold-weight font.
dim
Has no effect at this time. In future, may cause the text to appear with a lessened intensity, as appropriate when an input field is either disabled or should be deemphasized.
invisible
Removes any indication that the field is on the form.
isBoolean
Indicates whether the ConsoleField represents a Boolean value. The field isBoolean restricts the valid ConsoleField values and is useful for input or output.

The value of a numeric field is 0 (for false) or 1 (for true).

The value of a character field is represented by a word or subset of a word that is national-language dependent, and the specific values are determined by the locale. In English, for example, a boolean field of three or more characters has the value yes (for true) or no (for false), and a one-character boolean field value has the truncated value y or n.
  • Type: Boolean
  • Example: isBoolean = yes
  • Default: no
  • Updatable at run time? No
lineWrap
Indicates how to wrap text onto a new line whenever wrapping is necessary to avoid truncating text.
  • Type: LineWrapType
  • Example: value = compress
  • Default: character
  • Updatable at run time? Yes
Values are as follows:
character (the default)
The text in a field will not be split at a white space, but at the character position where the boundary of the field segment is.
compress
If possible, the text will be split at a white space. When the user leaves the consoleField (either by navigating to another consoleField or by pressing Esc), the value is assigned to the bound variable, and any additional spaces that are used to wrap text are removed.
word
If possible, the text in a field will be split at a white space. When the value is assigned to the bound variable, additional spaces are included to reflect how the value was padded to wrap at word boundaries.

The lineWrap field is meaningful only for a ConsoleField that has multiple segments, as is controlled by the segments property.

masked
Indicates whether each character in the ConsoleField is displayed as an asterisk (*), as is appropriate when the user types a password.
  • Type: Boolean
  • Example: masked = yes
  • Default: no
  • Updatable at run time? Yes
minimumInput
Indicates the minimum number of characters in valid input.
  • Type: INT
  • Example: minimumInput = 4
  • Default: no
  • Updatable at run time? No
name
ConsoleField name, as used in a programming context in which the name is resolved at run time. It is strongly recommended that the value of the name field be the same as the name of the variable.
  • Type: String
  • Example: name = "myField"
  • Default: none
  • Updatable at run time? No
numericFormat
Indicates how to format output; but specify numericFormat only if the ConsoleField accepts a number.
  • Type: String
  • Example: numericFormat = "-###@"
  • Default: none
  • Updatable at run time? No
Valid characters are as follows:
#
A placeholder for a digit.
*
Use an asterisk (*) as the fill character for a leading zero.
&
Use a zero as the fill character for a leading zero.
#
Use a space as the fill character for a leading zero.
<
Left justify the number.
,
Use a locale-dependent numeric separator unless the position contains a leading zero.
.
Use a locale-dependent decimal point.
-
Use a minus sign (-) for values less than 0; use a space for values greater than or equal to 0.
+
Use a minus sign for values less than 0; use a plus sign (+) for values greater than or equal to 0.
(
Precede negative values with a left parenthesis, as appropriate in accounting.
)
Place a right parenthesis after a negative value, as appropriate in accounting.
$
Precede the value with the locale-dependent currency symbol.
@
Place the locale-dependent currency symbol after the value.
pattern
Specifies the pattern for input and output formatting if the ConsoleField content is of a character type.
  • Type: String
  • Example: pattern = "(###) ###-####"
  • Default: none
  • Updatable at run time? No
These control characters are available:
  • A is a placeholder for letters, and the subset of characters that are considered to be letters is dependent on the locale
  • # is a placeholder for numeric digits
  • X is a placeholder for a required character of any kind
Characters other than the preceding three are included in the input or output; but for output, any overlaid characters are lost:
  • If the output pattern is "(###) ###-####", the value "6219655561212" is shown as follows:
      (219) 555-1212

    Each 6 in the original value is unavailable to the user and is lost if the data store is updated.

  • For input, the cursor skips the literal charcters and only allows typing where the placeholder characters occur. In the current example, if the user types 2195551212, the string "(219) 555-1212" becomes the value within the ConsoleField and is the value placed in the bound variable.
protect
Specifies whether the ConsoleField is protected from user update.
  • Type: Boolean
  • Example: protect = yes
  • Default: no
  • Updatable at run time? No
Values are as follows:
No (the default)
Sets the field so that the user can overwrite the value in it.
Yes
Sets the consoleField so that the user cannot overwrite the value in it. In addition, the cursor skips the consoleField whenever the user attempts to navigate to it, as in these cases:
  • The user is working on the previous consoleField in the tab order and either (a) presses Tab or (b) fills that previous consoleField with content when field autonext is set to yes.
  • The user is working on the next consoleField in the tab order and presses Shift Tab.
  • The user uses arrow keys to move to the next or previous consoleField.

You can bind a variable to a consoleField that is protected or not. The setting of the openUI property setInitial determines whether the value of the bound variable is displayed.

A runtime error occurs if the program tries to move to a consoleField that is protected.

SQLColumnName
Specifies the name of the database table column that is associated with the ConsoleField. The name is used to create search criteria when the openUI statement for the ConsoleField (or related ConsoleForm) includes the statement property isConstruct.
  • Type: String
  • Example: SQLColumnName = "ID"
  • Default: none
  • Updatable at run time? Yes
timeFormat
Indicates how to format output; but specify timeFormat only if the ConsoleField accepts a time.
  • Type: a String or time-related system constant
  • Example: timeFormat = isoTimeFormat
  • Default: none
  • Updatable at run time? No
Valid values are as follows:
"pattern"
The value of pattern consists of a set of characters, as described in Date, time, and timestamp format specifiers.

Characters may be dropped from the beginning or end of a complete time specification, but not from the middle.

defaultTimeFormat
The time format given in the runtime Java locale.
isoTimeFormat
The pattern "HH.mm.ss", which is the time format specified by the International Standards Organization (ISO).
usaTimeFormat
The pattern "hh:mm AM", which is the IBM USA standard time format.
eurTimeFormat
The pattern "HH.mm.ss", which is the IBM European standard time format.
jisTimeFormat
The pattern "HH:mm:ss", which is the Japanese Industrial Standard time format.
timestampFormat
Indicates how to format output; but specify timestampFormat only if the ConsoleField accepts a timestamp.
  • Type: a String or timestamp-related system constant
  • Example: timestampFormat = odbcTimestampFormat
  • Default: none
  • Updatable at run time? No
Valid values are as follows:
"pattern"
The value of pattern consists of a set of characters, as described in Date, time, and timestamp format specifiers.

Characters may be dropped from the beginning or end of a complete timestamp specification, but not from the middle.

defaultTimestampFormat
The timestamp format given in the runtime Java locale.
db2TimeStampFormat
The pattern "yyyy-MM-dd-HH.mm.ss.ffffff", which is the IBM DB2® default timestamp format.
odbcTimestampFormat
The pattern "yyyy-MM-dd HH:mm:ss.ffffff", which is the ODBC timestamp format.
value
The current value displayed in the consoleField. Your code can set this value so that invocation of ConsoleLib.displayForm displays the specified value in the consoleField.
  • Type: String
  • Example: value = "View"
  • Default: none
  • Updatable at run time? Yes
verify
Indicates whether the user is prompted to retype the same value after trying to exit the ConsoleField.
  • Type: Boolean
  • Example: verify = yes
  • Default: no
  • Updatable at run time? No
Values are as follows:
No (the default)
EGL run time does not issue a special prompt.
Yes
When the user tries to leave the ConsoleField, the EGL runtime acts as follows:
  • Clears the consoleField, keeping the cursor there
  • Displays a message for the user to repeat the entry
  • Compares the two input values when the user tries to leave the consoleField again

If the values match, the bound variable receives that value and processing continues as usual. If the values do not match, the consoleField content reverts to the value that preceded the first of the two user inputs, and the cursor remains in the field.

Related concepts
Console user interface

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.