Defines, Structures, Typedefs, Functions. More...

Files
file	clDbalApi.h
	Header file of DBAL related Definitions and APIs.
file	clDbalCfg.h
	Header file of DBAL Component Configuration APIs.
file	clDbalErrors.h
	Header file of Error Codes returned by the DBAL Library.

Macros
#define	CL_DB_APPEND 0x4
	This DB flag is used for opening a DB in APPEND mode.
#define	CL_DB_CREAT 0X1
	This DB flag is used for creating a DB.
#define	CL_DB_OPEN 0x2
	This DB flag is used for opening an existing DB.
#define	CL_DB_SYNC 0x8
	One of the three DB open modes (CL_DB_CREAT, CL_DB_OPEN, CL_DB_APPEND) may be OR-ed with DB sync flag.
#define	CL_DBAL_ERR_ABORT_FAILED 0x102
	An error has occured during transaction abort.
#define	CL_DBAL_ERR_COMMIT_FAILED 0x101
	An error has occured during transaction commit.
#define	CL_DBAL_ERR_DB_ERROR 0x100
	An unextected error has occured during DB operation.
#define	CL_DBAL_RC(ERROR_CODE) CL_RC(CL_CID_DBAL, (ERROR_CODE))
	Appends the DBAL Component ID to the Error Code.

Typedefs
typedef ClPtrT	ClDBEngineT
	Engine Handle.
typedef const char *	ClDBFileT
	Type of the DB File name.
typedef ClUint8T	ClDBFlagT
	Definition of database open flag type.
typedef ClPtrT	ClDBHandleT
	Database Handle.
typedef ClUint8T *	ClDBKeyHandleT
	Type of DB Key Handle (handle to the key of the record which is to be inserted in DB or to be fetched from the DB).
typedef ClDBKeyHandleT	ClDBKeyT
	Deprecated DB Key Handle type.
typedef const char *	ClDBNameT
	Type of the name of database.
typedef ClUint8T *	ClDBRecordHandleT
	Type of DB Record Handle (handle to the record which is to be inserted in DB or to be fetched from the DB).
typedef ClDBRecordHandleT	ClDBRecordT
	Deprecated DB Record Handle type.
typedef enum ClDBType	ClDBTypeT
	Definition of Database type.

Enumerations
enum	ClDBType { CL_DB_TYPE_HASH = 0, CL_DB_TYPE_BTREE }
	Definition of Database type. More...

Functions
ClRcT	clDbalClose (CL_IN ClDBHandleT dbHandle)
	Closes a database instance.
ClRcT	clDbalFirstRecordGet (CL_IN ClDBHandleT dbHandle, CL_OUT ClDBKeyHandleT pDBKey, CL_OUT ClUint32T pKeySize, CL_OUT ClDBRecordHandleT pDBRec, CL_OUT ClUint32T pRecSize)
	Returns the first key and associated record from a database instance.
ClRcT	clDbalKeyFree (CL_IN ClDBHandleT dbHandle, CL_IN ClDBKeyHandleT dbKey)
	Frees the database key.
ClRcT	clDbalLibFinalize (void)
	DBAL configuration module exit-point.
ClRcT	clDbalLibInitialize (void)
	DBAL configuration module entry-point.
ClRcT	clDbalNextRecordGet (CL_IN ClDBHandleT dbHandle, CL_IN ClDBKeyHandleT currentKey, CL_IN ClUint32T currentKeySize, CL_OUT ClDBKeyHandleT pDBNextKey, CL_OUT ClUint32T pNextKeySize, CL_OUT ClDBRecordHandleT pDBNextRec, CL_OUT ClUint32T pNextRecSize)
	Returns the next key and associated record from a database instance.
ClRcT	clDbalOpen (CL_IN ClDBFileT dbFile, CL_IN ClDBNameT dbName, CL_IN ClDBFlagT dbFlag, CL_IN ClUint32T maxKeySize, CL_IN ClUint32T maxRecordSize, CL_OUT ClDBHandleT *pDBHandle)
	Opens a database instance.
ClRcT	clDbalRecordDelete (CL_IN ClDBHandleT dbHandle, CL_IN ClDBKeyHandleT dbKey, CL_IN ClUint32T keySize)
	Deletes a record from a database instance.
ClRcT	clDbalRecordFree (CL_IN ClDBHandleT dbHandle, CL_IN ClDBRecordHandleT dbRec)
	Frees the database record.
