Distributed Tuning Interface Reference : PvCreateDatabase()
 
PvCreateDatabase()
Creates a database by adding an entry to dbnames.cfg file. This entry is later used to create DSNs.
Header File: catalog.h (See also Header Files)
Function First Available In Library: w3dbav75.dll (Windows), libpsqldti.so (Linux), libpsqldti.dylib (macOS) (See also Link Libraries)
Syntax
BTI_API 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 MicroKernel Engine 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);
See Also
PvStart()
PvConnectServer()
PvGetDbFlags()
PvModifyDatabase()
PvDropDatabase()
PvDisconnect()
PvStop()