DbCreate Function |  |
Create a database file from a database structure array.
Namespace: XSharp.RT
Assembly: XSharp.RT (in XSharp.RT.dll) Version: 2.21
SyntaxFUNCTION DbCreate( cTargetFile, aStruct, cDriver, lNew, cAlias, cDelim, lOpen, acRDDs ) AS LOGIC CLIPPER
Parameters
- cTargetFile (Optional)
- Type: Usual
The name of the new database file, including an optional drive, directory, and extension. See SetDefault() and SetPath() for file searching and creation rules.
The default extension for database files is determined by the RDD .
If cTargetFile does not exist, it is created.
If it exists, this function attempts to open the file in exclusive mode and, if successful, the file is overwritten without warning or error.
If access is denied because, for example, another process is using the file, NetErr() is set to TRUE.
DBCreate() creates the specified file in ANSI or OEM character set format, based on the SetAnsi() setting. (For more information, refer to the SetAnsi() function.) - aStruct (Optional)
- Type: Usual
An array containing field descriptions in the format returned by DBStruct().
This array defines the structure for the new database file. - cDriver (Optional)
- Type: Usual
The name of the RDD that will service the work area.
If not specified, the default RDD as determined by RDDSetDefault() is used. - lNew (Optional)
- Type: Usual
TRUE opens the database file in a new work area (first available). FALSE opens it in the current work area. lNew is useful only when lOpen has a value of TRUE. The default is FALSE. - cAlias (Optional)
- Type: Usual
The alias to be associated with the work area where the file is opened. Within a single application, X# will not accept duplicate aliases. cAlias is useful only when lOpen has a value of TRUE.
The default alias is the eight-letter database file name . - cDelim (Optional)
- Type: Usual
The delimiter for fields within a delimited database file.
If you are using one of the supplied RDDs for processing .DBF files, the delimiter should be a NULL_STRING, which is the default if the
argument is omitted. - lOpen (Optional)
- Type: Usual
TRUE specifies that an existing database file be opened; FALSE specifies that that a new database file be opened.
The default is FALSE.
This can be used to open existing SDF and delimited files, which do not have a structure in the header — in which case, aStruct should be used. - acRDDs (Optional)
- Type: Usual
A one-dimensional array with the names of RDDs from which the main RDD inherits special functionality.
This allows you to use RDDs with special capabilities, like encryption or decryption, in different work areas with different database drivers.
These RDDs overlay special functions of the main RDD (specified with the cDriver argument).
If multiple RDDs (specified with this argument) implement the same function, the function associated with the last RDD in the list takes precedence.
If acRDDs is omitted, no additional RDDs are assumed.
Return Value
Type: LogicTRUE if the requested actions are successful; otherwise, FALSE.
Remarks
DBCreate() creates a database file from an array containing the structure of the file. DBCreate() is similar to the CREATE FROM command, which creates a new database file structure from 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 the table above. You can create the array programmatically or by using DBStruct().
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 0. - 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. - 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.
The decimals attribute must be specified — even for non-numeric fields.
If the field does not have a decimals attribute, specify 0. - 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. - 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.
Examples
The following example demonstrates DBCreate():
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:
This next example performs the same types of actions as the example above, but it declares the structure array as a two-dimensional array, and then uses subscript addressing to specify the field definitions.
The database file is created using the DBFMDX RDD:
X#
1USE test 2IF Used() 3 DBCreate("newdb.dbf", DBStruct(), "",; 4 TRUE,"", "", FALSE) 5ENDIF
X#
1aDBF := {} 2AAdd(aDBF, {"Name", "C", 25, 0}) 3AAdd(aDBF, {"Address", "C", 1024, 0}) 4AAdd(aDBF, {"Phone", "N", 13, 0}) 5DBCreate("people", aDBF)
The database file is created using the DBFMDX RDD:
X#
1LOCAL aDBF[1][4] 2aDBF[1][DBS_NAME] := "Name" 3aDBF[1][DBS_TYPE] := "Character" 4aDBF[1][DBS_LEN] := 25 5aDBF[1][DBS_DEC] := 0 6DBCreate("Name", aDBF, "DBFMDX")
See Also