ClRcT	clDbalRecordGet (CL_IN ClDBHandleT dbHandle, CL_IN ClDBKeyHandleT dbKey, CL_IN ClUint32T keySize, CL_OUT ClDBRecordHandleT pDBRec, CL_OUT ClUint32T pRecSize)
	Retrieves a record from a database instance.
ClRcT	clDbalRecordInsert (CL_IN ClDBHandleT dbHandle, CL_IN ClDBKeyHandleT dbKey, CL_IN ClUint32T keySize, CL_IN ClDBRecordHandleT dbRec, CL_IN ClUint32T recSize)
	Record Operation APIs.
ClRcT	clDbalRecordReplace (CL_IN ClDBHandleT dbHandle, CL_IN ClDBKeyHandleT dbKey, CL_IN ClUint32T keySize, CL_IN ClDBRecordHandleT dbRec, CL_IN ClUint32T recSize)
	Replaces a record in a database instance.
ClRcT	clDbalSync (CL_IN ClDBHandleT dbHandle, ClUint32T flags)
	Flushes (synchronizes) the DB modifications stored in the in-memory cache to disk.
ClRcT	clDbalTransactionAbort (CL_IN ClDBHandleT dbHandle)
	Aborts a transaction on a database instance.
ClRcT	clDbalTransactionBegin (CL_IN ClDBHandleT dbHandle)
	Begins the transaction on a database instance.
ClRcT	clDbalTransactionCommit (CL_IN ClDBHandleT dbHandle)
	Commits the transaction on a database instance.
ClRcT	clDbalTxnOpen (CL_IN ClDBFileT dbFile, CL_IN ClDBNameT dbName, CL_IN ClDBFlagT dbFlag, CL_IN ClUint32T maxKeySize, CL_IN ClUint32T maxRecordSize, CL_OUT ClDBHandleT *pDBHandle)
	Transaction Related APIs.

Detailed Description

Defines, Structures, Typedefs, Functions.

Macro Definition Documentation

#define CL_DB_APPEND 0x4

This DB flag is used for opening a DB in APPEND mode.

Data inserted to the DB would be appended to the existing DB (if there is any).

#define CL_DB_CREAT 0X1

This DB flag is used for creating a DB.

If the DB already exists then it is removed and a new DB is be created.

#define CL_DB_OPEN 0x2

This DB flag is used for opening an existing DB.

If the DB doesn't exist already then an error is returned.

#define CL_DB_SYNC 0x8

One of the three DB open modes (CL_DB_CREAT, CL_DB_OPEN, CL_DB_APPEND) may be OR-ed with DB sync flag.

When specified, the underlying DB engine will automatically synchronize all database operations to the disk. Note : Currently this flag is supported only with GDBM and SQLite and it has no effect in case of other DB types. Please use clDbalSync() with other DBs to synchronize DB operations to the disk.

Typedef Documentation

typedef ClUint8T ClDBFlagT

Definition of database open flag type.

Database can be opened in following three modes : Create, Open, Append.

typedef ClPtrT ClDBHandleT

Database Handle.

The handle uniquely identifies the created/opened database instance.

typedef ClDBKeyHandleT ClDBKeyT

Deprecated DB Key Handle type.

ClDBKeyHandleT should be used in place of ClDBKeyT.

typedef ClDBRecordHandleT ClDBRecordT

Deprecated DB Record Handle type.

ClDBRecordHandleT should be used in place of ClDBRecordT.

Enumeration Type Documentation

enum ClDBType

Definition of Database type.

Enumerator:

CL_DB_TYPE_HASH	Hash table.
CL_DB_TYPE_BTREE	B-tree.

Function Documentation

ClRcT clDbalClose ( CL_IN ClDBHandleT dbHandle )

Closes a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle Handle of the Database instance to be closed. This is the handle that was returned to the user when clDbalOpen() call was successfully executed. All Db operations if performed using this DB handle after successful clDbalClose() are invalid and returned with an error.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.

Description:: This function closes the association, represented by the dbHandle parameter, between the invoking process and the DB instance. In case of Berkeley Database, if the database being closed is an in-memory database, then all data is lost once the database is closed. The process must have invoked clDbalOpen() before it invokes this function. A process must invoke this function once for each handle acquired by invoking clDbalOpen(). If the clDbalClose() function returns successfully, the clDbalClose() function releases all resources acquired when clDbalOpen() was called.

See Also: clDbalOpen()

