Commands and Statements

Command REPLACE Foundation

Assigns values to field variables.

REPLACE <cFieldname> WITH <Expression> ;
     [, <cFieldname> WITH <Expression>... ] ;
[FOR    <lForCondition>] ;
[WHILE  <lWhileCondition>] ;
[NEXT   <nCount>] ;
[RECORD <xRecordID>] ;
[REST] ;
[ALL] ;
<cFieldname> is the name of the field variable to which the value <Expression> is assigned. If an alias name is not specified, <cFieldname> indicates a field variable in the current work area.
<Expression> is an expression whose value is assigned to the field <cFieldname>. The data type of <Expression> must match the field data type.
<lForCondition> is an optional logical expression which sets a condition. Values are assigned only to those records where <lForCondition> returns the value .T. (true).
<lWhileCondition> is an optional logical expression which sets a condition. Values are assigned to the current record only as long as <lWhileCondition> returns the value .T. (true). As soon as the expression returns the value .F. (false), the process terminates.
<nCount> optionally specifies the number of records to which values are assigned, starting with the current record. By default, an assignment occurs only for the current record. This corresponds to NEXT 1.
<xRecordID> is an optional record ID (for DBF files, it is the record number). If a record ID is specified, a value is assigned only to the indicated record.
The option REST determines whether an assignment occurs only from the current record to the last record. If a condition is specified, the option ALL is the default.
The option ALL assigns a value to all records. If a condition is specified, the condition is tested for all records.

The file command REPLACE assigns values to specific field variables. After the key word REPLACE, a list of assignments can be specified (separated by commas) conforming to <Field1> WITH <Expr1>, <FieldN> WITH <ExprN>. The command has the same functionality as the assignment operator (:=). Of course, the variable referenced is always a field variable, even when no alias name is indicated with REPLACE. Values can also be assigned to field variables using the assignment operator when the alias name and alias operator are placed in front of the field name, or when the variable is explicitly declared as a field variable by the declaration FIELD.

When neither a condition nor the number of records are specified, REPLACE works with only the current record by default. Otherwise, the specified number of records or the records matching the condition are used.

In a multi-user application in a network operation, a record must be locked before the command REPLACE is executed or before an assignment occurs.

When a value is assigned to a field variable which is part of the index expression of the controlling index, the index is updated after the assignment. This can change the logical order of the data records. If only one record is changed using REPLACE, no problems occur. But if several records are changed, it can lead to unexpected results. In this case, the records should be in natural order, which is accomplished with the command SET ORDER TO 0. The index files remain open and continue to be updated.

// In the example, the data for a record is 
// read into memory variables which are edited. 
// After editing is complete, the variables are 
// assigned to the field variables using REPLACE 

   LOCAL cPartNo , cPart 

   USE Part INDEX PartA, PartB ALIAS Part NEW 
   cPartNo  := Part->PartNo 
   cPart    := Part->Part 

   @ 10,5 SAY "Part number     :" GET cPartNo 
   @ 11,5 SAY "Part designation:" GET cPart 

   IF .NOT. Empty( cPartNo + cPart ) 
      REPLACE PartNo WITH cPartNo   , ; 
              Part   WITH cPart 

   CLOSE Part 

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.