class CTField

Description

The CTField class deals with the field concept. The field is the basic component of the table. Any table may be composed of as many fields as one needs. It uses CTBase as the base class, and implements the constructor/destructor allocating/freeing memory to the field operations.

See also

CTBase, CTSession, CTDatabase, CTTable

Preconditions

Before any task is developed with a CTField object, a CTTable must have been initialized.

CTField Operators

• = : Assign a CTField object to another

CTField::operator=

Syntax

CTField& operator=(const CTField& pField)

Parameters

• pField [in] The field object.

Description

Assigns one CTField object to another

Return

Returns a CTField object

CTField Methods

Constructor / Destructor

• CTField(): Creates a CTField object
• ~CTField(): Destroys a CTField Object and resets all the dependent objects

Field Handling

• GetBinaryFlag(): Retrieves the field's binary flag
• GetLength(): Retrieves the field length
• GetName(): Retrieves the field name
• GetNullFlag(): Retrieves the field null flag
• GetNumber(): Retrieves the field position index in the table field list
• GetPrecision(): Retrieves the field precision
• GetScale(): Retrieves the field scale
• GetType(): Retrieves the field type
• IsNumeric(): Indicates if the field represents a numeric value
• SetBinaryFlag(): Sets the field's binary flag
• SetLength(): Sets the field length
• SetName(): Sets the field name
• SetNullFlag(): Sets the new null flag value
• SetPrecision(): Sets the field precision
• SetScale(): Sets the field scale value
• SetType(): Sets the field type

CTField::ClearFieldDefaultValue

Clears the default value associated with a field.

Declaration

void CTField::ClearFieldDefaultValue();

Description

CTField::ClearFieldDefaultValue() clears the default value associated with a field. The default date and time types are also reset to their default values of CTDATE_MDCY and CTTIME_HMS respectively.

Example

// clear the default field value
try
{
CTField hField = hTable.GetField("country");
hField.ClearFieldDefaultValue();
}
catch (CTException &err)
{
	printf("ClearFieldDefaultValue failed\n");
}
 

Return

void

See Also

SetFieldDefaultValue(), GetFieldDefaultValue(), IsFieldDefaultValueSet(), ClearAllFieldDefaultValue(), SetFieldDefaultDateTimeType(), GetFieldDefaultDateType(), GetFieldDefaultTimeType()

CTField::CTField

Syntax

CTField ( )
CTField(const CTField& pField)

Parameters

• pField [in] The field object.

Description

This is the constructor for the CTField object.

See also

~CTField()

CTField::~CTField

Syntax

~CTField

Parameters

This destructor has no parameters.

Description

This is the destructor for the CTField object.

See also

CTField()

CTField::GetBinaryFlag

Get the field binary flag.

Declaration

CTDB_BINARY_FLAG CTField::GetBinaryFlag() const

Description

This method gets the value of the field's binary flag. Some of the most frequently encountered values include:

• CTDB_BINARY_VARCHAR = 4, VARCHAR/LVARCHAR field created by c-treeSQL in v10
• CTDB_BINARY_CLOB = 5, CLOB field created by c-treeSQL in v10
• CTDB_BINARY_BLOB = 6, BLOB field created by c-treeSQL in v10
• CTDB_NUMBER_MONEY = 7, NUMBER field used to store MONEY type (instead of using CT_CURRENCY)

Return Values

Returns: binary_flag

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

• CTField::SetBinaryFlag

CTField::GetFieldDefaultDateType

Retrieves the default value date type.

Declaration

CTDATE_TYPE CTField::GetFieldDefaultDateType();

Description

CTField::GetFieldDefaultDateType() retrieves the default value date type used when converting strings to dates. The default value date type is returned.

Return

Example

TYPE parameters;

if (FunctionTemplate(parameters))
    printf("\nFunction error = %d",uerr_cod);

See Also

