Functions and Directives

Function DbCopyExtStruct() Foundation

Copies the field structure from a work area into a structure extended file.

DbCopyExtStruct( <cFilename> ) --> lSuccess
<cFilename> is a character string containing the name of the structure extended file where the file structure of the work area is copied.

The function DbCopyExtStruct() returns the value .T. (true) when the structure extended file <cFilename> could be created, otherwise it returns .F. (false).


The database function DbCopyExtStruct() copies the field definitions from a work area into a file. This file is called a "structure extended" file since it contains the structure description of a separate file. It uses the same file format (is managed by the same Data Base Engine) as the file whose field structure it describes.

A structure extended file has at least four fields with each record containing information about a field of another file. The predefined fields of a structure extended file are listed in the following table:

Fields of a structure extended file
Field name Field type Field length Decimal places
FIELD_NAME Character 10 0
FIELD_TYPE Character 1 0
FIELD_LEN Numeric 5 0
FIELD_DEC Numeric 4 0

The function DbCreateExtStruct() resembles the function DbStruct() which returns the field specifications in a two dimensional array. DbCreateExtStruct() writes this information into a file instead of an array. The function is also used define or change the file or field structure of database files at runtime of an Xbase++ application. A new file can be created from this information using the function DbCreateFrom().

Contrary to dBase or Clipper the length of the field FIELD_LEN is not 3 but 5. The length of a character field with more than 999 characters can be entered directly and no longer needs to be encoded using the decimal places FIELD_DEC.

// In the example, the file structure of a customer file is 
// modified using a structure extended file. A new field 
// is added for the Fax number of a customer. 


   DbUseArea( , , "Customer" )            // open file 
   DbCopyExtStruct( "Struct" )            // copy structure 

   DbUseArea( , , "Struct" )              // open structure extended 
   DbAppend()                             // file and enter new 
   FIELD->Field_Name := "FAXNo"           // field definition 
   FIELD->Field_Type := "C" 
   FIELD->Field_Len  := 15 
   FIELD->Field_Dec  :=  0 
                                          // backup copy of 
   FRename( "Customer.dbf", "Temp.dbf" )  //  - DBF file 
   Frename( "Customer.dbt", "Temp.dbt" )  //  - Memo file 

   DbCreateFrom( "Customer", "Struct" )   // create new file 
   DbUseArea( , , "Customer" )            // open file 

   DbImport( "Temp" )                     // import records 
                                          // from backup copy 
                                          // rename files 
   FRename( "Temp.dbf", "Customer.bak" )  //  - DBF file 
   FRename( "Temp.dbt", "Customer.tbk" )  //  - Memo file 
   FErase( "Struct.dbf" )                 // delete structure 
                                          // extended file 

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.