Advantage Client Engine
Retrieves a property of a field of a database table from the data dictionary.
UNSIGNED32 AdsDDGetFieldProperty( ADSHANDLE hDBConn,
UNSIGNED8 *pucTableName,
UNSIGNED8 *pucFieldName,
UNSIGNED16 usPropertyID,
VOID *pvProperty,
UNSIGNED16 *pusPropertyLen );
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. |
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. |
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. |
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 );
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 );