AdsDDGetFieldProperty

Advantage Client Engine

Retrieves a property of a field of a database table from the data dictionary.

Syntax

UNSIGNED32 AdsDDGetFieldProperty( ADSHANDLE hDBConn,

UNSIGNED8 *pucTableName,

UNSIGNED8 *pucFieldName,

UNSIGNED16 usPropertyID,

VOID *pvProperty,

UNSIGNED16 *pusPropertyLen );

Parameters

hDBConn (I)

Handle of a database connection.

pucTableName (I)

Name of the table in the database with the specified field.

pucFieldName (I)

Name of the field in the table with the specified property.

usPropertyID (I)

Index of the field 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 copied into the buffer.

Special Return Codes

AE_INVALID_PROPERTY_ID

Either the value supplied in usPropertyID is not a valid field 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

AdsDDGetFieldProperty retrieves one field property of the specified 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 field description in pvProperty.

ADS_DD_USER_DEFINED_PROP

The function returns the user defined field property in pvProperty.

ADS_DD_FIELD_DEFAULT_VALUE

The function returns the default field value that will be set when a new record is added into the table. The default field value is returned as a NULL terminated string in the pvProperty. If no default field value is defined for the specified field, 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.

ADS_DD_FIELD_CAN_NULL

The function returns a flag that indicates whether a NULL value is allowed for the specified field in the table. The flag is returned as a 2-byte (UNSIGNED16) number in pvProperty. The number is non-zero if a NULL value is allowed. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information.

ADS_DD_FIELD_MIN_VALUE

The function returns the minimum allowed value of the specified field in the table. The minimum value is returned as a NULL terminated expression in pvProperty. If there is no minimum required value for the specified field, 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.

ADS_DD_FIELD_MAX_VALUE

The function returns the maximum allowed valued of the specified field in the table. The maximum value is returned as a NULL terminated expression in pvProperty. If the field is not limited by a maximum value, 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.

ADS_DD_FIELD_VALIDATION_MSG

The function returns the error message that will be returned if a new field value or a modified field value failed to meet the constraints of the field. The constraints of the field include whether the field can have a NULL value, the required minimum value of the field, and the maximum allowed value of the field. This property can only be retrieved by users with administrative permissions. See Advantage Data Dictionary User Permissions for more information.

ADS_DD_FIELD_LENGTH

The function returns in pvProperty a 2 byte (UNSIGNED16) integer that is the length of the specified field.

ADS_DD_FIELD_TYPE

The function returns in pvProperty a 2 byte (UNSIGNED16) integer that is the data type of the specified field. See AdsGetFieldType for information of Advantage field types.

ADS_DD_FIELD_DECIMAL

The function returns in pvProperty a 2 byte (UNSIGNED16) integer that is the number of decimals the specified field.

Example 1

After making a connection to the database, find out whether the "Company Name" field in the "Customer Information" table can have a NULL value.

AdsConnect60( "n:\\MyData\\myData.ADD", ADS_REMOTE_SERVER, "ADSSYS", NULL, ADS_DEFAULT, &hDD );

usBufferSize = (UNSIGNED16)sizeof( usFieldCanNull );

AdsDDGetFieldProperty( hDD, "Customer Information", "Company Name", ADS_DD_FIELD_CAN_NULL,

&usFieldCanNull, &usBuffSize ) ;

AdsDisconnect( hDD );

Example 2

After making a database connection as an anonymous user, retrieve the default field value of the "Zip Code" field in the "Customer Information" table.

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

&hConn ));

usBufferSize = (UNSIGNED16)sizeof( acDefaultZipCode );

AdsDDGetFieldProperty( hConn, "Customer Information", "Zip Code", ADS_DD_FIELD_DEFAULT_VALUE,

acDefaultZipCode, &usBuffSize ) ;

AdsDisconnect( hConn );

See Also

AdsDDSetFieldProperty

AdsDDSetTableProperty

AdsDDGetTableProperty

AdsConnect60

system.columns