EGL Reference Guide for iSeries
You declare a form part in an EGL file, which is described in EGL source
format. If a form part is accessed by only one form group, it is
recommended that the form part be embedded in the formGroup part. If a
form part is accessed by multiple form groups, it is necessary to specify the
form part at the top level of an EGL file.
An example of a text form is as follows:
Form myTextForm type textForm
{
formsize= (24, 80),
position= (1, 1),
validationBypassKeys=(pf3, pf4),
helpKey=pf1,
helpForm=myHelpForm,
msgField=myMsg,
alias = form1
}
* { position=(1, 31), value="Sample Menu" } ;
* { position=(3, 18), value="Activity:" } ;
* { position=(3, 61), value="Command Code:" } ;
activity char(42)[5] { position=(4,18), protect=skip } ;
commandCode char(10)[5] { position=(4,61), protect=skip } ;
* { position=(10, 1), value="Response:" } ;
response char(228) { position=(10, 12), protect=skip } ;
* { position=(13, 1), value="Command:" } ;
myCommand char(70) { position=(13,10) } ;
* { position=(14, 1), value="Enter=Run F3=Exit"} ;
myMsg char(70) { position=(20,4) };
end
An example of a print form is as follows:
Form myPrintForm type printForm
{
formsize= (48, 80),
position= (1, 1),
msgField=myMsg,
alias = form2
}
* { position=(1, 10), value="Your ID: " } ;
ID char(70) { position=(1, 30) };
myMsg char(70) { position=(20, 4) };
end
The diagram of a form part is as follows:

- Form formName ...
end
- Identifies the part as a form and specifies the part name. For the
rules of naming, see Naming conventions.
- textForm
- Indicates that the form is a text form.
- textFormProperty
- A text-form property. For details, see Text form.
- textFormField
- A text-form field. For details, see Form fields.
- printForm
- Indicates that the form is a print form.
- printFormProperty
- A print-form property. For details, see Print
form.
- printFormField
- A print-form field. For details, see Form fields.
The text-form properties are as follows:
- formsize = (rows, columns)
- Number of rows and columns in the online presentation area. This
property is required.
The column value is equivalent to the number of single-byte characters that
can be displayed across the presentation area.
- position = (row, column)
- Row and column at which the form is displayed in the presentation
area. If you omit this property, the form is a floating form and is
displayed in the floating area, at the next free line where the entire form
can fit in the floating area.
- validationBypassKeys = bypassKeyValue
- Identifies one or more user keystrokes that causes the EGL run time to
skip input-field validations. This property is useful for reserving a
keystroke that ends the program quickly. The bypassKeyValue
option is as follows:
- pfn
- The name of an F or PF key, including a number between 1 and 24, inclusive
- Note:
- Function keys on a PC keyboard are often F keys such as F1, but
EGL uses the IBM PF terminology so that (for example) F1 is called
PF1.
If you wish to specify more than one key value, delimit the set of values
with parentheses and separate each value from the next with a comma, as in the
following example:
validationBypassKeys = (pf3, pf4)
- helpKey = helpKeyValue
- Identifies a user keystroke that causes the EGL run time to present a help
form to the user. The helpKeyValue option is as
follows:
- pfn
- The name of an F or PF key, including a number between 1 and 24, inclusive
- Note:
- Function keys on a PC keyboard are often F keys such as F1, but
EGL uses the IBM PF terminology so that (for example) F1 is called
PF1.
- helpForm = formName
- Name of the help form that is specific to the text form.
- msgField = fieldName
- Name of the text-form field that displays a message in response to a
validation error or in response to the running of
sysLib.displayMsgNum.
- alias = alias
- An alias of 8 characters or less, for use by the EGL run time. An
alias is necessary in a COBOL environment if the form name is longer than 8
characters.
The print-form properties are as follows:
- formsize = (rows, columns)
- Number of rows and columns in the online presentation area. This
property is required.
The column value is equivalent to the number of single-byte characters that
can be displayed across the presentation area.
- position = (row. column)
- Row and column at which the form is displayed in the presentation
area. If you omit this property, the form is a floating form and is
displayed in the floating area, at the next free line where the entire form
can fit in the floating area.
- addSpaceForSOSI = yes, addSpaceForSOSI = no)
- Directs report production in COBOL environments. If you set the
property to no, the EGL run time prints the line as is, including
any shift-out/shift-in (SO/SI) characters that are in fields of type
MBCHAR. If you set the property to yes (the default), the
EGL run time puts a space in place of each SO/SI character.
To cause the printed form to use the same columns as in the form
definition, specify no for printers that print a space for each SO
or SI character and specify yes for printers that strip SO or SI
characters from the print line.
- msgField = fieldName
- Name of the text-form field that displays a message in response to the
running of sysLib.displayMsgNum.
- alias = alias
- An alias of 8 characters or less, for use by the EGL run time. An
alias is necessary in a COBOL environment if the form name is longer than 8
characters.
The diagram of a form field is as follows:

