All data operations are performed in the context of a WT_SESSION. More...

Public Member Functions
int	close (WT_SESSION session, const char config)
	Close the session handle.
Cursor handles
int	open_cursor (WT_SESSION session, const char uri, WT_CURSOR to_dup, const char config, WT_CURSOR **cursorp)
	Open a cursor.
Table operations
int	create (WT_SESSION session, const char name, const char *config)
	Create a table, column group, index or file.
int	drop (WT_SESSION session, const char name, const char *config)
	Drop (delete) an object.
int	rename (WT_SESSION session, const char oldname, const char newname, const char config)
	Rename an object.
int	salvage (WT_SESSION session, const char name, const char *config)
	Salvage a file or table.
int	sync (WT_SESSION session, const char name, const char *config)
	Sync a file or table.
int	truncate (WT_SESSION session, const char name, WT_CURSOR start, WT_CURSOR stop, const char *config)
	Truncate a file, table or a cursor range.
int	upgrade (WT_SESSION session, const char name, const char *config)
	Upgrade a file or table.
int	verify (WT_SESSION session, const char name, const char *config)
	Verify a file or table.
Transactions
int	begin_transaction (WT_SESSION session, const char config)
	Start a transaction in this session.
int	commit_transaction (WT_SESSION session, const char config)
	Commit the current transaction.
int	rollback_transaction (WT_SESSION session, const char config)
	Roll back the current transaction.
int	checkpoint (WT_SESSION session, const char config)
	Flush the cache and/or the log and optionally archive log files.
Debugging
int	dumpfile (WT_SESSION session, const char name, const char *config)
	Dump a physical file in debugging mode.
int	msg_printf (WT_SESSION session, const char fmt,...)
	Send a string to the message handler for debugging.
Public Attributes
WT_CONNECTION *	connection
	The connection for this session.

Detailed Description

All data operations are performed in the context of a WT_SESSION.

This encapsulates the thread and transactional context of the operation.

Thread safety: A WT_SESSION handle cannot be shared between threads: it may only be used within a single thread. Each thread accessing a database should open a separate WT_SESSION handle.

Examples:: ex_access.c, ex_all.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_hello.c, ex_pack.c, ex_schema.c, ex_stat.c, ex_thread.c, and ex_transaction.c.

Member Function Documentation

int WT_SESSION::begin_transaction	(	WT_SESSION *	session,
		const char *	config
	)

Start a transaction in this session.

Not yet supported in WiredTiger.

All cursors opened in this session that support transactional semantics will operate in the context of the transaction. The transaction remains active until ended with WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction.

Ignored if a transaction is in progress.

        ret = session->begin_transaction(session, NULL);

Parameters:

session the session handle

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`isolation`	the isolation level for this transaction.	a string, chosen from the following options: `"serializable"`, `"snapshot"`, `"read-committed"`, `"read-uncommitted"`; default `read-committed`.
`name`	name of the transaction for tracing and debugging.	a string; default empty.
`priority`	priority of the transaction for resolving conflicts. Transactions with higher values are less likely to abort.	an integer between -100 and 100; default `0`.
`sync`	how to sync log records when the transaction commits.	a string, chosen from the following options: `"full"`, `"flush"`, `"write"`, `"none"`; default `full`.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c, ex_config.c, and ex_transaction.c.

int WT_SESSION::checkpoint	(	WT_SESSION *	session,
		const char *	config
	)

Flush the cache and/or the log and optionally archive log files.

Not yet supported in WiredTiger.

        ret = session->checkpoint(session, NULL);

Parameters:

session the session handle

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`archive`	remove log files no longer required for transactional durability.	a boolean flag; default `false`.
`flush_cache`	flush the cache.	a boolean flag; default `true`.
`flush_log`	flush the log to disk.	a boolean flag; default `true`.
`force`	write a new checkpoint even if nothing has changed since the last one.	a boolean flag; default `false`.
`log_size`	only proceed if more than the specified number of bytes of log records have been written since the last checkpoint.	an integer greater than or equal to 0; default `0`.
`timeout`	only proceed if more than the specified number of milliseconds have elapsed since the last checkpoint.	an integer greater than or equal to 0; default `0`.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::close	(	WT_SESSION *	session,
		const char *	config
	)