SetFieldDefaultValue(), GetFieldDefaultValue(), IsFieldDefaultValueSet(), ClearAllFieldDefaultValue(), SetFieldDefaultDateTimeType(), GetFieldDefaultDateType(), GetFieldDefaultTimeType()

CTField::GetFieldDefaultTimeType

Retrieves the default value time type.

Declaration

CTTIME_TYPE CTField::GetFieldDefaultTimeType();

Description

CTField::GetFieldDefaultTimeType() retrieves the default value time type used when converting string to time. The default value time type is returned.

Return

Example

// check the default date type
try
{
CTField hField = hTable.GetField("country");
if (hField.GetFieldDefaultTimeType() == CTTIME_HMS)
	printf("Field default time type is OK\n");
}
catch (CTException &err)
{
	printf("GetFieldDefaultTimeType() failed\n");
}
 

See Also

SetFieldDefaultValue(), GetFieldDefaultValue(), IsFieldDefaultValueSet(), ClearAllFieldDefaultValue(), SetFieldDefaultDateTimeType(), GetFieldDefaultDateType(), GetFieldDefaultTimeType()

CTField::GetFieldDefaultValue

Retrieves the current field default value.

Declaration

VRLEN GetFieldDefaultValue(pTEXT& value);
VRLEN GetFieldDefaultValue(CTString& value);

Description

CTField::GetFieldDefaultValue() retrieves the current field default value. If no default value is set CTField::GetFieldDefaultValue() returns zero. You can use CTField::IsFieldDefaultValueSet() method to check if a field default value is set or not. Parameter value receives the content of the field default value.

Return

Returns the number of bytes copied to value parameter. If no default value is available, the returned value is zero.

Example

// check if default field value is 'USA'
try
{
	CTString value;
	CTField hField = hTable.GetFielld("country");

hField = ctdbGetField(hTable, 5);
if (hField.GetFieldDefaultValue(value) > 0)
{
	if (value == "USA")
		printf("Default value is USA\n");
	else
		printf("Default value is not USA\n");
}
else
 	printf("No default value set\n");
}
catch (CTException &err)
{
	printf("GetFieldDefaultValue failed\n");
}
 

See Also

SetFieldDefaultValue(), GetFieldDefaultValue(), IsFieldDefaultValueSet(), ClearAllFieldDefaultValue(), SetFieldDefaultDateTimeType(), GetFieldDefaultDateType(), GetFieldDefaultTimeType()

CTField::GetLength

Syntax

VRLEN GetLength( ) const

Parameters

This method has no parameters.

Description

Retrieves the field length.

Return

GetLength() retrieves the field length.

See also

GetName(), GetType(), SetLength()

CTField::GetName

Syntax

CTString GetName( ) const

Parameters

This method has no parameters.

Description

Retrieves the field name.

Return

GetName() retrieves the field name.

See also

GetName(), GetType(), GetLength(), SetName()

CTField::GetNullFlag

Syntax

CTBOOL GetNullFlag( ) const

Parameters

This method has no parameters.

Description

Retrieves the field null flag.

The FairCom DB API null flag controls the NOT NULL property of a column. Setting this column has no effect on individual record null values: it is NOT enforced at the FairCom DB API layer. This attribute only applies to the FairCom DB SQL layer for constraint on values. It is useful to set this flag in c-tree data files before SQL import such that the property is maintained.

Return

GetNullFlag() returns the field null flag setting.

See also

SetNullFlag()

CTField::GetNumber

Syntax

NINT GetNumber( )

Parameters

This method has no parameters.

Description

Retrieves the field position index in the table field list.

Return

GetNumber() returns the field number.

CTField::GetPrecision

Syntax

NINT GetPrecision( ) const

Parameters

This method has no parameters.

Description

Retrieves the field precision (maximum number of digits).

Return

GetPrecision() returns the field precision value.

See also

SetPrecision()

CTField::GetScale

Syntax

NINT GetScale( ) const

Parameters

This method has no parameters.

