EGL Reference Guide for iSeries

Form part in EGL source format

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:



Syntax diagram for a form part

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.

Text-form properties

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.

Print-form properties

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.

Form fields

The diagram of a form field is as follows:



Syntax diagram for a form field

*
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.

Field properties

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.

For any field

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.

For variable text fields

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.

For field arrays

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:

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 ]