Function DbUpdate() | Xbase++

Updates the current work area with data from another work area.

DbUpdate( <cAlias>, ;
          <bReplace>, ;
          <bIndexKey>, ;
          [<lRandom>] ) --> NIL

<cAlias> is a character expression specifying the alias name of the source work area whose records are used to update the target work area.

The code block <bReplace> contains the expressions used to update fields in the target work area.

The code block <bIndexKey> contains a key expression used to determine whether records are to be updated. The target work area must be sorted or indexed using this key expression. The code block is evaluated in the source work area as well as the target work area. If the return value of the code block in both cases is identical, data records are updated in the target work area.

Normally the source work area <cAlias> must be sorted using the same key expression <bIndexKey> as the target work area. If this is not the case, the value .T. (true) must be specified for the parameter <lRandom>. This indicates that the records in the source work area occur in any order and are not sorted or indexed according to the key expression. The default value is .F. (false).

The return value of DbUpdate() is always NIL.

The function DbUpdate() updates records in a work area with values from the records of a second work area <cAlias>. An update occurs only when the code block <bIndexKey> provides the same value in both work areas. This assumes that the controlling index with the index key <bIndexKey> is active in the first work area and that no duplicate key values exist there. The records of the source work area are sequentially processed, using the return value of <bIndexKey> on each source record as the argument to DbSeek() in the target work area. If a matching record is found, the code block <bReplace> is evaluated. Within this code block, values from the fields in the source work area should be used to update the target work area.

If the value .T. (true) is specified for <lRandom>, the data records of the source work area can be in any order. Otherwise, the source work area must also be sorted or indexed by the index key <bIndexKey>.

If records in one of the two work areas are marked as deleted, they are ignored by DbUpdate() when SET DELETED is turned ON. If SET DELETED is OFF, all records are taken into consideration and their "deleted" status remains unchanged.

If the function DbUpdate() is used in multi-user (network) operation, the file in the target work area must be locked with FLock() or must be exclusively opened. The file in the source work area does not need to be locked, since only read access occurs.

DbUpdate()


// The example shows a typical use for DbUpdate(). 
// Data in the original file is updated using 
// transaction data from a temporary file. Then 
// the data is deleted in the transaction file. 

PROCEDURE Main 

   USE SaleTemp ALIAS Sale NEW EXCLUSIVE 
   INDEX ON ItemNo TO SalesA 

   USE Items ALIAS Item NEW EXCLUSIVE 
   INDEX ON ItemNo TO ItemsA 

   DbUpdate( "Sale", ; 
            {|| FIELD->Stock      -= Sale->Count, ; 
                FIELD->NumberSold += Sale->Count  }, ; 
            {|| FIELD->ItemNo } ) 

   SELECT Sale 
   ZAP 

   CLOSE DATABASES 

RETURN

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.

Function DbUpdate() Foundation