WT_SESSION Struct Reference

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. More...
int	reconfigure (WT_SESSION *session, const char *config)
	Reconfigure a session handle. More...
Cursor handles
int	open_cursor (WT_SESSION *session, const char *uri, WT_CURSOR *to_dup, const char *config, WT_CURSOR **cursorp)
	Open a new cursor on a data source or duplicate an existing cursor. More...
Table operations
int	create (WT_SESSION *session, const char *name, const char *config)
	Create a table, column group, index or file. More...
int	compact (WT_SESSION *session, const char *name, const char *config)
	Compact a live row- or column-store btree or LSM tree. More...
int	drop (WT_SESSION *session, const char *name, const char *config)
	Drop (delete) an object. More...
int	log_printf (WT_SESSION *session, const char *fmt,...)
	Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for logging when this method is called). More...
int	rename (WT_SESSION *session, const char *uri, const char *newuri, const char *config)
	Rename an object. More...
int	salvage (WT_SESSION *session, const char *name, const char *config)
	Salvage a file or table. More...
int	truncate (WT_SESSION *session, const char *name, WT_CURSOR *start, WT_CURSOR *stop, const char *config)
	Truncate a file, table or cursor range. More...
int	upgrade (WT_SESSION *session, const char *name, const char *config)
	Upgrade a file or table. More...
int	verify (WT_SESSION *session, const char *name, const char *config)
	Verify a file or table. More...
Transactions
int	begin_transaction (WT_SESSION *session, const char *config)
	Start a transaction in this session. More...
int	commit_transaction (WT_SESSION *session, const char *config)
	Commit the current transaction. More...
int	rollback_transaction (WT_SESSION *session, const char *config)
	Roll back the current transaction. More...
int	checkpoint (WT_SESSION *session, const char *config)
	Write a transactionally consistent snapshot of a database or set of objects. More...
int	transaction_pinned_range (WT_SESSION *session, uint64_t *range)
	Return the transaction ID range pinned by the session handle. More...

Public Attributes
WT_CONNECTION *	connection
	The connection for this session. More...
void *	app_private
	A location for applications to store information that will be available in callbacks taking a WT_SESSION handle.

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 is not usually shared between threads, see Multithreading for more information.

Examples:

ex_access.c, ex_async.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_extractor.c, ex_hello.c, ex_log.c, ex_pack.c, ex_schema.c, ex_stat.c, and ex_thread.c.

Member Function Documentation

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

Start a transaction in this session.

The transaction remains active until ended by WT_SESSION::commit_transaction or WT_SESSION::rollback_transaction. Operations performed on cursors capable of supporting transactional operations that are already open in this session, or which are opened before the transaction ends, will operate in the context of the transaction.

WT_SESSION::begin_transaction will fail if a transaction is already in progress in the session.

        /*
         * Cursors may be opened before or after the transaction begins, and in
         * either case, subsequent operations are included in the transaction.
         * Opening cursors before the transaction begins allows applications to
         * cache cursors and use them for multiple operations.
         */
        ret =
            session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
        ret = session->begin_transaction(session, NULL);

        cursor->set_key(cursor, "key");
        cursor->set_value(cursor, "value");
        switch (ret = cursor->update(cursor)) {
        case 0:                                 /* Update success */
                ret = session->commit_transaction(session, NULL);
                /*
                 * If commit_transaction succeeds, cursors remain positioned; if
                 * commit_transaction fails, the transaction was rolled-back and
                 * and all cursors are reset.
                 */
                break;
        case WT_ROLLBACK:                       /* Update conflict */
        default:                                /* Other error */
                ret = session->rollback_transaction(session, NULL);
                /* The rollback_transaction call resets all cursors. */
                break;
        }

        /*
         * Cursors remain open and may be used for multiple transactions.
         */

Parameters

session

the session handle

config

