APPEND FROM ARRAY Command
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, General, and Blob 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 |
Currency |
0 |
Date |
Empty Date (e.g. CTOD("")) |
DateTime |
Empty DateTime (e.g. CTOT("")) |
Double |
0 |
Float |
0 |
Integer |
0 |
Logical |
False (.F.) |
Memo |
Empty (no contents) |
Numeric |
0 |
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 corresponding array element's data type does not match the field's data type an provided that the array element data is compatible with the data type of the corresponding field. If the data is not compatible, the field is initialized to an empty value.
If the target table uses autoincrementing, APPEND FROM ARRAY fails if SET AUTOINCERROR is ON, unless the FIELDS option is used to omit the AUTOINC column. Setting AUTOINCERROR to OFF or turning off autoincrementing in the target table by using CURSORSETPROP( ) allows the APPEND FROM ARRAY to succeed. The target table's autoincrementing field or fields are incremented according to the values specified, and the values in source table are not applied.
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 array
aNewRec[2]="Red"
aNewRec[3]=12.5
APPEND FROM ARRAY aNewRec && Add record containing array contents
&& to the table