c-treeDB API API for C

ctdbSetFieldDefaultValue

Sets the field default value.

DECLARATION

CTDBRET ctdbSetFieldDefaultValue(CTHANDLE Handle, pTEXT value, VRLEN length)

DESCRIPTION

The default value of a field is used during an alter table operation when a full table rebuild is performed. During a full alter table rebuild, and after the old record buffer data is moved to the new record buffer, the new record buffer is scanned and if a NULL field is found and that NULL field has a default value, the default value is copied to the field buffer.

The field default value is kept as a string representation of the data. It is recommended that numeric data should be converted to string using one of the rich set of c-treeDB API data conversion functions.

Date values should be converted to string using the default date type value. The default date type value can be retrieved by calling ctdbGetFieldDefaultDateType() function. By default, the date type is CTDATE_MDCY.

Time values should be converted to string using the default time type value. The default time type value can be retrieved by calling ctdbGetFieldDefaultTimeType() function. By default, the time type is CTTIME_HMS.

Time stamp values should be converted to string using the default date type and time type values as described above.

Handle must be a c-treeDB API field handle.
value is a string with the default value. No checks are made to ensure the default value matches the correct field type. The caller is responsible for passing the appropriate value.
length correspond to the length of value parameter. You must pass a proper length of the string.

RETURN

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* set the default value for country - field #5 */

hField = ctdbGetField(hTable, 5);

if (hField)

if (ctdbSetFieldDefaultValue(hField, "USA", 3) != CTDBRET_OK)

printf("ctdbSetFieldDefaultValue failed\n");

EXTENDED DEFAULT FIELD VALUE SUPPORT

In V11 and later, it is possible to set default field values using functions such as SYSDATE, SYSDATETIME, etc. Previously, c-treeDB API only supported defining default values for fields using literal values. This improves c-treeDB API compliance with SQL, where it is possible to set default field values with literals or with functions.

A new enum, CTDEF_TYPE, has been added to use with these new functions:

CTDBRET ctdbDECL ctdbSetFieldDefaultValueType(CTHANDLE Handle, CTDEF_TYPE def_type);

Sets the default value type.

CTDEF_TYPE ctdbDECL ctdbGetFieldDefaultValueType(CTHANDLE Handle);

Gets the default value type.

Valid def_types are:

CTDEF_LITERAL: the value is a literal

CTDEF_USER: the current* user name

CTDEF_NULL: null

CTDEF_SYSDATE: the current* date

CTDEF_SYSTIME: the current* time

CTDEF_SYSTIMESTAMP: the current* timestamp

* “current” means at the time the default gets evaluated to be stored in the field.

To set the default value as a literal and automatically set its type to CTDEF_LITERAL, use a call to ctdbSetFieldDefaultValue.

To set the default value to any of the supported SQL functions, use a call to ctdbSetFieldDefaultValueType and pass the desired type, e.g. CTDEF_SYSDATE.

Default Values with ALTER TABLE

ctdbAlterTable has been enhanced to properly set the default value in new fields when doing a full rebuild.

ctdbAlterTable logic has been slightly changed so that the default value gets applied only to the fields just added, not to existing fields for which it may have been added or changed. Before this modification, existing fields could unintentionally change their values from NULL to the default value.