Function DbCopyExtStruct() | Xbase++

Functions and Directives Functions and Directives

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:

Field name	Field type	Field length
FIELD_NAME	Character	10
FIELD_TYPE	Character	1
FIELD_LEN	Numeric	5
FIELD_DEC	Numeric	4

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.

DbCopyExtStruct()

// 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. 

PROCEDURE Main 

   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 
   DbCloseArea() 
                                          // 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 
   DbCloseArea() 
                                          // rename files 
   FRename( "Temp.dbf", "Customer.bak" )  //  - DBF file 
   FRename( "Temp.dbt", "Customer.tbk" )  //  - Memo file 
   FErase( "Struct.dbf" )                 // delete structure 
                                          // extended file 
RETURN

Function DbCopyExtStruct() Foundation