openUI

The OpenUI statement allows the user to interact with a program whose interface is based on consoleUI. The statement defines user and program events and specifies how to respond to each.

The syntax of the OpenUI statement is as follows:


OpenUI Statement
OpenAttributes
OpenAttributes defines a set of property-and-value pairs, each separated from the next by a comma, as in this example:
  allowAppend = yes, allowDelete = no
Each of the properties affects the user interaction, and some overwrite a property of the consoleUI variable referenced in OpenableElements. The properties are as follows:
allowAppend
Specifies whether the user can insert data at the end of on on-screen arrayDictionary; if yes, the implications are as follows:
  • The user inserts a row of data by moving the cursor to the arrayDictionary line which follows the last line that includes data
  • The user's action appends an element to the dynamic array that is bound to that arrayDictionary
  • For variable type: ArrayDictionary
  • Property type: Boolean
  • Example: allowAppend = no
  • Default: yes; but the default is no if the openUI property displayOnly is set to yes
allowDelete
Specifies whether the user can delete a row from an on-screen arrayDictionary; if yes, the implications are as follows:
  • The user deletes a row by moving the cursor to that row and pressing the key referenced in ConsoleLib.key_delete.
  • The user's action deletes the related element in the dynamic array that is bound to that arrayDictionary.
  • For variable type: ArrayDictionary
  • Property type: Boolean
  • Example: allowDelete = no
  • Default: yes; but the default is no if the openUI property displayOnly is set to yes
allowInsert
Specifies whether the user can insert a row into an on-screen arrayDictionary; if yes, the implications are as follows:
  • The user inserts the row by moving the cursor to an existing row and pressing the key referenced in ConsoleLib.key_insert.
  • The new row precedes the row that shows the cursor
  • The user's action inserts an element to the dynamic array that is bound to that arrayDictionary.
  • For variable type: ArrayDictionary
  • Property type: Boolean
  • Example: allowInsert = no
  • Default: yes; but the default is no if the openUI property displayOnly is set to yes
bindingByName

Indicates how to bind a series of variables to a series of ConsoleFields; specifically, whether to match each variable name with a ConsoleField name. The variable name is listed in BindClause, and the ConsoleField name is the value in the ConsoleField name field.

  • For variable type: ConsoleForm, ConsoleField, or Dictionary; but not arrayDictionary
  • Property type: Boolean
  • Example: bindByName = yes
  • Default: no
Values are as follows:
no (the default)
Match variables and ConsoleFields by position:
  • The position of each variable in the list; and
  • The position of each ConsoleField in the consoleForm.

Whether consoleFields are listed explicitly in the openUI statement or are listed in a dictionary declaration, their order defines the order of consoleFields for the purpose of binding by position. (Their order also defines the tab order for user input, as noted in ConsoleUI parts and related variables.)

yes
Match variables and ConsoleFields by name.

If a consoleField is listed or is in a dictionary declaration when no matching variable is in the binding list, the user's input to the consoleField is ignored. Similarly, a binding variable that does not match any field is ignored.

At least one consoleField and variable must be bound together at run time; otherwise, an error occurs.

color
Specifies the color of the text in the ConsoleFields. The value overrides the color specified in the ConsoleField declaration.
  • For variable type: ConsoleForm, ConsoleField, ArrayDictionary, or Dictionary
  • Property type: ColorKind
  • Example: color = red
  • Default: white
Values are as follows:
defaultColor or white (the default)
White
black
Black
blue
Blue
cyan
Cyan
green
Green
magenta
Magenta
red
Red
yellow
Yellow
currentArrayCount
Specifies the number of elements that are available in the dynamic array to which the on-screen arrayDictionary is bound. If you do not specify this value, all the elements are available for use in the arrayDictionary.
  • For variable type: ArrayDictionary
  • Property type: INT
  • Example: currentArrayCount = 4
  • Default: none
displayOnly
Specifies whether consoleFields are displayed for viewing only. If yes, the user cannot modify the data, which is protected from update.
  • For variable type: ArrayDictionary, Dictionary, ConsoleField, ConsoleForm
  • Property type: Boolean
  • Example: displayOnly = yes
  • Default: no
help
Specifies the text to display when the user presses the key identified in ConsoleLib.key_help.

This help text is for the openUI command. In some cases, the text associated with the key is more context specific. For instance, each option in a menu can have its own help message.

  • For variable type: ConsoleForm, ConsoleField, ArrayDictionary, or Dictionary
  • Primitive type: String
  • Example: help = "Update the value"
  • Default: Empty string
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 a ConsoleUI variable (such as ConsoleForm) that is identified in OpenableElements; and
  • The user presses the key identified in ConsoleLib.key_help.
