Click above to get retro games delivered to your door ever month!

  REPLACE          - Assign new values to one or more fields in a database
-------------------------------------------------------------------------------

  Syntax:

  REPLACE <idField> WITH <exp> [,<idField2> WITH <exp2>...]
          [<scope>] [WHILE <lCondition>] [FOR <lCondition>]
          [NOOPTIMIZE]

  Arguments:

  <idField> is the name of the field variable to assign a new value. If
  <idField> is prefaced with an alias, the assignment takes place in the
  designated work area.

  <exp> is the value to assign to <idField>.

  <scope> is the portion of the current database file to REPLACE. The
  default is the current record, or NEXT 1.  Specifying a condition changes
  the default to ALL records in the current work area.  Mach SIx will only
  optimize the ALL scope.

  WHILE <lCondition> specifies the set of records meeting the condition
  from the current record until the condition fails.  Mach SIx does not
  support the WHILE condition.

  FOR <lCondition> specifies the conditional set of records to REPLACE
  within the given scope.  Mach SIx will optimize any FOR condition, that
  contains one or more active index keys.

  NOOPTIMIZE, preempts optimization and forces default Clipper processing.

  Description:

  REPLACE is a database command that assigns new values to the contents of
  one or more field variables in the current record in the specified work
  areas.  The target field variables can be character, date, logical, memo,
  or numeric.  REPLACE performs the same function as the assignment (:=)
  operator except that it assumes that an unaliased reference is to a field
  variable.  This means that you can assign new values to field variables
  using assignment statements provided that the field variable references are
  prefaced with an alias, the FIELD alias, or declared using the FIELD
  declaration statement.

  The default scope of REPLACE is the current record unless a scope or
  condition is specified.  If a scope or condition is specified, the replace
  operation is performed on each record matching the scope and/or condition.

  The REPLACE command my be optimized by specifying one or more active index
  keys in the FOR condition.  Note that Mach SIx will only optimize the
  REPLACE command when use with a FOR condition and a SCOPE of ALL.  WHILE
  conditions, and alternate scopes cannot be optimized by Mach SIx.

  -----------------------------------------------------------------------
  Warning:

  When REPLACEing a key field, the index is updated and the relative
  position of the record pointer within the index is changed.  This means
  that REPLACEing a key field with a scope or a condition may yield an
  erroneous result.  To update a key field, SET ORDER TO 0 before the
  REPLACE.  This insures that the record pointer moves sequentially in
  natural order.  All open indexes, however, are updated if the key field
  is REPLACEd.
  -----------------------------------------------------------------------

  In a network environment, REPLACEing the current record requires an
  RLOCK().  REPLACEing with a scope and/or condition requires an FLOCK()
  or EXCLUSIVE USE of the current database file.  If a field is being
  REPLACEd in another work area by specifying its alias, that record must
  also be locked with an RLOCK(). Refer to the Network Programming
  chapter in Clipper's Programming and Utilities book for more information.

  ---------------------------------| EXAMPLE |--------------------------------
  /*:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  *  Demonstrates optimized REPLACE command                                 *
  *::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::*/

  #include "DBFSIX.CH"
  #include "MACHSIX.CH"

  USE Account VIA "DBFSIX"  // Structural index ACCOUNT.CDX opened
                            // automatically
  CLEAR SCREEN
  ? "Example of an optimized REPLACE command."
  ?

  // Set order to 0 to enhance performance, and prevent erroneous
  // results replacing a controlling index key value.
  SET ORDER TO 0

  // Fully optimized update of Account numbers, for North Carolina
  REPLACE AcctNo WITH AcctNo + 1000000 FOR State = "NC"
  CLOSE ALL