Function DbImport() | Xbase++

Imports data from a file into a work area.

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

<cFilename> is a character string containing the name of the source file from which records are imported into a work area.

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

<aFieldNames> is an optional array specifying the name of fields copied from the file <cFilename>. Each array element must contain a character string containing a field name. By default all fields are imported from the file into the work area.

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

<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 imported. The import operation is terminated as soon as <bWhileCondition> returns the value .F. (false).

<nCount> optionally determines the number of records imported beginning with the current record in <cFilename>. By default the current record initially is the first record. It can be changed by specifying <xRecordID>.

<xRecordID> is a record ID (for DBF files it is the record number) which can be optionally specified. If it is included, the data import begins with the specified record of <cFileName>. If the value .T. (true) was specified for <lRest>, all subsequent data records are imported. Otherwise, only the record <xRecordID>is imported.

<lRest>

The optional logical value <lRest> specifies whether all data records from the file <cFilename> are imported (<lRest>==.F.), or only the records from the current to the last record (<lRest>==.T.). The default value is .F. (false), meaning all data records are imported. Specifying <xRecordID> controls which record in <cFilename> is the first record imported. If <xRecordID> is specified and <lRest> has the value .T. (true), all subsequent records are also imported. If <xRecordID> is specified but <lRest> has the value .F. (false), only the data record <xRecordID> is imported.

<cDbeName> is a character string containing the name of a previously loaded database engine. This optional argument specifies the database engine used to manage the file <cFilename>. By default the file <cFilename> is opened using the database engine selected by DbeSetDefault().

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

<aDbeInfo> is an optional two dimensional array. It contains database engine settings set before the opening of the file <cFilename>. Each element contains a subarray of two elements. The first element of the subarray is <nDefine> and must be a #define constant. The second element <xValue> contains the value for the setting (see DbeInfo()).

The return value of DbImport() is always NIL.

The function DbImport() imports records from a file <cFilename> into a work area. If the function is called without the alias operator, data is imported into the current work area. The file format of the source file and the database engine (DBE) used to manage it can be specified by the argument <cDbeName>. This allows file formats to be converted. If the source file <cFilename> has a file format different than the file open in the work area, the corresponding DBE must already be loaded under the name <cDbeName>. Loading database engines is done using the function DbeLoad().

The number of fields (columns) to be imported can be limited by specifying field names in the array <aFieldnames>. The number of records to be imported can also be limited. This is done by specifying conditions or by explicitly specifying the number of data records to import. When SET DELETED is set to ON, records with a deletion flag are not imported. If this switch is set to OFF, data records are imported from the source file even if they have a deletion flag.

If the file containing the data to import has a different format, the corresponding database engine (DBE) must be loaded and the name <cDbeName> of the this DBE must be specified. When the DBE allows it, the import format can be modified in certain ways by the configuration of the DBE. That applies to the DBEs SDFDBE (System Data Format) and DELDBE (Delimited Format). A two dimensional array containing information for the configuration can be passed as the parameter <aDbeInfo>. Only the DATA components of a DBE can be configured. The values from <aDbeInfo> are passed to the function DbeInfo(). After the data imported, the configuration of the DBE is reset to what it was prior to the call to DbImport().

If data is imported from a file in SDF format which was not created by an Xbase++ application, a structure file must be created if necessary (see the specification of the SDF database engine in the chapter "The Xbase++ Database Engine"in the Xbase++ documentation)

Import data into a work area


// In the example, data from an ASCII file in the SDF 
// format is appended to data for an item file in the 
// DBF format. Numeric values in the ASCII file have a 
// decimal comma instead of a decimal point. In conjunction 
// with the program example the structure file for the 
// import file is specified. 

PROCEDURE Test 

   ? DbeSetDefault()                           // result: DBFNTX 

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

   USE Item 

   DbImport( "NewItem.txt", ;                  // import file 
            {"ItemNo","Item","Price"},,,,,,;   // fields 
            "SDFDBE", ;                        // DBE 
            { {SDFDBE_DECIMAL_TOKEN, ","} } )  // decimal comma not 
                                               // decimal point 
   CLOSE Item 
RETURN 

// Example for a structure file for the definition of fields in 
// SDF format (the file name is NEWITEM.SDF) 

/* 
[INFO] 
file=NEWITEM.TXT 
fieldcount=3 
recsize=34 
reccount=10 
[FIELDS] 
ITEMNO=C,6,0 
ITEM=C,20,0 
PRICE=N,8,2 
[END] 
*/

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 DbImport() Foundation