ClRcT clDbalFirstRecordGet	(	CL_IN ClDBHandleT	dbHandle,
		CL_OUT ClDBKeyHandleT *	pDBKey,
		CL_OUT ClUint32T *	pKeySize,
		CL_OUT ClDBRecordHandleT *	pDBRec,
		CL_OUT ClUint32T *	pRecSize
	)

Returns the first key and associated record from a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle	Handle to the Database from where the object is being deleted. This is the handle that was returned to the user when clDbalOpen() call was successfully executed.
pDBKey	(out) Pointer to key handle, in which the first record's key is returned. Memory allocation is done by DBAL but you must free this memory using clDbalKeyFree() API.
pKeySize	(out) Pointer to variable in which size of the key is being returned.
pDBRec	(out) Pointer to record handle in which the first record is returned. Memory allocation is done by DBAL but you must free this memory using clDbalRecordFree() API.
pRecSize	(out) Pointer to variable in which size of the record is being returned.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_DBAL_ERR_DB_ERROR	If the underlying database fails.
CL_ERR_NOT_EXIST	If the first record does not exist.

Description:: This API is used to return the first key and associated record from a database. If no records are found in the specified database, an error is returned.

See Also: clDbalOpen(), clDbalClose(), clDbalRecordReplace(), clDbalRecordInsert(), clDbalRecordGet(), clDbalRecordDelete(), clDbalNextRecordGet()

ClRcT clDbalKeyFree	(	CL_IN ClDBHandleT	dbHandle,
		CL_IN ClDBKeyHandleT	dbKey
	)

Frees the database key.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle	Handle to the Database. This is the handle that was returned to the user when clDbalOpen() call was successfully executed.
dbKey	Key to be freed.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.

Description:: This API is used to free the Key returned by clDbalFirstRecordGet(), clDbalNextRecordGet(). Since the key is created by clDbalRecordInsert(), it can not be freed by clHeapFree. So for proper cleanup of keys, this API must be called after every successful call of clDbalFirstRecordGet(), clDbalNextRecordGet().

See Also: clDbalFirstRecordGet(), clDbalNextRecordGet()

ClRcT clDbalLibFinalize ( void )

DBAL configuration module exit-point.

Header File:: clDbalCfg.h

Library Files:

Parameters:: None

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	If the lib is not intialized before calling this function.

Description:: This API is Database Abstraction Layer configuration module exit-point. This function closes the association between the invoking process and Database Abstraction Layer. The process must have invoked clDbalLibInitialize() before it invokes this function. If the clDbalLibFinalize() function returns successfully, it releases all resources acquired when clDbalLibInitialize() was called.

See Also: clDbalLibInitialize()

ClRcT clDbalLibInitialize ( void )

DBAL configuration module entry-point.

Header File:: clDbalCfg.h

Library Files:

Parameters:: None

Return values

CL_OK	The API executed successfully.
CL_ERR_NO_MEMORY	On memory allocation failure.

Description:: This API is Database Abstraction Layer configuration module entry-point. This is used to set the configuration parameters of the DBAL. It initializes the Database Abstraction Layer. Once this API is executed successfully the DBAL is ready for use. This API must be executed before executing any other API.

See Also: clDbalLibFinalize()

ClRcT clDbalNextRecordGet	(	CL_IN ClDBHandleT	dbHandle,
		CL_IN ClDBKeyHandleT	currentKey,
		CL_IN ClUint32T	currentKeySize,
		CL_OUT ClDBKeyHandleT *	pDBNextKey,
		CL_OUT ClUint32T *	pNextKeySize,
		CL_OUT ClDBRecordHandleT *	pDBNextRec,
		CL_OUT ClUint32T *	pNextRecSize
	)

Returns the next key and associated record from a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle	Handle to the Database from which the next record is being retrieved. This is the handle that was returned to the user when clDbalOpen() call was successfully executed.
currentKey	Current record's key handle.
currentKeySize	Size of the current key.
pDBNextKey	(out) Pointer to key handle, in which the next record's key is being returned. Memory allocation is done by DBAL but you must free this memory using clDbalKeyFree() API.
pNextKeySize	(out) Pointer to variable in which size of the key is being returned.
pDBNextRec	(out) Pointer to record handle, in which handle of the next record is returned. Memory allocation is done by DBAL but you must free this memory using clDbalRecordFree() API.
pNextRecSize	(out) Pointer to variable in which size of the record is being returned.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_DBAL_ERR_DB_ERROR	If the underlying database fails.
CL_ERR_NOT_EXIST	If the key does not exist.