- *
- Indicates that the field is a constant field. It has no name but
has a constant value, which is specified in the field-specific value
property. Statements in your code cannot access the value in a constant
field.
- fieldProperty
- A field property. For details, see Field
properties.
- fieldName
- Specifies the name of the field. For rules, see Naming
conventions.
Your code can access the value of a named field, which is also called a
variable field.
If a text form contains a variable field that starts on one line and ends
on another, the text form can be displayed only on screens where the screen
width equals the width of the form.
- occurs
- The number of elements in a field array. Only one-dimensional
arrays are supported. For further details, see For field
arrays.
- primitiveType
- The primitive type assigned to the field. This specification
affects the maximum length; but any numeric field is generated as type
NUM.
Forms that contain fields of type DBCHAR can only be used on systems and
devices that support double-byte character sets. Similarly, forms that
contain fields of type MBCHAR can only be used on systems and devices that
support multiple-byte character sets.
The primitive type UNICODE is not supported for text or print forms.
- length
- The field's length, which is an integer that represents the maximum
number of characters or digits that can be placed in the field.
- decimals
- For a numeric type (BIN, DECIMAL, NUM, NUMC, or PACF), you may specify
decimals, which is an integer that represents the number of places
after the decimal point. The maximum number of decimal positions is the
smaller of two numbers: 18 or the number of digits declared as
length. The decimal point is not stored with the
data.
- dataItemPartName
- The name of a dataItem part that is a model of format for the field, as
described intypeDef. The dataItem part must be visible to
the form part, as described in References to parts.
This section describes properties that are useful only in form
fields. Additional properties are also of interest as described in
Field-presentation properties, Formatting properties,
and Validation properties.
The following properties are useful for any field on a form:
- position = (row. column)
- Row and column of the attribute byte that precedes the field. This
property is required.
- value = stringLiteral
- A character string that is displayed in the field.
This property can be specified for any item; for example, in a
dataItem part declaration.
- Note:
- If VisualAge Generator compatibility is in effect and you set the text-form
property value, the content of that property is available in the
program only after the user has returned the form. For this reason, the
value that you set in the program does not need to be valid for the item in
the program.
- fieldLen = lengthInBytes
- Field length; the number of single-byte characters that can be
displayed in the field. This value does not include the preceding
attribute byte.
The value of fieldLen for numeric fields must be great enough to
display the largest number that can be held in the field, plus (if the number
has decimal places) a decimal point. The value of fieldLen for
a field of type CHAR, DBCHAR, MBCHAR, or UNICODE must be large enough to
account for the double-byte characters, as well as any shift-in/shift-out
characters.
The default fieldLen is the number of bytes needed to display the
largest number possible for the primitive type, including all formatting
characters.
The following properties are useful for variable text fields:
- cursor = no, cursor = yes
- Indicates whether the on-screen cursor is at the beginning of the field
when the form is first displayed. Only one field in the form can have
the cursor property set to yes. The default is
no.
- detectable = no, detectable = yes
- Specifies whether the field's modified data tag is set when the field
is selected by a light pen or (for emulator sessions) by a cursor
click.
The detectable property is available only for COBOL programs and
only for text-form fields whose intensity property is other than
invisible.
The initial character in the field content (as specified in the
value property) must be a designator character, which
indicates what action is taken when the user clicks on the field. The
most common designator characters are as follows:
- &
- Causes an immediate detect, which means that clicking the field
at run time is equivalent to modifying the field and pressing the ENTER
key.
- ?
- Causes a delayed detect, which means that clicking the field at
run time is equivalent to modifying the field, but that the program receives
the form information only when the user presses the ENTER key or clicks a
field that is configured for an immediate detect.
To prevent the user from changing the designator character in a variable
field, set the protect property to yes or
skip.
- modified = no, modified = yes
- Indicates whether the program will consider the field to have been
modified, regardless of whether the user changed the value. For
details, see Modified data tag and modified property.
The default is no.
- protect = no, protect = skip, protect =
yes
- Specifies whether the user can access the field. Valid values are
as follows:
- no (the default for variable fields)
- Sets the field so that the user can overwrite the value in it.
- skip (the default for constant fields)
- Sets the field so that the user cannot overwrite the value in it.
In addition, the cursor skips the field in either of these cases:
- The user is working on the previous field in the tab order and either
presses Tab or fills that previous field with content; or
- The user is working on the next field in the tab order and presses
Shift Tab.
- yes
- Sets the field so that the user cannot overwrite the value in it.
- validationOrder = integer
- Indicates the field's position in the validation order. The
default order in which the fields are validated is the order of the fields on
screen, left to right, top to bottom.
One-dimensional arrays are supported on text and print forms. In an
array declaration, the value of the occurs property is greater than
1, as in this example:
myArray char(1)[3];
Array elements are positioned in relation to the placement specified for
the first element in the array. The default behavior is to position the
elements vertically on consecutive rows.
Use the following properties to vary the default behavior:
- columns = numberOfElements
- Number of array elements in each row. The default is 1.
- linesBetweenRows = numberOfLines
- Number of lines between each row that contains array elements. The
default is 0.
- spacesBetweenColumns = numberOfSpaces
- Number of spaces between each array element. The default is
1.
- indexOrientation = down, indexOrientation =
across
- Specifies how the program references the elements of an array:
- If you set indexOrientation to down, elements are
numbered from top to bottom, then left to right, so that the elements in a
given column are numbered sequentially. The value of
indexOrientation is down by default.
- If you set indexOrientation to across, elements are
numbered from left to right, then top to bottom, so that the elements in a
given row are numbered sequentially.
You can override properties for an array element. In the following
field declaration, for example, the cursor property is overridden in
the second element of myArray:
myArray char(10)[5]
{position=(4,61), protect=skip, myArray[2] { cursor } };
Related concepts
Modified data tag and modified property
Overview of EGL properties and overrides
Print forms
References to parts
Text forms
Typedef
Related reference
Field-presentation properties
Formatting properties
Naming conventions
NUM
Primitive types
sysLib.displayMsgNum
Validation properties
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.