Command APPEND FROM | Xbase++

Imports records from a file into the current work area.

APPEND FROM <cFilename> ;
    [FIELDS <cFieldname,...>] ;
    [FOR    <lForCondition>] ;
    [WHILE  <lWhileCondition>] ;
    [NEXT   <nCount>] ;
    [RECORD <xRecordID>] ;
    [ALL] ;
    [VIA <cDbe> | SDF | DELIMITED [WITH <cDelimiter>] ]

<cFilename> specifies the name of the file whose data is read or imported. The name must contain the drive and path if the file is not in the default directory. The filename can be specified either as a literal file name or as a character expression in parentheses. When the file name is specified without a file extension, the default extension predetermined by the current database engine (DBE)is used. The default file extension of the DBFDBE is ".DBF." If the option SDF or DELIMITED is specified, ".TXT" is used as the default file extension.

<cFieldname,...>

The option FIELDS specifies a comma-separated list of field names whose data is imported from the file <cFilename>. The field names can be specified as literals or as character expressions in parentheses. If this option is not included, all fields are imported from the file <cFilename>.

<lForCondition> is an optional logical expression which sets a condition. Only records from the source file for which <lForCondition> returns the value .T. (true) are imported.

<lWhileCondition> is an optional logical expression which sets a condition. Records are imported from the source file starting at the first record as long as <lWhileCondition> returns the value .T. (true). As soon as the expression gives the value .F. (false), the import terminates.

<nCount> optionally specifies the number of records to import starting with the first record of the source file.

<xRecordID> is an optional record ID (for DBF files it is the record number). If specified, the data import begins with this data record in the source file.

ALL

The option ALL specifies that all records from the source file are imported. This is the default setting.

<cDbe>

<cDbe> is a character string containing the name of the DBE used to manage the file <cFilename>. The option VIA cannot be specified if the options SDF or DELIMITED WITH are specified.

SDF

The option SDF specifies that the source file is an ASCII file in the "System Data Format." In this format, all records and fields have fixed length. These files are managed by the database engine SDFDBE.

DELIMITED

The option DELIMITED specifies that the source file is an ASCII file with data in each line separated by commas and character fields appearing in double quotes. Fields and records can have variable lengths. ASCII files in the delimited format are managed by the database engine DELDBE.

WITH <cDelimiter>

The argument <cDelimiter> specifies the delimiting character for character fields in a record (line) of an ASCII file in the delimited format. The fields are separated from one another by commas. <cDelimiter> can specify a literal or a character expression in parentheses.

The file command APPEND FROM imports records from a file into the current work area. The format of the source file can differ from the format of the target file open in the work area. This allows data translation between different file formats to occur. The source file must be capable of being opened by a database engine (DBE) for APPEND FROM to be successfully executed.

The options VIA, SDF and DELIMITED determine which DBE is used to open and manage the source file <cFilename>. If SDF is specified, the source file is opened by the SDFDBE and the file must be an ASCII file containing data in the "System Data Format." If DELIMITED is specified, the source file is opened by the DELDBE. In this case, <cFilename>must be an ASCII file in the "Delimited Format." If VIA <cDbe> is specified, any database engine capable of managing the specific file format can be specified. The DBE does not need to be loaded prior to calling APPEND FROM. If it is not loaded, it is automatically loaded into memory and deleted from memory after termination of the command.

If no database engine is specified, the source file is opened using the current DBE. If the source file has a different file format, the corresponding DBE capable of opening the source file must be specified. Copying data from the source file into the work area (target file) occurs based on matching field names and/or equal data types. It should be noted that different DBEs can support different data types. In the case of the DELDBE, field names are predefined (FIELD1, FIELD2 to FIELDn). The option DELIMITED, therefore, uses only the data type of the fields and not the field names.

Generally, only fields of the same data type are imported into the work area with APPEND FROM. When the source file and the target file have a different file format (meaning they are managed by two different DBEs), the data types which can be stored in both file formats must be considered. Available file formats and data types are predetermined by the database engines managing the source file and target files. The specification of file formats for different DBEs is found in the chapter "The Xbase++ DatabaseEngine"in the Xbase++ documentation.

Specifying FOR, WHILE, RECORD or NEXT limits the number of records imported. These options are related to the source file and test data records in the source file. If the source file permits the logical deletion of records, records marked for deletion are only imported when SET DELETED is set to OFF. The records keep their deletion flag.

The command APPEND FROM opens the source file in the mode SHARED and READONLY. If this is not successful, a runtime error is generated.

Import data using APPEND FROM

// The example illustrates a typical use for the command 
// APPEND FROM. A temporary DBF file is created to 
// store a subset of records. Operations are 
// performed with the subset and then the temporary 
// file is deleted. 

PROCEDURE Main 

   USE Customer NEW 
   COPY STRUCTURE TO Temp          // generate temporary file 
   USE Temp 

   APPEND FROM Customer FOR "NEW YORK" $ Upper(CITY) 

   Browse() 
   USE 

   ERASE Temp.dbf                  // delete temporary file 
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.

Command APPEND FROM Foundation