If you specify both help and helpKey, help is used.
  • For variable type: ConsoleForm, ConsoleField, ArrayDictionary, or Dictionary
  • Property type: String
  • Example: helpKey = "myKey"
  • Default: Empty string

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. The value overrides the equivalent value specified in the ConsoleField declaration.
  • For variable type: ConsoleForm, ConsoleField, ArrayDictionary, or Dictionary
  • Property type: HighlightKind[]
  • Example: highlight = [reverse, underline]
  • Default: [noHighLight]
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.
intensity
Specifies the strength of the displayed font.
  • For variable type: ConsoleField, ConsoleForm, ArrayDictionary, or Dictionary
  • Property type: IntensityKind[]
  • Example: intensity = [bold]
  • Default: [normalIntensity]
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 boldface.
dim
Causes the text to appear with a lessened intensity, as appropriate when an input field is disabled.
invisible
Removes any indication that the ConsoleField is on the form.
isConstruct

Specifies whether the purpose of the openUI statement is to create selection criteria for use in an SQL statement such as SELECT.

  • For variable type: ConsoleField, ConsoleForm, Dictionary
  • Property type: Boolean
  • Example: isConstruct = no
  • Default: yes
Values are as follows:
no (the default)
Each ConsoleField is bound to a variable, as usual.
yes

The openUI statement must be bound to a single variable of a character type. That variable does not provide initial values for the ConsoleFields, but does receive the user's input, which is formatted for use in an SQL WHERE clause.

maxArrayCount
Specifies the maximum number of rows that can be in the dynamic array bound to the on-screen arrayDictionary. After the maximum is reached, the user is unable to insert more rows.
  • For variable type: ArrayDictionary
  • Property type: INT
  • Example: maxArrayCount = 20
  • Default: none
setInitial
Specifies whether the initial value of a ConsoleField (as defined in the consoleForm declaration) is displayed until the user modifies that value. (You specify the initial value by setting the initialValue field of ConsoleField.)
  • For variable type: ConsoleField, ConsoleForm, Dictionary, ArrayDictionary
  • Property type: Boolean
  • Example: setInitial = yes
  • Default: no

If the value of setInitial is no, the values of the bound variables are fetched and displayed initially.

OpenableElements
The ConsoleUI variables on which the openUI statement can act:
  • ConsoleForm
  • A consoleField or one of these:
    • A list of consoleFields, each separated from the next by a comma
    • A dictionary that is declared in a consoleForm and refers to a set of consoleFields in that consoleForm
    • An arrayDictionary that is declared in a consoleForm and refers to a set of consoleField arrays in that consoleForm.
  • Menu
  • Prompt
  • Window
BindClause
The list of primitive variables, records, or arrays that are bound to the ConsoleUI variables. Characteristics of the binding variables depend on the characteristics of the consoleUI variable on which the openUI statement acts:
  • For a consoleField, you can specify a primitive variable.
  • For an on-screen arrayDictionary, you can specify an array of records, one element per row in the arrayDictionary; and if each row in the arrayDictionary represents a single value, you can specify an array of primitive variables.
  • For a dictionary or a list of consoleFields, you can specify a list of primitive variables. Alternatively, you can specify an array of records, with each element containing a series of fields that are bound to the consoleFields. This alternative is equivalent to binding a dynamic array with an on-screen arrayDictionary that has only one row; you can append, insert, or delete a record to change the dynamic array, and in any case only one record is displayed at a time.
  • For a prompt, you can specify a primitive field that receives the user's response.

For details on binding, see the section on OnEventBlock (later), as well as ConsoleUI parts and related variables.

OnEventBlock
An event block is a programming structure that includes 0 to many event handlers, each of which contains the code that you've written for responding to a particular event. An event handler begins with an OnEvent header:
  OnEvent(eventKind: eventQualifiers)
eventKind
One of several events. Valid values are described in Event types.
eventQualifier
Data that further defines the event. Such data might be the ConsoleField entered or the keystroke pressed.

The EGL statements that respond to a given event are between the OnEvent header and the next OnEvent header (if any), as shown in a later example. However, you cannot include a reference variable in the OnEvent block unless that variable was declared as a program global.

The user continually interacts with the program, and the program runs an event handler when the event occurs that is associated with that event handler. If the purpose of the openUI statement is to display a prompt, however, the user-program interaction is less like a loop:
  1. An event handler (potentially one of several) traps a user keystroke and responds
  2. The openUI statement ends

No event block is available for a window.

Consider the following example for guiding the interaction between the user and a ConsoleForm:
		openUI {bindingByName=yes}
			 activeForm
			 bind firstName, lastName, ID
			 OnEvent(AFTER_FIELD:"ID")
				  if (employeeID == 700)
        firstName = "Angela";
        lastName = "Smith";
				  end
  end
That code acts as follows:
Consider these details about the preceding example:

You can end an openUI statement by issuing an exit statement of the form exit openUI.

Event types

ConsoleUI supports the following events:
BEFORE_OPENUI
The EGL runtime begins to run the OpenUI statement. This event is available for all ConsoleUI variables other than those based on Window.
AFTER_OPENUI
The EGL runtime is about to stop running the OpenUI statement. This event is available for all ConsoleUI variables other than those based on Window.
ON_KEY:(ListOfStrings)
The user has pressed a specific key, as indicated by a string such as "ESC", "F2", or "CONTROL_W". You can identify multiple keys by separating one string from the next, as in this example:
  ON_KEY:("a", "ESC") 

