ABF Forms: Scoping Rules and Storage Classes

                         Document #: US-13269,EN
------------------------------------------------------------------------------

Major subject: 4gl    Minor subjects: forms_control

Keywords: forms, local_variables, tech_notes

Abstract:
ABF Forms: Scoping Rules and Storage Classes: Discusses 
scope (global vs. local) and storage class (static vs. automatic)
of fields and variables in ABF. Equivalent to Release 6 
Tech Note # 28 or Release 5 note # 73.


Expert note:
ABF Forms: Scoping Rules and Storage Classes 
============================================

Overview
--------
This document will discuss the scope and storage class of forms
used in ABF Frames.

o	Definitions
o	Scope of Frame Fields
o	Global Data
o	Storage Class of Frame Fields
o	Static Data
o	Nested Form Displays
o	Accessing ABF Forms from EQUEL/ESQL Procedures
o	Summary


Definitions
-----------
Scope of a variable - the region of a program over which a variable is
known.  Referencing a variable outside its scope will generate
"undefined variable" errors.

Local variable - Private information for a particular frame or
procedure.  The variable cannot be referenced in another frame or
procedure unless it is explicitly passed.  It is defined locally within 
the frame. 

Global variables and constants - Information available to every frame or
procedure in an application.  It can be set in one frame or procedure 
and then used in another, without being explicitly passed.  Globals are
defined for the application in the Globals section of the Edit an  
Application frame in ABF.

Storage class of a variable - Indicates whether the variable always
exists (i.e. it is 'static', or pre-allocated at compile or link time)
or comes into being only when the routine that uses it starts up, and
disappears when the routine RETURNs (i.e. it is 'automatic', or allocated
only when the routine is called).

Frame Fields - Simple fields, tablefields and hidden fields.

Static Frame - A frame that preserves entered data when calling other
frames.  Upon returning from the called frames, the information that
existed on the form prior to the CALLFRAME will be redisplayed on the
form.

Displayed Form - Form currently on display.  When a frame is called,
its VIFRED form is automatically displayed.  RETURNing from a frame
ends the display.  Calling another frame displays that frame's form;
but the caller's form is technically still on display -- it is just
temporarily not visible.


Scope of Frame Fields
---------------------
Frame Fields are local to a frame and cannot be accessed by other
frames without being explicitly passed as CALLFRAME arguments.

A summary of the scope of each type of frame field:

o Simple Fields - Local to a frame.  Must be passed explicitly
to be used elsewhere in the application.  May be passed BYREF() and
thereby changed in another frame or procedure.

o Hidden Fields - Same as Simple Fields.

o TableFields - Local to a frame.  A tablefield may NOT be passed to
another frame explicitly, but as of 6.3/03, a tablefield can be unloaded
into an array, and the array can be passed to another frame.  However, a 
SINGLE ROW may be passed using the short-hand 'tablefield.all' 
('tablefield.all' may NOT be passed BYREF()).  Individual cells in 
the tablefield MAY be passed BYREF() so values in cells can be changed in
another frame or procedure.

EQUEL and ESQL procedures can read and write directly to any form in
an application, once that form has been displayed.  Thus, an
application's forms are global to EQUEL and ESQL procedures; they can
access simple fields and tablefields on other forms, without receiving
them as CALLPROC arguments.


Global Data
-----------
Global data can be used to communicate between frames and procedures.
For example, frame F1 needs to communicate with procedure P1 and it is
inconvenient to pass arguments to P1 directly.  Frame F1 can
communicate with procedure P1 by making the data it needs to
communicate global to the application.

There are three ways to implement data which is global into an ABF
application:

1.  By far the simplest method is to declare a global variable in the
global definitions section of editing an ABF application.  This is only
available beginning with Ingres release 6.3/03.

2.  Write it to the Database - Frame F1 can write its information to a
database table.  P1 can then read that table.

Make sure that each task can distinguish its data in the table 
from that written by other tasks.  If a single table is used as a
global storage location for all applications running on a database, be
sure to 'stamp' each row with a Task or Process ID, or other unique
identifier.  Then each task can distinguish its data in the table from
that written by other tasks.  Or, if separate tables are desired for
each application, be sure that the combination of tablename and INGRES
usercode is unique for each user running the application.

3.  Write it to a flat file using a 3gl procedure that can read and write
data to and from that file.  ABF Frames cannot create or access files 
directly, but may enlist the assistance of an EQUEL/ESQL 
procedure.

For example, to read from global memory, OSL can allocate a field of
the proper size and type and then pass it BYREF() to an EQUEL/ESQL
procedure, which can then over-write OSL's field with the contents of
global memory.  An alternative way, useful for reading single
variables from global memory, is for the EQUEL/ESQL procedure to
RETURN the value in global memory and for OSL to assign the return
code for the procedure into one of it's fields.  To write to global
memory, OSL can call an EQUEL/ESQL procedure and pass it the fields to
be written.


Storage Class of Frame Fields
-----------------------------
There are two storage classes for a frame, static and automatic.  The
default storage class is automatic, which means that every time a frame
is called with a CALLFRAME, its form is cleared and hidden fields are
re-created.  Consequently, a frame cannot 'remember' data values from
a previous call.  However, if a frame is specified as a static frame in
the frame definition (6.3/03 and above), then the data values can be 
recalled when returning to the frame from a previous CALLFRAME.


Static Data
-----------
This is data which is permanent, but local to a frame or procedure.
In general, the way to create 'static' data is via the help of an
EQUEL/ESQL procedure.  The EQUEL/ESQL Procedure can allocate it's own
private variables (in languages that support private, or static
storage) and pass them back to the OSL Frame which called the
procedure, in exactly the same manner as described above for global
data in global memory.


Nested Form Displays
--------------------
A given form may be used in any number of frames and procedures in an
application, but the display of that form may not be nested.  An
example of an illegal attempt to nest a display of the same form would
be if Frame1 called Frame2 and Frame2 tried to display the same form
as Frame1.  This is a restriction in the INGRES forms system and
applies whether the nested display is made via a Frame or EQUEL/ESQL
Procedure.


Accessing ABF Forms from EQUEL/ESQL Procedures
----------------------------------------------
Forms used in ABF frames are not available to other frames in the
application but, once displayed, are globally available to EQUEL and
ESQL procedures in the application.

The following EQUEL/ESQL Forms Statements can be used in an EQUEL/ESQL
procedure to manipulate an ABF frame's form: CLEAR FIELD, CLEARROW,
CLEAR SCREEN, DELETEROW, GETFORM, GETROW, INITTABLE, INQUIRE_FRS,
INSERTROW, LOADTABLE, PUTFORM, PUTROW, REDISPLAY, SCROLL, SET_FRS,
SUBMENU, and UNLOADTABLE.

The following EQUEL/ESQL Forms Statements can NOT be used in  an
EQUEL/ESQL procedure to manipulate an ABF frame's form: ACTIVATE,
BREAKDISPLAY, DISPLAY, ENDDISPLAY, FINALIZE, INITIALIZE, RESUME and
VALIDATE (and, of course, FORMS and ENDFORMS, which should never be
executed from any EQUEL/ESQL program in an ABF Application).

The EQUEL and ESQL manuals have more information on these INGRES forms
statements.


Summary
-------
We have discussed the Scope and Storage Class of ABF Forms and their
components.  Similar to variables in a programming language, ABF Forms
and Fields also have the attributes of Scope and Storage Class.



Releases affected:     all(all.all) -   Releases not affected: 
Errors:                                                             
Bugs/SIRS:                                                             
------------------------------------------------------------------------------
Ingres Database Reference
To William's Home Page
Email William