SCATTER Command

Copies data from the current record to a set of variables or to an array.

SCATTER [FIELDS FieldNameList | FIELDS LIKE Skeleton
   | FIELDS EXCEPT Skeleton] [MEMO]
   TO ArrayName | TO ArrayName BLANK | MEMVAR | MEMVAR BLANK
   | NAME ObjectName [BLANK]

Parameters

• FIELDS FieldNameList
  Specifies the fields to be transferred to the variables or to the array. All fields are transferred if you omit FIELDS FieldNameList. The field list can contain memo fields if you follow the field list with the MEMO keyword. SCATTER always ignores general and picture fields, even if you include MEMO.

• FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton
  You can selectively transfer fields to variables or an array by including the LIKE or EXCEPT clause or both. If you include LIKE Skeleton, fields that match Skeleton are transferred to the variables or the array. If you include EXCEPT Skeleton, all fields except those that match Skeleton are transferred to the variables or the array.

  Skeleton supports wildcard characters. For example, to transfer all fields that begin with the letters A and P to the variables or the array, use:

  SCATTER FIELDS LIKE A*,P* TO myarray
  

  The LIKE clause can be combined with the EXCEPT clause:

  SCATTER FIELDS LIKE A*,P* EXCEPT PARTNO* TO myarray
  

• MEMO
  Specifies that the field list includes a memo field or memo fields. By default, memo fields are ignored in SCATTER.

  You must have sufficient memory to scatter large memo fields to variables or to an array. Visual FoxPro generates an error message if you lack sufficient memory. If a memo field is too large to fit in memory, neither it nor any additional memo fields in the field list are scattered. If a memo field isn't scattered, its variable or array element is set to false (.F.).

• TO ArrayName
  Specifies the array to which the record contents are copied. Starting with the first field, SCATTER copies in sequential order the contents of each field into each element of the array.

  Extra array elements are left unchanged if the array you specify has more elements than the number of fields. A new array is automatically created if the array doesn't already exist or if it has fewer elements than the number of fields. The array elements have the same size and data types as the corresponding fields.

• TO ArrayName BLANK
  Creates an array with empty elements, which are the same size and type as the fields in the table.

• MEMVAR
  Scatters the data to a set of variables instead of to an array. SCATTER creates one variable for each field in the table and fills each variable with data from the corresponding field in the current record, assigning to the variable the same name, size, and type as its field.

  A variable is created for each field in the field list if a field list is included.

  Preface the variable name with the M. qualifier to reference a variable that has the same name as a field in the current table.

  Caution   Do not include TO with MEMVAR. Visual FoxPro creates an array named MEMVAR if you include TO.

• MEMVAR BLANK
  Creates a set of empty variables. Each variable is assigned the same name, data type, and size as its field. If a field list is included, a variable is created for each field in the field list.

• NAME ObjectName [BLANK]
  Creates an object whose properties have the same names as fields in the table. If the BLANK keyword is not included, the values of each of the object's properties are the contents of the fields in the table. If the BLANK keyword is included, the properties are empty (see EMPTY( ) for a description of what the empty properties contain, based on the corresponding field type). Properties are not created for general fields in the table.

  To reference a property in an object that has the same name as an open table, preface the property name with the M. qualifier. For example:

  USE customer
  SCATTER NAME customer
  
  ? customer.company  && Returns the table value
  ? M.customer.company  && Returns the object property value
  

Remarks

SCATTER and COPY TO ARRAY are similar. COPY TO ARRAY copies multiple records into an array while SCATTER copies just one record into an array or a set of variables. SCATTER automatically creates the array or variables if they don't already exist.

Use GATHER to copy variables or array elements to table records.

Examples

Example 1

This example uses SCATTER to create a set of variables based on the fields in the test table. Each field is then assigned a value and a new blank record is added to the table. The data is copied to the table using the GATHER command.

CREATE TABLE Test FREE ;
   (Object C(10), Color C(16), SqFt n(6,2))

SCATTER MEMVAR BLANK
m.Object="Box"
m.Color="Red"
m.SqFt=12.5
APPEND BLANK
GATHER MEMVAR
BROWSE

Example 2

This example uses SCATTER along with the NAME clause to create an object with properties based on the fields in the table. The object's properties are then assigned values and a new blank record is added to the table. The data is copied to the new record using GATHER with the NAME clause.

CREATE TABLE Test FREE ;
   (Object C(10), Color C(16), SqFt n(6,2))

SCATTER NAME oTest BLANK
oTest.Object="Box"
oTest.Color="Red"
oTest.SqFt=12.5
APPEND BLANK
GATHER NAME oTest
RELEASE oTest
BROWSE

See Also

ALINES( ) | APPEND FROM ARRAY | COPY TO ARRAY | DECLARE | DIMENSION | GATHER