This event is available in an ArrayDictionary, a ConsoleField, a Menu, or a Prompt.

BEFORE_FIELD:(ListOfStrings)
The user has moved the cursor into the specified ConsoleField, as indicated by a string that matches the value of the ConsoleField name field. You can identify multiple consoleFields in the same consoleForm by separating one string from the next, as in this example:
  BEFORE_FIELD:("field01", "field02") 
AFTER_FIELD:(ListOfStrings)
The user has moved the cursor out of the specified ConsoleField, as indicated by a string that matches the value of the ConsoleField name field. You can identify multiple consoleFields in the same consoleForm by separating one string from the next, as in this example:
  AFTER_FIELD:("field01", "field02") 
BEFORE_DELETE
In relation to an on-screen arrayDictionary, the user has pressed the key specified in ConsoleLib.key_deleteLine, but the EGL runtime has not yet deleted the row. The program can invoke consoleLib.cancelDelete to avoid deleting the row.
BEFORE_INSERT
In relation to an on-screen arrayDictionary, the user has pressed the key specified in ConsoleLib.key_insertLine, but the EGL runtime has not yet inserted a row. The program can invoke consoleLib.cancelInsert to avoid inserting the row.
BEFORE_ROW
In relation to an on-screen arrayDictionary, the user has moved the cursor into a row.
AFTER_DELETE
In relation to an on-screen arrayDictionary, the user has pressed the key specified in ConsoleLib.key_deleteLine, and the EGL runtime has deleted a row.
AFTER_INSERT
In relation to an on-screen arrayDictionary, the user has pressed the key specified in ConsoleLib.key_insertLine; the EGL runtime has inserted a row; and the cursor leaves the row that was inserted.

The user can edit the row before committing changes to a database, as typically happens in the AFTER_INSERT handler.

AFTER_ROW
The user has moved the cursor from a row in an on-screen arrayDictionary.
MENU_ACTION:(ListOfStrings)
The user has selected a menuItem, as indicated by a string that matches the value of the menuItem name field. You can identify multiple menuItems by separating one string from the next, as in this example:
  MENU_ACTION:("item01", "item02") 

isConstruct

When the property isConstruct = yes, the text placed in the variable bound to the openUI command is specially formatted, as shown in this example:
  1. An openUI statement acts on a ConsoleForm of three ConsoleFields (employee, age, and city), and each field is associated with an SQL table column of the same name.

    You associate a consoleField with an SQL table column by setting the consoleField property SQLColumnName; and you must set the consoleField property dataType, as noted in ConsoleField Properties and Fields.

  2. The user acts as follows:
    • Leaves the employee field blank
    • Types this in the age field:
        > 25
    • Types this in the city field:
        = 'Sarasota'
  3. When the user leaves the on-screen variable on which the openUI statement acts, the bound variable receives the following content:
      AGE > 28 AND CITY = 'Sarasota'

As shown, EGL places the operator AND between each clause that the user provides.

The next table shows valid user input and the resulting clause. The phrase simple SQL types refers to SQL types that are neither structured nor LOB-like types.

Symbol Definition Supported data types Example Resulting clause (for a character column named C) Resulting clause (for a numeric column named C)
= Equal to Simple SQL Types =x, ==x C = 'x' C = x
> Greater than Simple SQL Types >x C > 'x' C > x
< Less than Simple SQL Types <x C < 'x' C < x
>= Not less than Simple SQL Types >=x C >= 'x' C >= x
<= Not greater than Simple SQL Types <=x C <= 'x' C <= x
<> or != Not equal to Simple SQL Types <>x or !=x C != 'x' C != x
.. Range Simple SQL Types x.y or x..y C BETWEEN 'x' AND 'y' C BETWEEN x AND y
* Wildcard for String (as described in next table) CHAR *x or x* or *x* C MATCHES '*x' not applicable
? Single character wildcard (as described in next table) CHAR ?x, x?, ?x?, x?? C MATCHES '?x' not applicable
| Logical Or Simple SQL Types x|y C IN ('x', 'y') C IN (x, y)

The equal sign (=) can mean IS NULL; and the not-equal sign (!= or <>) can mean IS NOT NULL.

A MATCHES clause results from the user's specifying one of the wildcard characters described in the next table.

Symbol Effect
* Matches zero or more characters.
? Matches any single character.
[ ] Matches any enclosed character.
- (hyphen) When used between characters inside brackets, a hyphen matches any character in the range between and including the two characters. For example, [a-z] matches any lowercase letter or special character in the lower case range.
^ When used in brackets, an initial caret matches any character not included within the brackets. For example, [^abc] matches any character except a, b, or c.
\ Is the default escape character; the next character is a literal. Allows any of the wildcard characters to be included in the string without having the wildcard effect.
Any other character outside of brackets Must match exactly.
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.