Use declaration
This section describes the use declaration, followed by details on how to write the declaration:
Background
The use declaration allows you to easily reference data areas and functions in parts that are separately generated. A program, for instance, can issue a use declaration that allows for easy reference to a data table, library, or form group, but only if those parts are visible to the program part. For details on visibility, see References to parts.
In most cases, you can reference data areas and functions from another part regardless of whether a use declaration is in effect. For example, if you are writing a program and do not have a use declaration for a library part called myLib, you can access the library variable called myVar as follows:
myLib.myVar
If you include the library name in a use declaration, however, you can reference the variable as follows:
myVar
The previous, short form of the reference is valid only if the symbol myVar is unique for every variable and structure item that is global to the program. (If the symbol is not unique, an error occurs.) Also, the symbol myVar refers to an item in the library only if a local variable or parameter does not have the same name. (A local data area takes precedence over a same-named, program-global data area.)
A use declaration is required in these situations:
- A program or library that uses any of the forms in a given formGroup part must have a use declaration for that formGroup part
- A formGroup part must have a use declaration for a form that is required by the program or library but is not embedded in the formGroup part
- If you have declared a function at the top level of an EGL source file
rather than physically inside a container (a program, page handler, or library),
that function can invoke library functions only if the following situation
is in effect:
- The container includes a use statement that refers to the library
- In the invoking function, the property containerContextDependent is set to yes
Each name specified in the use declaration may be qualified by a package name, library name, or both.
In a program or library part
Each use declaration in a program or library must be external to any function. The syntax for the declaration is as follows:
- dataTablePartName
- Name of a dataTable part that is visible to the program or library.
A reference in a use declaration is unnecessary for a dataTable part that is referenced in the program property msgTablePrefix.
You cannot override properties of a dataTable part in the use declaration.
For an overview of dataTable parts, see DataTable part.
- libraryPartName
- Name of a library part that is visible to the program or library.
You cannot override properties of the library part in the use declaration.
For an overview of library parts, see Library part.
- formGroupPartName
- Name of a formGroup part that is visible to the program or library. For
an overview of form groups, see FormGroup part.
A program that uses any of the forms in a given formGroup part must have a use declaration for that formGroup part.
No overrides occur for form-level properties. If a property like validationBypassKeys is specified in a form, for example, the value in the form is in effect at run time. If a form-level property is not specified in the form, however, the situation is as follows:
- EGL run time uses the value in the program's use declaration
- If no value is specified in the program's use declaration, EGL run time uses the value (if any) in the form group
The properties that follow let you change behaviors when a form group is accessed by a specific program.
- helpGroup = yes, helpGroup = no
- Specifies whether to use the formGroup part as a help group. The default is no.
- validationBypassKeys = bypassKeyValue
- Identifies a user keystroke that causes the EGL run time to skip input-field
validations. This property is useful for reserving a keystroke that ends the
program quickly. Each 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.
- 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.
- pfKeyEquate = yes, pfKeyEquate = no
- Specifies whether the keystoke that is registered when the user presses a high-numbered function key (PF13 through PF24) is the same as the keystroke that is registered when the user presses a function key that is lower by 12. For details, see pfKeyEquate.
In a formGroup part
In a formGroup part, a use declaration refers to a form that is specified outside the form group. This kind of declaration allows multiple form groups to share the same form.
The syntax for a use declaration in a formGroup part is as follows:
- formPartName
- Name of a form part that is visible to the form group. For an overview
of forms, see Form part.
You cannot override properties of a form part in the use declaration of a formGroup part.
In a pageHandler part
Each use declaration in a pageHandler part must be external to any function. The syntax for the declaration is as follows:
- dataTablePartName
- Name of a dataTable part that is visible to the pageHandler part.
You cannot override properties of a dataTable part in the use declaration.
For an overview of dataTable parts, see DataTable part.
- libraryPartName
- Name of a library part that is visible to the pageHandler part.
You cannot override properties of the library part in the use declaration.
For an overview of library parts, see Library part.
Related concepts
DataTable part
FormGroup part
Form part
Library part
References to parts
Related reference
pfKeyEquate