class CTTable

Description

Objects of the CTTable class are used to manage tables. One table may belong to several databases, and a database may have multiple tables. The table may have any number of fields. It uses CTBase as the base class, and implements the constructor/destructor allocating/freeing memory to the table operations.

See also

CTBase, CTDatabase, CTRecord

Preconditions

Before performing operations with a CTTable object, it is necessary to instantiate session and database objects.

CTTable Methods

Constructor / Destructor

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

Table Handling

• Alter(): Performs alter table functions
• Close(): Closes a table
• Create(): Creates a new table
• GetCreateMode(): Retrieves the table create mode.
• GetDataDefaultExtentSize(): Retrieves the c-tree data file default extent size
• GetDataExtension(): Retrieves the data file name extension.
• GetDatno(): Retrieve the table data file number.
• GetGroupid(): Retrieves the table group id
• GetIndexDefaultExtentSize(): Retrieves the c-tree index file default extent size
• GetIndexExtension(): Retrieves the index file name extension.
• GetIdxno(): Retrieve a table index file number.
• GetName(): Retrieves the table name, without the name extension.
• GetOpenMode(): Retrieves the table open mode.
• GetPassword(): Retrieves the table password
• GetPath(): Retrieves the table path.
• GetPermission(): Retrieves the table permission mask
• HasNullFieldSupport(): Indicates if a table has null field support
• HasDelField(): Indicates if a table has delete field support.
• HasLocks(): Indicates if a table has locks in the current session.
• IsActive(): Indicates if a table is open or closed.
• Open(): Opens an existing table
• ResetAll(): Resets all active record buffers associated with the table
• SetDataDefaultExtentSize(): Sets the c-tree data file default extent size
• SetDataExtension(): Sets the table data file extension
• SetGroupid(): Sets the table groupid
• SetIndexDefaultExtentSize(): Sets the c-tree index file default extent size
• SetIndexExtension(): Sets the table index file extension.
• SetPassword(): Sets the table password
• SetPath(): Sets the table path
• SetPermission(): Sets the table permission mask
• UnlockTable(): Unlocks all record locks from the table.
• UpdateCreateMode(): updates the table create mode

Field Handling

• AddField(): Adds a new field to table
• DelField(): Deletes one field from the table.
• GetField(): Retrieves a field by its number or name.
• GetFieldCount(): Retrieves the number of fields in table.
• GetFieldNumber(): Retrieves the field number from a field name.
• GetPadChar(): Retrieves the table pad and field delimiter characters.
• InsertField(): Inserts a new field to table, in the specified position.
• MoveField(): Moves the field from one position to a new position in the table.
• SetPadChar(): Set the table pad and field delimiter characters.
• UpdatePadChar(): Update the table pad and delimiter character resource.

Filter Handling

• FilterRecord(): Sets the filtering for a table.
• GetFilter(): Retrieves the filter that is filtering the table.
• IsFilteredRecord(): Indicates if the table is being filtered or not.

Index Handling

• AddIndex(): Adds a new index to the table
• DelIndex(): Deletes an index from a table
• GetCndxIndex(): Retrieves the conditional index expression string, given the index number.
• GetCndxIndexByName(): Retrieves the conditional index expression string, given the index name.
• GetCndxIndexLength(): Retrieves the length in bytes of the conditional expression string, given the index number.
• GetCndxIndexLengthByName(): Retrieves the length in bytes of the conditional expression string, given the index name.
• GetIndex(): Retrieves an index object
• GetIndexByUID(): Retrieves the index given its UID
• GetIndexCount(): Retrieves the number of indexes of the table
• HasRecbyt(): Indicates if a table was created with support to a recbyt index
• HasRowid(): Indicates if a table was created with support to a rowid index

Segment Handling

• AddSegment(): Adds a new segment to an index
• DelSegment(): Deletes an existing segment
• GetSegment(): Retrieves an index segment object
• InsertSegment(): Inserts a new segment

See also Locking.

CTTable::AddField

Syntax

CTField AddField(const CTString& Name, CTDBTYPE Type, VRLEN Length)

Parameters

• Name [in] - The field name to add to the table
• Type [in] - The field type. Valid field type values are shown in the "Field Types".
• Length [in] - The field length, the maximum length of [VAR]CHAR or [VAR]BINARY field in bytes (64K max). Set to 0 for "unlimited" (2GB) LVARCHAR.

Description

Adds a new field to table.

Return

AddField() returns a field object on success or NULL on failure.

See also

InsertField(), DelField(), GetField(), AddIndex()

CTTable::AddField (by field object) - FTS

Add a new segment to a Full-Text Index.

See CTTable::AddField (by field object)

CTTable::AddField (by name) - FTS

Add a new segment to an index using the field name.

See CTTable::AddField (by name)

CTTable::AddField (by number) - FTS

Add a new segment to an index using the field number.

See CTTable::AddField (by number)

CTTable::AddFullTextIndex

Add a new Full-Text Index to the table.

See AddFullTextIndex

CTTable::AddIndex

Syntax

CTIndex AddIndex(const CTString& name, CTDBKEY KeyType,
                 CTBOOL AllowDuplicates, CTBOOL NullFlag)

Parameters

• name [in] The index name to add to the table
• KeyType [in] The index type. Allowed types are:
  • CTINDEX_FIXED
  • CTINDEX_LEADING
  • CTINDEX_PADDING
  • CTINDEX_LEADPAD
  • CTINDEX_ERROR
• AllowDuplicates [in] The flag indicating if the index accepts duplicates or not.
• NullFlag [in] The flag indicating if Null fields are allowed or not.

Description

Adds a new index to the table

Return

None.

See also

DelIndex(), AddField(), HasNullFieldSupport()

CTTable::AddSegment

Syntax

CTSegment AddSegment(const CTIndex& pIndex, const CTField& pField,
                     CTSEG_MODE SegMode)
CTSegment AddSegment(const CTIndex& pIndex, const CTString& FieldName,
                     CTSEG_MODE SegMode)
CTSegment AddSegment(const CTIndex& pIndex, NINT FieldNumber,
                     CTSEG_MODE SegMode)
CTSegment AddSegment(const CTIndex& pIndex, NINT offset, NINT Length,
                     CTSEG_MODE SegMode)
CTSegment AddSegment(NINT IndexNbr, NINT FieldNbr, CTSEG_MODE SegMode)
CTSegment AddSegment(NINT IndexNbr, const CTString& FieldName,
                     CTSEG_MODE SegMode)
CTSegment AddSegment(NINT IndexNbr, const CTField& pField, CTSEG_MODE SegMode)
CTSegment AddSegment(const CTString& IndexName, const CTString& FieldName,
                     CTSEG_MODE SegMode)
CTSegment AddSegment(const CTString& IndexName, NINT FieldNumber,
                     CTSEG_MODE SegMode)
CTSegment AddSegment(const CTString& IndexName, const CTField& pField,
                     CTSEG_MODE SegMode)

Parameters