Description

Retrieves the field scale (the number of digits to the right of the decimal point).

Return

GetScale() returns the field scale value.

See also

SetScale()

CTField::GetStatus

Retrieves the changed status of a field object.

Declaration

ULONG CTField::GetStatus() const;

Description

CTField::GetStatus() retrieves the changed status of a field object. The status of a field object is a bit map describing one or more changes that have occurred with the field object.

Return

CTField::GetStatus returns a bitmap of the following:

Example

// if field is new delete it
for (i = 0; i < (NINT) hTable.GetFieldCount(); i++)
{
    CTField hField = hTable.GetField(i);
 
    if (hField.GetStatus() & CTDBFIELD_NEW)
       hTable.DelField(i);
}
 

See Also

CTIndex::GetStatus(), CTSegment::GetStatus()

CTField::GetType

Syntax

CTDBTYPE GetType( ) const

Parameters

This method has no parameters.

Description

Retrieves the field type.

Return

GetType() retrieves the field type.

See also

GetName(), GetLength(), SetType()

CTField::IsFieldDefaultValueSet

Checks if a field default value has been set or not.

Declaration

CTBOOL CTField::IsFieldDefaultValueSet()

Description

CTField::IsFieldDefaultValueSet() checks if a field default value has been set or not. This method returns YES if a field default value was set, otherwise it returns NO.

Return

Example

// check if default field value is set
CTField hField = hTable.GetField("country");
if (hField.IsFieldDefaultValueSet())
    printf("Default field value is set\n");
else
   printf("No default field value\n");
 

See Also

SetFieldDefaultValue(), GetFieldDefaultValue(), ClearFieldDefaultValue(), ClearAllFieldDefaultValue(), SetFieldDefaultDateTimeType(), GetFieldDefaultDateType(), GetFieldDefaultTimeType()

CTField::IsNumeric

Syntax

CTBOOL IsNumeric( ) const

Parameters

This method has no parameters.

Description

Indicates if the field represents a numeric value.

Return

IsNumeric() returns YES if the field is numeric.

See also

SetNullFlag()

CTField::SetBinaryFlag

Set the field binary flag.

Declaration

void CTField::SetBinaryFlag(CTDB_BINARY_FLAG binary_flag)

Description

This method sets the field's binary flag. Many times this flag is needed to indicate that the field is not binary.

The value of binary_flag [IN] is the value to set the flag. It can be any valid value for a binary flag. Some of the more commonly usd values are:

• CTDB_BINARY_VARCHAR = 4, VARCHAR/LVARCHAR field created by c-treeSQL in v10
• CTDB_BINARY_CLOB = 5, CLOB field created by c-treeSQL in v10
• CTDB_BINARY_BLOB = 6, BLOB field created by c-treeSQL in v10
• CTDB_NUMBER_MONEY = 7, NUMBER field used to store MONEY type (instead of using CT_CURRENCY)

Return Values

See c-tree Error Codes for a complete listing of valid c-tree Plus error values.

See Also

• CTField::GetBinaryFlag

CTField::SetFieldDefaultDateTimeType

Sets the default field value date and time type.

Declaration

void CTField::SetFieldDefaultDateTimeType(CTDATE_TYPE dateType, CTTIME_TYPE timeType);

Description

CTField::SetFieldDefaultDateTimeType() sets the default field value date and time type to be used when converting CT_DATE, CT_TIME and CT_TIMES string values. By default the date type is CTDATE_MDCY and the time type is CTTIME_HMS. Use this method to modify the default values.

The CTField::SetFieldDefaultDateTimeType() method modifies both the date and time types. If you wish to change only the default date time, but keep the current time type, use the following example:

hField.SetFieldDefaultDateTimeType(CTDATE_YMD, hField.GetFieldDefaultTimeType());

You can use the same approach to change only the time type, keeping the current date type:

hField.SetFieldDefaultDateTimeType(ctdbGetFieldDefaultDateType(),CTIME_HMP);

