+---------------------------------+
|             SCATTER             |
+---------------------------------+
SCATTER [FIELDS <field list>]
        [MEMO]
        TO <array> | TO <array> BLANK
        | MEMVAR | MEMVAR BLANK

-----------------------------------
Copies data from a database record to an array or a set of
memory variables.
-----------------------------------

SCATTER copies data from the current database record to an array or a
set of memory variables.  The array or memory variables can be edited,
and the record may then be replaced with the contents of the edited
array or memory variables.  GATHER facilitates copying arrays or memory
variables to database records.  If the array or memory variables have
not been created before the SCATTER is issued, they are automatically
created.

FIELDS <field list>
        FIELDS <field list> transfers only the fields specified in the field
list to the array.  The field list may included memo fields.  If FIELDS
is omitted, all fields are transferred.

MEMO
        By default, memo fields are ignored in SCATTER.  To include memo fields
in the scatter process, include the MEMO keyword.

        You must have sufficient memory to scatter large memo fields to an
array or to memory variables.  If you lack sufficient memory, the alert
"Insufficient memory" is displayed.  If a memo field is too large to fit
in memory, it is not scattered, and any memo fields that follow are not
scattered.  When a memo field is not scattered, its array element or
memory variable is set to a logical false (.F.).

TO <array>
        The contents of the fields in the record are copied, starting with the
first field, into each element of <array> in sequential order.

        If the array has more elements than the number of fields to be
transferred, any extra array elements are left unchanged.  If no such
array exists or the array size is insufficient for the number of fields,
a new array is automatically created.  The data types of the array
elements will be the same as those of the corresponding fields in the
record.

TO <array> BLANK
        If BLANK is included, a memory variable array is created with memory
variables of the same size and type as the fields from the database, but
the elements of the array are empty.

MEMVAR
        MEMVAR scatters the data to memory variables instead of an array.  One
memory variable is created for each field in the database.  Each memory
variable will be filled with the corresponding field contents of the
current record.

        If a <field list> is included, a memory variable is created for each
field in the field list.  Each memory variable is the same data type and
size as its corresponding field and is assigned the same name as the
field it was created from.

        To reference a memory variable that has the same name as a field in the
currently selected database, the memory variable must be prefaced with
the M. qualifier.

        . Do not include TO with MEMVAR -- if TO is included an array named
MEMVAR is created!

MEMVAR BLANK
        If MEMVAR BLANK is used instead of an array name or MEMVAR, a set of
empty memory variables is created.  As with MEMVAR, one memory variable
is created for each field in the database.  If a <field list> is
included, a memory variable is created for each field in the field list.
Each memory variable is the same data type and size as its corresponding
field, and is assigned the same name as the field it was created from.

+---------------------------------+
|             Example             |
+---------------------------------+
SET TALK OFF
CLOSE ALL
USE customer
SCATTER MEMVAR
DEFINE WINDOW menter FROM 6,10 to 18,70 PANEL
ACTIVATE WINDOW menter
@ 1,3  SAY 'Customer: ' GET m.company
@ 3,3  SAY 'Address: '  GET m.address1
@ 5,3  SAY 'City: '     GET m.city
@ 7,3  SAY 'State: '    GET m.state
@ 7,18 SAY 'Zip: '      GET m.zip
@ 9,13 SAY 'Press <Escape> to discard changes'
READ
IF LASTKEY() != 27
    GATHER MEMVAR
ENDIF
DEACTIVATE WINDOW menter
USE

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

See Also:  APPEND FROM ARRAY, COPY TO ARRAY, DECLARE, DIMENSION, GATHER

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