xHarbour Reference Documentation > Command Reference

APPEND FROM

Imports records from a database file or an ASCII text file.

Syntax

APPEND FROM <sourceFile> ;
    [FIELDS <fieldNames,...> ;]
    [<Scope> ; ]
     [WHILE <lWhileCondition> ;]
       [FOR <lForCondition> ;]
       [VIA <rddName> ;]
       [SDF | DELIMITED [WITH BLANK | TAB | PIPE | <xDelimiter> ;] 
  [CODEPAGE <cCodePage> ;] 
[CONNECTION <nConnection>] ]

Arguments

FROM <sourceFile>

This is the name of the source file as a literal character string or a character expression enclosed in parentheses. When the file name is specified without a file extension, .dbf is assumed as default extension, unless the SDF or DELIMITED option is specified. In this case, the default file extension is .txt.

FIELDS <fieldNames,...>

The names of the fields to import from the external file can be specified as a comma separated list of literal field names or character expressions enclosed in parentheses. When this option is omitted, all fields of the source file are imported.

<Scope>

This option defines the number of records to import. It defaults to ALL. The NEXT <nCount> scope imports the first <nCount> records, while the RECORD <nRecno> scope imports only one record having the record number <nRecno>.

WHILE <lWhileCondition>

This is a logical expression indicating to continue importing records while the condition is true. The APPEND FROM operation stops as soon as <lWhileCondition> yields .F. (false).

FOR <lForCondition>

This is a logical expression which is evaluated for all records in the source file. Those records where <lForCondition> yields .T. (true) are imported.

VIA <rddName>

The VIA option specifies the replaceable database driver (RDD) to use for opening the source file. <rddName> is a character expression. If it is written as a literal name, it must be enclosed in quotes.

When no RDD is specified, the RDD active in the current work area is used to open the import file. If the VIA clause is used, the specified RDD must be linked to the application. Use the REQUEST command to force an RRD be linked.

SDF

The SDF option specifies the source file as an ASCII file in System Data Format. See file format description below.

DELIMITED

The DELIMETED option specifies the source file as a delimited ASCII file where field values are separated with a comma and Character values are enclosed with a delimiting character. The default delimiter for Character values is a double quotation mark.

DELIMITED WITH BLANK | TAB | PIPE

When the delimiter is specifiwed as BLANK, field values in the ASCII text file are separated by one space and character fields are not enclosed in delimiters. Alternatively, the delimiting character between field values can be specified as TAB (Chr(9)) or PIPE (Chr(124)).

DELIMITED WITH <xDelimiter>

The WITH option specifies the delimiting character to enclose values of Character fields in. <xDelimiter> can be specified as a literal character or a character expression enclosed in parentheses.

<xDelimiter> can also be specified as an array with two elements: { <cCharacterDelimiter>, <cFieldDelimiter> }. If this option is used, the array must be enclosed in parentheses. It defines the delimiting characters for field values of type "C" and the delimiters between field values.

Important:  If the DELIMITED WITH option is used in the APPEND FROM command, it must be placed as the last option in the command.

CODEPAGE <cCodePage>

This is a character string specifying the code page to use for character strings stored in the new database. It defaults to the return value of HB_SetCodePage().

CONNECTION <nConnection>

This option specifies a numeric server connection handle. It is returned by a server connection function which establishes a connection to a database server, such as SR_AddConnection() of the xHarbour Builder SQLRDD. When CONNECTION is used, the APPEND FROM command appends data from a database on the server.

Description

APPEND FROM is a database command used to import data from a second file into the current work area. Imported records are added to the end of the table open in the current work area. When the external file is a database, only fields with matching names are imported. Fields with matching names must have the same data type, otherwise a runtime error occurs.

The file in the current work area can be opened in SHARED mode. APPEND FROM automatically maintains required record locks while data is being imported.

The import file is attempted to be opened in SHARED and READONLY mode. If opening the import file fails, APPEND FROM raises a runtime error.

When the external file is an ASCII text file, all date values must be stored in the StoD() compliant format yyyymmdd. Other specifications for supported ASCII formats ar listed in the folowing tables:

SDF Text File

File Element	Format
Character fields	Padded with trailing blanks
Date fields	yyyymmdd
Logical fields	T or F
Memo fields	Ignored
Numeric fields	Padded with leading blanks or zeros
Field separator	None
Record separator	Carriage return/linefeed
End of file marker	0x1A or CHR(26)

DELIMITED Text File

File Element	Format
Character fields	May be delimited, with trailing blanks truncated
Date fields	yyyymmdd
Logical fields	T or F
Memo fields	Ignored
Numeric fields	Leading zeros may be truncated
Field separator	Comma
Record separator	Carriage return/linefeed
End of file marker	0x1A or CHR(26)

DELIMITED WITH BLANK Text File

File Element	Format
Character fields	Not delimited, trailing blanks may be truncated
Date fields	yyyymmdd
Logical fields	T or F
Memo fields	Ignored
Numeric fields	Leading zeros may be truncated
Field separator	Single blank space
Record separator	Carriage return/linefeed
End of file marker	0x1A or CHR(26)

Field length:  When the length of Character fields in the current work area is shorter than the length of a corresponding field in the import file, character data is truncated up to the length of the field in the current work area. Truncated data is lost. If the field is longer, remaining characters are filled with blank spaces.

When the length of a numeric field in the current work area does not suffice to hold all digits of an imported numeric field, a runtime error is created.

Deleted records:  Records in an import database file that are marked for deletion are ignored when SET DELETED is set to ON. These records are not imported. With SET DELETED OFF, all records matching the import scope are imported and the deleted flag is set accordingly.

Info

See also:	COPY TO, DbAppend(), UPDATE
Category:	Database commands
Source:	rdd\dbcmd.c, rtl\dbdelim.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example creates a subset of records from a database
// within an intermediate file.

   PROCEDURE Main

      USE Address NEW
      COPY STRUCTURE TO Tmp          // create an intermediate file
      USE Tmp

      APPEND FROM Address FOR "LONDON" $ Upper(CITY)

      Browse()
      USE

      ERASE Tmp.dbf                  // delete intermediate file
   RETURN