xHarbour Reference Documentation > Command Reference

COPY TO

Exports records from the current work area to a database or an ASCII text file.

Syntax

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

Arguments

TO <targetFile>

This is the name of the target 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 export to 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 exported.

<Scope>

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

WHILE <lWhileCondition>

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

FOR <lForCondition>

This is a logical expression which is evaluated for all records in the current work area. Those records where <lForCondition> yields .T. (true) are exported.

VIA <rddName>

The VIA option specifies the replaceable database driver (RDD) to use for opening the target 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 external 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 target file as an ASCII file in System Data Format. See file format description below.

DELIMITED

The DELIMETED option specifies the target 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 specified as BLANK, field values in the new created 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 COPY TO 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 COPY TO command copies data to a database on the server.

Description

COPY TO is a database command used to export data of the current work are into a second file. Exported records are added to the end of the target file. The target file receives data from all fields of the current work area, unless a list of fields is explicitely specified.

The file in the current work area can be opened in SHARED mode. COPY TO creates the target file and opens it in EXCLUSIVE mode while data is being exported.

When the target file is an ASCII text file, all date values are written as a string in the 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)

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

Info

See also:	APPEND FROM, COPY FILE, COPY STRUCTURE
Category:	Database commands
Source:	rdd\dbcmd.c, rtl\dbdelim.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Examples

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

   PROCEDURE Main

      USE Address NEW

      COPY TO Tmp FOR "LONDON" $ Upper(CITY)
      USE Tmp

      Browse()
      USE

      ERASE Tmp.dbf                  // delete intermediate file
   RETURN

// The example creates different delimited ASCII files.

   PROCEDURE Main

      USE Address NEW

      // Creates a regular DELIMITED ASCII file
      COPY TO Test.txt DELIMITED

      // Uses Chr(9) as field delimiter
      COPY TO Test1.txt DELIMITED WITH TAB

      // Uses "|" as field delimiter
      COPY TO Test2.txt DELIMITED WITH PIPE

      // Encloses character values in single quotes and separates
      // fields with Chr(255)
      COPY TO Test3.txt DELIMITED WITH ( {"'", Chr(255) } )

      USE
   RETURN