Description:: This API is used to retrieve the next key and associated record from a Database using the current record's key. If no record is available, an error is returned.

See Also: clDbalOpen(), clDbalClose(), clDbalRecordReplace(), clDbalRecordInsert(), clDbalRecordGet(), clDbalRecordDelete()

ClRcT clDbalOpen	(	CL_IN ClDBFileT	dbFile,
		CL_IN ClDBNameT	dbName,
		CL_IN ClDBFlagT	dbFlag,
		CL_IN ClUint32T	maxKeySize,
		CL_IN ClUint32T	maxRecordSize,
		CL_OUT ClDBHandleT *	pDBHandle
	)

Opens a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbFile	This parameter specifies the file name along with its path, where the database is to be created. If this parameter is NULL and the database is Berkeley Database, then an in-memory database is created. This parameter is ignored if the database is other than Berkeley Database.
dbName	This parameter specifies the database name along with its path, where the database is to be created. The records are stored in the database of this name. This parameter is used in case of both Berkeley and GDBM Database.
dbFlag	This flag accepts following three values: If CL_DB_CREAT is specified and the database already exists, then the existing database is deleted and a fresh one is created. If the database does not exist, then a new one is created. If CL_DB_OPEN is specified then existing database is opened. If the database does not exist, then an error is returned. If CL_DB_APPEND is specified and the database already exists, then the existing database is opened in append mode.If the database does not exist, then a fresh one is created.
maxKeySize	Maximum size of the key (in bytes) to be stored in the database. This parameter is ignored in case of Berkeley and GDBM databases.
maxRecordSize	Maximum size of the record (in bytes) to be stored in the database. This parameter is ignored in case of Berkeley and GDBM databases.
pDBHandle	(out)Pointer to variable of type ClDBHandleT in which the newly created database handle is returned. This handle should be used for all the subsequent operations on this database instance.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_PARAMETER	On passing invalid parameters.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_DBAL_ERR_DB_ERROR	If the underlying database fails.

Description:: This API opens a database instance on the specified Database. Once this API is executed successfully the DB instance is ready for use. This API must be executed before performing any DB operation (insert, delete, replace, close, etc). DB handle returned by this API should be used for further DB operations on this database instance.

See Also: clDbalClose()

ClRcT clDbalRecordDelete	(	CL_IN ClDBHandleT	dbHandle,
		CL_IN ClDBKeyHandleT	dbKey,
		CL_IN ClUint32T	keySize
	)

Deletes a record from a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle	Handle to the Database from which the record is being deleted.
dbKey	Key handle of the record.
keySize	Size of the key.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	on passing an invalid handle.
CL_DBAL_ERR_DB_ERROR	If the underlying database fails.
CL_ERR_NOT_EXIST	If the key does not exist.

Description:: This API is used to delete a record from a Database using its handle and record's key.If the record is not found, the API returns an error.

See Also: clDbalOpen(), clDbalClose(), clDbalRecordReplace(), clDbalRecordInsert(), clDbalRecordGet()

ClRcT clDbalRecordFree	(	CL_IN ClDBHandleT	dbHandle,
		CL_IN ClDBRecordHandleT	dbRec
	)

Frees the database record.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle	Handle to the Database. This is the handle that was returned to the user when clDbalOpen() call was successfully executed.
dbRec	Record to be freed.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.

Description:: This API is used to free the record returned by clDbalRecordGet(), clDbalNextRecordGet(), clDbalFirstRecordGet(). Since the record is created by clDbalRecordInsert(), it can not be freed by clHeapFree. So for proper cleanup of records, this API must be called after every successful call of clDbalRecordGet(), clDbalFirstRecordGet(), clDbalNextRecordGet().

See Also: clDbalRecordGet(), clDbalFirstRecordGet(), clDbalNextRecordGet()

ClRcT clDbalRecordGet	(	CL_IN ClDBHandleT	dbHandle,
		CL_IN ClDBKeyHandleT	dbKey,
		CL_IN ClUint32T	keySize,
		CL_OUT ClDBRecordHandleT *	pDBRec,
		CL_OUT ClUint32T *	pRecSize
	)