• pIndex [in] A pointer to the index object.
• pField [in] A pointer to the field object that composes part of the index segment
• SegMode [in] The segment mode. The valid values for the segment mode are shown in "Segment Modes". Notice that, if this method is used in the implementation that requires the offset, the segment is called extended, and in this specific case, the segment modes should be those that depend on the offset. If the implementation used is any other, the segment mode should be one of the so called schema segments (CTSEG_SCHSEG, CTSEG_USCHSEG, CTSEG_VSCHSEG, CTSEG_UVSCHSEG, CTSEG_SCHSRL).
• FieldName [in] Field name to compose the index segment
• FieldNumber [in] Field number to compose the index segment
• offset [in] Absolute byte offset of the segment. If used, this offset should be calculated with care, since the hidden fields included by FairCom DB API should be taken into account: $DELFLD$ (always included, to account for the deleted record) - 4 bytes; $NULFLD$ (always present - 1 bit for every user defined field, rounded for the next byte); $ROWID$ (8 bytes to account for the automatic auto-increment record - see the discussion on ROWID in "Hidden fields"). This variation makes it difficult to predict the correct offset of each user defined offset.
• Length [in] Segment length in bytes
• IndexNbr [in] Index number
• FieldNbr [in] Field number to compose the index segment
• IndexName [in] Index name to be updated.

Description

Adds a new segment to an index.

It is strongly recommended that the CTSegment::AddSegment(const CTIndex& pIndex, NINT offset, NINT Length, CTSEG_MODE SegMode) implementation is not used, with considerable advantages for the use of the other implementations. The use of the extended segments (based on the segment offset), as needed in this implementation, may prevent the use of advanced FairCom DB API functions like CTTable::Alter(). If, for any reason, it is mandatory to use this implementation, try to adapt the example presented in the description of the ctdbAddSegmentEx() function.

Return

AddSegment() returns a segment object.

See also

InsertSegment(), DelSegment()

CTTable::Alter

Syntax

void Alter(NINT Action)

Parameters

• Action [in] The alter table action. One or more of the following actions can be selected:
  • CTDB_ALTER_NORMAL: Check for changes before altering
  • CTDB_ALTER_INDEX: Force rebuild of all indexes
  • CTDB_ALTER_FULL: Force full table rebuild.
  • CTDB_ALTER_TRUNCATE: Quickly remove all records.
  • CTDB_ALTER_PURGEDUP: OR in with any of the other modes to deal with cases where an alter table is performed on data files with duplicated index information.
  • CTDB_ALTER_KEEPTRAN: Allow tables with different TRANDEP modes (e.g. transaction capable, however, transaction control disabled for performance) to undergo ALTER TABLE. (This is generally an internal FairCom operation for certain table types.)

Description

Performs alter table functions. This method may be used to update a table after its creation. The table must be open in CTOPEN_EXCLUSIVE mode before it is updated.

Return

None.

See also

Open()

CTTable::Attach

Attaches a c-tree Plus ISAM datno object to a FairCom DB API table object.

Declaration

void CTTable::Attach(NINT datno);

Description

• datno is data file number opened with one of the c-tree ISAM open functions.

CTTable::Attach() attaches a c-tree Plus ISAM datno object to a FairCom DB API table object. This function is useful if you have opened a data and index file using one of c-tree’s ISAM open functions and need to attach it to a table handle to use some of the advanced FairCom DB API features such as alter table or the record handler.

Return

void

Example

CTSession hSession(CTSESSION_CTREE);
CTTable hTable(hSession);
CTRecord hRecord(hTable);
NINT datno, count = 0;

// logon to c-tree
hSession.Logon(SERVER, USER, PASSWD);

// open the file using c-tree ISAM
datno = (NINT)OPNRFILX((COUNT) -1, "test309.dat", (COUNT)0, NULL);)

// attach to table
hTable.Attach(datno);

// read the records
if (hRecord.First())
do
{
	count++;
}
while (hRecord.Next());

// cleanup
hTable.Detach();
hSession.Logout();
 

See Also

CTTable::AttachXtd(), CTTable::Detach()

CTTable::AttachXtd

Attaches a c-tree Plus ISAM datno object to a FairCom DB API table handle allowing a DODA and IFIL to be specified.

Declaration

void CTTable::AttachXtd(NINT datno, NINT nbrfields, pDATOBJ dodaptr, 
	pIFIL ifilptr);

Description

• datno is the data file number.
• nbrfields is the number of fields described by dodaptr. If nbrfields is zero, it is assumed that the DODA is not supplied and a DODA resource will be read from the table itself.
• dodaptr pointer to DODA entries for each field in table. If dodaptr is NULL, it is assumed that the DODA is not supplied and a DODA resource will be read from the table itself.
• ifilptr is a pointer to IFIL structure describing indexes of table. If ifilptr is NULL it is assumed that an IFIL is not supplied and an IFIL resource will be read from the table itself.

CTTable::AttachXtd() attaches a c-tree Plus ISAM datno object to a FairCom DB API table object. This function is useful if you have opened a data and index file using one of c-tree’s ISAM open functions and need to attach it to a table handle to use some of the advanced FairCom DB API features such as alter table or the record handler. This extended version allows the user to specify the DODA and IFIL for the table, enabling tables without DODA and/or IFIL to be attached to FairCom DB API.

Return

void

Example

/* DODA */
static DATOBJ doda[] =
{
	{"f1", (pTEXT)0, CT_INT4, 4},
	{"f2", (pTEXT)4, CT_FSTRING, 10}
};
/* IFIL */
static ISEG iseg = {0, 4, 12};
static IIDX iidx = {4, 0, 0, 0, 0, 1, &iseg, "i311x1", NULL, NULL, NULL};
static IFIL ifil = {"test310", -1, 14, 0, 0, 1, 0, 0, &iidx, "f1", "f2", 0};
 
CTSession hSession(CTSESSION_CTREE);
CTTable hTable(hSession);
CTRecord hRecord(hTable);
NINT datno, count = 0;
	
// logon to c-tree
hSession.Logon(SERVER, USER, PASSWD);
// open the file using c-tree ISAM
datno = (NINT)OPNRFILX((COUNT) -1, "test309.dat", (COUNT)0, NULL);)
// attach to table
hTable.AttachXtd(datno, 2, doda, &ifil);
// read the records
if (hRecord.First())
do
{
	count++;
}
while (hRecord.Next());
// cleanup
hTable.Detach();
hSession.Logout();

CTTable::ClearAllFieldDefaultValue

Clears the default value associated with all fields in a table.

Declaration

void CTTable::ClearAllFieldDefaultValue();

Description

Clears the default value associated with all fields in a table. The default date and time types for each field are also reset to the default values of CTDATE_MDCY and CTIME_HMS respectively.

Return

void

Example

// clear all field default value
try
{
hTable.ClearAllFieldDefaultValue();
}
catch (CTException &err)
{
	printf("ClearAllFieldDefaultValue failed\n");
}
 

See Also

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

CTTable::Clone

Syntax

void Clone(CTTable &target, const CTString& Name)

Parameters

• target [in] - The new table handle
• Name [in] - The new table name (without file extension)

Description

Creates a new table with the attributes from an existing source table. This does NOT create a duplicate table -- records are not copied.

Note This function is only for a CTSESSION_CTREE session or for cloning tables from/into different databases.

Return

None. Throws a CTException on error. Typical CreateTable() exceptions are possible.

See also

CTTable::CreateTable()

CTTable::Close

Syntax

void Close( )

Parameters

This method has no parameters.

Description

Closes a table.

Return

None.

See also

Open()

CTTable::Create

Syntax

void Create(const CTString& Name, const CTCREATE_MODE CreateMode)

Parameters

• Name [in] The table name
• CreateMode [in] The create mode for the table. The valid values for the table create mode are shown in "Table Create Modes".

