AdsDDGetTableProperty

Advantage Client Engine

  This is the first topic This is the last topic  

Retrieves one table property from the data dictionary into the supplied buffer.

Syntax

UNSIGNED32 AdsDDGetTableProperty( ADSHANDLE hDBConn,

UNSIGNED8 *pucTableName,

UNSIGNED16 usPropertyID,

VOID *pvProperty,

UNSIGNED16 *pusPropertyLen );

Parameters

hDBConn (I)

Handle of a database connection.

pucTableName (I)

Name of the table in the database to retrieve the property.

usPropertyID (I)

Index of the table property to retrieve. See Remarks for allowed values.

pvProperty (O)

Pointer to the buffer where the property is to be copied into.

*pusPropertyLen (I/O)

On input, specifies the size of the buffer pointed by pvProperty. On output, returns the length of property stored in the buffer.

Special Return Codes

AE_INVALID_PROPERTY_ID

Either the value supplied in usPropertyID is not a valid table property, or the specified property cannot be retrieved.

AE_INSUFFICIENT_BUFFER

The size of the property to be copied into pvProperty is larger than the buffer size specified by *pusPropertyLen. The required buffer length is returned in *pusPropertyLen when this error occurs.

AE_PROPERTY_NOT_SET

The requested property is not set in the data dictionary. No data is returned in pvProperty and *pusPropertyLen.

Remarks

AdsDDGetTableProperty retrieves one table property of the specified database table from the data dictionary. The following are the valid values of usPropertyID and the expected return value in pvProperty and *pusPropertyLen.

usPropertyID

Description

ADS_DD_COMMENT

The function returns the table description in pvProperty.

ADS_DD_USER_DEFINED_PROP

The function returns the user defined table property in pvProperty.

ADS_DD_TABLE_VALIDATION_EXPR

The function returns the table’s record level validation expression. The validation expression is returned as a NULL terminated string. If no record level validation expression is defined in the data dictionary, the function returns an AE_PROPERTY_NOT_SET error. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information.  Returns data as ANSI encoded text.

ADS_DD_TABLE_VALIDATION_EXPR_W

The function returns the table’s record level validation expression. The validation expression is returned as a NULL terminated string. If no record level validation expression is defined in the data dictionary, the function returns an AE_PROPERTY_NOT_SET error. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information.  Returns data as UTF-16 encoded text.

ADS_DD_TABLE_VALIDATION_MSG

The function returns the error message that will be returned when a record in the table is being modified in such a manner that the record will fail to pass the record level constraint. It is returned as a NULL terminated string. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information.

ADS_DD_TABLE_PRIMARY_KEY

The function returns the index name of the table’s primary key. The index name is returned as a NULL terminated string. The maximum length of the index name is ADS_MAX_OBJECT_NAME_LEN. If no primary key is defined for the table, the functions return an AE_PROPERTY_NOT_SET error.

ADS_DD_TABLE_TYPE

The function returns the type of the base table. The table type is returned as a 2 byte (UNSIGNED16) number with the following possible values: ADS_NTX, ADS_CDX, ADS_VFP, and ADS_ADT.

ADS_DD_TABLE_FIELD_COUNT

The function returns the number of fields or columns in the table. The field count is returned as a 2 byte (UNSIGNED16) number.

ADS_DD_TABLE_ENCRYPTION

The function returns the encryption state of the database table in pvProperty. The value returned in pvProperty is a 2-byte value. It is non-zero if the database table is encrypted.

ADS_DD_TABLE_DEFAULT_INDEX

Gets the default index to be used by the table. For optimized performance the default index is initially not set, indicating no default index should be used. The Advantage Client Engine does not use the default index directly. Client front-ends can call this API to retrieve the index name, and then take the appropriate actions to implement default index functionality.

ADS_DD_TABLE_IS_RI_PARENT

 

The function returns a boolean value indicating if the table in question is a parent in a referential integrity rule. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information.