Configuration string, see Configuration Strings. Permitted values: Name Effect Values isolation the isolation level for this transaction; defaults to the session's isolation level. a string, chosen from the following options: "read-uncommitted", "read-committed", "snapshot"; default empty. 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 whether to sync log records when the transaction commits, inherited from wiredtiger_open transaction_sync. a boolean flag; default empty.

Returns

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

Examples:

ex_config.c, and ex_log.c.

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

Write a transactionally consistent snapshot of a database or set of objects.

The checkpoint includes all transactions committed before the checkpoint starts. Additionally, checkpoints may optionally be discarded.

        /* Checkpoint the database. */
        ret = session->checkpoint(session, NULL);

        /* Checkpoint of the database, creating a named snapshot. */
        ret = session->checkpoint(session, "name=June01");

        /*
         * Checkpoint a list of objects.
         * JSON parsing requires quoting the list of target URIs.
         */
        ret = session->
            checkpoint(session, "target=(\"table:table1\",\"table:table2\")");

        /*
         * Checkpoint a list of objects, creating a named snapshot.
         * JSON parsing requires quoting the list of target URIs.
         */
        ret = session->
            checkpoint(session, "target=(\"table:mytable\"),name=midnight");

        /* Checkpoint the database, discarding all previous snapshots. */
        ret = session->checkpoint(session, "drop=(from=all)");

        /* Checkpoint the database, discarding the "midnight" snapshot. */
        ret = session->checkpoint(session, "drop=(midnight)");

        /*
         * Checkpoint the database, discarding all snapshots after and
         * including "noon".
         */
        ret = session->checkpoint(session, "drop=(from=noon)");

        /*
         * Checkpoint the database, discarding all snapshots before and
         * including "midnight".
         */
        ret = session->checkpoint(session, "drop=(to=midnight)");

        /*
         * Create a checkpoint of a table, creating the "July01" snapshot and
         * discarding the "May01" and "June01" snapshots.
         * JSON parsing requires quoting the list of target URIs.
         */
        ret = session->checkpoint(session,
            "target=(\"table:mytable\"),name=July01,drop=(May01,June01)");

Parameters

session

the session handle

config

Configuration string, see Configuration Strings. Permitted values: Name Effect Values drop specify a list of checkpoints to drop. The list may additionally contain one of the following keys: "from=all" to drop all checkpoints, "from=<checkpoint>" to drop all checkpoints after and including the named checkpoint, or "to=<checkpoint>" to drop all checkpoints before and including the named checkpoint. Checkpoints cannot be dropped while a hot backup is in progress or if open in a cursor. a list of strings; default empty. force by default, checkpoints may be skipped if the underlying object has not been modified, this option forces the checkpoint. a boolean flag; default false. name if set, specify a name for the checkpoint (note that checkpoints including LSM trees may not be named). a string; default empty. target if non-empty, checkpoint the list of objects. a list of strings; default empty.

Returns

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

Examples:

ex_stat.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 back 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_log.c, and ex_thread.c.

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

Commit the current transaction.

A transaction must be in progress when this method is called.

If WT_SESSION::commit_transaction returns an error, the transaction was rolled back, not committed.

        /*
         * Cursors may be opened before or after the transaction begins, and in
         * either case, subsequent operations are included in the transaction.
         * Opening cursors before the transaction begins allows applications to
         * cache cursors and use them for multiple operations.
         */
        ret =
            session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
        ret = session->begin_transaction(session, NULL);

        cursor->set_key(cursor, "key");
        cursor->set_value(cursor, "value");
        switch (ret = cursor->update(cursor)) {
        case 0:                                 /* Update success */
                ret = session->commit_transaction(session, NULL);
                /*
                 * If commit_transaction succeeds, cursors remain positioned; if
                 * commit_transaction fails, the transaction was rolled-back and
                 * and all cursors are reset.
                 */
                break;
        case WT_ROLLBACK:                       /* Update conflict */
        default:                                /* Other error */
                ret = session->rollback_transaction(session, NULL);
                /* The rollback_transaction call resets all cursors. */
                break;
        }

        /*
         * Cursors remain open and may be used for multiple transactions.
         */

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_config.c, and ex_log.c.

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

