PvCreateDatabase()

Creates a database by adding an entry to dbnames.cfg file. This entry is later used to create DSNs.

Header file: CATALOG.HRequires: W3DBAV75.DLL or higher version

Syntax

BTI_SINT PvCreateDatabase( 
	BTI_LONG           hConnection, 
	BTI_CHAR_PTR       dbName, 
	BTI_CHAR_PTR       dictPath, 
	BTI_CHAR_PTR       dataPath, 
	BTI_ULONG          dbFlags);

Arguments


In	hConnection	Connection handle that identifies the server. Connection handles are obtained with the PvConnectServer() function.
In	dbName	Name of the database.
In	dictPath	Dictionary path.
In	dataPath	Data path. Pass an empty string to use the default data path (that is, the same as the dictionary path) If you want to create a database that consists of transactional interface data files located in multiple paths, specify this parameter as a semicolon (;) delimited list. For example: `C:\data\path1;C:\data\path2`
In	dbFlags	Database flags, which can be a combination of the P_DBFLAG_ constants. P_DBFLAG_RI (enforce integrity constraints, including referential integrity and triggers) P_DBFLAG_BOUND (create DDF files and stamp the database name on the dictionary files so only that database can use them. If the database is not bound, then several databases can use the same dictionary file set.) If trying to create a bound database and you want to bind to DDF files that already exist, specify both P_DBFLAG_CREATE_DDF and P_DBFLAG_BOUND. P_DBFLAG_CREATE_DDF (create DDF files. The directory specified for dictPath has to exist.) P_DBFLAG_DBSEC_AUTHENTICATION (use database security authentication, Mixed security policy. See Btrieve Security Policy .) P_DBFLAG_DBSEC_AUTHORIZATION (use database security authorization, Database security policy. See Btrieve Security Policy .) P_DBFLAG_LONGMETADATA (use V2 metadata. See Metadata Version .)

Return Values


P_OK	The operation was successful.
P_E_INVALID_HANDLE	Invalid connection handle.
P_E_NULL_PTR	Call with NULL pointer
P_E_ACCESS_RIGHT	Insufficient access right for the operation
P_E_DICTIONARY_ALREADY_EXISTS	Cannot create dictionary because it already exists.
P_E_SHARED_DDF_EXIST	The dictionary path is being used by another database.
P_E_DUPLICATE_NAME	Named database already exists on the server.
P_E_FAIL	Failed for other reasons.

Remarks

The following preconditions must be met:

DTI session started by calling PvStart().

Connection established by PvConnectServer() or if you are performing the operation on a local machine, P_LOCAL_DB_CONNECTION may be used as the connection handle.

Btrieve Security Policy

The following table indicates how to specify a security model in a new database, or to interpret the security model of an existing database. Using any other combination of flags for security will result in status code 7024.


This Flag Combination	Represents this Security Model
No flags	Classic
P_DBFLAG_DBSEC_AUTHENTICATION	Mixed
P_DBFLAG_DBSEC_AUTHENTICATION P_DBFLAG_DBSEC_AUTHORIZATION	Database

Metadata Version

If you specify P_DBFLAG_LONGMETADATA, the database property in dbnames.cfg is set to V2 metadata. If you specify P_DBFLAG_LONGMETADATA and P_DBFLAG_CREATE_DDF, the DDFs created are also V2 metadata.

The result of DDF creation varies depending on the DDF versions that already exist in the dictionary location.


Dictionary Location Contains	Result of DDF Creation
No DDFs	New DDFs added to dictionary location
DDFs of other metadata version	New DDFs added to group of existing DDFs
DDFs of same metadata version	New DDFs overwrite existing DDFs. Information in old DDFs is lost.

For example, suppose that your dictionary location contains V1 metadata DDFs and you create V2 metadata DDFs. The dictionary location will then contain a combination of V1 metadata DDFs and V2 metadata DDFs. A particular database can use one set of DDFs or the other, but not both concurrently.

Example

The following example creates a database and DDFs that uses V2 metadata.

BTI_LONG connectionHandle = P_LOCAL_DB_CONNECTION; 
BTI_CHAR_PTR dataPath = "c:\\data\\gallery"; 
BTI_CHAR_PTR dictPath = "c:\\data\\gallery"; 
BTI_CHAR_PTR databaseName = "Gallery"; 
BTI_SINT status = 0; 
BTI_CHAR_PTR server = "MyServer"; 
BTI_CHAR_PTR user = "Administrator"; 
BTI_CHAR_PTR pwd = "Admin"; 
//only need to connect to server if it is remote 
//otherwise can pass P_LOCAL_DB_CONNECTION for the 
handle 
status = PvCreateDatabase( 
connectionHandle, 
databaseName, 
dictPath, 
dataPath, 
P_DBFLAG_CREATE_DDF, 
P_DBFLAG_LONGMETADATA);