DBCREATE()
 Create a database file from a database structure array
------------------------------------------------------------------------------
 Syntax

     DBCREATE(<cDatabase>, <aStruct>
        [<cDriver>]) --> NIL

 Arguments

     <cDatabase> is the name of the new database file, with an optional
     drive and directory, specified as a character string.  If specified
     without an extension, .dbf is assumed.

     <aStruct> is an array that contains the structure of <cDatabase> as
     a series of subarrays, one per field.  Each subarray contains the
     definition of each field's attributes and has the following structure:

     Field Definition Subarray
     ------------------------------------------------------------------------
     Position     Metasymbol     Dbstruct.ch
     ------------------------------------------------------------------------
     1            cName          DBS_NAME
     2            cType          DBS_TYPE
     3            nLength        DBS_LEN
     4            nDecimals      DBS_DEC
     ------------------------------------------------------------------------

     <cDriver> specifies the replaceable database driver (RDD) to use to
     process the current work area.  <cDriver> is the name of the RDD
     specified as a character expression.  If you specify <cDriver> as a
     literal value, you must enclose it in quotes.

 Returns

     DBCREATE() always returns NIL.

 Description

     DBCREATE() is a database function that creates a database file from an
     array containing the structure of the file.  You may create the array
     programmatically or by using DBSTRUCT().  DBCREATE() is similar to the
     CREATE FROM command which creates a new database file structure from a
     structure extended file.  Use CREATE or COPY STRUCTURE EXTENDED commands
     to create a structure extended file.

     Before using DBCREATE(), you must first create the <aStruct> array and
     fill it with the field definition arrays according to the structure in
     Field Definition Subarray table (above).  There are some specific rules
     for creating a field definition array, including:

     .  Specify all field attributes with a value of the proper data
        type for the attribute.  The decimals attribute must be specified--
        even for non-numeric fields.  If the field does not have a decimals
        attribute, specify zero.

     .  Specify the type attribute using the first letter of the data
        type as a minimum.  Use longer and more descriptive terms for
        readability.  For example, both "C" and "Character" can be specified
        as the type attribute for character fields.

     .  In Clipper, character fields contain up to 64,000
        characters.  Unlike the CREATE FROM command, DBCREATE() does not use
        the decimals attribute to specify the high-order part of the field
        length.  Specify the field length directly, regardless of its
        magnitude.

     To make references to the various elements of the field definition
     subarray more readable, the header file called Dbstruct.ch is supplied.
     It contains the #defines to assign a name to the array position for each
     field attribute.  It is located in \CLIP53\INCLUDE.

 Notes

     .  Duplicate field names: DBCREATE() does not check for duplicate
        field names.  Therefore, be careful not to use the same field name
        twice.

     .  EG_ARG error: DBCREATE() generates an EG_ARG error if the
        filename is NIL.

 Examples

     .  This example creates an empty array and then adds field
        definition subarrays using the AADD() function before creating
        People.dbf.  You might use this technique to add field definitions to
        your structure array dynamically:

        aDbf := {}
        AADD(aDbf, { "Name", "C", 25, 0 })
        AADD(aDbf, { "Address", "C", 1024, 0 })
        AADD(aDbf, { "Phone", "N", 13, 0 })
        //
        DBCREATE("People", aDbf)

     .  This example performs the same types of actions but declares
        the structure array as a two-dimensional array, and then uses
        subscript addressing to specify the field definitions.  It will be
        created using the DBFMDX RDD:

        #include "Dbstruct.ch"
        //
        LOCAL aDbf[1][4]
        aDbf[1][ DBS_NAME ] := "Name"
        aDbf[1][ DBS_TYPE ] := "Character"
        aDbf[1][ DBS_LEN ]  := 25
        aDbf[1][ DBS_DEC ]  := 0
        //
        DBCREATE("Name", aDbf, "DBFMDX")

 Files   Library is CLIPPER.LIB, header file is Dbstruct.ch.

See Also: AFIELDS()* COPY STRU EXTE CREATE FROM DBSTRUCT()