Table

Data Structures
struct	db_fielddef_t
	Field definition. More...
struct	db_tabledef_t
	Table definition. More...
Functions
db_result_t	db_fielddef_init (db_fielddef_t *)
db_result_t	db_fielddef_destroy (db_fielddef_t *)
db_result_t	db_tabledef_init (db_tabledef_t *, db_heap_t heap)
db_result_t	db_tabledef_destroy (db_tabledef_t *)
db_result_t	db_tabledef_set_tabletype (db_tabledef_t *, db_tabletype_t)
db_result_t	db_tabledef_set_field_count (db_tabledef_t *, db_fieldno_t nfields)
db_result_t	db_tabledef_set_field (db_tabledef_t *, db_fieldno_t nfield, const db_fielddef_t *)
db_result_t	db_tabledef_set_fields (db_tabledef_t *, const db_fielddef_t *, db_fieldno_t nfields)
db_result_t	db_create_table (db_t, const db_objname_t *, const db_tabledef_t *, db_flags_t)
db_result_t	db_drop_table (db_t, const db_objname_t *)
db_result_t	db_describe_table (db_t, const db_objname_t *, db_tabledef_t *, db_flags_t)
db_result_t	db_add_field (db_t, const db_objname_t *table, const db_fielddef_t *)
db_result_t	db_drop_field (db_t, const db_objname_t *table, const db_objname_t *field)
Field Flags
#define	DB_NULLABLE   _DB_NULLABLE
#define	DB_NOT_NULL   _DB_NOT_NULL
#define	DB_NULL_MASK   _DB_NULL_MASK
Table Types
#define	DB_TABLETYPE_DEFAULT   _DB_TABLETYPE_DEFAULT
#define	DB_TABLETYPE_KHEAP   _DB_TABLETYPE_KHEAP
#define	DB_TABLETYPE_MEMORY   _DB_TABLETYPE_MEMORY
#define	DB_TABLETYPE_CLUSTERED   _DB_TABLETYPE_CLUSTERED

---

Detailed Description

A table is composed of fields.

---

Define Documentation

#define DB_NULLABLE   _DB_NULLABLE

Field can be NULL.

Examples:

phonebook_c_schema.c.

#define DB_TABLETYPE_DEFAULT   _DB_TABLETYPE_DEFAULT

Default table type.

Examples:

phonebook_c_schema.c.

#define DB_NOT_NULL   _DB_NOT_NULL

Field cannot be NULL.

Examples:

phonebook_c_schema.c.

#define DB_TABLETYPE_KHEAP   _DB_TABLETYPE_KHEAP

Key heap table type, stored on disk.

#define DB_TABLETYPE_MEMORY   _DB_TABLETYPE_MEMORY

Memory table, stored on in-memory storage.

#define DB_TABLETYPE_CLUSTERED   _DB_TABLETYPE_CLUSTERED

Clustered table, stored on disk and grouped by a clustering index.

---

Function Documentation

db_result_t db_fielddef_init

(

db_fielddef_t *

fdef

)

Initialize a field schema definition.

Parameters:

fdef	Address of a field configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Field configuration is null.

See also:

db_fielddef_destroy,
get_db_error, clear_db_error, Error Handling.

db_result_t db_fielddef_destroy

(

db_fielddef_t *

fdef

)

Destroy a field schema definition.

Parameters:

fdef	Field configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

• DB_EINVAL Field configuration is null.

See also:

db_fielddef_init,
get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_init	(	db_tabledef_t *	tdef,
		db_heap_t	heap
	)

Initialize a table definition.

Parameters:

tdef	Table configuration.
heap	Pointer to heap.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

• DB_EINVAL Caused by: table configuration is null.

See also:

db_tabledef_destroy,
get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_destroy

(

db_tabledef_t *

tdef

)

Destroy a table definition.

Unlock a database object.

Parameters:

tdef	Table configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Table configuration is null.

See also:

db_tabledef_init,
get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_set_tabletype	(	db_tabledef_t *	tdef,
		db_tabletype_t	type
	)

Set the table type for a table definition.

Parameters:

tdef	Table configuration.
type	Table type. DB_TABLETYPE_DEFAULT DB_TABLETYPE_KHEAP

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: table configuration is null, table type is neither DB_TABLETYPE_DEFAULT nor DB_TABLETYPE_KHEAP.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_set_field_count	(	db_tabledef_t *	tdef,
		db_fieldno_t	nfields
	)

Set the number of fields in a table definition.

Parameters:

tdef	Table configuration.
nfields	Number of fields.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: table configuration is null, number of fields < 0.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_set_field	(	db_tabledef_t *	tdef,
		db_fieldno_t	nfield,
		const db_fielddef_t *	field
	)

Set a field in a table definition.

Parameters:

tdef	Table configuration.
nfield	Number of field.
field	Field configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Table configuration is null.
• DB_ERANGE Caused by: field number < 0, field number >= table fields size.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_set_fields	(	db_tabledef_t *	tdef,
		const db_fielddef_t *	fields,
		db_fieldno_t	nfields
	)

Set all of the fields for a table definition.

