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.

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 sysLib.displayMsgNum.

alias = alias

An alias of 8 characters or less, for use by the EGL run time.

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

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. 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 } };

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