c-treeDB API for C++ - Developers Guide

Table Properties

c-treeDB tables have a number of properties that can be set when the table is created or with "set" and "get" functions.

In This Section Table name Table Path Table file extension Index file extension Data file extent size Index file extent size Table password Table group ID Table permission mask Number of fields Number of indexes Field padding Update create mode

Table name

The table name is a read only property as it can’t be changed once the table is created. Use CTTable::GetName() to retrieve the table name.

Table Path

The table path property is by default set to NULL. If this property is not changed prior to a CTTable::Create() call, the table is created in the same directory the database is located. Change the table path property with CTTable::SetPath(). CTTable::GetPath() retrieves the current table path.

Table file extension

The table data file extension is by default set to ".dat". Change the default data file extension with CTTable::SetDataExtension(). CTTable::GetDataExtension() retrieves the current data file extension for the table.

Index file extension

The table index file extension is by default set to ".idx". Change the default index file extension with CTTable::SetIndexExtension(). CTTable::GetIndexExtension() retrieves the current index file extension for the table.

Data file extent size

The data file extent is the default size by which the data file is extended when necessary. This value is 0 bytes by default. If there is the need to change it, use CTTable::SetDataDefaultExtentSize(). To retrieve the index default extent size, use CTTable::GetDataDefaultExtentSize().

Index file extent size

The index file extent is the default size by which the index file is extended when necessary. This value is 0 bytes by default. If there is the need to change it, use CTTable::SetIndexDefaultExtentSize(). To retrieve the index default extent size, use CTTable::GetIndexDefaultExtentSize().

Table password

By default tables do not have a password, i.e. the password property is set to NULL. If a table is to be created with a password, change this property before creating the table. To set the password use CTTable::SetPassword(), and CTTable::GetPassword() to retrieve it.

Table group ID

The group ID can be used to manage table permissions for multiple users. By default, no group ID settings are specified for c-treeDB tables, i.e. the default group ID value is NULL. If a table is to be created with a group ID, set the value of this property before creating the table. To set a group ID, use CTTable::SetGroupid() and CTTable::GetGroupid() to retrieve it.

Table permission mask

The permission mask is set at table creation and specifies a permission mask that determines the kind of access that users may acquire on subsequent opens. The mask is comprised of three components: owner permissions, group permissions and world permissions. With this structure, you are able to allow different users different levels of access to the file.

The default permission mask is set to (OPF_ALL | GPF_READ | GPF_WRITE | WPF_READ | WPF_WRITE).

To set the table permissions, use CTTable::SetPermission().

To retrieve the permission mask, use CTTable::GetPermission().

The valid permission mask values are: 

c-treeDB Permission Constant	c-treeDB .NET Permission Constant	Explanation
OPF_READ	O_READ	owner read permission
OPF_WRITE	O_WRITE	owner write/update permission
OPF_DEF	O_DEF	owner file definition permission
OPF_DELETE	O_DELETE	owner file deletion permission
OPF_ALL	O_ALL	owner granted all permissions
OPF_NOPASS	O_NOPASS	owner grants read only without password
GPF_NONE	G_NONE	group access denied
GPF_READ	G_READ	group read permission
GPF_WRITE	G_WRITE	group write/update permission
GPF_DEF	G_DEF	group file definition permission
GPF_DELETE	G_DELETE	group file deletion permission
GPF_NOPASS	G_NOPASS	group read only access without password
WPF_NONE	W_NONE	world access denied
WPF_READ	W_READ	world read permission
WPF_WRITE	W_WRITE	world write/update permission
WPF_DEF	W_DEF	world file definition permission
WPF_DELETE	W_DELETE	world file deletion permission
WPF_NOPASS	W_NOPASS	world read only access without password

Number of fields

The "number of fields" property indicates the total number of fields defined for a table. The value takes in consideration only user defined fields and does not include any hidden fields that exist for the table. Use CTTable::GetFieldCount() method to retrieve the number of fields associated with a table.

Number of indexes

The number of indexes property indicates the total number of indexes defined for a table. The value takes in consideration only user defined indexes and does not include the RECBYT or ROWID indexes. Use CTTable::GetIndexCount() method to retrieve the number of indexes associated with a table.

Field padding

By default the c-treeDB API pad fixed length string fields CT_CHARS (CT_FSTRING), CT_FPSTRING, CT_F2STRING and CT_F4STRING with Nulls (‘\0’) bytes. The field padding property sets the table pad and field delimiter characters to allow proper target key formation. This property allows the c-treeDB API to operate on files created using the c-tree Plus ISAM and low level APIs using a fixed string padding strategy that is different from the c-treeDB API default.

Use CTTable::SetPadChar() to set the pad and field delimiter character. CTTable::GetPadChar() retrieves the current pad and field delimiter character.

// set the table pad and delimiter characters to spaces

try

{
ATable.SetPadChar(' ', ' ');

}

catch (CTException &err)

{

printf("Set pad character failed with error %d\n", err.GetErrorCode());

}

The most common strategies for padding fixed string fields are:

• Pad with Nulls: pad character is ‘\0’ and field delimiter is ‘\0’
• Pad with spaces: pad character is ‘ ’ and field delimiter is ‘ ’
• Pad with spaces and terminate with NUL: pad character is ‘ ’ and field delimiter is ‘\0’

Update create mode

Use the update table create mode property to change the table create mode after the table has been created. use the function ctdbUpdateCreateMode() to change the table create mode. You can only update the create mode if the table was opened in exclusive mode.

// create a new table object

CTTable ATable(ADatabase);

// open the table exclusive

ATable.Open("MyTable", CTOPEN_EXCLUSIVE);

// update the table create mode

try

{

// retrieve the current create mode

CTCREATE_MODE curmode = ATable.GetCreateMode();

// add transaction processing

curmode |= CTCREATE_TRNLOG;

// update the table create mode

ATable.UpdateCreateMode(CTCREATE_TRNLOG);

}

catch (CTException &err)

{

printf("Update create mode failed with error %d\n", err.GetErrorCode());

}

CTTable::UpdateCreateMode() changes 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. Use this function with caution as data may be lost. For instance, changing a data file from transaction processing to no transaction processing makes automatic recovery unavailable.

The mode parameter passed to CTTable::UpdateCreateMode() represents the new table create mode. It must be perfectly formed, as it will replace the current table create mode. Use the function ctdbGetTableCreateMode() to retrieve the current create 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