Notes of a Clipper Language Student

Menu

C5_APPEND FROM

APPEND FROM
Import records from a database (.dbf) file or ASCII text file
------------------------------------------------------------------------------
SyntaxAPPEND FROM <xcFile> [FIELDS <idField list>] [<scope>] [WHILE <lCondition>] [FOR <lCondition>] [SDF | DELIMITED [WITH BLANK | <xcDelimiter>] | [VIA <xcDriver>]]ArgumentsFROM <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.

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 Files Library is CLIPPER.LIB.