Advantage Client Engine
Sets one database property in the data dictionary.
UNSIGNED32 AdsDDSetDatabaseProperty( ADSHANDLE hAdminConn, UNSIGNED16 usPropertyID,
VOID *pvProperty, UNSIGNED16 usPropertyLen );
hAdminConn (I) |
Handle of a database connection. |
usPropertyID (I) |
Index of a database property to set. See below for possible values. |
pvProperty (I) |
Pointer to the property to be stored in the data dictionary. |
usPropertyLen (I) |
Length of the property pointed to by the pvProperty parameter. |
AE_INVALID_PROPERTY_ID |
Either the value supplied in usPropertyID is not a valid database property index, or the specified property cannot be modified. |
AE_NO_TABLE_ENCRYPTION_PASSWORD |
This error is returned when setting the ADS_DD_ENCRYPT_NEW_TABLE property to True and the database’s table encryption password property, ADS_DD_ENCRYPT_TABLE_PASSWORD, has not been set. |
AdsDDSetDatabaseProperty sets one database property in the data dictionary. The new property overwrites the existing property in the data dictionary. The following are the valid values of usPropertyID and the expected value in pvProperty and usPropertyLen.
ALTER DATABASE permission is required to modify any database property. See Advantage Data Dictionary User Permissions for more information.
Note This function can be called inside a transaction, but will not be part of the transaction. Any changes it makes cannot be rolled back.
UsPropertyID |
Description |
ADS_DD_COMMENT |
Changes the database description. The pvProperty is expected to be a NULL terminated string. usPropertyLen is the length of the string including the NULL terminator. |
ADS_DD_VERSION_MAJOR |
Sets the user defined major version property of the data dictionary. This property is intended for storing a value associated with the major version of the user's dictionary. The user version property is set, read, and interpreted by the application. The Advantage Database Server does not currently use it internally. This value can be used by the application developer to determine when the Advantage "database upgrade" functionality needs to be used. This allows developers to ship version "1.0" of a database defined in a data dictionary, then later ship version "1.1" of the data dictionary. The "database upgrade" functionality will be available for application developers to create and execute the code necessary to upgrade the files and/or definitions in the version "1.0" database to the version "1.1" database. The default value for this property, if it has never been set, is 0. If pvProperty is NULL, the user version property value will be removed. |
ADS_DD_VERSION_MINOR |
Sets the user defined minor version property of the data dictionary. This property is intended for storing a value associated with the minor version of the user's dictionary. The user version property is set, read, and interpreted by the application. The Advantage Database Server does not currently use it internally. This value can be used by the application developer to determine when the Advantage "database upgrade" functionality needs to be used. This allows developers to ship version "1.0" of a database defined in a data dictionary, then later ship version "1.1" of the data dictionary. The "database upgrade" functionality will be available for application developers to create and execute the code necessary to upgrade the files and/or definitions in the version "1.0" database to the version "1.1" database. The default value for this property, if it has never been set, is 0. If pvProperty is NULL, the user version property value will be removed. |
ADS_DD_USER_DEFINED_PROP |
Changes the user defined database property. If pvProperty is NULL, the user defined database property will be removed. User defined property is set, read, and interpreted by the application. It is not used by the Advantage Database Server. Example use of a user defined database property will be to store the version of the database tables. |
ADS_DD_DEFAULT_TABLE_PATH |
Changes the default path for creating new tables. If pvProperty is NULL or an empty string, new tables will be created in the same directory as the data dictionary. No verification of the validity of the path is made. If the default table path is set to an invalid path, subsequent attempts to create new tables in this data dictionary will fail. |
ADS_DD_TEMP_TABLE_PATH |
Changes the path for creating temporary tables. If pvProperty is NULL or an empty string, a temporary table will be created in the same directory as the normal tables. Advantage Database Server and Advantage Local Server create temporary tables and indexes when executing SQL statements. |
ADS_DD_ADMIN_PASSWORD |
Changes the ADSSYS password of the database. If pvProperty is NULL or an empty string, the data dictionary is re-set to not require a password for the ADSSYS user. |
ADS_DD_LOG_IN_REQUIRED |
Changes whether an anonymous user connection to the database is allowed. This property is a Boolean value. It is defaulted to False when the data dictionary is created. pvProperty is expected to be a pointer to a 2-byte (UNSIGNED16) integer. usPropertyLen is expected to be 2. If the integer pointed to by the pvProperty is zero, the property is set to False. Otherwise the property is set to True. If this property is set to False, an anonymous connection to the database with no user name and no password is allowed. Otherwise a user name and password is required to make a database connection to the data dictionary. See AdsConnect60 for more information. |
ADS_DD_VERIFY_ACCESS_RIGHTS |
This property determines whether the Advantage Database Server will enforce the user’s access rights when opening a database table or view or executing a stored procedure. This property is a Boolean value. It is defaulted to False when the data dictionary is created. pvProperty is expected to be a pointer to a 2 byte (UNSIGNED16) integer. usPropertyLen is expected to be 2. If the integer pointed to by the pvProperty is zero, the property is set to False. Otherwise the property is set to True. If this property is set to False, the Advantage database server does not verify the user’s access rights when opening a database table or view or when executing a stored procedure. The implication is that all users have full rights to all objects in the database. If this property is set to True, the user’s access rights are verified. See AdsDDGrantPermission and AdsDDRevokePermission for more information on object access rights. Note that an anonymous user does not have any rights to objects in the database. If the database is set up to verify user access rights, an anonymous user can make a connection to the database but he cannot open any table or view or execute any stored procedure. See AdsConnect60 and AdsOpenTable for more information. |
ADS_DD_ENCRYPT_TABLE_PASSWORD |
This property sets the encryption password for the database tables. Setting this property does not encrypt any table in the data dictionary. It only sets the password that all database tables in the data dictionary will be encrypted with. The pvProperty should be a pointer to a NULL terminated string. The usPropertyLen should be the length of the password including the NULL terminator. If pvProperty is NULL or a pointer to an empty string, the function will remove the database encryption password from the data dictionary and, as a side effect, sets the database property ADS_DD_ENCRYPT_NEW_TABLE to False. Setting and removing this property requires that all database tables in the data dictionary not be encrypted. If there are encrypted table(s) in the data dictionary, this function will fail with error AE_DD_REQUEST_NOT_COMPLETED. Once this property is set, individual tables in the data dictionary can be encrypted by calling AdsDDSetTableProperty and setting the table property ADS_DD_TABLE_ENCRYPTION to True. |
ADS_DD_ENCRYPT_NEW_TABLE |
This property determines whether a new table added or created in the in the data dictionary should be encrypted. This property is a Boolean value. It is defaulted to False when the data dictionary is created. pvProperty is expected to be a pointer to a 2 byte (UNSIGNED16) integer. usPropertyLen is expected to be 2. When this property is set to True, all tables added or created into the database will be automatically encrypted. Setting this property has no effect on existing tables in the database. If this property is set to False, new table added or created in the data dictionary will not be encrypted. When setting this property to True, the database property ADS_DD_ENCRYPT_TABLE_PASSWORD must be set. |
ADS_DD_ENABLE_INTERNET |
This property enables/disables the Internet access for the data dictionary. If it is disabled, no users will be allowed to connect from the Internet. pvProperty is expected to be a pointer to a 2-byte (UNSIGNED16) integer. usPropertyLen is expected to be 2. Expected values are True and False. For more information see Advantage Internet Server. |
ADS_DD_INTERNET_SECURITY_LEVEL |
This is the security level for communications between the Advantage Database Server and the clients when they are communicating over the Internet. pvProperty is expected to be a pointer to a 2-byte (UNSIGNED16) integer. usPropertyLen is expected to be 2. The values are ADS_DD_LEVEL_0, ADS_DD_LEVEL_1, ADS_DD_LEVEL_2. For more information, see Internet Security Levels. |
ADS_DD_MAX_FAILED_ATTEMPTS |
This is the maximum number of failed Internet login attempts a user can have. Once the user has reached this number, their Internet access will be shut off. pvProperty is expected to be a pointer to a 2-byte (UNSIGNED16) integer. usPropertyLen is expected to be 2. For more information on this setting, see Maximum Failed Login Attempts. |
ADS_DD_FTS_DELIMITERS |
Changes the default Full Text Search (FTS) delimiter characters for the data dictionary. When new FTS indexes are created with the default delimiters, these will be used as the defaults for the new index. The pvProperty is expected to be a NULL terminated string. usPropertyLen is the length of the string including the NULL terminator. |
ADS_DD_FTS_NOISE |
Changes the default Full Text Search (FTS) noise words for the data dictionary. When new FTS indexes are created with the default noise words, these will be used as the defaults for the new index. The pvProperty is expected to be a NULL terminated string. usPropertyLen is the length of the string including the NULL terminator. |
ADS_DD_FTS_DROP_CHARS |
Changes the default Full Text Search (FTS) drop characters for the data dictionary. When new FTS indexes are created with the default drop characters, these will be used as the defaults for the new index. The pvProperty is expected to be a NULL terminated string. usPropertyLen is the length of the string including the NULL terminator. |
ADS_DD_FTS_CONDITIONAL_CHARS |
Changes the default Full Text Search (FTS) conditional drop characters for the data dictionary. When new FTS indexes are created with the default conditional drop characters, these will be used as the defaults for the new index. The pvProperty is expected to be a NULL terminated string. usPropertyLen is the length of the string including the NULL terminator. |
ADS_DD_LOGINS_DISABLED |
Enables/disables logins to the database. Logins can be disabled in order to perform database maintenance in which you do not want new users connecting to the database. See Disabling Database Logins for more details. Only an administrative user can set this property. |
ADS_DD_LOGINS_DISABLED_ERRSTR |
Used to specify a custom error string to return when database logins are attempted and the database is currently not accepting new connections (see ADS_DD_LOGINS_DISABLED property above). Only an administrative user can set this property. |
ADS_DD_DISABLE_DLL_CACHING |
This property enables/disables the DLL caching functionality for the data dictionary. If it is disabled, DLL caching will not take place. By default it is enabled. pvProperty is expected to be a pointer to a 2-byte (UNSIGNED16) integer. usPropertyLen is expected to be 2. Expected values are True and False. For more information see DLL Caching. |
ADS_DD_ENCRYPT_INDEXES |
This property determines whether indexes on dictionary bound ADT tables should be encrypted. This property is a Boolean value. It is defaulted to False when the data dictionary is created. pvProperty is expected to be a pointer to a 2 byte (UNSIGNED16) integer. usPropertyLen is expected to be 2. When this property is set to True, all encrypted tables must be re-indexed for the property to take effect. If this property is set to False, indexes on encrypted tables will remain encrypted until the table is re-indexed. When setting this property to True, the database property ADS_DD_ENCRYPT_TABLE_PASSWORD must be set. |
ADS_DD_ENCRYPT_COMMUNICATION |
This property determines whether all communication between the Advantage Database Server and Advantage-enabled client applications is encrypted. This property is a Boolean value. It is defaulted to False when the data dictionary is created. pvProperty is expected to be a pointer to a 2 byte (UNSIGNED16) integer. usPropertyLen is expected to be 2. |
After making a connection to the database, change the description of the database. Then change the data dictionary to require a password for administrative access.
AdsConnect60( "n:\\MyData\\myData.ADD", ADS_REMOTE_SERVER, "ADSSYS", NULL, ADS_DEFAULT, &hDD );
usBufferSize = (UNSIGNED16)strlen( aucMessage ) + 1;
AdsDDSetDatabaseProperty( hDD, ADS_DD_COMMENT, aucMessage, usBufferSize ) ;
AdsDDSetDatabaseProperty( hDD, ADS_DD_ADMIN_PASSWORD,
"Secret", 7 /* length of "Secret" plus 1 */ );
AdsDisconnect( hDD );
/* This will fail because administrative password is required now. */
AdsConnect60( "n:\\MyData\\myData.ADD", ADS_REMOTE_SERVER, "ADSSYS", NULL, ADS_DEFAULT, &hDD );
/* This will succeed because correct password is given */
AdsConnect60( "n:\\MyData\\myData.ADD", ADS_REMOTE_SERVER, "ADSSYS", "Secret", ADS_DEFAULT, &hDD );