ADS_DD_TABLE_AUTO_CREATE

Returns in pvProperty a 2-byte integer (UNSIGNED16) indicating whether this particular table and any indexes associated with it are automatically created should the files be missing when an open occurs. The returned value is False if files are not to be re-created and True if they should be. The default for this property is False. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information.

ADS_DD_TABLE_PERMISSION_LEVEL

Returns in pvProperty a 2-byte integer (UNSIGNED16) indicating the table’s access permission level. The table permission level determines how column permissions are enforced for the table. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information. The table permission level can be one of the following three values:

ADS_DD_TABLE_PERMISSION_LEVEL_1: If the user does not have read permission to a column in the table, reading the value of the column by the user will not cause an error. Instead, NULL value is always returned on the column that the user does not have read permission. Filtering the table (using scope, filter, SQL WHERE clause) on the column that the user does not have permission is allowed. This level is most compatible with other shared file access databases such as Paradox.

ADS_DD_TABLE_PERMISSION_LEVEL_2: This is the default table permission level in Advantage. Reading of a column in the table that the user does not have read permission does not cause an error condition. Instead, NULL value is always returned on the column that user does not have read permission. However, filtering the table (using scope, filter, SQL WHERE clause) on the column that the user does not have permission will return an error.

ADS_DD_TABLE_PERMISSION_LEVEL_3: This is the most restricted table permission level. Direct access to the table is not allowed. The table can only be access using SQL statements. If the SQL statement contains a column that the user does not have the proper access to, an error will be returned. In other words, the user must have read permission to all columns in the SELECT, WHERE, HAVING, and ORDER BY clause of the SQL statement. This level is most compatible with other client server database such as MS SQL Server.

ADS_DD_TABLE_MEMO_BLOCK_SIZE

Returns in pvProperty a 2-byte integer (UNSIGNED16) containing the value auto-creation functionality will use for the memo block size of the memo file should this table need to be re-created. AE_PROPERTY_NOT_SET will be returned if the property has not been set, in which case auto-creation will use the default memo block based on the table type. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information.

ADS_DD_TABLE_CACHING   

Returns in pvProperty a 2-byte integer (UNSIGNED16) containing the caching mode of the table.  Database ALTER permissions are required to read this property.  By default, the table caching mode is ADS_TABLE_CACHE_NONE.  If read caching is enabled for the specified table, ADS_TABLE_CACHE_READS will be returned.  If write caching is enabled, ADS_TABLE_CACHE_WRITES will be returned.  Please read Table Data Caching for more information.

ADS_DD_TABLE_TXN_FREE

Returns in pvProperty a 2-byte integer (UNSIGNED16) indicating whether this particular table is treated as a transaction-free table or not.  The returned value is true if the updates to this table performed during a transaction are excluded from the transaction, and false otherwise.  The default for this property is False.

Example 1

After making a connection to the database, retrieve the number of fields in the "Customer Information" table.

AdsDDOpen( "n:\\MyData\\myData.ADD", NULL, &hDD );

usBufferSize = sizeof( usFieldCount );

AdsDDGetTableProperty( hDD, "Customer Information", ADS_DD_TABLE_FIELD_COUNT,

&usFieldCount, &usBuffSize ) ;

AdsDDClose( hDD );

Example 2

After making a database connection as an anonymous user, retrieve the description of the "Customer Information" table.

AdsConnect60( "n:\\MyData\\MyData.ADD", ADS_REMOTE_SERVER, NULL, NULL, ADS_DEFAULT,

&hConn ));

usBufferSize = sizeof( acTableDescription );

AdsDDGetTableProperty( hConn, "Customer Information", ADS_DD_COMMENT,

acTableDescription, &usBuffSize ) ;

AdsDisconnect( hConn );

See Also

AdsDDSetTableProperty

AdsDDSetFieldProperty

AdsDDGetFieldProperty

AdsConnect60

system.tables