Close the session handle.

This will release the resources associated with the session handle, including rolling any active transactions and closing any cursors that remain open in the session.

        ret = session->close(session, NULL);

Parameters:

session	the session handle
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c, and ex_thread.c.

int WT_SESSION::commit_transaction	(	WT_SESSION *	session,
		const char *	config
	)

Commit the current transaction.

Not yet supported in WiredTiger.

Any cursors opened during the transaction will be closed before the commit is processed.

Ignored if no transaction is in progress.

        ret = session->commit_transaction(session, NULL);

Parameters:

session	the session handle
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c, ex_config.c, and ex_transaction.c.

int WT_SESSION::create	(	WT_SESSION *	session,
		const char *	name,
		const char *	config
	)

Create a table, column group, index or file.

        ret = session->create(session, "table:mytable",
            "key_format=S,value_format=S");

Parameters:

session the session handle

name the URI of the object to create, such as "table:stock"

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`allocation_size`	the file unit allocation size, in bytes, must a power-of-two; smaller values decrease the file space required by overflow items, and the default value of 512B is a good choice absent requirements from the operating system or storage device.	an integer between 512B and 128MB; default `512B`.
`block_compressor`	configure a compressor for file blocks. Permitted values are empty (off) or `"bzip2"`, `"snappy"` or custom compression engine `"name"` created with WT_CONNECTION::add_compressor. See Compressors for more information.	a string; default empty.
`checksum`	configure file block checksums; if false, the block manager is free to not write or check block checksums. This can increase performance in applications where compression provides checksum functionality or read-only applications where blocks require no verification.	a boolean flag; default `true`.
`colgroups`	comma-separated list of names of column groups. Each column group is stored separately, keyed by the primary key of the table. If no column groups are specified, all columns are stored together in a single file. All value columns in the table must appear in at least one column group. Each column group must be created with a separate call to WT_SESSION::create.	a list of strings; default empty.
`collator`	configure custom collation for keys. Value must be a collator name created with WT_CONNECTION::add_collator.	a string; default empty.
`columns`	list of the column names. Comma-separated list of the form `(column[,...])`. For tables, the number of entries must match the total number of values in `key_format` and `value_format`. For colgroups and indices, all column names must appear in the list of columns for the table.	a list of strings; default empty.
`exclusive`	fail if the object exists. When false (the default), if the object exists, check that its settings match the specified configuration.	a boolean flag; default `false`.
`filename`	override the default filename derived from the object name.	a string; default empty.
`huffman_key`	configure Huffman encoding for keys. Permitted values are empty (off), `"english"`, `"utf8<file>"` or `"utf16<file>"`. See Huffman Encoding for more information.	a string; default empty.
`huffman_value`	configure Huffman encoding for values. Permitted values are empty (off), `"english"`, `"utf8<file>"` or `"utf16<file>"`. See Huffman Encoding for more information.	a string; default empty.
`internal_item_max`	the maximum key size stored on internal nodes, in bytes. If zero, a maximum is calculated to permit at least 8 keys per internal page.	an integer greater than or equal to 0; default `0`.
`internal_key_truncate`	configure internal key truncation, discarding unnecessary trailing bytes on internal keys.	a boolean flag; default `true`.
`internal_page_max`	the maximum page size for internal nodes, in bytes; the size must be a multiple of the allocation size and is significant for applications wanting to avoid excessive L2 cache misses while searching the tree.	an integer between 512B and 512MB; default `2KB`.
`key_format`	the format of the data packed into key items. See Format types for details. By default, the key_format is `'u'` and applications use WT_ITEM structures to manipulate raw byte arrays. By default, records are stored in row-store files: keys of type `'r'` are record numbers and records referenced by record number are stored in column-store files.	a format string; default `u`.
`key_gap`	the maximum gap between instantiated keys in a Btree leaf page, constraining the number of keys processed to instantiate a random Btree leaf page key.	an integer greater than or equal to 0; default `10`.
`leaf_item_max`	the maximum key or value size stored on leaf nodes, in bytes. If zero, a size is calculated to permit at least 8 items (values or row store keys) per leaf page.	an integer greater than or equal to 0; default `0`.
`leaf_page_max`	the maximum page size for leaf nodes, in bytes; the size must be a multiple of the allocation size, and is significant for applications wanting to maximize sequential data transfer from a storage device.	an integer between 512B and 512MB; default `1MB`.
`prefix_compression`	configure row-store format key prefix compression.	a boolean flag; default `true`.
`split_pct`	the Btree page split size as a percentage of the maximum Btree page size, that is, when a Btree page is split, it will be split into smaller pages, where each page is the specified percentage of the maximum Btree page size.	an integer between 25 and 100; default `75`.
`type`	the file type.	a string, chosen from the following options: `"btree"`; default `btree`.
`value_format`	the format of the data packed into value items. See Format types for details. By default, the value_format is `'u'` and applications use a WT_ITEM structure to manipulate raw byte arrays. Value items of type 't' are bitfields, and when configured with record number type keys, will be stored using a fixed-length store.	a format string; default `u`.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_access.c, ex_all.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_schema.c, ex_stat.c, and ex_thread.c.

