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

SCATTER and COPY TO ARRAY behave similarly. SCATTER copies only a single and current record into an array or a set of variables and automatically creates the array or variables if they do not already exist. COPY TO ARRAY copies multiple records into an array. For more information, see COPY TO ARRAY Command.

To copy variables or array elements to table records, use the GATHER Command.

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

Parameters

FIELDS FieldNameList

Specifies the fields whose values are to be copied to the variables or the array.

SCATTER disregards memo fields by default; however, you can include memo fields in the field list by following the field list with the MEMO keyword. However, SCATTER disregards general fields even when you include the MEMO keyword.

Omitting FIELDS FieldNameList copies values from all fields.

FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton

Copies fields matching or excluding Skeleton to variables or an array. You can include the LIKE or EXCEPT clause or both.

To copy values of fields matching Skeleton to variables or an array, use LIKE Skeleton. To copy values of all fields except those matching Skeleton to variables or an array, use EXCEPT Skeleton. Skeleton supports wildcard characters. For example, to copy the values from all fields that begin with the letters A and P to variables or an array, use the following lines of code:

 CopyCode imageCopy Code
SCATTER FIELDS LIKE A*,P* TO myArray

The LIKE clause can be combined with the EXCEPT clause:

 CopyCode imageCopy Code
SCATTER FIELDS LIKE A*,P* EXCEPT PARTNO* TO myArray
MEMO

Specifies that the field list include one or more memo fields.

NoteNote

Your computer must have sufficient memory to scatter large memo fields to variables or to an array. Visual FoxPro generates an error message if your computer lacks sufficient memory. SCATTER does not copy data from a memo field if it is too large to fit in memory nor does it copy from any additional memo fields in the field list. If SCATTER does not succeed for a memo field, the value of the variable or array element is set to False (.F.).

TO ArrayName

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

If the array you specify contains more elements than the number of fields, the extra array elements remain unchanged. SCATTER automatically creates a new array if the array does not already exist, or if it contains fewer elements than the number of fields. The array elements have the same size and data types as the corresponding fields.

TO ArrayName

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

SCATTER creates a variable for each field in the field list if a field list is included.

To reference a variable that has the same name as a field in the current table, preface the variable name with the m. qualifier.

Caution noteCaution

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

Include the BLANK keyword to create 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 [ADDITIVE]

Creates an object whose properties have the same names as fields in the table.

To copy the value of each field in the table to each object property, do not include the BLANK keyword. To leave the properties empty, include the BLANK keyword. For a description of what the empty properties contain, based on the corresponding field type, see EMPTY( ) Function. Properties are not created for general fields that exist in the table.

To update the property values of an existing and valid Visual FoxPro object specified by ObjectName, but not COM objects, with values from the current record, include the ADDITIVE keyword. If the object does not exist, Visual FoxPro creates the object automatically. You cannot use the ADDITIVE keyword without the NAME clause. Doing so generates an error.

Using BLANK with ADDITIVE omits the values for existing properties that have matching field names.

Expand imageRemarks

Expand imageExamples

Expand imageSee Also