Share via

SCATTER Command

  • Article

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

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]
   TO ArrayName | TO ArrayName BLANK | MEMVAR | MEMVAR BLANK
   | NAME ObjectName [BLANK] [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 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:

    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 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 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 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   Do not include the word TO with MEMVAR. Visual FoxPro creates an array named MEMVAR if you include the word 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] [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.

Remarks

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 Customer object:

USE Customer
SCATTER NAME Customer
? Customer.Company  && Returns the table value
? m.Customer.Company  && Returns the object property value

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

Example 3

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 ReportDate and Rating fields in the CreditHistory table and the CookieText and 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

See Also

ALINES( ) | APPEND FROM ARRAY | DECLARE | DIMENSION