Copies data from the current record to a set of variables or to an array.
Syntax
SCATTER
[FIELDS FieldNameList
| FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton] [MEMO]
TO ArrayName | TO ArrayName BLANK | MEMVAR | MEMVAR BLANK
| NAME ObjectName [BLANK]
Arguments
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.
Important 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.