+---------------------------------+
|            REGIONAL             |
+---------------------------------+
REGIONAL <memvar list>

-----------------------------------
Creates regional memory variables and memory variable arrays.
-----------------------------------

The REGIONAL command lets you create regional memory variables and
memory variable arrays.  Memory variables or arrays with identical names
can be created without interfering with each other - their values are
protected within a "region".  Regional variables are similar to private
variables.

An example where regional variables can be used is screen sets.  Screen
sets can be created with the FoxPro screen builder.  Multiple screens
are combined into a screen set and a single program is generated.  It's
possible that a control in a screen uses the same variable name as a
control in another screen.  When these screens are combined into a
screen set and a single program is created, a conflict occurs with the
variable common to both screens.

Declaring screen variables as regional in the set up code ensures that a
variable is not affected by a variable with the same name used in
another screen in the screen set.  If the variables in the screens in
the screen set are declared as regional variables in their setup code,
FoxPro automatically resolves the conflicts.

When regional variables are declared in the screen setup code, the
GENSCRN screen generating program automatically inserts the necessary
#REGION compiler directives needed to resolve memory variable name
conflicts.

Creating Regional Variables
---------------------------

#REGION <number>
        Regional variables should be declared before they're used in a program.
Their region is first created with the #REGION compiler directive
(#REGION is not a command).  Include a region number 0 through 31.

REGIONAL <memvar list>
        After a region is created with the #REGION directive, you can declare
the variables for that region with the REGIONAL command.  You can
include a list of memory variables and arrays separated by commas in the
<memvar list>.

REGIONAL variables have all the characteristics of private variables.

During program compilation, if another identically named regional
variable has already been compiled when a regional declaration is
encountered by the compiler, the new variable's name is made unique to
insure no conflict is possible with the previously declared regional
variable.

A variable's name is made unique by padding the new regional variable's
name with underscores and the current region number.  This substitution
to create a unique variable name takes place entirely during program
compilation and has no effect on execution speed.

When a variable name has been modified, the modified variable name is
shown when you use DISPLAY MEMORY.  To monitor the variable in the Debug
window, use its modified variable name.  Since the Trace window uses the
original program source code, the original variable name (not the
modified name created by the compiler) appears in the Trace window.

+---------------------------------+
|         Program Example         |
+---------------------------------+
Two sets of regional variables are created.  In region 1, the variables
A, B, C and D are created, and the character string 'One' is stored to
each.  In region 2 the variables C, D, E and F are created, and the
character string 'Two' is stored to each.  The variables C and D are
common to both regions.

The screen output from DISPLAY MEMORY is shown.  The names of memory
variables C and D are modified in the second region.  C becomes
C________2, and D becomes D________2.  All the variables are private,
and may be accessed by lower-level programs.

#REGION 1
REGIONAL A,B,C,D
STORE 'One' to A,B,C,D

#REGION 2
REGIONAL C,D,E,F                && C and D are common to both regions
STORE 'Two' to C,D,E,F
DO showmemory
PROCEDURE showmemory
DISPLAY MEMORY LIKE *

-----------------------------------

See Also:  PRIVATE, PUBLIC, STORE

-----------------------------------