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]
- 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 FIELDSFieldNameList 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 LIKESkeleton. To copy values of all fields except those matching Skeleton to variables or an array, use EXCEPTSkeleton. 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:
The LIKE clause can be combined with the EXCEPT clause:
В Copy Code
SCATTER FIELDS LIKE A*,P* TO myArray
В Copy Code
SCATTER FIELDS LIKE A*,P* EXCEPT PARTNO* TO myArray
Specifies that the field list include one or more memo fields.
Note: 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.
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.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.
Caution: Do not include the word TO with MEMVAR. Visual FoxPro creates an array named
MEMVARif you include the word TO.
- 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.
If properties corresponding to field names do not exist for the object, SCATTER...NAME ADDITIVE automatically creates them. However, SCATTER might not create all the necessary properties because some might be marked as Hidden or Protected. If Visual FoxPro cannot create or set a property, it generates an error. For example, you can have a field name that matches a native Visual FoxPro object property name as long as the field and property data types are the same. However, Visual FoxPro generates an error if the field name matches a method, event, or object name.
You can avoid problems by using an object created by SCATTER...NAME and not one derived from a Visual FoxPro class. Unlike when SCATTER is used with only NAME, Visual FoxPro does not overwrite the existing object to create a new object.
SCATTER...NAME ADDITIVE does not generate an error when a read-only property cannot be set for a field in the table. However, the value of the property remains unchanged.
To reference a property in an object that has the same name as an open table, preface the property name with the
m. qualifier. The following example displays the value of the
Company field in the
Customer table followed by the value of the
Company property for the
USE Customer SCATTER NAME Customer ? Customer.Company && Returns the table value ? m.Customer.Company && Returns the object property value
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
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
Suppose you have two or more tables or cursors and wish to create an object that combines the data from those cursors. The following example selects the
Customer table and uses SCATTER...NAME to create the
oCustomer object and its properties from fields in the
Customer table. SCATTER...NAME...ADDITIVE then updates the values from the
Rating fields in the
CreditHistory table and the
SessionId fields in the
MySessionTable table in the
oCustomer object or creates those properties if they do not exist.
SELECT Customer SCATTER NAME oCustomer SELECT CreditHistory SCATTER FIELDS ReportDate, Rating NAME oCustomer ADDITIVE SELECT MySessionTable SCATTER FIELDS CookieText, SessionId NAME oCustomer ADDITIVE