Description

Creates a new table. Before the table creation, it must be defined with AddField(), and optionally with AddIndex() and AddSegment().

Return

None.

See also

AddField(), GetCreateMode(), Open()

CTTable::CTTable

Syntax

CTTable(const CTDatabase& Handle)
CTTable(const CTDatabase* Handle)
CTTable(const CTSession& Handle)
CTTable(const CTSession* Handle)

Parameters

• Handle [In] Is the database or session object. When the CTTable(const CTDatabase& Handle) or the CTTable(const CTDatabase* Handle) prototype is used, Handle is a database object or pointer to a database object. When the CTTable(const CTSession& Handle) or the CTTable(const CTSession* Handle) prototype is used, Handle is a session object or pointer to a session object. The CTTable object being created is a child of the CTDatabase or CTSession object.

Description

This is the constructor for the CTTable class.

See also

~CTTable()

CTTable::DelField

Syntax

void DelField(const NINT FieldNumber)
void DelField(const CTString&FieldName)

Parameters

• FieldNumber [in] Delete this field number, if the prototype DelField(const NINT FieldNumber) is used.
• FieldName [in] Delete this field name, if the prototype DelField(const CTString& FieldName) is used.

Description

Deletes a field from the table.

Return

None.

See also

InsertField(), AddField(), CTDatabase::DeleteTable()

CTTable::DelFullTextIndex (by index name)

Delete a Full-Text Index from a table using the index name.

See CTTable::DelFullTextIndex (by name)

CTTable::DelFullTextIndex (by index number)

Delete a Full-Text index from a table using the index number.

See CTTable::DelFullTextIndex (by number)

CTTable::DelIndex

Syntax

void DelIndex(NINT IndexNumber)
void DelIndex(const CTString& IndexName)

Parameters

• IndexNumber [in] Index number to be deleted, if the prototype DelIndex(NINT IndexNumber) is used.
• IndexName [in] Index name to be deleted, if the prototype DelIndex(const CTString& IndexName) is used.

Description

Deletes an index from a table, either by name or number.

Return

None.

See also

AddIndex(), DelField()

CTTable::DelSegment

Syntax

void DelSegment(NINT IndexNumber, NINT SegNumber)
void DelSegment(const CTString& IndexName, NINT SegNumber)

Parameters

• IndexNumber [in] The index number whose segment is to be deleted.
• SegNumber [in] The segment number to be deleted.
• IndexName [in] The index name whose segment is to be deleted.

Description

Deletes an existing segment.

Return

None.

See also

AddSegment(), InsertSegment()

CTTable::Detach

Detaches a FairCom DB API table object from a c-tree data and index files.

Declaration

void CTTable::Detach();

Description

CTTable::Detach() detaches a FairCom DB API table object from a c-tree data and index files. The table is not closed but the FairCom DB API table handle resources are released and the handle re-initialized.

Return

void

Example

CTSession hSession(CTSESSION_CTREE);
CTTable hTable(hSession);
CTRecord hRecord(hTable);
NINT datno, count = 0;

// logon to c-tree
hSession.Logon(SERVER, USER, PASSWD);

// open the file using c-tree ISAM
datno = (NINT)OPNRFILX((COUNT) -1, "test309.dat", (COUNT)0, NULL);)

// attach to table
hTable.Attach(datno);

// read the records
if (hRecord.First())
do
{
	count++;
}
while (hRecord.Next());

// cleanup
hTable.Detach();
hSession.Logout();
 

See Also

CTTable::Attach(), CTTable::AttachXtd()

CTTable::FilterRecord

Syntax

void FilterRecord(const CTString& cndexpr)

Deprecated

Returns CTDBRET_NOTSUPPORTED. <FC_PROD_CTED> Filters are record based as of FairCom DB V9.

Please See

CTRecord::SetFilter(), CTRecord::GetFilter(), CTRecord::IsFiltered()

CTTable::GetCndxIndex

Syntax

void CTTable::GetCndxIndex(NINT indexnbr, CTString&cndexpr)
void CTTable::GetCndxIndex(const CTString& indexname, CTString&cndexpr)

Parameters

• indexnbr [in] index number
• indexname [in] index name
• cndexpr [out] conditional index expression

Description

Retrieves the conditional index expression string, given the index number.

Return

None.

See also

GetCndxIndexByName(), GetCndxIndexLength(), GetCndxIndexLengthByName()

CTTable::GetCndxIndexByName

Syntax

#ifdef PROTOTYPE
CTDBRET ctdbDECL ctdbGetCndxIndexByName(CTHANDLE Handle, pTEXT indexname,
                                        pTEXT buffer, NINT bufferlen)
#else
CTDBRET ctdbDECL ctdbGetCndxIndexByName(Handle, indexname, buffer, bufferlen)
CTHANDLE Handle;
pTEXT indexname;
pTEXT buffer;
NINT bufferlen;
#endif

Parameters

• handle [in] table handle
• indexname [in] index name
• buffer [out] pointer to buffer to receive the conditional expression
• bufferlen [in] size in bytes of buffer

Description

Retrieves the conditional index expression string, given the index name.

Return

Return CTDBRET_OK on success

See also

GetCndxIndex(), GetCndxIndexLength(), GetCndxIndexLengthByName()

CTTable::GetCndxIndexLength

Syntax

#ifdef PROTOTYPE
NINT ctdbDECL ctdbGetCndxIndexLength(CTHANDLE Handle, NINT indexnbr)
#else
NINT ctdbDECL ctdbGetCndxIndexLength(Handle, indexnbr)
CTHANDLE Handle;
NINT indexnbr;
#endif

Parameters

• handle [in] table handle
• indexnbr [in] index number

Description

Retrieves the length in bytes of the conditional expression string, given the index number.

Return

Return the length in bytes of the conditional expression or -1 on error.

See also

GetCndxIndex(), GetCndxIndexByName(), GetCndxIndexLengthByName()

CTTable::GetCndxIndexLengthByName

Syntax

#ifdef PROTOTYPE
NINT ctdbDECL ctdbGetCndxIndexLengthByName(CTHANDLE Handle, pTEXT indexname)
#else
NINT ctdbDECL ctdbGetCndxIndexLengthByName(Handle, indexname)
CTHANDLE Handle;
pTEXT indexname;
#endif

Parameters

• handle [in] table handle
• indexname [in] index name

Description

Retrieves the length in bytes of the conditional expression string, given the index name.

Return

Return the length in bytes of the conditional expression or -1 on error.

See also

GetCndxIndex(), GetCndxIndexByName(), GetCndxIndexLength()

CTTable::GetCreateMode

Syntax

CTCREATE_MODE GetCreateMode( ) const

Parameters

This method has no parameters.

Description

Retrieves the table create mode. The valid values for the table create mode are shown in "Table Create Modes".

Return

GetCreateMode() returns the table create mode.

See also

Create(), GetOpenMode()

CTTable::GetDataDefaultExtentSize

Syntax

NINT GetDataDefaultExtentSize( ) const

Parameters

This method has no parameters.

Description

Retrieves the c-tree data file default extent size. The default value, 8192 bytes, may be changed by calling SetDataDefaultExtentSize().

Return

GetDataDefaultExtentSize() returns the default data file extent size.

See also

SetDataDefaultExtentSize(), GetIndexDefaultExtentSize()