Compact a live row- or column-store btree or LSM tree.

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

Parameters

session	the session handle
name	the URI of the object to compact, such as "table:stock"
config	Configuration string, see Configuration Strings. Permitted values: Name Effect Values timeout maximum amount of time to allow for compact in seconds. The actual amount of time spent in compact may exceed the configured value. A value of zero disables the timeout. an integer; default 1200.

Returns

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

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". For a description of URI formats see Data Sources.
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 4KB is a good choice absent requirements from the operating system or storage device. an integer between 512B and 128MB; default 4KB. app_metadata application-owned metadata for this object. a string; default empty. block_allocation configure block allocation. Permitted values are "first" or "best"; the "first" configuration uses a first-available algorithm during block allocation, the "best" configuration uses a best-fit algorithm. a string, chosen from the following options: "first", "best"; default best. block_compressor configure a compressor for file blocks. Permitted values are "none" or custom compression engine name created with WT_CONNECTION::add_compressor. If WiredTiger has builtin support for "snappy" or "zlib" compression, these names are also available. See Compressors for more information. a string; default none. cache_resident do not ever evict the object's pages; see Cache resident objects for more information. a boolean flag; default false. checksum configure block checksums; permitted values are on (checksum all blocks), off (checksum no blocks) and uncompresssed (checksum only blocks which are not compressed for any reason). The uncompressed setting is for applications which can rely on decompression to fail if a block has been corrupted. a string, chosen from the following options: "on", "off", "uncompressed"; default uncompressed. 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. Permitted values are "none" or a custom collator name created with WT_CONNECTION::add_collator. a string; default none. 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. dictionary the maximum number of unique values remembered in the Btree row-store leaf page value dictionary; see File formats and compression for more information. an integer greater than or equal to 0; default 0. 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. extractor configure custom extractor for indices. Permitted values are "none" or an extractor name created with WT_CONNECTION::add_extractor. a string; default none. format the file format. a string, chosen from the following options: "btree"; default btree. huffman_key configure Huffman encoding for keys. Permitted values are "none", "english", "utf8<file>" or "utf16<file>". See Huffman Encoding for more information. a string; default none. huffman_value configure Huffman encoding for values. Permitted values are "none", "english", "utf8<file>" or "utf16<file>". See Huffman Encoding for more information. a string; default none. immutable configure the index to be immutable - that is an index is not changed by any update to a record in the table. a boolean flag; default false. internal_key_max the largest key stored in an internal node, in bytes. If set, keys larger than the specified size are stored as overflow items (which may require additional I/O to access). The default and the maximum allowed value are both one-tenth the size of a newly split 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 (ignored for custom collators). 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. The page maximum is the bytes of uncompressed data, that is, the limit is applied before any block compression is done. an integer between 512B and 512MB; default 4KB. 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. leaf_key_max the largest key stored in a leaf node, in bytes. If set, keys larger than the specified size are stored as overflow items (which may require additional I/O to access). The default value is one-tenth the size of a newly split 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. The page maximum is the bytes of uncompressed data, that is, the limit is applied before any block compression is done. an integer between 512B and 512MB; default 32KB. leaf_value_max the largest value stored in a leaf node, in bytes. If set, values larger than the specified size are stored as overflow items (which may require additional I/O to access). If the size is larger than the maximum leaf page size, the page size is temporarily ignored when large values are written. The default is one-half the size of a newly split leaf page. an integer greater than or equal to 0; default 0. lsm = ( options only relevant for LSM data sources. a set of related configuration options defined below.     auto_throttle Throttle inserts into LSM trees if flushing to disk isn't keeping up. a boolean flag; default true.     bloom create bloom filters on LSM tree chunks as they are merged. a boolean flag; default true.     bloom_bit_count the number of bits used per item for LSM bloom filters. an integer between 2 and 1000; default 16.     bloom_config config string used when creating Bloom filter files, passed to WT_SESSION::create. a string; default empty.     bloom_hash_count the number of hash values per item used for LSM bloom filters. an integer between 2 and 100; default 8.     bloom_oldest create a bloom filter on the oldest LSM tree chunk. Only supported if bloom filters are enabled. a boolean flag; default false.     chunk_max the maximum size a single chunk can be. Chunks larger than this size are not considered for further merges. This is a soft limit, and chunks larger than this value can be created. Must be larger than chunk_size. an integer between 100MB and 10TB; default 5GB.     chunk_size the maximum size of the in-memory chunk of an LSM tree. This limit is soft - it is possible for chunks to be temporarily larger than this value. This overrides the memory_page_max setting. an integer between 512K and 500MB; default 10MB.     merge_max the maximum number of chunks to include in a merge operation. an integer between 2 and 100; default 15.     merge_min the minimum number of chunks to include in a merge operation. If set to 0 or 1 half the value of merge_max is used. an integer no more than 100; default 0. ) memory_page_max the maximum size a page can grow to in memory before being reconciled to disk. The specified size will be adjusted to a lower bound of 50 * leaf_page_max, and an upper bound of cache_size / 2. This limit is soft - it is possible for pages to be temporarily larger than this value. This setting is ignored for LSM trees, see chunk_size. an integer between 512B and 10TB; default 5MB. os_cache_dirty_max maximum dirty system buffer cache usage, in bytes. If non-zero, schedule writes for dirty blocks belonging to this object in the system buffer cache after that many bytes from this object are written into the buffer cache. an integer greater than or equal to 0; default 0. os_cache_max maximum system buffer cache usage, in bytes. If non-zero, evict object blocks from the system buffer cache after that many bytes from this object are read or written into the buffer cache. an integer greater than or equal to 0; default 0. prefix_compression configure prefix compression on row-store leaf pages. a boolean flag; default false. prefix_compression_min minimum gain before prefix compression will be used on row-store leaf pages. an integer greater than or equal to 0; default 4. 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 set the type of data source used to store a column group, index or simple table. By default, a "file:" URI is derived from the object name. The type configuration can be used to switch to a different data source, such as LSM or an extension configured by the application. a string; default file. 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_async.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_extractor.c, ex_log.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. remove_files should the underlying files be removed?. a boolean flag; default true.

Returns

zero on success, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

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

Insert a WT_LOGREC_MESSAGE type record in the database log files (the database must be configured for logging when this method is called).

Parameters

session	the session handle
fmt	a printf format specifier

Returns

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

Examples:

ex_log.c.

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

Open a new cursor on a data source or duplicate an existing cursor.

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

An existing cursor can be duplicated by passing it as the to_dup parameter and setting the uri parameter to NULL:

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

        /* Duplicate the cursor. */
        ret = session->open_cursor(session, NULL, cursor, NULL, &duplicate);

Cursors being duplicated must have a key set, and successfully duplicated cursors are positioned at the same place in the data source as the original.

To reconfigure a cursor, duplicate it with a new configuration value:

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

        /* Reconfigure the cursor to overwrite the record. */
        ret = session->open_cursor(
            session, NULL, cursor, "overwrite", &overwrite_cursor);
        ret = cursor->close(cursor);

        overwrite_cursor->set_value(overwrite_cursor, value);
        ret = overwrite_cursor->insert(cursor);

Cursor handles should be discarded by calling WT_CURSOR::close.

Cursors capable of supporting transactional operations operate in the context of the current transaction, if any.

WT_SESSION::rollback_transaction implicitly resets all cursors.

Cursors are relatively light-weight objects but may hold references to heavier-weight objects; applications should re-use cursors when possible, but instantiating new cursors is not so expensive that applications need to cache cursors at all cost.

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, they may be read-only or not support transactional updates). See Data Sources for more information.

The following are the builtin basic cursor types:

URI	Type	Notes
table:<table name>[<projection>]	table cursor	table key, table value(s) with optional projection of columns
colgroup:<table name>:<column group name>	column group cursor	table key, column group value(s)
index:<table name>:<index name>[<projection>]	index cursor	key=index key, value=table value(s) with optional projection of columns

Some administrative tasks can be accomplished using the following special cursor types that give access to data managed by WiredTiger:

URI	Type	Notes
backup:	backup cursor	key=string, see Backups for details
log:	log cursor	key=(long fileID, long offset, int seqno), value=(uint64_t txnid, uint32_t rectype, uint32_t optype, uint32_t fileid, WT_ITEM key, WT_ITEM value), see Log cursors for details
metadata:	metadata cursor	key=string, value=string, see Reading WiredTiger Metadata for details
statistics:[<data source URI>]	database or data source statistics cursor	key=int id, value=(string description, string value, uint64_t value), see Statistics Data for details

Advanced applications may also open the following low-level cursor types:

URI	Type	Notes
file:<file name>	file cursor	file key, file value(s)
lsm:<name>	LSM cursor (key=LSM key, value=LSM value)	LSM key, LSM value, see Log-Structured Merge Trees

Parameters

	to_dup	a cursor to duplicate
	config	Configuration string, see Configuration Strings. Permitted values: Name Effect Values append append the value as a new record, creating a new record number key; valid only for cursors with record number keys. a boolean flag; default false. bulk configure the cursor for bulk-loading, a fast, initial load path (see Bulk-load for more information). Bulk-load may only be used for newly created objects and cursors configured for bulk-load only support the WT_CURSOR::insert and WT_CURSOR::close methods. When bulk-loading row-store objects, keys must be loaded in sorted order. The value is usually a true/false flag; when bulk-loading fixed-length column store objects, the special value bitmap allows chunks of a memory resident bitmap to be loaded directly into a file by passing a WT_ITEM to WT_CURSOR::set_value where the size field indicates the number of records in the bitmap (as specified by the object's value_format configuration). Bulk-loaded bitmap values must end on a byte boundary relative to the bit count (except for the last set of values loaded). a string; default false. checkpoint the name of a checkpoint to open (the reserved name "WiredTigerCheckpoint" opens the most recent internal checkpoint taken for the object). The cursor does not support data modification. a string; default empty. dump configure the cursor for dump format inputs and outputs: "hex" selects a simple hexadecimal format, "json" selects a JSON format with each record formatted as fields named by column names if available, and "print" selects a format where only non-printing characters are hexadecimal encoded. These formats are compatible with the wt dump and wt load commands. a string, chosen from the following options: "hex", "json", "print"; default empty. next_random configure the cursor to return a pseudo-random record from the object; valid only for row-store cursors. Cursors configured with next_random=true only support the WT_CURSOR::next and WT_CURSOR::close methods. See Cursor random for details. a boolean flag; default false. overwrite configures whether the cursor's insert, update and remove methods check the existing state of the record. If overwrite is false, WT_CURSOR::insert fails with WT_DUPLICATE_KEY if the record exists, WT_CURSOR::update and WT_CURSOR::remove fail with WT_NOTFOUND if the record does not exist. a boolean flag; default true. 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. readonly only query operations are supported by this cursor. An error is returned if a modification is attempted using the cursor. The default is false for all cursor types except for log and metadata cursors. a boolean flag; default false. statistics Specify the statistics to be gathered. Choosing "all" gathers statistics regardless of cost and may include traversing on-disk files; "fast" gathers a subset of relatively inexpensive statistics. The selection must agree with the database statistics configuration specified to wiredtiger_open or WT_CONNECTION::reconfigure. For example, "all" or "fast" can be configured when the database is configured with "all", but the cursor open will fail if "all" is specified when the database is configured with "fast", and the cursor open will fail in all cases when the database is configured with "none". If statistics is not configured, the default configuration is the database configuration. The "clear" configuration resets statistics after gathering them, where appropriate (for example, a cache size statistic is not cleared, while the count of cursor insert operations will be cleared). See Statistics for more information. a list, with values chosen from the following options: "all", "fast", "clear"; default empty. target if non-empty, backup the list of objects; valid only for a backup data source. a list of strings; default empty.
[out]	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_call_center.c, ex_config.c, ex_cursor.c, ex_extractor.c, ex_log.c, ex_schema.c, ex_stat.c, and ex_thread.c.

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

Reconfigure a session handle.

        ret = session->reconfigure(session, "isolation=snapshot");

WT_SESSION::reconfigure will fail if a transaction is in progress in the session.

All cursors are reset.

Parameters

session	the session handle
config	Configuration string, see Configuration Strings. Permitted values: Name Effect Values isolation the default isolation level for operations in this session. a string, chosen from the following options: "read-uncommitted", "read-committed", "snapshot"; default read-committed.

Returns

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

int WT_SESSION::rename	(	WT_SESSION *	session,
		const char *	uri,
		const char *	newuri,
		const char *	config
	)

Rename an object.

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

Parameters

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

Returns

zero on success, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

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

Roll back the current transaction.

A transaction must be in progress when this method is called.

All cursors are reset.

        /*
         * Cursors may be opened before or after the transaction begins, and in
         * either case, subsequent operations are included in the transaction.
         * Opening cursors before the transaction begins allows applications to
         * cache cursors and use them for multiple operations.
         */
        ret =
            session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
        ret = session->begin_transaction(session, NULL);

        cursor->set_key(cursor, "key");
        cursor->set_value(cursor, "value");
        switch (ret = cursor->update(cursor)) {
        case 0:                                 /* Update success */
                ret = session->commit_transaction(session, NULL);
                /*
                 * If commit_transaction succeeds, cursors remain positioned; if
                 * commit_transaction fails, the transaction was rolled-back and
                 * and all cursors are reset.
                 */
                break;
        case WT_ROLLBACK:                       /* Update conflict */
        default:                                /* Other error */
                ret = session->rollback_transaction(session, NULL);
                /* The rollback_transaction call resets all cursors. */
                break;
        }

        /*
         * Cursors remain open and may be used for multiple transactions.
         */

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.

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, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

int WT_SESSION::transaction_pinned_range	(	WT_SESSION *	session,
		uint64_t *	range
	)

Return the transaction ID range pinned by the session handle.

The ID range is approximate and is calculated based on the oldest ID needed for the active transaction in this session, compared to the newest transaction in the system.

        /* Check the transaction ID range pinned by the session handle. */
        uint64_t range;

        ret = session->transaction_pinned_range(session, &range);

Parameters

	session	the session handle
[out]	range	the range of IDs pinned by this session. Zero if there is no active transaction.

Returns

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

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

Truncate a file, table or cursor range.

Truncate a file or table.

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

Truncate a cursor range. When truncating based on a cursor position, it is not required the cursor reference a record in the object, only that the key be set. This allows applications to discard portions of the object name space without knowing exactly what records the object contains.

        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 object
stop	optional cursor marking the last record discarded; if NULL, the truncate continues to the end of the object
config	Configuration string, see Configuration Strings. No values currently permitted.

Returns

zero on success, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

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

Upgrade a file or table.

Upgrade upgrades a file or table, if upgrade is required.

        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, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

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. Permitted values: Name Effect Values dump_address Display addresses and page types as pages are verified, using the application's message handler, intended for debugging. a boolean flag; default false. dump_blocks Display the contents of on-disk blocks as they are verified, using the application's message handler, intended for debugging. a boolean flag; default false. dump_offsets Display the contents of specific on-disk blocks, using the application's message handler, intended for debugging. a list of strings; default empty. dump_pages Display the contents of in-memory pages as they are verified, using the application's message handler, intended for debugging. a boolean flag; default false.

Returns

zero on success, EBUSY if there are open cursors on the object and a non-zero error code on failure. See Error Returns for details.

Member Data Documentation

WT_CONNECTION* WT_SESSION::connection

The connection for this session.