Share via

REPLACE FROM ARRAY Command

  • Article

Updates data in fields with values from a variable array.

REPLACE FROM ARRAY ArrayName [FIELDS FieldList] [Scope]
   [FOR lExpression1] [WHILE lExpression2] [NOOPTIMIZE]

Parameters

  • ArrayName
    Specifies the name of the array whose values replace the field data.

  • FIELDS FieldList
    Specifies that only the fields in FieldList be replaced by the contents of the array. Fields in unselected work areas must be prefaced with their table alias.

  • Scope
    Specifies a range of records to replace with the contents of the array. Only the records that fall within the range are replaced. Replacement occurs until the end of the scope or the end of the array is reached.

    The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see the Scope Clauses or Overview of the Language online topics.

    The default scope for REPLACE FROM ARRAY is the current record (NEXT 1).

  • FOR lExpression1
    Specifies that fields be replaced only in records for which lExpression1 evaluates to true (.T.). Including FOR makes it possible for you to conditionally replace records, filtering out those you don't want. Replacement occurs in each record for which lExpression1 is true (.T.), or until the end of the array is reached.

    Rushmore optimizes REPLACE FROM ARRAY FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause.

    For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

  • WHILE lExpression2
    Specifies a condition whereby fields in records are replaced by the contents of the array for as long as the logical expression lExpression2 evaluates to true (.T.).

  • NOOPTIMIZE
    Prevents Rushmore optimization.

    For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

Remarks

Memo and general fields are ignored in REPLACE FROM ARRAY. To import data into these fields, use GATHER and APPEND GENERAL.

Starting with the first element, the elements of the array replace the corresponding fields of the record. The first array element replaces the first field of the record, the second array element replaces the second field, and so on.

If the array has fewer elements than the table has fields, the additional fields are ignored. If the array has more elements than the table has fields, the additional array elements are ignored.

Note   No replacement occurs if the record pointer is at the end of the file in the current work area and you specify a field in another work area.

See Also

APPEND FROM ARRAY | APPEND GENERAL | COPY TO ARRAY | GATHER | REPLACE | SCATTER | SET OPTIMIZE