APPEND FROM ARRAY Command

  • Article

Adds one record to the currently selected table for each row in an array and fills each record with data from the corresponding array row.

APPEND FROM ARRAY ArrayName [FOR lExpression] 
   [FIELDS FieldList | FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton]

Parameters

  • ArrayName
    Specifies the name of the array that contains the data to be copied to the new records. New records are added to the table until all rows in the array are appended.

  • FOR lExpression
    Specifies a condition for appending records from the array. lExpression must contain the name of a target field in its conditional expression.

    Before a row of the array is appended to a record in the table, the array element corresponding to the target field specified in lExpression is checked to determine whether that array element meets the condition in lExpression. If the array element satisfies the condition, a record is appended.

    If the array element does not satisfy the condition, the array row is not appended and the next row in the array is checked to determine whether it meets the condition.

  • FIELDS FieldList
    Specifies that only the fields in FieldList are updated from the array. The first field in the list is updated with the contents of the first element in the array, the second field is updated from the second element, and so on.

  • FIELDS LIKE Skeleton
    Specifies that fields that match the field skeleton Skeleton are updated from the array.

  • FIELDS EXCEPT Skeleton
    Specifies that all fields except those that match the field skeleton Skeleton are updated from the array.

    The field skeleton Skeleton supports wildcards. For example, to specify that all fields that begin with the letters A and P are updated from the array, use the following:

    APPEND FROM ARRAY aMyArray FIELDS LIKE A*,P*

    The LIKE clause can be combined with the EXCEPT clause:

    APPEND FROM ARRAY aMyArray FIELDS LIKE A*,P* EXCEPT PARTNO*

Remarks

Memo and general fields are ignored in APPEND FROM ARRAY. When a table is open for shared use, APPEND FROM ARRAY locks the table header while records are being added.

If the array is one-dimensional, APPEND FROM ARRAY adds one record to the table. The contents of the first array element fill the first field of the newly added record, the contents of the second element of the array fill the second field of the record, and so on.

If the one-dimensional array has more elements than the table has fields, the additional elements are ignored. If the table has more fields than the array has elements, the additional fields are initialized to the default empty value. Here are the default empty values for each field type:

Field type Default value
Character Spaces
Numeric 0
Currency 0
Float 0
Integer 0
Double 0
Date Empty Date (e.g. CTOD(""))
DateTime Empty DateTime (e.g. CTOT(""))
Logical False (.F.)
Memo Empty (no contents)

If the array is two-dimensional, APPEND FROM ARRAY adds a new record to the table for each row in the array. For example, if the array has four rows, four new records are appended to the table.

The contents of the first array column fill the first field of the newly added records, the second array column fills the second field of the new records, and so on. For example, if the array has four rows and three columns, elements from the first array column fill the first field in each of the four new records appended to the table.

If the two-dimensional array has more columns than the table has fields, the additional columns are ignored. If the table has more fields than the array has columns, the additional fields are initialized to empty values.

APPEND FROM ARRAY can fill a field even if the data type of the corresponding array element doesn't match the data type of the field, provided that the array element data is compatible with the data type of the corresponding field. If the data isn't compatible, the field is initialized to an empty value.

Example

This example creates a table and then uses APPEND FROM ARRAY to append a record to the new table.

LOCAL ARRAY aNewRec(3)

* Create the table
CREATE TABLE Test FREE  (Object C(10), Color C(16), SqFt n(6,2))
SCATTER TO aNewRec BLANK  && Create a new array from the table
aNewRec[1]="Box"         && Fill the the array
aNewRec[2]="Red"
aNewRec[3]=12.5
APPEND FROM ARRAY aNewRec   && Add record containing array contents
          && to the table

See Also

APPEND | COPY TO ARRAY | DIMENSION | GATHER | SCATTER