int WT_SESSION::drop	(	WT_SESSION *	session,
		const char *	name,
		const char *	config
	)

Drop (delete) an object.

        ret = session->drop(session, "table:mytable", NULL);

Parameters:

session the session handle

name the URI of the object to drop, such as "table:stock"

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`force`	return success if the object does not exist.	a boolean flag; default `false`.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::dumpfile	(	WT_SESSION *	session,
		const char *	name,
		const char *	config
	)

Dump a physical file in debugging mode.

The specified file is displayed in a non-portable debugging mode to the application's standard output.

        ret = session->dumpfile(session, "file:myfile", NULL);

Parameters:

session	the session handle
name	the URI of the file to dump
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::msg_printf	(	WT_SESSION *	session,
		const char *	fmt,
			...
	)

Send a string to the message handler for debugging.

        ret = session->msg_printf(session, "process pid %lu", mypid);

Parameters:

session	the session handle
fmt	a printf-like format specification

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::open_cursor	(	WT_SESSION *	session,
		const char *	uri,
		WT_CURSOR *	to_dup,
		const char *	config,
		WT_CURSOR **	cursorp
	)

Open a cursor.

Open a new cursor on the specified data source. Cursor handles should be discarded by calling WT_CURSOR::close.

Cursors are light-weight objects but may hold references to heavier-weight objects. Applications should usually not cache cursors as a performance optimization, instead, a new cursor should be opened for new groups of operations.

Cursors are opened in the context of the current transaction. The cursor must be closed before the transaction can end. If WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction are called with cursors open in the transaction, the cursor handles will be closed implicitly and must not be accessed again.

An existing cursor can be duplicated by passing it as the to_dup parameter and setting the uri parameter to NULL, otherwise the to_dup parameter should be NULL.

        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &cursor);

Parameters:

session the session handle

uri

the data source on which the cursor operates; cursors are usually opened on tables, however, cursors can be opened on any data source, regardless of whether it is ultimately stored in a table. Some cursor types may have limited functionality (for example, be read-only or not support transactional updates). See Cursor types for more information.
The following are the builtin cursor types:

URI	Type	Key/Value types
`colgroup:<tablename>.<columnset>`	column group cursor	table key, column group value(s)
`table:<tablename>`	table cursor	table key, table value(s)
`file:<filename>`	file cursor	file key, file value(s)
`index:<tablename>.<indexname>`	index cursor	key=index key, value=table value(s)
`statistics:[file:<filename>]`	database or file statistics cursor	key=`int id`, value=(`string description, string value, uint64_t value`), see Statistics cursors for details

to_dup a cursor to duplicate

session the session handle

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`append`	only supported by cursors with record number keys: append the value as a new record, creating a new record number key.	a boolean flag; default `false`.
`bulk`	configure the cursor for bulk loads; bulk-load is a fast load path for empty objects, only empty objects may be bulk-loaded.	a boolean flag; default `false`.
`clear_on_close`	for statistics cursors, reset statistics counters when the cursor is closed.	a boolean flag; default `false`.
`dump`	configure the cursor for dump format inputs and outputs: "hex" selects a simple hexadecimal format, "print" selects a format where only non-printing characters are hexadecimal encoded. The cursor dump format is compatible with the wt dump and wt load commands.	a string, chosen from the following options: `"hex"`, `"print"`; default empty.
`isolation`	the isolation level for this cursor, ignored for transactional cursors.	a string, chosen from the following options: `"snapshot"`, `"read-committed"`, `"read-uncommitted"`; default `read-committed`.
`overwrite`	change the behavior of the cursor's insert method to overwrite previously existing values.	a boolean flag; default `false`.
`raw`	ignore the encodings for the key and value, manage data as if the formats were `"u"`. See Raw mode for details.	a boolean flag; default `false`.
`statistics`	configure the cursor for statistics.	a boolean flag; default `false`.

