APPEND FROM

Import records from a database (.dbf) file or ASCII text file

Syntax

      APPEND FROM <xcFile>
             [FIELDS <idField list>]
             [<scope>] [WHILE <lCondition>] [FOR <lCondition>]
             [SDF | DELIMITED [WITH BLANK | <xcDelimiter>] |
             [VIA <xcDriver>]]

Arguments

FROM <xcFile> specifies the name of the source file. You can specify <xcFile> either as a literal file name or as a character expression enclosed in parentheses. If a file extension is not specified, .dbf is the default input file type. If SDF or DELIMITED is specified, the file extension is assumed to be .txt unless otherwise specified.

FIELDS <idField list> specifies the list of fields to copy from <xcFile>. The default is all fields.

<scope> is the portion of the source database file to APPEND FROM. NEXT <n> APPENDs the first <n> records. RECORD <n> APPENDs only record number <n> from <xcFile>. The default scope is ALL records in <xcFile>.

WHILE <lCondition> specifies the set of records meeting the condition from the first record in the source file until the condition fails.

FOR <lCondition> specifies the conditional set of records to APPEND FROM within the given scope.

SDF identifies a System Data Format ASCII file. Records and fields are fixed length.

DELIMITED identifies an ASCII text file where character fields are enclosed in double quotation marks (the default delimiter). Note that delimiters are not required and Clipper correctly APPENDs character fields not enclosed in them. Fields and records are variable length.

DELIMITED WITH BLANK identifies an ASCII text file in which fields are separated by one space and character fields are not enclosed in delimiters.

DELIMITED WITH <xcDelimiter> identifies a delimited ASCII text file where character fields are enclosed using the specified delimiter. You can specify <xcDelimiter> as a literal character or as a character expression enclosed in parentheses.

See the tables below for more information regarding the format specification requirements for ASCII text files that you want to APPEND using these arguments.

VIA <xcDriver> specifies the replaceable database driver (RDD) to use to import the desired data. <cDriver> is the name of the RDD specified as a character expression. If <cDriver> is specified as a literal value, it must be enclosed in quotes.

If the VIA clause is omitted, APPEND FROM uses the driver in the current work area. If you specify the VIA clause, you must REQUEST the appropriate RDDs to be linked into the application.

Warning! If the DELIMITED WITH clause is specified on a COPY TO or APPEND FROM command line, it must be the last clause specified.

Description

APPEND FROM adds records to the current database file from an ASCII text file or another database file. Only fields with the same names and types are APPENDed. Fields with the same name from both the current database file and <xcFile> must be the same data type. If they are not, a runtime error occurs when the APPEND FROM command is invoked.

Any date information in <xcFile> must be in the format yyyymmdd to be properly APPENDed.

In a network environment, APPEND FROM does not require that the current database file be USEed EXCLUSIVEly or locked with FLOCK() to perform its operation. As each record is added, Clipper automatically arbitrates contention for the new record.

When you invoke APPEND FROM, Clipper attempts to open <xcFile> as shared and read-only. If access is denied, APPEND FROM terminates with a runtime error. Refer to the “Network Programming” chapter in the Programming and Utilities Guide for more information. No error is raised if you attempt to open a .dbf file that is already open.

          This table shows the format specifications for SDF text files:

 SDF Text File Format Specifications
 ------------------------------------------------------------------------
 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 1A hex or CHR(26)
 ------------------------------------------------------------------------

 This table shows the format specifications for DELIMITED and DELIMITED
 WITH <xcDelimiter> ASCII text files:
 DELIMITED Text File Format Specifications
 ------------------------------------------------------------------------
 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 1A hex or CHR(26)
 ------------------------------------------------------------------------

 This table shows the format specifications for DELIMITED WITH BLANK
 ASCII text files:
 DELIMITED WITH BLANK Text File Format Specifications
 ------------------------------------------------------------------------
 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 1A hex or CHR(26)
 ------------------------------------------------------------------------

Notes

. Deleted records: If DELETED is OFF, deleted records in <xcFile> are APPENDed to the current database file and retain their deleted status. If DELETED is ON, however, none of the deleted <xcFile> records are APPENDed.

. Unmatched field widths: If a field in the current database file is a character type and has a field length greater than the incoming <xcFile> data, Clipper pads the <xcFile> data with blanks. If the current field is a character data type and its field length is less than the incoming <xcFile> data, the <xcFile> data is truncated to fit. If the current field is a numeric type and the incoming <xcFile> data has more digits than the current field length, a runtime error occurs.

. CAUTION:

The  FROM <xcFile> (source file) shouldn’t be open and should be accessible. Otherwise 0 (zero) record will be appended.

Sample :

PROCEDURE MAIN()

   USE SOURCE
   COPY STRU TO TARGET
   SELE B 
   USE TARGET
   APPEND FROM SOURCE
   ? LASTREC() // IF "SELE B" active, 0 else > 0

RETURN // MAIN()

Examples

      .  This example demonstrates an APPEND FROM command using a
          fields list and a FOR condition:
      USE Sales NEW
      APPEND FROM BranchFile FIELDS Branch, Salesman, Amount;
         FOR Branch = 100
      .  This example demonstrates how a <scope> can be specified to
         import a particular record from another database file:
      APPEND RECORD 5 FROM Temp

Seealso

COPY TO