dateType is the date type to be used for converting values between dates and strings. The possible values are:

timeType is the time type to be used for converting values between time and strings. The possible values are:

Example

// set the field default date and time types
try
{
CTField hField = hTable.GetField("country");
hField.SetFieldDefaultDateTimeType(CTDATE_MDCY, CTTIME_HMSP);
}
catch (CTException &err)
{
  printf("SetFieldDefaultDateTimeType failed\n");
}
 

See Also

SetFieldDefaultValue(), GetFieldDefaultValue(), IsFieldDefaultValueSet(), ClearFieldDefaultValue(), ClearAllFieldDefaultValue(), GetFieldDefaultDateType(), GetFieldDefaultTimeType()

CTField::SetFieldDefaultValue

Sets the field default value.

Declaration

void CTField::SetFieldDefaultValue(const CTString& value);
void CTField::SetFieldDefaultValue(pTEXT value, VRLEN length);

Description

• value is a string with the default value. No checks are made to make sure the default value matches the correct field type. The caller is responsible for passing the appropriate value.
• length is the length of string. You must pass a proper length of the string.

CTField::SetFieldDefaultValue() sets the field default value. 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 FairCom DB 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 CTField::GetFieldDefaultDateType() method. 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 CTField::GetFieldDefaultTimeType() 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.

Return

void

Example

// set the default value of country field */
try
{
	CTField hField = hTable.GetField("country"));
	hField.SetFieldDefaultValue("USA");
}
catch (CTException &err)
{
printf("SetFieldDefaultValue failed\n");
}
 

See Also

SetFieldDefaultValue(), GetFieldDefaultValue(), ClearFieldDefaultValue(), IsFieldDefaultValueSet(), ClearAllFieldDefaultValue(), SetFieldDefaultDateTimeType(), GetFieldDefaultDateType(), GetFieldDefaultTimeType()

CTField::SetLength

Syntax

void SetLength(const VRLEN Length)

Parameters

• Length [in] The field length to be set to the field.

Description

Sets the field length

Return

None.

See also

GetLength(), SetName(), SetType()

CTField::SetName

Syntax

void SetName(const CTString& FieldName)

Parameters

• FieldName [in] The field name to be set to the field.

Description

Sets the field name.

Return

None.

See also

GetName(), SetType(), SetLength()

CTField::SetNullFlag

Syntax

void SetNullFlag(CTBOOL flag)

Parameters

• flag [in] The new null flag setting.

Description

Sets the new null flag value. The null flag indicates if the field can contain a null value.

The FairCom DB API null flag controls the NOT NULL property of a column. Setting this column has no effect on individual record null values: it is NOT enforced at the FairCom DB API layer. This attribute only applies to the FairCom DB SQL layer for constraint on values. It is useful to set this flag in c-tree data files before SQL import such that the property is maintained.

Return

None.

See also

GetNullFlag()

CTField::SetPrecision

Syntax

void SetPrecision(NINT precision)

Parameters

• precision [in] The new field precision.

Description

Sets the field precision (maximum number of digits).

Return

None.

See also

GetPrecision()

CTField::SetScale

Syntax

void SetScale(NINT scale)

Parameters

• scale [in] The new field scale value.

Description

Sets the field scale (the number of digits to the right of the decimal point).

Return

None.

See also

GetScale()

CTField::SetType

Syntax

void SetType(const CTDBTYPE Type, const VRLEN Length=0)

Parameters

• Type [in] The field type to be set to the field. Valid type values are: CTBIGINT, CTBLOB, CTBOOL, CTCURRENCY, CTDATE, CTDATETIME, CTFLOAT, CTMONEY, CTNUMBER, CTSIGNED, CTSTRING, CTTIME and CTUNSIGNED.
• Length [in] The field length to be set to the field.

Description

Sets the field type.

Return

None.

See also

GetType(), SetName(), SetLength()