CTTable::GetDataExtension

Syntax

CTString GetDataExtension( ) const

Parameters

This method has no parameters.

Description

Gets the data file name extension. If not changed by SetDataExtension(), the data extension is "dat".

Return

GetDataExtension() returns the data file name extension

See also

SetDataExtension(), GetIndexExtension()

CTTable::GetDatno

Retrieve the table data file number.

Declaration

NINT CTTable::GetDatno()

Description

Retrieves the table data file number from a table object. If an error is detected, GetDatno() throw a CTException.

Return

GetDatno() returns the table data file number.

Example

void DeleteTable(CTSEssion& hSession, pTEXT tablename)
{
    CTDBRET eRet;
    CTTable hTable(hSession);

    // open the table exclusive
    hTable.Open(tablename, CTOPEN_EXCLUSIVE);

    // delete a file
    eRet = (CTDBRET)DeleteRFile((COUNT)hTable.GetDatno());
    if (eRet != CTDBRET_OK)
        throw CTException(eRet, "DeleteTable", __FILE__, __LINE__);
}
 

See Also

CTBase::SwitchInstance(), CTRecord::SwitchContext(), CTTable::GetIdxno(), CTIndex::GetIdxno()

CTTable::GetField

Syntax

CTField GetField(NINT FieldNumber) const
CTField GetField(const CTString& FieldName) const

Parameters

• FieldNumber [in] The field number to be retrieved from the table. The first field in the table is field number zero.
• FieldName [in] The field name to be retrieved from the table.

Description

Retrieves a field by its number or name. The first field in the table is the field number zero.

Return

GetField() returns the field object.

See also

GetFieldNumber(), GetFieldCount()

CTTable::GetFieldCount

Syntax

VRLENGetFieldCount( ) const

Parameters

This method has no parameters.

Description

Retrieves the number of fields in the table

Return

GetFieldCount() returns the number of fields.

See also

AddField(), DelField(), InsertField(), GetFieldNumber(), GetIndexCount()

CTTable::GetFieldNumber

Syntax

NINT GetFieldNumber(const CTString& FieldName) const

Parameters

• FieldName [in] The field name whose field number is to be retrieved from the table.

Description

Retrieves the field number from a table, given its field name.

Return

GetFieldNumber() returns the field number.

See also

GetField(), GetFieldCount()

CTTable::GetFilter

Syntax

void GetFilter (CTString& cndexpr)

Deprecated

Returns CTDBRET_NOTSUPPORTED. FairCom DB API Filters are record based as of FairCom DB V9.

Please See

CTRecord::SetFilter(), CTRecord::GetFilter(), CTRecord::IsFiltered()

CTTable::GetFirstPartition

Syntax

LONG CTTable::GetFirstPartition()

Parameters

None

Description

Retrieves the first raw partition number, if the table is a partitioned file.

Return

CTException is thrown if the table is not a partitioned file.

See Also

GetLastPartition()

CTTable::GetFullTextIndex (by index name)

Retrieve the Full-Text Index using its name.

See CTTable::GetFullTextIndex (by name)

CTTable::GetFullTextIndex (by index number)

Retrieve a Full-Text Index object using the index number.

See CTTable::GetFullTextIndex (by number)

CTTable::GetFullTextIndexCount

Retrieve the number of Full-Text Indexes of this table.

See CTTable::GetFullTextIndexCount

CTTable::GetGroupid

Syntax

CTString GetGroupid( ) const

Parameters

This method has no parameters.

Description

Retrieves the table group id

Return

GetGroupid() returns the table group id.

See also

SetGroupid()

CTTable::GetIdxno

Retrieve a table index file number given the index name or the FairCom DB API index number.

Declaration

NINT CTTable::GetIdxno(const CTString& IndexName)
NINT CTTable::GetIdxno(NINT index)

Description

Retrieves the index file number given the index name or the FairCom DB API index number.

• IndexName contains the symbolic name for the index. Please note the difference between the index symbolic name and the index file name.
• index is a FairCom DB API index number. The first FairCom DB API index number is zero.

Return

GetIdxno() returns a table index file number.

Example

// retrieve the first key  of first index
TEXT keyval[256];