Retrieves a record from a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle	Handle to the Database from which the record is being retrieved. This is the handle that was returned to the user when clDbalOpen() call was successfully executed.
dbKey	Key handle, whose associated record is being retrieved.
keySize	Size of the key.
pDBRec	(out) Pointer to record handle, in which the record is being returned. Memory allocation is done by DBAL but you must free this memory using clDbalRecordFree() API.
pRecSize	(out) Pointer to variable in which size of the record is being returned.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_DBAL_ERR_DB_ERROR	If the underlying database fails.
CL_ERR_NOT_EXIST	If the key does not exist.

Description:: This API retrieves a record from the Database using the database handle and the record's key. If no record is found on the key of the specified record, an error is returned.

See Also: clDbalOpen(), clDbalClose(), clDbalRecordReplace(), clDbalRecordInsert(), clDbalRecordDelete()

ClRcT clDbalRecordInsert	(	CL_IN ClDBHandleT	dbHandle,
		CL_IN ClDBKeyHandleT	dbKey,
		CL_IN ClUint32T	keySize,
		CL_IN ClDBRecordHandleT	dbRec,
		CL_IN ClUint32T	recSize
	)

Record Operation APIs.

Adds a record into a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle	Handle to the Database into which the record is being added. This is the handle that was returned to the user when clDbalOpen() call was successfully executed.
dbKey	Record's key handle. In case of GDBM the key must be a string.
keySize	Size of the key.
dbRec	Record handle. In case of GDBM, the record must be a string.
recSize	Size of the record.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_ERR_DUPLICATE	If an already existing key is added.
CL_DBAL_ERR_DB_ERROR	If the underlying database fails.

Description:: This API adds a record into a Database known by its handle. If the specified key already exists in the database, then an error is returned.

See Also: clDbalOpen(), clDbalClose(), clDbalRecordGet(), clDbalRecordReplace(), clDbalRecordDelete()

ClRcT clDbalRecordReplace	(	CL_IN ClDBHandleT	dbHandle,
		CL_IN ClDBKeyHandleT	dbKey,
		CL_IN ClUint32T	keySize,
		CL_IN ClDBRecordHandleT	dbRec,
		CL_IN ClUint32T	recSize
	)

Replaces a record in a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle	Handle to the Database into which the record is being added. This is the handle that was returned to the user when clDbalOpen() call was successfully executed.
dbKey	Record's key handle.
keySize	Size of the key.
dbRec	Record handle.
recSize	Size of the record.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_DBAL_ERR_DB_ERROR	If the underlying database fails.

Description:: This API replaces a record in a Database known by its handle. If the specified key already exists in the database, then the record associated with it is replaced with the current record. If the key does not exist, then the record is added.

See Also: clDbalOpen(), clDbalClose(), clDbalRecordGet(), clDbalRecordInsert(), clDbalRecordDelete()

ClRcT clDbalSync	(	CL_IN ClDBHandleT	dbHandle,
		ClUint32T	flags
	)

Flushes (synchronizes) the DB modifications stored in the in-memory cache to disk.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle	Handle of the Database instance to be synchronized. This is the handle that was returned to the user when clDbalOpen() call was successfully executed.
flags	The flags parameter is currently unused, and must be set to 0.

Return values

CL_OK	The API executed successfully.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_ERR_INVALID_PARAMETER	On passing invalid parameters (flags).
CL_DBAL_ERR_DB_ERROR	If the underlying database fails.

Description:: This function is used to flush the DB modifications stored in the in-memory cache to disk for the DB represented by the dbHandle parameter. When you perform a database modification (insert, delete, replace etc), your modification may be made in the in-memory cache. This means that your data modifications are not necessarily flushed to disk, and so your data may not appear in the database after an application restart (if you have not called clDbalSync() after DB modifications). Note that as a normal part of closing a database (using clDbalClose()), its cache is written to disk. However, in the event of an application or system failure, there is no guarantee that your databases will close cleanly. In this event, it is possible for you to lose data. Therefore, if you want your data to be durable across system failures, i.e. you want some guarantee that your database modifications are persistent, then you should periodically call clDbalSync(). Syncs cause any dirty entries in the in-memory cache and the operating system's file cache to be written to disk. Note that clDbalSync() is expensive and you should use it sparingly.

See Also: clDbalClose()

ClRcT clDbalTransactionAbort ( CL_IN ClDBHandleT dbHandle )

Aborts a transaction on a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle Handle to the Database in which the transaction is being aborted. This is the handle that was returned to the user when clDbalTxnOpen() call was successfully executed.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_DBAL_ERR_ABORT_FAILED	If the abort of underlying database fails.
CL_ERR_NOT_SUPPORTED	If the underlying database does not support transactions.