Parameters:

tdef	Table configuration.
fields	Field configuration(s).
nfields	Number of fields.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Table configuration is null.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_create_table	(	db_t	hdb,
		const db_objname_t *	table,
		const db_tabledef_t *	param,
		db_flags_t	flags
	)

Create a table in a database using a table schema definition.

Parameters:

hdb	Database handle.
table	Table name. A name must start with a letter and can be followed by one or more letters, numbers, or underscores.
param	Table definition parameters. Field names must start with a letter and can be followed by one or more letters, numbers, or underscores.
flags	Reserved for future use. Set to zero.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid database handle, table name is null, table definition is null, fields in table definition is null, field count in table definition <=0. .
• DB_ENAME Table name is not in a valid format.
• DB_EFIELD Invalid field name.
• DB_ERECORDSIZE Record size too large for chosen page size.
• DB_EDUPLICATE Table with given name already exists.

Invariant:

No transaction is active on hdb.

Note:

This function does not create indexes, unless the table is clustered, or foreign keys. Use db_create_index and db_create_foreign_key to add indexes and foreign keys to the table after it has been created.

If param->table_type is DB_TABLETYPE_CLUSTERED, a clustering index must be supplied in param->indexes. The index_mode for that index must be set to DB_CLUSTERING_INDEX | DB_PRIMARY_INDEX and all index fields must have the flag DB_NOT_NULL.

See also:

db_drop_table,
get_db_error, clear_db_error, Error Handling

db_result_t db_drop_table	(	db_t	hdb,
		const db_objname_t *	name
	)

Drop a table from a database.

Parameters:

hdb	Database handle.
name	Table name. A name must start with a letter and can be followed by one or more letters, numbers, or underscores.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Casued by: invalid database handle.
• DB_ENAME Table name is not in a valid format.
• DB_ELOCKED Table is locked by cursor or concurrent transaction.
• DB_ETXSTATE A transaction is active.

Invariant:

No transaction is active on hdb.

A table can only be altered or dropped when there is no active transaction. If a transaction has been started, db_commit_tx or db_abort_tx must be used before db_drop_table can be called.

See also:

db_create_table,
get_db_error, clear_db_error, Error Handling

db_result_t db_describe_table	(	db_t	hdb,
		const db_objname_t *	name,
		db_tabledef_t *	param,
		db_flags_t	flags
	)

Obtain the schema definition for a table in a database.

Parameters:

hdb	Database handle.
name	Table name. A name must start with a letter and can be followed by one or more letters, numbers, or underscores.
param	Table configuration.
flags	DB_DESCRIBE_TABLE_FIELDSObtain information about fields. DB_DESCRIBE_TABLE_INDEXESObtain information about indexes.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid database handle, table name is null, table configuration is null, invalid flags, index defintion is null, index field is null.
• DB_ENAME Table name is not in a valid format.

See also:

db_create_table,
get_db_error, clear_db_error, Error Handling

db_result_t db_add_field	(	db_t	hdb,
		const db_objname_t *	table,
		const db_fielddef_t *	field_def
	)

Add a field to an existing table.

Parameters:

hdb	Database handle.
table	Table name.
field_def	Field configuration. A field name must start with a letter and can be followed by one or more letters, numbers, or underscores.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid database handle, table is null, field configuration is null.
• DB_ENAME Invalid field name.
• DB_EBINDSIZE Invalid bind size. Datatype and size dont match.
• DB_ETABLE Table error. Field size=0.
• DB_EFIELD Caused by: invalid name, index field can not be blob type.
• DB_EDUPLICATEFIELDS Can not create duplicate fields.
• DB_EINDEX Index error. Two indexes are eqivalent.
• DB_ELOCKED Table is locked by cursor or concurrent transaction.
• DB_ETXSTATE A transaction is active.
• DB_ENULLFIELD New field is NOT NULL and table is not empty.

Invariant:

No transaction is active on hdb.

A table can only be altered or dropped when there is no active transaction. If a transaction has been started, db_commit_tx or db_abort_tx must be used before db_drop_table can be called.

See also:

db_rename_field, db_update_field, db_drop_field,
get_db_error, clear_db_error, Error Handling

db_result_t db_drop_field	(	db_t	hdb,
		const db_objname_t *	table,
		const db_objname_t *	field
	)

Drop a field from a table.

Parameters:

hdb	Database handle.
table	Table name.
field	Field name. A name must start with a letter and can be followed by one or more letters, numbers, or underscores.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid database handle, unable to open database file.
• DB_ENAME Invalid field name.
• DB_EFIELD General field error.
• DB_ENOTFOUND Field not found.
• DB_EINDEX Field is used by an index. Remove field from index first.
• DB_ELOCKED Table is locked by cursor or concurrent transaction.
• DB_ETXSTATE A transaction is active.

Invariant:

No transaction is active on hdb.

A table can only be altered or dropped when there is no active transaction. If a transaction has been started, db_commit_tx or db_abort_tx must be used before db_drop_table can be called.

See also:

db_add_field, db_rename_field, db_update_field,
get_db_error, clear_db_error, Error Handling