An item is a named area of memory that contains a single value. Such an area may be described by any of the following entities:
An item may have subordinate structure items, and any of those subordinates may represent an array.
An item is distinct from any of these entities:
The following two syntax diagrams tell how to refer to an item.
An item used as a subscript of an array cannot itself be an array element. In each of the following examples, myItemB[1] is both a subscript and an array element; as a result, the following syntax is not valid:
/* the next syntax is not valid */ myItemA[myItemB[1]] // This next syntax is not valid; but the // reason (if you are working in VisualAge Generator // compatibility mode) is that myItemB is myItemB[1], // the first element of a one-dimensional array myItemA[myItemB]
For further details on referencing an item, see References to variables and constants. See also Arrays.
Related concepts
Compatibility with VisualAge Generator
DataItem part
Record parts
References to variables and constants
Structure
Related tasks
Syntax diagram
Related reference
Arrays
Data initialization
Items
Logical expressions
Numeric expressions
Operators and precedence
Primitive types
String expressions
The EGL field-presentation properties specify characteristics that are meaningful when a field is displayed in an on-screen output, when the destination is a command window, but not a Web browser.
The properties are as follows:
In addition, the following properties are meaningful when the field is displayed in a printable output, when the destination is a printer or a print file:
The field-presentation properties have no effect on data that is returned to the program from a text form; they are solely for output.
The color property specifies the color of a field in a text form. You can select any of these:
If you assign the value defaultColor, other conditions determine the displayed color, as shown in the next table.
Are all fields on the form assigned the value defaultColor? | Value of protect | Value of intensity | Displayed color for a field assigned the value defaultColor |
---|---|---|---|
yes | yes or skip | not bold | blue |
yes | yes or skip | bold | white |
yes | no | not bold | green |
yes | no | bold | red |
no | any value | not bold | green |
no | any value | bold | white |
The highlight property specifies the special effect (if any) with which to display the field. Valid values are as follows:
The intensity property specifies the strength of the displayed font. Valid values are as follows:
The outline property lets you draw lines at the edges of fields on any device that supports double-byte characters. Valid values are as follows:
In addition, you can specify any or all of the components of a box. In this case, place parentheses around one or more values, with each value separated from the next by a comma, as in this example:
outline = (left, over, right, under)
The partial values are as follows:
The content of each form field is preceded by an attribute byte. Be aware that you cannot place an attribute byte in the last column of a form and expect an outline value to appear in the next column, which is beyond the form's edge. (The field does not wrap to the next line.) Similarly, you cannot place an attribute byte in the first column of a form and expect the outline value to appear in that column; the outline value can appear only in the next column.
Related concepts
Overview of EGL properties and overrides
The formatting properties specify characteristics that are meaningful when data is presented on a form or a Web browser. The properties affect data at output or at both input and output.
The properties are as follows:
The align property specifies the position of data in a variable field when the length of the data is smaller than the length of the field. This property is useful on text and print forms.
On output, character and numeric data are affected by this property. On input, character data is affected by this property, but numeric data is always right-justified.
Valid values are as follows:
The boolean property indicates that the field represents a Boolean value. The property restricts the valid field values and is useful in text and print forms and in page handlers, for input or output.
On a Web page associated with an EGL page handler, a boolean item is represented by a checkbox. On a form, the situation is as follows:
In Java programs, the specific character values for yes and no are determined by the locale.
The currency property indicates whether to include a currency symbol before the value in the text field, with the exact position of the symbol determined by the zero format property. This property is useful in text and print forms and in page handlers. Values are as follows:
The fillCharacter property indicates what character fills unused positions in a text or print form or in page-handler data. In addition, the property changes the effect of set field full, as described in set. The effect of this property is only at output.
The default is a space for numbers and a 0 for hex items. The default for character types depends on the medium:
In page handlers, the value of fillCharacter must be a space (as is the default) for items of type DBCHAR or UNICODE.
The dateFormat property identifies the format for dates that are displayed on a form or maintained in a page handler. This property affects both input and output, but is not used in the following cases:
Valid values are as follows:
Characters | Meaning |
---|---|
< | If this character is in the first position of the mask, leading zeros are dropped from the item at output. |
dd | Day of month as a 2-digit number. |
ddd | Day of the year as a 3-digit number. |
mm | Month as a 2-digit number. |
yy | Year as a 2-digit number. |
yyyy | Year as a 4-digit number. |
Any other single-byte character | A separator character. Separator characters can be omitted when a date is entered by the user or maintained in the page handler. |
For COBOL programs, the system administrator for EGL run-time services sets the format at installation.
For Java programs, the format is in this Java run-time property:
vgj.datemask.gregorian.long.NLS
For additional details on vgj.nls.code, see Java run-time properties (details).
For COBOL programs, the system administrator for EGL run-time services sets the format at installation.
For Java programs, the format is in this Java run-time property:
vgj.datemask.julian.long.NLS
For additional details on vgj.nls.code, see Java run-time properties (details).
When the user enters valid data, the date is converted from the format specified for the field to an internal format, as is used for subsequent validation.
The internal format for a character date is the same as the system default format and includes separator characters.
For a numeric date, the internal formats are as follows:
In a form, the field length must match the length of the date mask you specify. In a page-handler item, the rules are as follows:
Examples are in the next table.
Format type | Example | Length of form field | Minimum length of page-handler item (character type) | Valid length of page-handler item (numeric type) |
---|---|---|---|---|
Short Gregorian | YY/MM/DD | 8 | 8 | 6 |
Long Gregorian | YYYY/MM/DD | 10 | 10 | 8 |
Short Julian | DDD-YY | 6 | 6 | 5 |
Long Julian | DDD-YYYY | 8 | 8 | 7 |
Data entered into a variable field is checked to ensure that the date was entered in the format specified. The user does not need to enter the leading zeros for days and months, but can specify (for example) 8/5/1996 instead of 08/05/1996. The user who omits the separator characters, however, must enter all leading zeros.
A date stored in internal format is not recognized as a date, but simply as data. If an 8-character date field is moved to a character item of length 10, for example, EGL pads the destination field with blanks. A 2-digit year is not converted to a 4-digit year.
When a date field is presented on a form, however, the date is converted from its internal format, as appropriate.
The numericSeparator property indicates whether to place a character in a number that has an integer component of more than 3 digits. If the numeric separator is a comma, for example, one thousand is shown as 1,000 and one million is shown as 1,000,000. Values are as follows:
In Java code, the default is determined by the machine locale. In COBOL code, the default is determined by the national language option.
The sign property indicates the position in which a positive (+) or negative (-) sign is displayed when a number is placed in the field, whether from user input or from the program. Values are as follows:
The timeFormat property identifies the format for times that are displayed on a form or maintained in a page handler. This property affects both input and output, but is not used in the following cases:
Valid values are as follows:
Characters | Meaning |
---|---|
< | If this character is in the first position of the mask, leading zeros are dropped from the item at output. |
hh | Hours of the day as a 2-digit number that ranges from 1 to 12 (if the pattern includes the characters am) or from 0 to 23. |
mm | Minutes as a 2-digit number. |
ss | Seconds as a 2-digit number. |
am | AM or PM; if specified, the hours range from 1 to 12. |
Any other single-byte character | A separator character. Separator characters can be omitted when a time is entered by the user or maintained in the page handler. |
In a form, the field length must match the length of the time mask you specify. In a page-handler item, the rules are as follows:
Data entered into a variable field is checked to ensure that the time was entered in the format specified. The user does not need to enter the leading zeros for hours, minutes, and second, but can specify (for example) 8:15 instead of 08:15. The user who omits the separator characters, however, must enter all leading zeros.
A date stored in internal format is not recognized as a time, but simply as data. If a 6-character time field is moved to a character item of length 10, for example, EGL pads the destination field with blanks. When the 6-character value is presented on a form, however, the time is converted from its internal format, as appropriate.
The upperCase property indicates whether to set alphabetic characters to upper case in the user's single-byte character input.
This property is useful in forms and in page handlers.
The values of upperCase are as follows:
The zeroFormat property specifies how zero values are displayed in numeric fields. This property is affected by the numeric separator, currency, and fillCharacter properties. The values of zeroFormat are as follows:
Related reference
Java run-time properties (details)
set
The page item properties specify characteristics that are meaningful when an item or array is declared in a PageHandler part.
The properties are as follows:
In the descriptions that follow, a bind property is a property whose value is in effect when a page designer places the item (or a record that includes the item) on the Web page. The page designer can override the value, which is a default.
The action property is a bind property, which means that the assigned value is used as a default when you are working in Page Designer. The property is meaningful only if the value of the item property displayUse is button or hyperlink.
The value of action refers to the code that is invoked when the user clicks the button or hypertext link.
The format for setting action is as follows:
action = actionValue
If you do not specify a value for action, the user's click of the item has the following effect:
The displayName property is a bind property, which means that the assigned value is used as a default when you are working in Page Designer. The property specifies the label that is displayed next to the item.
The format is as follows:
displayName = literal
The displayUse property is a bind property, which means that the assigned value is used as a default when you are working in Page Designer. The property associates the item with a user-interface control.
The format is as follows:
displayUse = displayUse
The property newWindow indicates whether to use a new browser window when the EGL run time presents a Web page in response to the activity identified in the action property.
The format is as follows:
newWindow = yesOrNo
The property newWindow is meaningful only when the property action is specified; otherwise, the current browser window is used to display the next page.
The property numElementsItem is specified on a static array variable or record item and identifies the name of another item in the page handler. At run time, the page handler code sets that item to indicate to the JSP how many array elements to display. This property is only used for output.
The property is meaningful for either of these:
The format is as follows:
numElementsItem = itemName
The property numElementsItem is not valid for dynamic arrays because each dynamic array includes an indicator of how many elements are in use. For details, see Arrays.
The property selectFromList is a bind property, which means that the assigned value is used as a default when you are working in Page Designer.
The property refers to an array or table column from which the user selects one or more values; and the property indicates that the array or item being declared will receive data in response to the user's selection from that list.
If the user is allowed to select multiple values, the property is specified for an array. Otherwise, the property is specified for an item.
The values received from the user must correspond to one of these types:
The property selectType indicates the type of value to receive, whether the content selected by the user or an index into an array or column.
The format of selectFromList is as follows:
selectFromList = listName
For details on resolving names, see References to parts.
The property selectType is a bind property, which means that the assigned value is used as a default when you are working in Page Designer.
The property indicates the kind of value that is retrieved into the item being declared.
The format is as follows:
selectType = selectType
For background information, see the property selectFromList.
The value of the property validationOrder is an integer that indicates when the item's validator function runs in relation to any other item's validator function. The property is important if the validation of one item depends on the previous validation of another.
Validation occurs first for any items for which you specified a value for the property validationOrder, and the items with the lowest-numbered values are validated first. Validation then occurs for any items for which you did not specify a value for validationOrder, and the order of validation in this case is the order in which the items are defined in the page handler.
The format of the property is as follows:
validationOrder = integer
The property value is a bind property, which means that the assigned value is used as a default when you are working in Page Designer. The property specifies a character string that is displayed as the item content when a Web page is displayed, before the user changes the value.
The format is as follows:
value = literal
Related concepts
PageHandler part
References to parts
Related reference
Arrays
The SQL item properties specify characteristics that are meaningful when an item is used in a record of type SQLRecord. You do not need to specify any of the SQL item properties, however, as default values are available.
The properties are as follows:
The property column refers to the name of the database table column that is associated with the item. The default is the name of the item. The column and related item affect the default SQL statements, as described in SQL support.
For columnName, substitute a quoted string; a variable of a character type; or a concatenation, as in this example:
column = "Column" + "01"
A special syntax applies if a column name is one of the following SQL reserved words:
As shown in the following example, each of those names must be embedded in a doubled pair of quote marks, and each of the internal quote marks must be preceded with an escape character (\):
column = "\"SELECT\""
(A similar situation applies if you use of those reserved words as a table name.)
The property isNullable indicates whether the item can be set to null, as is appropriate if the table column associated with the item can be set to NULL. Valid values are yes (the default) and no.
For a given item in an SQL record, the following features are available only if isNullable is set to yes:
The property isReadOnly indicates whether the item and related column should be omitted from the default SQL statements that write to the database or include a FOR UPDATE OF clause. The default value is no; but EGL treats the structure item as "read only" in these situations:
The value of property sqlDataCode is a number that identifies the SQL data type that is associated with the record item. The data code is used by the database management system when you access that system at declaration time, validation time, or generated-program run time.
The property sqlDataCode is available only if you have set up your environment for VisualAge Generator compatibility. For details, see Compatibility with VisualAge Generator.
The default value depends on the primitive type and length of the record item, as shown in the next table. For other details, see SQL data codes.
EGL primitive type | Length | SQL data code |
---|---|---|
BIN | 4 | 501 |
9 | 497 | |
CHAR | <=254 | 453 |
>254 and <=4000 | 449 | |
>4000 | 457 | |
DBCHAR | <=127 | 469 |
>127 and <=2000 | 465 | |
>2000 | 473 | |
DECIMAL | any | 485 |
HEX | any | 481 |
UNICODE | <=127 | 469 |
>127 and <=2000 | 465 | |
>2000 | 473 |
The value of property sqlVar indicates whether trailing blanks and nulls in a character field are truncated before the EGL run time writes the data to an SQL database. This property has no effect on non-character data.
Specify yes if the corresponding SQL table column is a varchar or vargraphic SQL data type.
Related concepts
Compatibility with VisualAge Generator
Record types and properties
SQL support
Structure
Typedef
Related tasks
Retrieving SQL table data
Related reference
add
close
Data initialization
delete
execute
get
get next
open
prepare
Primitive types
Record and file type cross-reference
replace
set
SQL data codes and EGL host variables
sysVar.terminalID
VAGCompatibility
The validation properties restrict what is accepted when the user enters data in a text form.
The properties are as follows:
The fill property indicates whether the user is required to enter data in each field position. Valid values are no (the default) and yes.
The inputRequired property indicates whether the user is required to place data in the field. Valid values are no (the default) and yes.
If the user does not place data in the field when the property value is yes, EGL run time displays a message, as described in relation to the field property inputRequiredMsgKey.
The property inputRequiredMsgKey identifies the message that is displayed if the field property inputRequired is set to yes and the user fails to place data into the field.
The message table (the data table that contains the message) is identified in the program property msgTablePrefix. For details on the data-table name, see DataTable part in EGL source format.
The value of inputRequiredMsgKey is a string or literal that matches an entry of the first column in the message table.
If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.
The isDecimalDigit property determines whether to check that the input value includes only decimal digits, which are as follows:
0123456789
Valid values are no (the default) and yes.
This property applies only to character fields.
The isHexDigit property determines whether to check that the input value includes only hexadecimal digits, which are as follows:
0123456789abcdefABCDEF
Valid values are no (the default) and yes.
This property applies only to character fields.
The minimumInput property indicates the minimum number of characters that the user is required to place in the field, if the user places any data in the field. The default is 0.
If the user places fewer than the minimum number of characters, EGL run time displays a message, as described in relation to the field property minimumInputMsgKey.
The property minimumInputMsgKey identifies the message that is displayed if the user acts as follows:
The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the table name, see DataTable part in EGL source format.
The value of minimumInputMsgKey is a string or literal that matches an entry of the first column in the message table.
If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.
The needsSO/SI property is used only for a multibyte field (a field of type MBCHAR) and indicates whether EGL does a special check when the user enters data of type MBCHAR on an ASCII device. Valid values are yes (the default) and no. The check determines whether the input can be converted properly to the host SO/SI format.
The property is useful because, during conversion, trailing blanks are deleted from the end of a multibyte string to allow for insertion of SO/SI delimiters around each substring of double-byte characters. For a proper conversion, the form field must have at least two blanks for each double-byte string in the multibyte value.
If needsSO/SI is set to no, the user can fill the input field, in which case the conversion truncates data without warning.
If needsSO/SI is set to yes, however, the result is as follows when the user enters multibyte data:
Set needsSOSI to yes if the user's ASCII input of multibyte data may be used on a z/OS or iSeries system.
The range property indicates the lowest and highest values that valid for user input. The property is only used for numeric fields. The format of the property is as follows:
range = (lowestValue, highestValue)
If the user's input is outside the specified range, EGL run time displays a message, as described in relation to the field property rangeMsgKey.
This property applies only to numeric fields.
The property rangeMsgKey identifies the message that is displayed if the field property range is set and the user places out-of-range data into the field.
The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the table name, see DataTable part in EGL source format.
The value of rangeMsgKey is a string or literal that matches an entry of the first column in the message table.
If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.
This property applies only to numeric fields.
The property typeChkMsgKey identifies the message that is displayed if the input data is not appropriate for the field type.
The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the table name, see DataTable part in EGL source format.
The value of typeChkMsgKey is a string or literal that matches an entry of the first column in the message table.
If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.
The validator property identifies a validator function, which is logic that runs after the EGL run time does the elementary validation checks, if any. Those checks are described in relation to the following properties:
The elementary checks precede use of the validator table (as described in relation to the validatorTable property), and all checks precede use of the validator property. This order of events is important because the validator function can do cross-field checking, and such checking often requires valid field values.
The value of validator is a validator function that your write. You code that function with no parameters and such that, if the function detects an error, it requests the re-display of the form by invoking sysLib.validationFailed.
If validation fails when you specify one of the two system functions, the displayed message is based on the value of the property validatorMsgKey. If validation fails when you specify a validator function of your own, however, the function does not use validatorMsgKey, but displays a message by invoking sysLib.validationFailed.
The property validatorMsgKey identifies a message that is displayed in the following case:
The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the table name, see DataTable part in EGL source format.
The value of validatorMsgKey is a string or literal that matches an entry of the first column in the message table.
If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.
The validatorTable property identifies a validator table, which is a dataTable part that acts as the basis of a comparison with user input. Use of a validator table occurs after the EGL run time does the elementary validation checks, if any. Those elementary checks are described in relation to the following properties:
All checks precede use of the validator property, which specifies a validation function that does cross-value validation.
You can specify a validator table that is of any of the following types, as described in DataTable part in EGL source format:
If validation fails, the displayed message is based on the value of the property validatorTableMsgKey.
The property validatorTableMsgKey identifies the message that is displayed if the user provides data that does not correspond to the requirements of the validator table, which is the table specified in the property validatorTable.
The message table (the table that contains the message) is identified in the program property msgTablePrefix. For details on the message-table name, see DataTable part in EGL source format.
The value of validatorTableMsgKey is a string or literal that matches an entry of the first column in the message table.
If a numeric key is used with a message table that expects a character key, the number is converted to a character string. If a string literal is used with a message table that expects a numeric key, the value in the string must be a signed or unsigned integer.
Related concepts
Text forms
Related reference
DataTable part in EGL source format
sysLib.validationFailed
sysLib.verifyChkDigitMod10
sysLib.verifyChkDigitMod11
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.