How to Use the SCATTER and GATHER Commands in FoxPro

ID: Q99136

1.00 1.02 2.00 2.50 2.50a | 2.50 2.50a 3.00 

MS-DOS                    | WINDOWS
 kbprg
The information in this article applies to:

SUMMARY

The SCATTER command moves data from a database record to an array or a set of memory variables. The array or memory variables can be edited, and the record can then be replaced with the contents of the edited array or memory variables.

The GATHER command moves data from a set of memory variables or a memory variable array into the current database record of the active database.

MORE INFORMATION

NOTE: Although article applies to Visual FoxPro,an alternative to the SCATTER and GATHER is to turn on BUFFERING. For more information about Buffering, see Visual FoxPro' online Help on CURSORSETPROP(), Pessimistic Record Locking, and Optimistic Record Locking.

For more information about using Buffering, please see the following article in the Microsoft Knowledge Base: 

   ARTICLE-ID: Q129641
   TITLE     : Alternative to SCATTER and GATHER in the New VFP Model

SCATTER and GATHER

The syntax for the SCATTER command is as follows: 

   SCATTER [FIELDS <fields list>] TO  <array>  | TO <array> BLANK |
   MEMVAR | MEMVAR BLANK | MEMO
The syntax for the GATHER command is as follows: 

   GATHER MEMVAR | FROM <array> FIELDS <field list> | MEMO

  NOTE: In FoxPro 1.02, the SCATTER and GATHER commands ignore memo
  fields and work with only one record. In FoxPro versions 2.0 and 2.5, the
  MEMO keyword places the memo information in an element of an array
  or a memory variable.
If a memory variable (<array>) is specified, the contents of the fields in the record are copied, starting with the first field, into each element of the array in sequential order.

If the FIELDS clause is included with a field list, only the specified fields are transferred to the array. If the FIELDS clause is omitted, all the fields are transferred.

The BLANK option creates a memory variable array the same size and type as the fields from the database. The elements of this array are left blank.

The MEMVAR option creates a set of memory variables. One memory variable is created for each field in the database. Each memory variable is filled with the corresponding field contents from the current record.

NOTE: If you issue the DISPLAY MEMORY command you will see that the memory variables created by SCATTER are the exact same names as the fields which they are created from. The convention of using "m." in front of the field name is used to distinguish the memory variable from the field. This is important due to the fact that references to the fields have precedence over references to the memory variables.

When the MEMVAR BLANK option is used, a set of empty memory variables is created.

The sample code below demonstrates using the SCATTER and GATHER commands. The Customer database used below is from the FoxPro version 2.x TUTORIAL directory. 

   SET TALK OFF
   USE customer
   SCATTER MEMVAR BLANK
   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.address
   @ 5,3 SAY 'City:  '    GET m.city
   @ 7,3 SAY 'State:  '   GET m.state
   @ 7,18 SAY 'ZIP:'      GET m.zip
   @ 9,18 SAY 'Press <esc> to abort'
   READ
   If lastkey() = 27
      GATHER FROM temp
   ENDIF
   DEACTIVATE WINDOW menter
   DISPLAY

REFERENCES

"Commands & Functions": see the SCATTER and GATHER commands

"Language Reference," version 2.5, L3-542 to L3-543 and L3-851 to L3-853

Additional reference words: VFoxWin 3.00 FoxDos FoxWin 1.02 2.00 2.50 2.50a scatter gather KBCategory: kbprg KBSubcategory: FxenvMemory 

Keywords          : kbenv FxenvMemory 
Version           : 1.00 1.02 2.00 2.50 2.50a | 2.50
Platform          : MS-DOS WINDOWS

Last Reviewed: May 13, 1998