Commands and Statements Commands and Statements

Command GATHER NAME Foundation

Replaces data in the current record with data in a DataObject.

Syntax
GATHER NAME <oData> [FIELDS <FieldNameList>] [IN <nWorkArea>|<cAlias>]
GATHER NAME <oData> FIELDS EXCEPT <SkeletonList> [IN <nWorkArea>|<cAlias>]
GATHER NAME <oData> FIELDS LIKE <SkeletonList> [EXCEPT <SkeletonList>] [IN <nWorkArea>|<cAlias>]
Parameters
<oData>
The DataObject with the data to be used for the replace.
<FieldNameList>
A comma-separated list of field names. If no field names are specified, all fields are selected.
<SkeletonList>
A list of field names specified as string literals to be included or excluded in the operation. The list can include both qualified field names as well as wildcard patterns. See Like() for supported wildcard patterns.
<nWorkArea>|<cAlias>
The work area to replace the data in. <nWorkArea> is a positive integer with the ordinal number of the work area. <cAlias> is the alias name of the work area specified either as a literal string or as a character expression in parentheses. If no work area is specified, the current work area is selected.
Description

The command GATHER NAME tries to transfer all data from a DataObject to the current record of a work area. <oData> must have exported members with the same name as the fields in the work area. If no such member exists, no replace occurs and the record remains unchanged.

The FIELDS, FIELD EXCEPT and FIELD LIKE arguments can be used to qualify the fields to be changed by the operation. In this case, only the values in the specified fields are replaced provided a corresponding member variable exists in the data object.

The GATHER NAME command automatically detects shared work areas and performs an explicit record lock prior to performing the operation, if required.

Examples
Example for GATHER NAME usage 
/// - opens a dbf table and loads record #5 into a DataObject 
/// - changes values and closes the table 
PROCEDURE Main 
LOCAL oCustomer 

USE customer 
GO 5 
SCATTER NAME oCustomer 

? field->lastname           // Hellstrom 
? oCustomer:lastname        // Hellstrom 

oCustomer:lastname := "StromFromHell" 

? field->lastname           // Hellstrom 
GATHER NAME oCustomer 
? field->lastname           // StromFromHell 


// Only firstname and lastname are updated. Street is not updated. 
oCustomer:lastname := "Hellstrom" 
oCustomer:street   := "Invalid" 
GATHER NAME oCustomer FIELDS lastname, firstname 
? field->lastname           // Hellstrom 
? field->street             // 7689 Shiffer 

// Only fields with pattern ""*name" are updated. Street is not updated. 
oCustomer:lastname := "StromFromHell" 
oCustomer:street   := "Invalid" 
GATHER NAME oCustomer FIELDS LIKE "*name" 
? field->lastname           // StromFromHell 
? field->street             // 7689 Shiffer 

USE 

RETURN
Feedback

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.