Command COPY TO | Xbase++ | Alaska Software

Exports records from a work area into a new file.

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

<cFilename> specifies the name of the new file where the exported records are written. The name must contain the drive and path if they are necessary. It can be specified either as a literal file name or a character expression in parentheses. If 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 fields whose contents are exported to the file <cFilename>. The field names can be specified as literals or as character expressions in parentheses. If this option is not included, data for all fields in the current work area are copied into the file <cFilename>.

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

<lWhileCondition> is an optional logical expression defining a condition. records are exported from the work area starting at the current record as long as <lWhileCondition> provides the value .T. (true). As soon as the expression results in the value .F. (false), the operation terminates.

<nCount> specifies the number of records to export, starting at the current record.

<xRecordID> is a record ID (for DBF files, it is the record number). The data export begins with this record.

REST

The option REST specifies that records are only exported from the current record up to the last record. If a condition is specified, the option ALL is the default value.

ALL

The option ALL exports all records in the work area. This is the default setting. If a condition is specified, the condition is tested for all records.

<cDbe>

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

SDF

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

DELIMITED

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

WITH BLANK

DELIMITED WITH BLANK indicates that the blank space (Chr(32)) is used as the separation character between the fields of an ASCII file in the delimited format. Character fields have no additional delimiters.

WITH <cDelimiter>

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

The file command COPY TO exports records from the current work area to a new file. If the target file already exists, it is overwritten without warning. The format of the source file open in the current work area can be different from the format of the target file. This allows file conversion between different file formats to be performed. The target file must be capable of being opened by a database engine (DBE) for the COPY TO to successfully execute.

The options VIA, SDF and DELIMITED determine the DBE used to create the target file <cFilename>. If SDF is specified, the target file is generated using the SDFDBE and the file is an ASCII file in the "System Data Format." If DELIMITED is specified, the target file is generated by the DELDBE. In this case, <cFilename> is an ASCII file in the "Delimited Format." If VIA <cDbe> is specified, a database engine can be specified to manage the specific file format. The DBE does not need to be loaded prior to the call of COPY TO. If it is not loaded, it is automatically loaded into memory and deleted from memory after termination of the command.

The extension of the target file is determined by the database engine. SDBFBE and DELDBE use TXT as default extension. This can be changed using the DbeInfo() function.

If no database engine is specified, the target file is opened using the current DBE. If the target file has a different file format, a corresponding DBE must be specified which can open the target file. Copying data from the work area into the target file occurs on the basis of matching field names and/or data types. 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 with matching data types are exported into the target file by COPY TO. When the source file and the target file have different file formats (meaning that they are managed by two different DBEs), data types which can be stored in both file formats must be considered. File formats and available data types are predetermined by the database engines used to manage the source file and target file. The specification of the file formats for different DBEs is found in the chapter "The Xbase++ Database Engines"in the Xbase++ documentation.

Specifying FOR, WHILE, RECORD and NEXT limits the number of records exported. These options are related to the source and are tested for records in the current work area. If the DBE managing the work area permits the logical deletion of records, records with deletion marks are only exported when SET DELETED is set to OFF. records keep their deletion flags if this is supported in the target file format.

The command COPY TO opens the target file in the EXCLUSIVE mode. If this is not successful or if the target file cannot be created, a runtime error occurs.

When using the SDF clause the SDF database engine (SDFDBE) is used. By default the SDFDBE creates a structure extended file with SDF as extension. For this reason, the following code is illegal:

USE Customer 
COPY TO Customer.sdf SDF

COPY TO

// In this example, records are copied to a 
// temporary file using COPY TO 

PROCEDURE Main 

     USE Customer NEW 
     COPY TO Temp FOR "BOSTON" $ Upper(City) 

     USE Temp 

     Browse() 

     CLOSE 
     ERASE Temp.dbf 
     ERASE Temp.dbt 

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 COPY TO Foundation