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, PageHandler, 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:


Syntax diagram for a use declaration in a program or library part
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 of type basicLibrary and Library part of type nativeLibrary.

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:
  • The EGL runtime uses the value in the program's use declaration
  • If no value is specified in the program's use declaration, the EGL runtime 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 = no, helpGroup = yes
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 runtime 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.

If you specify multiple keys, separate one from the next with a comma.

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.
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. The default is yes. 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:


Syntax diagram for a use declaration in a formGroup part
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:


Syntax diagram for a use declaration in a pageHandler part
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 reference
pfKeyEquate

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.