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 runtime 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 runtime 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 ConverseLib.displayMsgNum.
alias = "alias"
An alias of 8 characters or less, for use by the EGL runtime.

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.
msgField = "fieldName"
Name of the text-form field that displays a message in response to the running of ConverseLib.displayMsgNum.
alias = "alias"
An alias of 8 characters or less, for use by the EGL runtime.

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 text-form field property. For details, see Text-form 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 types FLOAT, SMALLFLOAT, and UNICODE are 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 in typeDef. The dataItem part must be visible to the form part, as described in References to parts.

Text-form field properties

Properties that are useful only in text-form fields are described later. The following properties are used more widely and also available:

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. Quotes are required.

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.
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:
  • 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 = yes} };
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.