xHarbour Reference Documentation > Command Reference

REPLACE

Assigns values to field variables.

Syntax

REPLACE <fieldName1> WITH <expression1> ;
     [, <fieldNameN> WITH <expressionN>] ;
  [NEXT <nCount>|ALL] ;
 [WHILE <lWhileCondition>] ;
   [FOR <lForCondition>]

Arguments

<fieldName>

This is the symbolic name of the field variable to assign a new value to. The field variable is searched in the current work area unless prefixed with an alias name of another work area.

WITH <expression>

The value of <expression> is assigned to <fieldName>. Note that <expression> must yield a value of the same data type as the field variable. Memo fields must be assigned values of data type Character.

NEXT <nCount>

This option defines the number of records to process for assignment operations. It defaults to the current record. The NEXT <nCount> scope performs assignments to the fields of the next <nCount> records.

ALL

The option ALL processes all records. It becomes the default scope when a FOR condition is specified.

WHILE <lWhileCondition>

This is a logical expression indicating to continue processing records while the condition is true. The REPLACE command stops as soon as <lWhileCondition> yields .F. (false).

FOR <lForCondition>

This is a logical expression which is evaluated for all records in the current work area. Those records where <lForCondition> yields .T. (true) are processed.

Description

The REPLACE command assigns values to one or more field variables. The field variables are identified with their symbolic field names and are searched in the current work area, unless being prefixed with the alias name of a different work area.

The scope of the REPLACE command is the current record when no further condition of scope is specified. otherwise, all records matching scope and condition are processed.

When a database is open in SHARED mode, the current record must be locked with the RLock() function before REPLACE may be called. Failure to do so generates a runtime error. If multiple records should be processed, the entire file must be locked using FLock(), or the file must be open in EXCLUSIVE mode. This applies to files open in all work areas praticipating in the assignment operation.

Note:  When field variables that are part of an index expression of open indexes are changed, the corresponding index is automatically updated, unless the index is created with the CUSTOM attribute. In the latter case a custom index must be updated manually.

It is recommended to SET ORDER TO 0 before changing field variables that are part of index expressions. This makes sure that the relative record pointer position does not change automatically while indexes are updated.

Info

See also:	COMMIT, DbRlock(), FLock(), RLock()
Category:	Database commands

Example

// The example demonstrates how to assigne values to a database
// open in SHARED mode.

   PROCEDURE Main
      LOCAL cFirstname, cLastname

      USE Customer INDEX CustA, CustB ALIAS Cust NEW SHARED
      cFirstname := Cust->Firstname
      cLastname  := Cust->Lastname

      CLS
      @ 5,1 SAY "First name:" GET cFirstname
      @ 6,1 SAY "Last name :" GET cLastname
      READ

      IF .NOT. Empty( cFirstname + cLastname ) .AND. RLock()
         REPLACE Firstname WITH cFirstname, ;
                 Lastname  WITH cLastname
         COMMIT
         UNLOCK
      ENDIF

      CLOSE Cust
   RETURN