Advantage Database Server

AdsDDCreate101

Advantage Client Engine

AdsDDCreate101

Advantage Client Engine

This is the first topic This is the last topic  

AdsDDCreate101

Advantage Client Engine

This is the first topic This is the last topic  

Creates a data dictionary using a connection string.

Syntax

UNSIGNED32 AdsDDCreate101( UNSIGNED8 *pucConnectString,

ADSHANDLE *phConnectOptions,

ADSHANDLE *phAdminConn );

Parameters

pucConnectString (I)

Connection string specifying the new data dictionary path, among other things.  See AdsConnect101 for a complete list of supported options.

phConnectOptions (O)

The handle of an in-memory table that contains the provided connection string options.  Optional, can be NULL.

phAdminConn (O)

Returns a database connection handle if the data dictionary is created successfully.

Special Return Codes

AE_NO_DRIVE_CONNECTION

An Advantage server could not be located for the indicated path.

AE_DICTIONARY_ALREADY_EXISTS

An Advantage data dictionary already exists at the indicated path.

Remarks

AdsDDCreate101 connects to the Advantage Database Server or Advantage Local Server at the supplied Data Source path and creates the Advantage Data Dictionary file. It returns a database connection if it succeeds. The returned database connection handle has the administrative access of the ADSSYS user and can be used to modify the contents of the Advantage Data Dictionary. Examples of APIs that modify the data dictionary are all AdsDDSet***** functions, AdsDDAddUserToGroup, and AdsDDDeleteIndex.

This call will use the ServerType setting specified in the connection string.  Otherwise it obeys the default server types that may have been set by the ADS.INI file or by calling AdsSetServerType.

If TRUE is specified for the EncryptDictionary connection string option, an encrypted data dictionary file is created. If the EncryptDictionary option is FALSE or not specified, the data dictionary is not encrypted. Even if the data dictionary file is not encrypted, all security related information in the data dictionary, such as user and table passwords are automatically encrypted using the encryption specified by the EncryptionType option. An encrypted data dictionary file provides extra security by because all data in the dictionary such as table and user names will be encrypted. However, there may be some performance degradation when using an encrypted data dictionary file. If security of the information in the data dictionary is a high priority, it is recommended that the data dictionary file be placed in a location that is only accessible by authorized personnel.

In addition, using AES encryption provides greatly increased security for the dictionary content because it is encrypted with an externally-provided dictionary password (DDPassword connection option). When creating a dictionary with AES encryption, the DDPassword is required. The dictionary password is unrelated to the ADSSYS administrative user password. User passwords are used for authentication to the dictionary and to assign rights. The dictionary password is used for table and data dictionary file encryption. It must be provided to the Advantage Database Server the first time it opens the dictionary. It can be provided via the connection string in calls to AdsConnect101 but should probably be provided at the server in a production environment via the SE_Passwords configuration parameter.

If the Password connection string option is not specified, the data dictionary is created with no administrative password.  Otherwise, the password specified by the Password option will be the ADSSYS administrative user password for the new data dictionary.  The administrative password can be defined later by calling the function AdsDDSetDatabaseProperty. See AdsConnect101 for information about data dictionary administrative passwords.

If successful, the new data dictionary is created with no user access control. User authentication and access control can be added by defining users in the data dictionary and setting the database properties, ADS_DD_LOG_IN_REQUIRED and ADS_DD_VERIFY_ACCESS_RIGHTS, to appropriate values. See AdsDDAddUserToGroup, AdsDDSetDatabaseProperty, AdsDDGrantPermission, Advantage Data Dictionary User Permissions, and AdsConnect60 for information on how user access control works with data dictionary. A data dictionary with no administrative password or user access control is useful if the security of the data is not of concern, but other advanced database functionality such as referential integrity and using NTX files with the Advantage SQL engine are required.

Note AdsDDCreate101 can be called inside a transaction, but will not be part of the transaction. Any changes it makes cannot be rolled back.

Example

Create a data dictionary and encrypt the data dictionary data files. Specifying EncryptionType=AES256 means that any table in the dictionary that is encrypted will use 256-bit AES encryption. The DDPassword option is required when using AES encryption because it is used to generate the key data for encrypting tables and the dictionary itself.After a dictionary has been created with AES encryption and is being used in a production environment, it may make sense to specify the dictionary password via the SE_Passwords configuration option at the server so that it does not have to be provided by the application or user.

AdsDDCreate101( "Data Source=n:\\MyData\\myData.ADD; Password=admin1; DDPassword=ddpass; Description=This is the database of my tables and indexes.; EncryptDictionary=TRUE;EncryptionType=AES256; ", &hOptions, &hDD );

 

See Also

AdsConnect101

AdsDDSetDatabaseProperty

AdsDDGetDatabaseProperty

AdsDDAddTable

AdsDDAddIndexFile

AdsDDCreateUser

AdsDDDeleteUser

AdsDDCreateUserGroup

AdsDDDeleteUserGroup

AdsDDAddUserToGroup

AdsDDRemoveUserFromGroup

AdsDDGrantPermission

AdsDDRevokePermission