xHarbour Reference Documentation > Function Reference

DbCreate()

Creates an empty database from a structure definition array.

Syntax

DbCreate( <cDatabase> , ;
          <aStructure>, ;
         [<cDriver>]  , ;
         [<lNewArea>] , ;
         [<cAlias>]     ) --> NIL

Arguments

<cDatabase>

This is a character expression holding the name of the database file to create. It can include path and file extension. When no path is given, the file is created in the current directory.

<aStructure>

A variable holding the reference of a two-dimensional array that has at least four columns. The first column must contain character strings holding the field names, the second column specifies the field type using single letters of C, D, L, N, M, the third column holds numeric values with the length of the fields, and the fourth column is only relevant for numeric fields. It specifies the number of decimal places that can be stored in a numeric field.

The following #define constants exist in file DBSTRUCT.CH to address each column of <aStructure>.

#define constants for the structure definition array

Constant	Value	Meaning
DBS_NAME	1	Field name
DBS_TYPE	2	Field type
DBS_LEN	3	Field length
DBS_DEC	4	Field decimals

Note:  only the first four columns of <aStructure> are used. If the array has more columns, they are ignored.

<cDriver>

The replaceable database driver to use for creating the new database file can be specified as a character string. It defaults to the return value of RddSetDefault().

<lOpenNew>

This optional parameter instructs the RDD if and how to open the database after creation. Three values are possible:

Open modes for new database files

Value	Description
NIL (*)	the database is not opened.
.F.	the database is opened in the current work area.
.T.	the database is opened in a new, unused work area.
(*) default

<cAlias>

A character expression specifying the symbolic alias name to assign to the work area where <cDatabase> is opened can be optionally passed. If not given, <cAlias> is build from the file name of <cDatabase> without extension.

Return

The return value is always NIL.

Description

This function creates the database file specified as <cDatabase> from the two-dimensional array <aStructure>. If no file extension is included with <cDatabase> the .DBF extension is assumed. The array specified with <aStructure> must contan at least four columns as outlined above.

The DbCreate( ) function does not use the decimal field to calculate the length of a character field that can store than 256 characters. Values of up to the maximum length of a character field, which is 65,519 bytes, can be assigned directly to the DBS_LEN column of <aStructure>.

The <cDriver> parameter specifies the name of the Replaceable Database Driver to use for database creation. If not specified, the return value of RddSetDefault() is used.

The <lOpenNew> parameter specifies if the already created database is to be opened, and where. If NIL, the file is not opened. If .T. (true), it is opened in a new work area, and if .F. (false) it is opened in the current work area, closing any file already occupying that area.

The <cAlias> parameter specifies the alias name for the newly opened database.

Info

See also:	AFields(), COPY STRUCTURE EXTENDED, CREATE, CREATE FROM, DbStruct()
Category:	Database functions
Header:	Dbstruct.ch
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example shows how to create a new database from a
// structure definition array using the DBFCDX driver.

   REQUEST DBFCDX

   PROCEDURE Main()
      LOCAL aStruct := { ;
               { "CHARACTER", "C", 25, 0 }, ;
               { "NUMERIC"  , "N",  8, 0 }, ;
               { "DOUBLE"   , "N",  8, 2 }, ;
               { "DATE"     , "D",  8, 0 }, ;
               { "LOGICAL"  , "L",  1, 0 }, ;
               { "MEMO1"    , "M", 10, 0 }, ;
               { "MEMO2"    , "M", 10, 0 }  ;
            }

      DbCreate( "testdbf", aStruct, "DBFCDX", .T., "MYALIAS" )

      Browse()
   RETURN