How to Use the SCATTER and GATHER Commands in FoxPro

• Microsoft Visual FoxPro for Windows, version 3.0
• Microsoft FoxPro for MS-DOS, versions 1.0, 1.02, 2.0, 2.5, and 2.5a
• Microsoft FoxPro for Windows, versions 2.5 and 2.5a

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

   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 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