FairCom DB API for C

ctdbCreateTable

Create a new table.

Declaration

CTDBRET ctdbCreateTable(CTHANDLE Handle, pTEXT TableName,

CTCREATE_MODE CreateMode)

Description

ctdbCreateTable() creates a new table.

To give the new table a password, call ctdbSetTablePassword() with Handle before calling this function.

To create a session, use ctdbCreateSession().

To create a database, use ctdbCreateDatabase().

To retrieve the table create mode, use ctdbGetTableCreateMode().

To open an existing table, use ctdbOpenTable().

The default directory for the table creation is the server directory (client/server applications) or the execution directory (standalone applications). To change the directory, call ctdbSetTablePath() to set the new directory before creating the table. In order to create the table, its fields, indexes and segments must be created first using, for instance, ctdbAddField(), ctdbAddIndex(), ctdbAddSegment().

Note that the create table process does not leave the table open after the table is created. The new table must be explicitly opened before it is used; see ctdbOpenTable().

Care should be exercised when selecting the table create mode. For example, if you wish to use transaction processing (the ctdbBegin(), ctdbCommit(), and ctdbAbort() functions) to ensure atomicity, then it is important to create the table using the CTCREATE_PREIMG or the CTCREATE_TRNLOG mode, and not the CTCREATE_NORMAL mode. See the Transactions section in Data Integrity for more details.

Handle [in] the table handle.
TableName [in] the table name.
CreateMode [in] the table create mode. The valid values for the table create mode are listed in FairCom DB API Table Create Modes.

Mirrored Files

The FairCom mirroring feature makes it possible to store important files on different drive volumes, partitions or physical drives. If the primary storage location is damaged or lost, the mirroring logic will automatically detect the situation and switch to the secondary or "mirrored" storage area.

The mirrored file is easily specified by appending a vertical bar ( | ) after the table name followed by the table mirror name. For example, to mirror a table named "customer" to "mirror", specify the table name as "customer|mirror". If no path is specified for the mirrored table, both tables will be located in the same directory. If the primary table and the mirrored table are to be located in different directories, then the path names must be specified the same way as the table names: "primary-path|mirrored-path".To create a mirrored table, use the ctdbCreateTable() function passing as the table name a proper mirrored naming convention:

if (ctdbCreateTable(hTable, "customer|mirror", CTCREATE_TRNLOG) )

printf("Create table failed\n");

If you need to specify different locations for the mirrored tables, use ctdbSetTablePath() to specify the mirrored paths:

if (ctdbSetTablePath(hTable, "primary_path|mirrored_path"))

printf("ctdbSetTablePath failed\n");

Under c-tree Server operation, all mirroring can be suspended by adding the following entry to the server configuration file (ctsrvr.cfg):

MIRRORS NO

This may be useful when the mirroring hardware is not operational and the use of the primary data is necessary. By default, read and write operations on mirrored tables will continue without returning an error if either one of the files fail, but the other succeeds. When this happens, the failed file is shut down and subsequent I/O operations continue only with the remaining "good" file. If mirroring is used in the client/server model, the SystemMonitor() function receives an event when one of the files succeed and the other fails.

Note: The FairCom DB API alter table function will not operate on mirrored tables. If ctdbAlterTable() is called for a mirrored table, nothing is done and it returns error CTDBRET_NOTSUPPORTED.

Mirroring is supplied for c-tree Server and single-user operations. It applies to all c-tree file modes including transaction processing. Once a table is created and opened with mirroring, all subsequent table opens must be mirrored (ctdbOpenTable() called with two table names separated by the vertical bar ( | )), except when the table is opened in exclusive mode (ctdbOpenTable()’s third parameter).

Returns

ctdbCreateTable() returns CTDBRET_OK on success or the FairCom DB API error code on failure.

Example

pMyTable = ctdbAllocTable(pMySession);

pMyField = ctdbAddField(pMyTable, "Name", CT_FSTRING,32);

pMyIndex = ctdbAddIndex(pMyTable, "iName", CTINDEX_FIXED,NO,NO);

pMyIseg = ctdbAddSegment(pMyIndex, pMyField, 2);

RetVal = ctdbCreateTable(pMyTable,"Table1",CTCREATE_NORMAL);