Function DbExport() | Xbase++

Exports data from a work area into a new file.

DbExport( <cFilename>, ;
         [<aFieldNames>], ;
         [<bForCondition>], ;
         [<bWhileCondition>], ;
         [<nCount>], ;
         [<xRecordID>], ;
         [<lRest>], ;
         [<cDbeName>], ;
         [<aDbeInfo>] ) --> NIL

<cFilename> is a character string containing the name of the target file into which records are exported from a work area. A new file is created. If the target file already exists, it is overwritten without warning.

<aFieldNames> := { [<cField,...>] }

<aFieldNames> contains an array with the names of the fields to copy into the new file <cFilename>. Each array element must contain a character string indicating a field name. By default, all fields in the work area are copied into the new file.

<bForCondition> is an optional code block containing a condition as a logical expression. Only those records for which <bForCondition> returns the value .T. (true) are exported.

<bWhileCondition> is an optional code block containing a condition as a logical expression. As long as this code block returns the value .T. (true), records are exported. The export operation is terminated as soon as <bWhileCondition> returns the value .F. (false).

The optional argument <nCount> specifies the number of records exported beginning with the current record.

The optional argument <xRecordID> specifies a record ID (for DBF files it is the record number). If <xRecordID> is specified, only the specified record is exported.

<lRest>

The logical value <lRest> optionally specifies whether all data records of a work area are exported (<lRest>==.F.), or only the records from the current to the last record (<lRest>==.T.). The default value is .F. (false), indicating that all records are exported.

<cDbeName> is an optional character string containing the name of a previously loaded database engine. If it is included, it specifies the database engine used to manage the new file. By default, the file <cFilename> is created using the database engine selected with DbeSetDefault().

<aDbeInfo> := { {<nDefine>,<xValue>}, ... }

<aDbeInfo> can be used to pass a two dimensional array. This array contains settings for the DATA components of the database engine which are set before the file<cFilename> is created. Each element contains a subarray of two elements. The first element of the subarray is <nDefine> and must be a #define constant from an #include file. The second element <xValue> contains the value for the setting (see DbeInfo()).

The return value of DbExport() is always NIL.

The function DbExport() exports records from a work area into a file <cFilename>. A new file is created by the call to this function, and if a file exists with this name it is overwritten. The file format of the new file can be set by specifying the database engine (DBE) <cDbeName> which is to manage the new file. This allows file formats to be converted. If the new file has a different file format, the corresponding DBE must already be loaded under the name <cDbeName>. The function DbeLoad() is used to load database engines.

The number of fields (columns) to be exported can be limited by including only the desired field names in the array <aFieldnames>. Also the number of records exported can be limited. This can be done by specifying conditions or by explicitly defining the number of records to be exported. When SET DELETED is set to ON, records with a deletion flag are not exported. If this switch is set to OFF, records with a deletion flag are also exported. If the DBE for the export file supports deletion flag, the exported records maintain the deletion flag.

If the file into which data is exported should have a different format, a corresponding database engine (DBE) must be loaded and the name of the applicable DBE must be specified as <cDbeName>. When the DBE allows it, the export format can be modified in certain ways by the configuration of the DBE. This applies to the DBEs SDFDBE (System Data Format) and DELDBE (Delimited Format). In addition, the parameter <aDbeInfo> can be used to pass a two dimensional array containing information for the configuration. Only the DATA components of a DBE can be configured. The values from <aDbeInfo> are passed to the function DbeInfo(). After the data is exported, the configuration of the DBE is reset to what was current before the call to DbExport().

Exporting data


// In the example, address data is exported from a customer file 
// to a temporary file. Data is exported only for customers 
// whose residence is in "Chicago" 

PROCEDURE Main 

   USE Customer 

   DbExport( "Temp.dbf", ;                 // export file 
             {"LastName","FirstName", ; 
             "Street","City","State","Zip"}, ;    // fields 
             {|| "CHICAGO" $ Upper(Customer->City) } ) 
                                           // FOR condition 
   USE Temp 
   Browse() 

   CLOSE Temp 
   ERASE Temp 
RETURN

Converts file format


// In this example, data in DBF file format is exported 
// into a file having the SDF format (System Data Format). 
// The SDF format is modified, in that the characters "1" 
// and "0" can be used for logical values instead of "T" 
// and "F" (true,false) 

#include "SdfDbe.ch" 

PROCEDURE Main 

   ? DbeSetDefault()                // result: DBFNTX 

   ? DbeLoad( "SDFDBE" )            // result: .T. 
   USE Customer 

   DbExport( "Cust1.txt",,,,,,, "SDFDBE", ; 
             { {SDFDBE_LOGICAL_TOKEN, "10"} } ) 

   CLOSE Customer 

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.

Function DbExport() Foundation