Function DbCreateFrom() | Xbase++

Functions and Directives Functions and Directives

Creates and opens a new file from a structure extended file.

DbCreateFrom( <cNewFilename>, ;
             [<cNewDbeName>], ;
              <cStructFile>, ;
             [<cStructDbeName>], ;
             [<lNewArea>], ;
             [<cAlias>] ) --> NIL

<cNewFilename> is a character string containing the name of the file to be created. When the file name is specified without a file extension, the default extension predetermined by the current database engine (DBE) is used. The default file extension of the DBFDBE is ".DBF".

The optional argument <cNewDbeName> specifies the database engine used to manage the new file. <cNewDbeName> is a character string containing the name of a database engine. By default, the file <cNewFilename> is managed by the database engine set with DbeSetDefault().

<cStructFile> is a character string containing the name of the structure extended file containing the field definitions for the file <cNewFilename>.

The optional argument <cStructDbeName> specifies the database engine used to manage the file containing the structure data. <cStructDbeName> is a character string containing the name of a database engine. By default, the file <cStructFilename> is managed by the database engine set with DbeSetDefault().

<lNewArea> is a logical expression specifying whether a new work area is selected before the new file is opened. Including <lNewArea> is optional, the default value is .F. (false). When <lNewArea> has the value .T. (true), the new file is opened in a free work area. Otherwise all open files in the current work area are closed and the file <cNewFilename> is opened there.

The optional argument <cAlias> specifies the alias name for the work area where the new file is opened. If included, it should be a character value. When <cAlias> is not included, the alias name is created from the file name <cNewFilename>.

The return value of DbCreateFrom() is always NIL.

The database function DbCreateFrom() reads the field definitions for the new file from the structure extended file <cStructFile> and creates a new database named <cNewFilename> from it. The created file is opened after the operation is completed. If the value .T. (true) is specified for <lNewArea>, the file is opened in a free work area.

A structure extended file has at least four fields. Each record contains information about a field. The following table lists the fields which must be included in a structure extended file:

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

If additional fields are present in the structure extended file, they are ignored by DbCreateFrom().

A file can also be created using the function DbCreate() and field definitions contained in a two dimensional array.

Contrary to dBase or CA 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.

Changes file structure using DbCreateFrom()


// In this example, modifying the structure of a file is 
// demonstrated. A new field is added to an address file. The 
// structure of the address file is copied into a structure 
// extended file "Struct". A new record is appended to the file 
// "Struct" and the file "Temp" is created from it. All data 
// records from the source file "Address" are copied into the 
// file "Temp". The source file is renamed so that a backup copy 
// exists and the file "Temp" is renamed "Address". 

PROCEDURE Main 

   DbUseArea( .T.,,"Address" ) 
   DbCopyExtStruct( "Struct" )      // create and open 
                                    // structure extended 
   DbUseArea( ,,"Struct" )          // file 
   DbAppend()                       // add new record 

   FIELD->FIELD_NAME := "FAXNO"     // new field definition 
   FIELD->FIELD_TYPE := "C" 
   FIELD->FIELD_LEN  := 15 
   FIELD->FIELD_DEC  := 0 

   DbCloseArea() 
   DbCreateFrom( "Temp", "Struct" ) // create temporary file 
   DbImport( "Address" )            // import records 
   DbCloseArea()                    // from previous file 

                                    // rename files 
   FRename( "Address.dbf", "Address.bak" ) 
   FRename( "Address.dbt", "Address.tbk" ) 
                                    // rename temporary file 
   FRename( "Temp.dbf", "Address.dbf" ) 
   FRename( "Temp.dbt", "Address.dbt" ) 
   FErase( "Struct.dbf" )           // delete extended file 
RETURN

Defines the structure for a DBF file in an ASCII file


// The file shows how an ASCII file in delimited format 
// can contain the structure definition of a database file. 
// The ASCII file is opened using the DEL database engine. 
// The DELDBE must be set to multi field mode. 
// The DBF file TEST.DBF is created using the information 
// from the ASCII file STRUCT.TXT. 

/* ASCII file STRUCT.TXT in delimited format (Multi-Field) 

FIELD_NAME,FIELD_TYPE,FIELD_LEN,FIELD_DEC 
"CHAR","C",10,0 
"NUM","N",6,2 
"LOGICAL","L",1,0 
"DATUM","D",8,0 
"MEMO","M",10,0 

*/ 

#include "Deldbe.ch" 

PROCEDURE Main 

   DbeLoad( "DELDBE" )              // load DELDBE and 
   DbeSetDefault( "DELDBE" )        // set Multi-Field mode 
   DbeInfo( COMPONENT_DATA, DELDBE_MODE, DELDBE_MULTIFIELD ) 

   DbeSetDefault( "DBFNTX" )        // create database file 
                                    // from TXT file 
   DbCreateFrom( "Test.dbf"  , "DBFNTX", ; 
                 "Struct.txt", "DELDBE", ; 
                 .T. ) 
   ? Alias()                        // result: TEST 
   ? Fieldname(1)                   // result: CHAR 

   WAIT 
   Browse() 
   CLOSE ALL 
RETURN

Function DbCreateFrom() Foundation