cursorp a pointer to the newly opened cursor

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_access.c, ex_all.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_schema.c, ex_stat.c, and ex_thread.c.

int WT_SESSION::rename	(	WT_SESSION *	session,
		const char *	oldname,
		const char *	newname,
		const char *	config
	)

Rename an object.

        ret = session->rename(session, "table:old", "table:new", NULL);

Parameters:

session	the session handle
oldname	the current URI of the object, such as `"table:old"`
newname	the new name of the object, such as `"table:new"`
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::rollback_transaction	(	WT_SESSION *	session,
		const char *	config
	)

Roll back the current transaction.

Not yet supported in WiredTiger.

Any cursors opened during the transaction will be closed before the rollback is processed.

Ignored if no transaction is in progress.

        ret = session->rollback_transaction(session, NULL);

Parameters:

session	the session handle
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::salvage	(	WT_SESSION *	session,
		const char *	name,
		const char *	config
	)

Salvage a file or table.

Salvage rebuilds the file, or files of which a table is comprised, discarding any corrupted file blocks.

Previously deleted records may re-appear, and inserted records may disappear, when salvage is done, so salvage should not be run unless it is known to be necessary. Normally, salvage should be called after a file or table has been corrupted, as reported by the WT_SESSION::verify method.

Files are rebuilt in place, the salvage method overwrites the existing files.

        ret = session->salvage(session, "table:mytable", NULL);

Parameters:

session the session handle

name the URI of the file or table to salvage

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`force`	force salvage even of files that do not appear to be WiredTiger files.	a boolean flag; default `false`.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::sync	(	WT_SESSION *	session,
		const char *	name,
		const char *	config
	)

Sync a file or table.

Flush dirty pages from a table to stable storage. Note that not all pages are necessarily flushed (pages pinned in memory, or in use by other threads of control may not be written until all open session handles for the table are closed).

        ret = session->sync(session, "table:mytable", NULL);

Parameters:

session	the session handle
name	the URI of the file or table to sync
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::truncate	(	WT_SESSION *	session,
		const char *	name,
		WT_CURSOR *	start,
		WT_CURSOR *	stop,
		const char *	config
	)

Truncate a file, table or a cursor range.

        ret = session->truncate(session, "table:mytable", NULL, NULL, NULL);

        WT_CURSOR *start, *stop;

        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &start);
        start->set_key(start, "June01");
        ret = start->search(start);

        ret = session->open_cursor(
            session, "table:mytable", NULL, NULL, &stop);
        stop->set_key(stop, "June30");
        ret = stop->search(stop);

        ret = session->truncate(session, NULL, start, stop, NULL);

Parameters:

session	the session handle
name	the URI of the file or table to truncate
start	optional cursor marking the first record discarded; if `NULL`, the truncate starts from the beginning of the table
stop	optional cursor marking the last record discarded; if `NULL`, the truncate continues to the end of the table
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::upgrade	(	WT_SESSION *	session,
		const char *	name,
		const char *	config
	)

Upgrade a file or table.

Upgrade upgrades a file, or the files of which a table is comprised.

        ret = session->upgrade(session, "table:mytable", NULL);

Parameters:

session	the session handle
name	the URI of the file or table to upgrade
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

int WT_SESSION::verify	(	WT_SESSION *	session,
		const char *	name,
		const char *	config
	)

Verify a file or table.

Verify reports if a file, or the files of which a table is comprised, have been corrupted. The WT_SESSION::salvage method can be used to repair a corrupted file,

        ret = session->verify(session, "table:mytable", NULL);

Parameters:

session	the session handle
name	the URI of the file or table to verify
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns:: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_all.c.

Member Data Documentation

WT_CONNECTION* WT_SESSION::connection

The connection for this session.

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation