FairCom ISAM for C

Data file snapshots

A data snapshot provides a point-in-time view of a data file. A database client that reads the snapshot reads the records from the data file as they existed at that point in time, even if the data file has been updated since then. Non-snapshot readers read the data file in its current state. The snapshot log contains record images as they existed at the time of the snapshot. The log exists until the snapshot is deleted.

Data snapshot attributes

A data snapshot includes the following attributes:

The name of the data file.
The snapshot ID.
The transaction log position at which the data snapshot was created.

Data snapshot limitations

When a data file is included in a data snapshot, we do not allow database connections to open it in exclusive mode. An exclusive open request will fail with error code SNAPSHOT_EXISTS_FOR_FILE (1220), indicating that an active snapshot prevents the operation. This restriction prevents operations on the data file that could change the file’s definitions in a way that would interfere with snapshot readers.
Data snapshot is only supported on a data file that uses full transaction control (ctTRNLOG transaction mode).
Data snapshot is supported on fixed-length and variable-length record data files. It is supported on partitioned files.
Data snapshots are not supported on superfiles, memory files, or segmented files.
A data file can have only one active snapshot at a time.

Data snapshot operations

We support the following operations for a data snapshot:

1) Create a data snapshot

Function name

NINT CreateDataSnapshot(CREATE_DATA_SNAPSHOT* options);

Description

Create a data snapshot for the specified data file. A data snapshot provides a point-in-time view of the file's contents.

CREATE_DATA_SNAPSHOT Field	Type	Description	Version
ULONG version	Input	The structure version. Supported versions are: CREATE_DATA_SNAPSHOT_VERSION_1	1
ULONG options	Input	One of the following values: createByDataFileName indicates that the dataFileName field contains the name of the data file. createByDataFileNumber indicates that the dataFileNumber field contains the file number of the data file, which the caller has already opened.	1
const char* dataFileName	Input	[Optional] If options specifies createByDataFileName, this field specifies the name of the data file to include in the snapshot. The caller must be able to open the file.	1
FILNO dataFileNumber	Input	[Options] If options specifies createByDataFileNumber, this field specifies the file number of the data file open by the caller.	1
ULONG isamErrorCode	Output	If the function fails, this field returns the ISAM error code.	1
ULONG systemErrorCode	Output	If the function fails, this field returns the system error code.	1
LONG8 snapshotID	Output	On success, this field returns a unique ID for the snapshot.	1
ctLOGP logPosition	Output	On success, this field returns the transaction log position at which the snapshot was created.	1
char* errorBuffer	Output	[Optional] If the function call fails, an error message is written to this buffer.	1
size_t errorBufferSize	Input	The size of errorBuffer in bytes.	1

2) Read a data snapshot

Use a batch physical read to read a data file's snapshot. Call DoBatchXtd() with the BAT_PHYS and BAT_SNAP bits set in the batchmode2 field. The function call behaves like a normal batch read call does, except for the following differences:

DoBatchXtd() reads records from the snapshot instead of from the current state of the data file.

The batch lock request options BAT_LOK_RED and BAT_LOK_WRT are ignored.

To read a data file's snapshot using the c-treeDB API, call ctdbSetBatch() with the CTBATCH_PHYS and CTBATCH_READ_SNAPSHOT batch modes.

3) Delete a data snapshot

Function name

NINT DeleteDataSnapshot(DELETE_DATA_SNAPSHOT* options);

Description

Delete the data snapshot that has the specified snapshot ID.

DELETE_DATA_SNAPSHOT Field	Type	Description	Version
ULONG version	Input	The structure version. Supported versions are: DELETE_DATA_SNAPSHOT_VERSION_1	1
ULONG options	Input	deleteBySnapshotID indicates that the snapshotID field contains the unique ID of the snapshot to delete. deleteByDataFileName indicates that the dataFileName field contains the name of the data file. deleteByDataFileNumber indicates that the dataFileNumber field contains the file number of the data file that the caller has already opened.	1
ULONG8 snapshotID	Input	[Optional] If options specifies deleteBySnapshotID, this field specifies the ID of the snapshot to delete.	1
const char* dataFileName	Input	[Optional] If options specifies deleteByDataFileName, this field specifies the data file name.	1
FILNO dataFileNumber	Input	[Optional] If the option specifies deleteByDataFileNumber, this field specifies the file number of the data file already opened by the caller.	1
char* errorBuffer	Output	[Optional] If the function fails, it writes an error message to the errorBuffer buffer.	1
size_t errorBufferSize	Input	The size of errorBuffer in bytes.	1
LONG systemErrorCode	Output	[Optional] If the function fails, systemErrorCode is set to the system error code (or zero if no system-level error occurred).	1