if (FirstKey(hTable.GetIdxno("IndexName"), keyval)
    printf("FirstKey failed\n");

if (FirstKey(hTable.GetIdxno(0), keyval)
    printf("FirstKey failed\n");
 

See Also

CTBase::SwitchInstance(), CTRecord::SwitchContext(), CTTable::GetDatno(), CTIndex::GetIdxno()

CTTable::GetIndex

Syntax

CTIndex GetIndex(NINT IndexNumber)
CTIndex GetIndex(const CTString& name)

Parameters

• IndexNumber [in] The Index number to be retrieved.
• name [in] The index name to be retrieved.

Description

Retrieves an index object, given its number or name.

Return

GetIndex() returns the Index object.

See also

DelIndex(), AddIndex()

CTTable::GetIndexByUID

Syntax

CTIndex GetIndexByUID(ULONG uid)

Parameters

• uid [in] the index unique identifier.

Description

Retrieves the index object given its unique identifier.

Return

GetIndexByUID() returns the Index object.

See also

GetIndex()

CTTable::GetIndexCount

Syntax

VRLEN GetIndexCount( ) const

Parameters

This method has no parameters.

Description

Retrieves the number of table indexes

Return

GetIndexCount() returns the number of indexes.

See also

GetFieldCount()

CTTable::GetIndexDefaultExtentSize

Syntax

NINT GetIndexDefaultExtentSize( ) const

Parameters

This method has no parameters.

Description

Retrieves the c-tree index file default extent size

Return

GetIndexDefaultExtentSize() returns the default index file extent size. The default value, 8192 bytes, may be changed by SetIndexDefaultExtentSize().

See also

SetIndexDefaultExtentSize(), GetDataDefaultExtentSize()

CTTable::GetIndexExtension

Syntax

CTString GetIndexExtension( ) const

Parameters

This method has no parameters.

Description

Gets the index file name extension (usually .idx).

Return

GetIndexExtension() returns the index file name extension. If not changed by SetIndexExtension(), the index extension is "idx".

See also

SetIndexExtension(), GetDataExtension()

CTTable::GetIndexFileName

Syntax

CTString GetIndexFilename(NINT IndexNumber);
CTString GetIndexFilename(const CTString& IndexName);

Parameters

These overloaded methods identify the index by number (IndexNumber) or by name (IndexName).

Description

Retrieves the index physical file name.

Return

GetIndexFilename() returns the index physical file name.

See also

CTTable::SetIndexFileName()

CTTable::GetLastPartition

Syntax

LONG CTTable::GetLastPartition()

Parameters

None

Description

Retrieves the last raw partition number, if the table is a partitioned file.

Return

CTException is thrown if the table is not a partitioned file.

See Also

GetFirstPartition()

CTTable::GetName

Syntax

CTString GetName( ) const

Parameters

This method has no parameters.

Description

Gets the table name, without the name extension.

Return

GetName() returns the table name.

Example

pTable=pDatabase->GetFirstActive();
printf("\nFirst Active table: %s",
          pTable->GetName().c_str());
 

See also

GetPath(), GetOpenMode(), GetPassword(), GetPermission()

CTTable::GetOpenMode

Syntax

CTOPEN_MODE GetOpenMode( ) const

Parameters

This method has no parameters.

Description

Retrieves the table open mode. The valid values for the table open mode are shown in "Table Open Modes".

Return

GetOpenMode() returns the table open mode.

See also

Open(), GetCreateMode()

CTTable::GetOwner

Declaration

CTString CTTable::GetOwner() const

Description

Retrieves the table owner.

Return Values

If the table owner was not previously set by SetOwner(), GetOwner() returns an empty string. GetOwner() returns the table owner or empty string if no table owner is set.

See Also

SetOwner()

CTTable::GetPadChar

Syntax

void GetPadChar(TEXT &Padchar, TEXT &Dmlchar)

Parameters

• Padchar [out] receive the pad character
• Dmlchar [out] receive the field delimiter character

Description

Retrieve the table pad and field delimiter characters. These characters are used to pad fixed string fields (CT_FSTRING) to allow proper target key formation.

Return

None.

See also

SetPadChar(), UpdatePadChar()

CTTable::GetPartitionIndexNbr

Get the Partition index number.

Syntax

NINT CTTable::GetPartitionIndexNbr()

Parameters

None.

Return

The partition index number.

-1 if none.

See also

CTTable::SetPartitionIndexNbr CTTable:: CTTable::SetPartitionNumberBits CTTable::SetParitionRule CTTable::SetPartitionMaximumActive CTTable::GetPartitionIndexNbr

CTTable::GetPassword

Syntax

CTString GetPassword( ) const

Parameters

This method has no parameters.

Description

Retrieves the table password

Return

GetPassword() returns the table password

See also

SetPassword(), GetName(), GetPath()

CTTable::GetPath

Syntax

CTString GetPath( ) const

Parameters

This method has no parameters.

Description

Gets the table path.

Return

GetPath() returns the table path.

See also

GetName()

CTTable::GetPermission

Syntax

LONG GetPermission( ) const

Parameters

This method has no parameters.

Description

Retrieves the table permission mask. The valid values for the table permission mask are shown in "Table Permissions".

Return

GetPermission() returns the table permission mask.

See also

SetPermission()

CTTable::GetSegment

Syntax

CTSegment GetSegment(const CTIndex& pIndex, VRLEN SegNumber)

Parameters

• pIndex [in] The index object whose segment is to be retrieved
• SegNumber [in] The segment number to be retrieved

Description

Retrieves an index segment object

Return

GetSegment() returns the segment object

See also

AddSegment(), InsertSegment(), DelSegment()

CTTable::GetStatus

Declaration

ULONG CTTable::GetStatus();

Description

Retrieves the table status. The table status indicates which rebuild action will be taken by an alter table operation.

Return Values

GetStatus() returns CTDB_REBUILD_NONE if the table is not changed or a bit mask of the values below describing the table status.

The possible rebuild status returns are:

Example

ULONG status = hTable.GetStatus();
 
if (status & CTDB_REBUILD_ALL || status & CTDB_REBUILD_FULL)
     hTable.Alter(CTDB_ALTER_FULL)
else if (status)
     hTable.Alter(CTDB_ALTER_NORMAL);

See Also

CTIndex::GetStatus(), CTSegment::GetStatus(), CTTable::Alter()

CTTable::GetTableKSeg

Retrieves the current table wide extended key segment definition.

Declaration

void CTTable::GetTableKSeg(pctKSEGDEF pKSeg);

Description

CTTable::GetTableKSeg() retrieves the current table wide extended key segment definition. pKSeg is a pointer to an extended key segment definition structure which will receive the definition.

Return

void

Example

ctKSEGDEF kseg;
hTable.GetTableKSeg(&ksge);
 

See Also

CTIndex::GetIndexKSeg(), CTIndex::SetIndexKSeg(), CTSegment::GetSegmentKSeg(),
CTSegment::SetKSegDefaults(), CTSegment::SetSegmentKSeg(), CTTable::SetTableKSeg()

CTTable::HasDelField

Determines if a table has a delete $DEL$ field.

Declaration

bool CTTable::HasDelField()

Description

CTTable::HasDelField() indicates if a table associated with the current handle has a delete field.

Return

Example

if myTable->HasDelField()
  printf("My Table has a Delete Field in it\n");

CTTable::HasLocks

Syntax

CTBOOL HasLocks( )

Parameters

This method has no parameters.

Description

Check if there are any locks on the table in the current session.

Return Values

YES if the table has locks.

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

See Also

CTTable::HasNullFieldSupport

Syntax

CTBOOL HasNullFieldSupport( )

Parameters

This method has no parameters.

Description

Indicates if a table has null field support.

Return

HasNullFieldSupport() returns YES if the table has null field support, NO otherwise.

CTTable::HasRecbyt

Syntax

CTBOOL HasRecbyt( )

Parameters

This method has no parameters.

Description

Indicates if a table has support to a recbyt index or not. By default, when a table is created it has support to this index enabled.

Return

HasRecbyt() returns YES if the table has support to the recbyt index, NO otherwise.

See also

Create()

CTTable::HasRowid

Syntax

CTBOOL HasRowid( )

Parameters

This method has no parameters.

Description

Indicates if a table has support to a rowid index or not. By default, when a table is created it has support to this index enabled. A rowid index is an automatic sequence number.

Return

HasRecbyt() returns YES if the table has support to the rowid index, NO otherwise.

See also

Create(), Record::FindRowid(), Record::GetRowid()

CTTable::InsertField

Syntax

CTField InsertField(const NINT BeforeField, const CTString& Name,
                    CTDBTYPE Type, VRLEN Length)
CTField InsertField(const CTString& BeforeField, const CTString& Name,
                    CTDBTYPE Type, VRLEN Length)

Parameters

• BeforeField [in] Insert the new field before this field number, if the prototype InsertField(const NINT BeforeField, const CTString& Name, CTDBTYPE Type, VRLEN Length) is used. Insert the new field before this field name, if the prototype InsertField(const CTString& BeforeField, const CTString& Name, CTDBTYPE Type, VRLEN Length) is used.
• Name [in] The field name to insert in the table
• Type [in] the field type. Valid field type values are shown in "Field Types".
• Length [in] the field length

Description

Inserts a new field into the table, in the specified position.

Return

InsertField() returns a field object on success or NULL on failure.

See also

AddField(), DelField(), GetFieldNumber()

CTTable::InsertSegment

Syntax

CTSegment InsertSegment(const CTIndex& pIndex, NINT BeforeSegment,
                        const CTField& Field, CTSEG_MODE SegMode)
CTSegment InsertSegment(const CTIndex& pIndex, NINT BeforeSegment,
                        const CTString& FieldName, CTSEG_MODE SegMode)
CTSegment InsertSegment(const CTIndex& pIndex, NINT BeforeSegment,
                        NINT FieldNumber, CTSEG_MODE SegMode)
CTSegment InsertSegment(const CTIndex& pIndex, NINT BeforeSegment,
                        NINT offset, NINT length, CTSEG_MODE SegMode)
CTSegment InsertSegment(NINT IndexNbr, NINT BeforeSegment,
                        NINT FieldNumber, CTSEG_MODE SegMode)
CTSegment InsertSegment(NINT IndexNbr, NINT BeforeSegment,
                        const CTString& FieldName, CTSEG_MODE SegMode)
CTSegment InsertSegment(const CTString& IndexName, NINT BeforeSegment,
                        const CTString& FieldName, CTSEG_MODE SegMode)
CTSegment InsertSegment(const CTString& IndexName, NINT BeforeSegment,
                        NINT FieldNumber, CTSEG_MODE SegMode)
CTSegment InsertSegment(const CTString& IndexName, NINT BeforeSegment,
                        const CTField& Field, CTSEG_MODE SegMode)
CTSegment InsertSegment(NINT IndexNbr, NINT BeforeSegment,
                        const CTField& Field, CTSEG_MODE SegMode)

Parameters

• pIndex [in] A pointer to the index object.
• BeforeSegment [in] Insert the new segment before this segment.
• Field [in] A pointer to the field object that composes part of the index segment
• SegMode [in] The segment mode. The valid values to the segment mode are shown in "Segment Modes".
• FieldName [in] Field name to compose the index segment
• FieldNumber [in] Field number to compose the index segment
• offset [in] Absolute byte offset of the segment
• Length [in] Segment length in bytes
• IndexNbr [in] Index number
• IndexName [in] Index name
• Field [in] Field segment to be inserted

Description

Inserts a new segment in an index.

Return

InsertSegment() returns a segment object.

See also

AddSegment(), DelSegment()

CTTable::IsActive

Syntax

CTBOOL IsActive( ) const

Parameters

This method has no parameters.

Description

Indicates if a table is open or closed.

Return

IsActive() returns YES if the table is open and NO otherwise.

Example

if (!pTable->IsActive())
        pTable->Open(tb_name, "CTOPEN_NORMAL");
 

See also

Open()

CTTable::IsFilteredRecord

Syntax

CTBOOL IsFilteredRecord( )

Deprecated

Returns CTDBRET_NOTSUPPORTED. FairCom DB API Filters are record based as of FairCom DB V9.

Please See

CTRecord::SetFilter(), CTRecord::GetFilter(), CTRecord::IsFiltered()

CTTable::MoveField

Syntax

void MoveField(const NINT FieldNumber, NINT newNumber)
void MoveField(const CTString& FieldName, NINT newNumber)

Parameters

• FieldNumber [in] The field number to be moved, if the prototype MoveField(const NINT FieldNumber, NINT newNumber) is used.
• newNumber [in] The new field number in the table.
• FieldName [in] The field name to be moved, if the prototype MoveField(CTString& FieldName, NINT newNumber) is used.

Description

Moves the field from one position to another position in the same table.

Return

None.

See also

AddField(), InsertField(), DelField()

CTTable::MoveSegment

Moves a key segment to a location.

Declaration

void CTTable::MoveSegment(CTIndex hIndex, NINT segNumber, NINT newIndex);
void CTTable::MoveSegment(NINT indexNumber, NINT segNumber, NINT newIndex);
void CTTAble::MoveSegment(const CTString& indexName, NINT segNumber, 
	NINT newIndex);

Description

CTTable::MoveSegment() moves a key segment to a location indicated by newIndex.

• hIndex is an index object.
• indexNumber is a relative number for a index object in a table definition.
• indexName is the unique name for the index.
• newIndex indicates the relative position were the key segment should be moved to.

Return

void

Example

// move the last segment to first
CTIndex hIndex = hTable.GetIndex(0);
NINT count = hIndex.GetSegmentCount();

if (count > 0)
    hTable.MoveSegment(hIndex, (count - 1), 0);
 

See Also

CTIndex::MoveSegment(), CTSegment::MoveSegment()

CTTable::Open

Syntax

void Open(const CTString& Name, const CTOPEN_MODE OpenMode)

Parameters

• Name [in] The table name
• OpenMode [in] The open mode for the table. The valid values for the table open mode are shown in "Table Open Modes".

Description

Opens an existing table.

Return

None.

See also

GetOpenMode(), Create(), Close()

CTTable::PartAdminByKey

Performs an administrative partition operation on the partition specified by key value.

Declaration

COUNT PartAdminByKey(pVOID key, CTPART_MODE_E partmode);

Description

PartAdminByKey() manages the partitions for a table.

• keyval [in] - pointer to a partition key value that has been transformed
• partmode [in] - partition operation mode. partmode is one of:

Return Values

CTDBRET_NOERROR is returned if no error.

If CTPART_STATUS is passed as a partition mode, then one of the following partstatus values is returned:

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

See Also

CTTable::PartAdminByName(), CTTable::PartAdminByNumber()

CTTable::PartAdminByName

Performs an administrative partition operation on the partition specified by partition name.

Declaration

COUNT PartAdminByName(pTEXT partname, CTPART_MODE_E partmode);

Description

PartAdminByName() manages the partitions for a table.

• partname [in] - partition name.
• partmode [in] - partition operation mode. partmode is one of:

Return Values

CTDBRET_NOERROR is returned if no error.

If CTPART_STATUS is passed as a partition mode, then one of the following partstatus values is returned:

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

See Also

CTTable::PartAdminByKey(), CTTable::PartAdminByNumber()

CTTable::PartAdminByNumber

Performs an administrative partition operation on the partition specified by partition number.

Declaration

COUNT PartAdminByNumber(LONG partno, CTPART_MODE_E partmode);

Description

PartAdminByKey() manages the partitions for a table.

• partno [in] - partition number
• partmode [in] - partition operation mode. partmode is one of:

Return Values

CTDBRET_NOERROR is returned if no error.

If CTPART_STATUS is passed as a partition mode, then one of the following partstatus values is returned:

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

See Also

CTTable::PartAdminByKey(), CTTable::PartAdminByName()

CTTable::Rebuild

Declaration

CTTable::Rebuild(CTREBUILD_MODE mode);

Description

• See AlsoHandle [IN] Table handle
• mode [IN] The following modes are available:

Note Exercise care when using CTREBUILD_DATAONLY and CTCREBUILD_UPDATEIFIL modes together as the index files will be removed from the table IFIL definition even if the index files still exist in the file system. This can cause later problems if Alter() is called to recreate the removed indexes.

Rebuild() calls the FairCom DB CTRBLIFILX() function to rebuild a c-tree table. When used in conjunction with the open modes CTOPEN_CORRUPT and CTOPEN_DATAONLY, the Rebuild() function can be used as a direct replacement for the c-tree Plus ctrbldif rebuild utility.

The following steps are performed by FairCom DB API during a table rebuild process:

1. If a transaction is active, and the table being rebuilt was created with CTCREATE_TRNLOG or CTCREATE_PREIMG, the transaction is committed before the table is rebuilt, and the transaction is restarted after the table rebuild process is completed.
2. The update corrupt flag, updflg, of the header of the data file is cleared.
3. The internal delete stack chain of fixed-length data files or the internal delete management index of variable length data files are rebuilt.
4. The existing index files are removed and new index files are rebuilt over the existing files, optimized for both size and speed.

You must open the table before Rebuild() is executed. It is recommended that the table be opened with CTOPEN_EXCLUSIVE mode. If the table is corrupt, you will need to open the table with the CTOPEN_CORRUPT mode and then call Rebuild() to rebuild the data and index files. If there are missing or corrupt index files, open the table with CTOPEN_DATAONLY mode and Rebuild() will reconstruct the missing index files.

There may be situations when you need to invoke this function to rebuild only the data file. After the data file rebuild is successful, you may need to call Rebuild() again to rebuild the index files.

Return Values

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

See Also

Alter()

CTTable::Remove

Removes any FairCom DB API table.

Declaration

void CTTable::Remove();

Description

The CTTable::Remove() function allows any table to be deleted, including tables that are not members of a database.

The CTTable::Remove() function deletes a c-tree data file and the associated index files from disk. If the table was opened under a database handle, the table is closed and CTDatabase::DeleteTable() is called. If the handle is not active, the table is opened exclusive and then deleted. If the table handle is not active, you must set the path, file extension and password for the handle before calling the RemoveTable() method.

A CTException is thrown when an error occurs. Use CTException::GetErrorCode() and CTException::GetErrorMsg() to retrieve the error code and descriptive message.

Return

void

Example

/* delete a FairCom DB API Table */
try {
   MyTable.Remove();
}
catch(CTException &E) {
   printf("MyTable.Remove error: (%d) - %s\n", 		E.GetErrorCode(),
          E.GetErrorMsg());
}

See Also

CTDatabase::DeleteTable()

CTTable::ResetAll

Syntax

void ResetAll( )

Parameters

This method has no parameters.

Description

Resets all active record buffers associated with the table

Return

None.

CTTable::SetDataDefaultExtentSize

Syntax

void SetDataDefaultExtentSize(const NINT size)

Parameters

• size [in] The default data extent size. The data extent default value is 8192 initially.

Description

Sets the c-tree data file default extent size. Each time the data file needs to be extended, it will use this value to extent the file. If not changed by SetDataDefaultExtentSize(), this value is 8192 bytes.

Return

None.

See also

GetDataDefaultExtentSize(), SetIndexDefaultExtentSize()

CTTable::SetDataExtension

Syntax

void SetDataExtension(const CTString& Ext)

Parameters

• Ext [in] The table extension, usually "dat" (default value).

Description

Sets the table data file extension. If not changed by SetDataExtension(), the data extension is "dat".

Return

None.

See also

GetDataExtension(), SetIndexExtension()

CTTable::SetFullTextIndexOption (by index object)

Set Full-Text Index options using the Full-Text Index object.

See CTTable::SetFullTextIndexOption (by index object)

CTTable::SetFullTextIndexOption (by name)

Set Full-Text Index options using the Full-Text Index name.

See CTTable::SetFullTextIndexOption (by name)

CTTable::SetFullTextIndexOption (by number)

Set Full-Text Index options using the Full-Text Index number.

See CTTable::SetFullTextIndexOption (by number)

CTTable::SetGroupid

Syntax

void SetGroupid(const CTString& Groupid)

Parameters

• Groupid [in] The new table Group id.

Description

Sets the table group id.

Return

None.

See also

GetGroupid()

CTTable::SetIndexDefaultExtentSize

Syntax

void SetIndexDefaultExtentSize(const NINT size)

Parameters

• size [in] The default index extent size. The index extent default value is 8192 initially.

Description

Sets the c-tree index file default extent size. Each time the index file needs to be extended, it will use this value to extent the file. If not changed by SetIndexDefaultExtentSize(), this value is 8192 bytes.

Return

None.

See also

GetIndexDefaultExtentSize(), SetDataDefaultExtentSize()

CTTable::SetIndexExtension

Syntax

void SetIndexExtension(const CTString& Ext)

Parameters

• Ext [in] The table index file extension, usually "idx" (default value).

Description

Sets the table index file extension. If not changed by SetIndexExtension(), the index extension is "idx".

Return

None.

See also

GetIndexExtension(), SetDataExtension()

CTTable::SetIndexFileName

Syntax

void CTTable::SetIndexFileName(NINT IndexNumber, const CTString* path,
                               const CTString* filename);
void CTTable::SetIndexFileName(const CTString& IndexName, const CTString* path,
                               const CTString* filename);

Parameters

These overloaded methods identify the index by number (IndexNumber) or by name (IndexName).

• path specifies the directory location of the index file. A NULL value for path indicates that the index file is to be located in the same directory as the data file.
• filename specifies the name of the index file. If filename is NULL, the index file name is cleared.

An application can change the current index file extension by calling the CTTable::SetIndexExtension() method.

Description

Sets the physical file name for the index.

Return

None.

See also

CTTable::GetIndexFileName(), CTTable::SetIndexExtension(), CTIndex::GetIndexFileName()

CTTable::SetOwner

Declaration

void CTTable::SetOwner(const CTString& owner)

Description

Sets the table owner. You should set the table owner before the table is created to allow the proper c-tree security setting to take place.

Return Values

None.

See Also

CTTable::GetOwner()

CTTable::SetPadChar

Syntax

void SetPadChar(NINT Padchar, NINT Dmlchar)

Parameters

• Padchar [in] pad character
• Dmlchar [in] field delimiter character

Description

Set the table pad and field delimiter characters in the table object. These characters are used to pad fixed string fields (CT_FSTRING) to allow proper target key formation.

Return

None.

See also

GetPadChar(), UpdatePadChar()

CTTable::SetPartitionIndexNbr

Set the Partition index number.

Syntax

void CTTable::SetPartitionIndexNbr(NINT idxno)

Parameters

idxno [IN] - The index number for partition key*

Return

Void.

See also

CTTable::SetPartitionIndexNbr CTTable:: CTTable::SetPartitionNumberBits CTTable::SetParitionRule CTTable::SetPartitionMaximumActive CTTable::GetPartitionIndexNbr

CTTable::SetPartitionMaximumActive

Set the number of maximum active partitions, when exceeding the maximum c-tree's auto purging feature takes care of purging.

Syntax

void CTTable::SetPartitionMaximumActive(UCOUNT max)

Parameters

• max [IN] - Number of maximum active partition members

Return

Void

See also

CTTable::SetPartitionIndexNbr CTTable:: CTTable::SetPartitionNumberBits CTTable::SetParitionRule CTTable::SetPartitionMaximumActive CTTable::GetPartitionIndexNbr

CTTable::SetPartitionNumberBits

Set the number of bits used to store the raw partition number. By default, 16 bits of the 64-bit record offset are used to reference the raw partition number, allowing each partitioned file to support up to 65535 member files over its lifetime. This function (when called before creating the file) allows adjusting this. A value of 0 defaults to 16 bits, values less than 4 bits default to 4 bits (maximum 15 member files), and 32 bits is the maximum value.

Syntax

void CTTable::SetPartitionNumberBits(UCOUNT bitno)

Parameters

• bitno [IN] - Number of bits to be used for raw partition number

Return

Void

See also

CTTable::SetPartitionIndexNbr CTTable:: CTTable::SetPartitionNumberBits CTTable::SetParitionRule CTTable::SetPartitionMaximumActive CTTable::GetPartitionIndexNbr

CTTable::SetPartitionRule

Set partition rule using an expression.

Syntax

void CTTable::SetPartitionRule(pTEXT expr)

Parameters

• expr [IN] - Expression that evaluates into an integer that will be used as partition number.

See Expression Filters section for details on supported expressions.

Return

Void

See also

CTTable::SetPartitionIndexNbr CTTable:: CTTable::SetPartitionNumberBits CTTable::SetParitionRule CTTable::SetPartitionMaximumActive CTTable::GetPartitionIndexNbr

CTTable::SetPassword

Syntax

void SetPassword(const CTString& Password)

Parameters

• Password [in] The new table password.

Description

Sets the table password

Return

None.

See also

GetPassword()

CTTable::SetPath

Syntax

void SetPath(const CTString& Path)

Parameters

• Path [in] the new table path.

Description

Sets the table path.

Return

None.

See also

GetPath()

CTTable::SetPermission

Syntax

void SetPermission(const LONG Permmask)

Parameters

• Permmask [in] The table permission mask. The valid values for the table permission mask are shown in "Table Permissions".

Description

Sets the table permission mask.

Return

None.

See also

GetPermission()

CTTable::SetTableKSeg

Establishes a table wide extended key segment definition.

Declaration

void CTTable::SetTableKSeg(pctKSEGDEF pKSeg);

Description

CTTable::SetTableKSeg() establishes a table wide extended key segment definition. pKSeg is a pointer to an extended key segment definition structure with the extended key definition.

Return

void

Example

ctKSEGDEF kseg;

kseg.kseg_ssiz = ctKSEG_SSIZ_COMPUTED;
kseg.kseg_type = ctKSEG_TYPE_UNICODE;
kseg.kseg_styp = ctKSEG_STYP_UTF16;
kseg.kseg_comp = ctKSEG_COMPU_S_DEFAULT | ctKSEG_COMPU_N_NONE;
kseg.kseg_desc = "en_US"
hTable.SetTableKSeg(&kseg);
 

See Also

CTIndex::GetIndexKSeg(), CTIndex::SetIndexKSeg(), CTSegment::GetSegmentKSeg(),
CTSegment::SetKSegDefaults(), CTSegment::SetSegmentKSeg(), CTTable::GetTableKSeg()

CTTable::SystemFilterOff

Deletes a permanent system wide record filter.

Declaration

void CTTable::SystemFilterOff(CTSYSFILTER mode);

Description

Deletes a permanent system wide record filter. The table must be opened exclusive and the user must have file definition permission for the table.

mode specifies one of the following:

• CTSYSFILTER_READ - Indicates you are deleting only a system wide read record filter.
• CTSYSFILTER_WRITE - Indicates you are deleting only a system wide write record filter
• CTSYSFILTER_READ | CTSYSFILTER_WRITE - Indicates you are deleting both a system wide read record filter and a system wide write record filter.

Return

On error CTTable::SystemFilterOff() throws a CTException exception object.

See Also

CTTable::SystemFilterOn()

CTTable::SystemFilterOn

Establishes a permanent system wide data record filter.

Declaration

void CTTable::SystemFilterOn(CTSYSFILTER mode);

Description

Establishes a permanent system wide, i.e. the filter applies to all users, read and/or write record filter. Depending on server file security setting, the table must be opened exclusive and the user must have file definition permission for the table. Once a read or a write filter is established, it can only be deleted by calling method CTTable::SystemFilterOff().

A table may have at most one read and one write system wide filter. A write filter will be called when data records are added, updated or deleted.

mode specifies one of the following:

• CTSYSFILTER_READ - Indicates you are deleting only a system wide read record filter.
• CTSYSFILTER_WRITE - Indicates you are deleting only a system wide write record filter
• CTSYSFILTER_READ | CTSYSFILTER_WRITE - Indicates you are deleting both a system wide read record filter and a system wide write record filter.

System wide filters must be callback filters. The actual callback evaluation takes place in a new callback function ctfiltercb_rowl() located in module ctclbk.c.

There different levels of security settings when users modify data file definition resources such as IFIL and DODA. The c-tree Server can be configured for three different levels of data file resource security:

FILEDEF_SECURITY_LEVEL LOW:
Lowest security setting. There is no protection as any user may add or delete data file definition resources. This setting may be used to keep the c-tree Server data compatible with legacy applications.

FILEDEF_SECURITY_LEVEL MEDIUM:
Default security setting. Any user may add or delete data file definition resources, but the file must be opened exclusive. This default setting may be enough to keep the c-tree Server data compatible with most legacy applications.

FILEDEF_SECURITY_LEVEL HIGH:
Highest security setting. A user must have file definition permission before a definition resource is added or deleted. The file must be opened exclusive. This setting is appropriate for applications that require the highest level of security and may cause compatibility problems with existing legacy applications.

Return

On error CTTable::SystemFilterOn() throws a CTException exception object.

Example

try
{
    // open an existing table
    hTable.Open("table_name", CTOPEN_EXCLUSIVE);
    // establish a new system wide read-write filter
    hTable.SystemFilterOn(CTSYSFILTER_READ | CTSYSFILTER_WRITE);
    // close the table
    hTable.Close();
}
catch (CTException &err)
{
    printf("Setting system filter failed with error %d\n", err.GetErrorCode());
}
 

See Also

CTTable::SystemFilterOff()

CTTable::Truncate

Removes all records from an existing table.

Declaration

void CTTable::Truncate();

Description

• Handle - open table handle.

CTTable::Truncate() truncates a data file, meaning a new copy of the file is created with no data records. File properties and resources are preserved. The function closes the table, truncates it, and reopens it. Return value of CTDBRET_OK indicates success.

Return

A CTException is thrown when an error occurs. Use CTException::GetErrorCode() and CTException::GetErrorMsg() to retrieve the error code and descriptive message.

Limitations

Requires data file to have an IFIL resource; otherwise, the function call fails with error RNOT_ERR (408, resource not found).

See Also

CTDatabase::DeleteTable()

CTTable::UnlockTable

Syntax

void UnlockTable( )

Parameters

None.

Description

Unlocks all record locks from the table, if they were obtained with a call to CTRecord::LockRecord(). To free a specific record lock obtained with LockRecord(), use CTRecord::UnlockRecord().

Return

None.

See also

CTRecord::LockRecord(), CTRecord::UnlockRecord(), Locking

CTTable::UpdateCreateMode

Syntax

void CTTable::UpdateCreateMode(CTCREATE_MODE mode)

Parameters

• mode [in] Represents the new table create mode. It must be perfectly formed, as it will replace the current table create mode. Use the method GetCreateMode() to retrieve the current crete mode and apply the changes on a fully qualified create mode. Update only the following create table modes:
  • CTCREATE_PREIMG
  • CTCREATE_TRNLOG
  • CTCREATE_WRITETHRU
  • CTCREATE_CHECKLOCK
  • CTCREATE_CHECKREAD
  • CTCREATE_HUGEFILE

Description

Update the table create mode. This method changed critical file mode attributes such as the level of transaction control.

No check is made to determine if the mode change will damage data. No check is made if the new mode is valid.

Note: Use this method with caution as data may be lost. For instance, changing a data file from transaction processing to no transaction processing make automatic recovery unavailable.

Return

None.

See also

Create()

CTTable::UpdatePadChar

Syntax

void UpdatePadChar(NINT Padchar, NINT Dmlchar, CTBOOL rebuild)

Parameters

• Padchar [in] pad character
• Dmlchar [in] field delimiter character
• rebuild [in] - NOT YET IMPLEMENTED. Indicates if the table should be rebuilt. If rebuild is set to YES, every record is read and the fixed string fields (CT_FSTRING) are padded according to new padding strategy.

Description

Update the table pad and delimiter character resource. The table must be opened exclusive to allow update of the resource.

Return

None.

See also

GetPadChar(), SetPadChar()

CTTable::~CTTable

Syntax

~CTTable

Parameters

This destructor has no parameters.

Description

This is the destructor for the CTTable class. It frees the allocated memory to the Table. No table operations are allowed after the CTTable destructor is called.

See also

CTTable()