+---------------------------------+
|             REPLACE             |
+---------------------------------+
REPLACE
        <field1> WITH <expr1>
        [ADDITIVE]
        [, <field2> WITH <expr2>
        [ADDITIVE]] ...
        [<scope>] [FOR <expL1>]
        [WHILE <expL2>]
        [NOOPTIMIZE]

-----------------------------------
Updates database records.
-----------------------------------

The REPLACE command REPLACEs the data that was previously in <field1>
WITH the data in <expr1>.  Fields in unselected work areas must be
specified with an alias.

Note that if the record pointer is at the end of the file in the
currently selected work area and you specify a field in another work
area in the REPLACE command no replacement will occur.  This is because
the default scope for REPLACE is the current record in the selected work
area.  If the record pointer is at the end of file in the currently
selected work area, the scope is not met and no replacements are made,
either in the currently selected work area or any other work areas.

<scope>
FOR <expL1>
WHILE <expL2>
        Unless a <scope>, FOR or WHILE clause is specified, only the current
record is affected by the REPLACE command.

        . Because the REPLACE command updates active indexes with each
execution of the command, it is important that REPLACEments never be
performed on the key field of an indexed file when a <scope>, FOR or
WHILE clause is in effect.

        If this warning is ignored, it is possible that only part of the
intended replacements will actually occur.

<field1> WITH <expr1>
[, <field2> WITH <expr2> ...
        Replaces the data in <field1> with the data in <expr1>, replaces the
data in <field2> with the data in <expr2>, and so on.

        In numeric fields, when the WITH expression value is longer than the
actual field width, REPLACE will force it to fit as follows:

        . First, decimal places are truncated and the remaining decimal portion
of the field is rounded.

        . If the value still does not fit, scientific notation  replaces the
field contents specified (precision is lost).

        . Finally, if all else fails, asterisks replace the field contents.

ADDITIVE
        The ADDITIVE clause applies to replacements in memo fields only. If the
ADDITIVE clause is included, replacements to memo fields are appended to
the end of the memo field.  If the ADDITIVE clause is not included, the
memo field is overwritten with <expr1>.

NOOPTIMIZE
        The REPLACE command benefits from FoxPro's Rushmore technology.
Rushmore optimizes data retrieval.  Commands (like REPLACE) that support
a FOR clause use Rushmore to enhance their performance.

        There are rare cases when you should disable Rushmore.  When a command
that utilizes Rushmore is issued, Rushmore determines which records
match the FOR clause criterion.  The command is then executed on records
in the database that match the Rushmore record set.

        If a potentially optimizable command like REPLACE modifies the index
key in the FOR clause, Rushmore's record set may become outdated.  In a
case like this, you may disable Rushmore to ensure that you have the
most current information from the database.

        To disable Rushmore, include the NOOPTIMIZE keyword.  Rushmore may be
globally disabled (or enabled) for all commands that benefit from
Rushmore with the SET OPTIMIZE command.

        For further information on utilizing FoxPro's Rushmore technology, see
the Rushmore discussion in the FoxPro Developer's Guide, and the SET
OPTIMIZE command in this help facility.

+---------------------------------+
|         Program Example         |
+---------------------------------+
CLOSE ALL
USE customer
SET TALK OFF
SCATTER MEMVAR BLANK
DEFINE WINDOW menter FROM 7,10 to 17,70 PANEL
ACTIVATE WINDOW menter
@ 1,3  SAY 'Company: ' GET m.company
@ 3,3  SAY 'Address: '  GET m.address1
@ 5,3  SAY 'City: '     GET m.city
@ 7,3  SAY 'State: '    GET m.state
@ 7,18 SAY 'Zip: '      GET m.zip
READ
DEACTIVATE WINDOW menter
IF UPDATED()
    APPEND BLANK
    REPLACE company           WITH m.company
    REPLACE address1          WITH m.address1
    REPLACE city              WITH m.city
    REPLACE state             WITH m.state
    REPLACE zip               WITH m.zip
ENDIF

-----------------------------------

See Also:  GATHER, SCATTER

-----------------------------------