Command COPY TO Foundation
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>] ]
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.
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.