Show/Hide Toolbars

XSharp

NoteThis command is defined in a header file and will be preprocessed by the X# preprocessor to a function call. If you disable the standard header (-nostddefs) files then this command will not be available. If you tell the compiler to use a different standard header file (-stddef ) then this command may also be not available

Purpose

Assign new values to the contents of one or more fields in the current record.

Syntax

REPLACE <idField> WITH <uValue> [, <idField> WITH <uValue>...] [<Scope>] [WHILE <lCondition>]
 [FOR <lCondition>]  [[IN|ALIAS] <workarea>]

Arguments

<idField>The name of the field variable to assign a new value.  If <idField> is prefaced with an alias or declared using FIELD <idField> IN <idAlias>, the assignment takes place in the designated work area.  Otherwise, the current work area is assumed.

 

WITH <uValue>Defines the value to assign to <idField>.

 

<Scope>The portion of the current database file to process.  The default is all visible records. Scope is one or more clauses of:
[NEXT <NEXT>]        Optionally specifies the number of records to process starting
               with the first record of the source file.
[RECORD <rec>]        An optional record ID If specified, the processing begins
               with this data record in the source file.
[<rest:REST>]        The option REST specifies whether records are sequentially
               searched only from the current up to the last record.
               If a condition is specified, the option ALL is the default value.
[ALL]                The option ALL specifies that all records from the source file are imported.
               This is the default setting.

 

FOR <lCondition>A condition that each visible record within the scope must meet in order to be processed.  If a record does not meet the specified condition, it is ignored and the next visible record is processed.  If no <Scope> or WHILE clause is specified, having a for condition changes the default scope to all visible records.

 

WHILE <lCondition>A condition that each visible record within the scope must meet, starting with the current record.  As soon as the while condition fails, the process terminates.  If no <Scope> is specified, having a while condition changes the default scope to the rest of the visible records in the file.

 

IN|ALIAS <workarea>Specifies the work area for which the operation must be performed

Description

REPLACE performs the same function as the assignment operator (:=) except that it assumes field variables.  

 

Warning!  When you REPLACE a key field, the index is updated and the relative position of the record pointer within the index is changed.  This means that replacing a key field with a scope or a condition can yield an erroneous result.  To update a key field, suppress the controlling order (with, for example, SET ORDER TO 0 or DBSetOrder(0)) before the REPLACE.  This insures that the record pointer moves sequentially in natural order and that all orders in the order list are updated properly.

 

Shared mode: For a shared database, this command requires all records that it operates on to be locked.  You can accomplish this using one or more record locks or a file lock, depending on the scope of the command.  

Examples

This example shows a simple use of REPLACE:

 

USE customer NEW
APPEND BLANK
USE invoices NEW
APPEND BLANK
 
REPLACE Charges WITH Customer->Markup * Cost,;
 CustID WITH Customer->CustID,;
 Customer->TranDate WITH TODAY()

 

Using assignment statements in place of the REPLACE command looks like this:

 

Invoices->Charges := Customer->Markup * ;
 Invoices->Cost
Invoices->CustID := Customer->CustID
Customer->TranDate := TODAY()

Assembly

XSharp.RT.DLL

See Also

COMMIT, DbRLock(), DbSetOrder(), FLock(), RLock(), SET ORDER