Description:: This API is used to abort the recently started transaction. This removes the transaction ID specified in the handle.

Note: Once you have aborted a transaction, the transaction handle that is used for the transaction is no longer valid. To perform database activities under the control of a new transaction, you must update the DB handle using clDbalTransactionBegin().

See Also: clDbalTransactionBegin(), clDbalTransactionCommit()

ClRcT clDbalTransactionBegin ( CL_IN ClDBHandleT dbHandle )

Begins the transaction on a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle Handle to the Database in which the transaction is to be started. This is the handle that was returned to the user when clDbalTxnOpen() call was successfully executed.

Note: Transactions may only span threads if they do so serially, that is, each transaction must be active in only a single thread of control at a given point of time.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_ERR_NOT_SUPPORTED	If the underlying database does not support transactions.

Description:: This API marks the beginning of a transaction. This API must be called before calling further DBAL transaction related APIs. This API returns transactionId as part of the dbHandle, which will be passed for further operations.

See Also: clDbalTransactionCommit(), clDbalTransactionAbort()

ClRcT clDbalTransactionCommit ( CL_IN ClDBHandleT dbHandle )

Commits the transaction on a database instance.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbHandle Handle to the Database in which the transaction is being commited. This is the handle that was returned to the user when clDbalTxnOpen() call was successfully executed.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_HANDLE	On passing an invalid handle.
CL_DBAL_ERR_COMMIT_FAILED	If the commit of underlying database fails.
CL_ERR_NOT_SUPPORTED	If the underlying database does not support transactions.

Description:: This API commits the recently started transaction. All operations performed after calling clDbalTransactionBegin, will be committed in the database.

Note: Once you have committed a transaction, the transaction handle that is used for the transaction is no longer valid. To perform database activities under the control of a new transaction, you must update the DB handle using clDbalTransactionBegin().

See Also: clDbalTransactionBegin(), clDbalTransactionAbort()

ClRcT clDbalTxnOpen	(	CL_IN ClDBFileT	dbFile,
		CL_IN ClDBNameT	dbName,
		CL_IN ClDBFlagT	dbFlag,
		CL_IN ClUint32T	maxKeySize,
		CL_IN ClUint32T	maxRecordSize,
		CL_OUT ClDBHandleT *	pDBHandle
	)

Transaction Related APIs.

Opens a database instance with transaction support.

Header File:: clDbalApi.h

Library Files:: ClDbal

Parameters

dbFile	This parameter specifies the file name along with its path, where the database is to be created. If this parameter is NULL and the database is Berkeley Database, then an in-memory database is created. This parameter is ignored if the database is other than Berkeley Database.
dbName	This parameter specifies the database name along with its path, where the database is to be created. The records are stored in the database of this name. This parameter is used in case of both Berkeley and GDBM Database.
dbFlag	This flag accepts following three values: If CL_DB_CREAT is specified and the database already exists, then the existing database is deleted and a fresh one is created. If the database does not exist, then a new one is created. If CL_DB_OPEN is specified then existing database is opened. If the database does not exist, then an error is returned. If CL_DB_APPEND is specified and the database already exists, then the existing database is opened in append mode.If the database does not exist, then a fresh one is created.
maxKeySize	Maximum size of the key (in bytes) to be stored in the database. This parameter is ignored in case of Berkeley and GDBM databases.
maxRecordSize	Maximum size of the record (in bytes) to be stored in the database. This parameter is ignored in case of Berkeley and GDBM databases.
pDBHandle	(out)Pointer to variable of type ClDBHandleT in which the newly created database handle is returned. This handle should be used for all the subsequent operations on this database instance.

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	On passing a NULL pointer.
CL_ERR_INVALID_PARAMETER	On passing invalid parameters.
CL_ERR_NO_MEMORY	On memory allocation failure.
CL_DBAL_ERR_DB_ERROR	If the underlying database fails.
CL_ERR_NOT_SUPPORTED	If the underlying database does not support transactions.

Description:: This API opens a database instance on the specified Database and is transaction protected. Once this API is executed successfully the DB instance is ready for use in the transaction environment. This API must be executed before calling clDbalTransactionBegin() on the DB instance. DB handle returned by this API should be used for further operations on this database instance.

See Also: clDbalClose()

Files

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation