AdsDDSetDatabaseProperty

Advantage Client Engine

Sets one database property in the data dictionary.

Syntax

UNSIGNED32 AdsDDSetDatabaseProperty( ADSHANDLE hAdminConn, UNSIGNED16 usPropertyID,

VOID *pvProperty, UNSIGNED16 usPropertyLen );

Parameters

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.

Special Return Codes

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.

Remarks

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.

Example

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 );

See Also

AdsDDCreate

AdsConnect60

AdsDDGetDatabaseProperty

AdsCreateTable

AdsCreateIndex

AdsDDCreateUser

AdsDDDeleteUser

AdsDDCreateUserGroup

AdsDDDeleteUserGroup

AdsDDAddUserToGroup

AdsDDRemoveUserFromGroup

AdsDDGrantPermission

AdsDDRevokePermission

sp_ModifyDatabase