OpenClovis Logo

Code Examples.

Code Examples.

Global Data which are nedded for the code examples

#define NUMBER_OF_ITEMS 10
typedef struct exampleData{
ClCharT key[3];
ClCharT data[30];
}ExampleDataT;
ExampleDataT exmp[] = { {"1","Ravi Kumar Singh"},
{"2","Har Gagan Sahai"},
{"3","Deepak B"},
{"4","Karthic A R"},
{"5","Amit Gourgonda"},
{"6","Vikram"},
{"7","Jnanesh Kumar"},
{"8","Naveen"},
{"9","Mayank Rungta"},
{"10","Ramesh"}
};

Example 1 - Normal Database operation (without transaction support) :

Open or create a Database instance. In the following example, dbFlag can take one of the following values : CL_DB_CREAT, CL_DB_OPEN, CL_DB_APPEND

ClDBFileT dbFile = "/tmp/my_db_file";
ClDBNameT dbName = "/tmp/myDB.db";
ClUint32T maxKeySize = 5;
ClUint32T maxRecSize = 30;
rc = clDbalOpen(dbName, dbFile, dbFlag, maxKeySize,
maxRecSize, &dbHandle);
if(CL_OK != rc)
{
printf("Create: could not create database. rc = [0x %x]",
return rc;
}
#define CL_GET_ERROR_CODE(RC)
This macro extracts the error code from the return code.
Definition: clCommonErrors.h:297
#define CL_OK
Every thing is OK.
Definition: clCommonErrors.h:68
ClUint8T ClDBFlagT
Definition of database open flag type.
Definition: clDbalApi.h:127
ClPtrT ClDBHandleT
Database Handle.
Definition: clDbalApi.h:174
const char * ClDBNameT
Type of the name of database.
Definition: clDbalApi.h:163
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.
#define CL_DB_CREAT
This DB flag is used for creating a DB.
Definition: clDbalApi.h:133
const char * ClDBFileT
Type of the DB File name.
Definition: clDbalApi.h:168
#define CL_HANDLE_INVALID_VALUE
Defines.
Definition: clHandleApi.h:95

Add ten records into the database

for(i = 0; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalRecordInsert(dbHandle,
(ClDBKeyHandleT)exmp[i].key,
strlen(exmp[i].key)+1,
(ClDBRecordHandleT)exmp[i].data,
strlen(exmp[i].data)+1);
if(CL_OK != rc)
{
printf("Could not add record into DB, rc = [0x %x]",
return rc;
}
else
{
printf("Successfully added %s:%s", exmp[i].key, exmp[i].data);
}
}
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.
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...
Definition: clDbalApi.h:192
ClUint8T * ClDBRecordHandleT
Type of DB Record Handle (handle to the record which is to be inserted in DB or to be fetched from th...
Definition: clDbalApi.h:180

Retrieve all ten records which were added earlier.

ClCharT *data = NULL;
ClUint32T dataSize = 0;
for(i = 0; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalRecordGet(dbHandle, (ClDBKeyHandleT)exmp[i].key,
strlen(exmp[i].key)+1,
&dataSize);
if(CL_OK != rc)
{
printf("Could not get record from DB. rc = [0x %x]",
return rc;
}
else
{
printf("Successfully retrieved record with key=%s:%s",
exmp[i].key, data);
}
}
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.

Replace the ten records which were added earlier.

for(i = 0; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalRecordReplace(dbHandle, (ClDBKeyHandleT)exmp[i].key,
strlen(exmp[i].key)+1,
(ClDBRecordHandleT)exmp[NUMBER_OF_ITEMS-i-1].data,
strlen(exmp[NUMBER_OF_ITEMS-i-1].data)+1);
if(CL_OK != rc)
{
printf("Could not replace record into DB. rc = [0x %x]",
return rc;
}
else
{
printf("Successfully replaced %s:%s", exmp[i].key,
exmp[NUMBER_OF_ITEMS-i-1].data);
}
}
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.

Traverse through the database and get the records :

[1] Return the first record

ClCharT *firstKey = NULL;
ClUint32T firstKeySize = 0;
ClCharT *firstData = NULL;
ClUint32T firstDataSize = 0;
rc = clDbalFirstRecordGet(dbHandle, (ClDBKeyHandleT*)&firstKey,
&firstKeySize, (ClDBRecordHandleT*)&firstData,
&firstDataSize);
if(CL_OK != rc)
{
printf("Could not retrieve the first record. rc = [0x %x]",
return rc;
}
else
{
printf("Retrieved record %s:%s", key, data);
clDbalKeyFree(dbHandle, (ClDBKeyHandleT)firstKey);
clDbalRecordFree(dbHandle, (ClDBRecordHandleT)firstData);
}
ClRcT clDbalKeyFree(CL_IN ClDBHandleT dbHandle, CL_IN ClDBKeyHandleT dbKey)
Frees the database key.
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.

[2] Get the next nine records.

/* Get the 'firstKey' using call to clDbalFirstRecordGet() */
ClCharT *curkey = firstKey;
for(i = 1; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalNextRecordGet(dbHandle, (ClDBKeyHandleT)curKey, curKeySize,
(ClDBKeyHandleT*)&nextKey, &nextKeySize,
(ClDBRecordHandleT*)&nextData, &dataSize);
if(CL_OK != rc)
{
printf("Could not retrieve the next record. rc = %d",
return rc;
}
else
{
printf("Retrieved record %s:%s", nextKey, nextData);
clDbalKeyFree(dbHandle, (ClDBKeyHandleT)curKey);
clDbalRecordFree(dbHandle, (ClDBRecordHandleT)nextData);
curKey = nextKey;
}
}
/*Free The last key */
clDbalKeyFree(dbHandle, (ClDBKeyHandleT)curKey);
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.

Delete all ten records added earlier

for(i = 0; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalRecordDelete(dbHandle, (ClDBKeyHandleT)exmp[i].key,
strlen(exmp[i].key)+1);
if(CL_OK != rc)
{
printf("Could not delete record from DB. rc = [0x %x]",
return rc;
}
else
{
printf("Successfully deleted record with key=%s", exmp[i].key);
}
}
ClRcT clDbalRecordDelete(CL_IN ClDBHandleT dbHandle, CL_IN ClDBKeyHandleT dbKey, CL_IN ClUint32T keySize)
Deletes a record from a database instance.

Close the Database

rc = clDbalClose(dbHandle);
if(CL_OK != rc)
{
printf("Could not close the database");
return rc;
}
ClRcT clDbalClose(CL_IN ClDBHandleT dbHandle)
Closes a database instance.

Example 2 - Database operation with transaction support :

Note : In case of GDBM and SQLite, transaction APIs are not supported.

Open or create a Database instance with transaction support.

ClDBFileT dbFile = "/tmp/my_db_file";
ClDBNameT dbName = "/tmp/myDB.db";
ClUint32T maxKeySize = 5;
ClUint32T maxRecSize = 30;
rc = clDbalTxnOpen(dbName, dbFile, dbFlag, maxKeySize, maxRecSize,
&dbHandle);
if(CL_OK != rc)
{
printf("Create: could not create database. rc = [0x %x]",
return rc;
}
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.

Begins a transaction if transaction protection is needed.
In case of GDBM, transaction APIs are not supported.

rc = clDbalTransactionBegin(dbHandle);
if(CL_OK != rc)
{
printf("Could not begin transaction. rc = [0x %x]",
return rc;
}
ClRcT clDbalTransactionBegin(CL_IN ClDBHandleT dbHandle)
Begins the transaction on a database instance.

Add ten records into the database

for(i = 0; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalRecordInsert(dbHandle, (ClDBKeyHandleT)exmp[i].key,
strlen(exmp[i].key)+1,
(ClDBRecordHandleT)exmp[i].data,
strlen(exmp[i].data)+1);
if(CL_OK != rc)
{
printf("Could not add record into DB, rc = [0x %x]",
return rc;
}
else
{
printf("Successfully added %s:%s", exmp[i].key, exmp[i].data);
}
}

Retrieve all ten records which were added earlier.

ClCharT *data = NULL;
ClUint32T dataSize = 0;
for(i = 0; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalRecordGet(dbHandle, (ClDBKeyHandleT)exmp[i].key,
strlen(exmp[i].key)+1,
&dataSize);
if(CL_OK != rc)
{
printf("Could not get record from DB. rc = [0x %x]",
return rc;
}
else
{
printf("Successfully retrieved record with key=%s:%s",
exmp[i].key, data);
}
}

Replace the ten records which were added earlier.

for(i = 0; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalRecordReplace(dbHandle, (ClDBKeyHandleT)exmp[i].key,
strlen(exmp[i].key)+1,
(ClDBRecordHandleT)exmp[NUMBER_OF_ITEMS-i-1].data,
strlen(exmp[NUMBER_OF_ITEMS-i-1].data)+1);
if(CL_OK != rc)
{
printf("Could not replace record into DB. rc = [0x %x]",
return rc;
}
else
{
printf("Successfully replaced %s:%s", exmp[i].key,
exmp[NUMBER_OF_ITEMS-i-1].data);
}
}

Traverse through the database and get the records :

[1] Return the first record

ClCharT *firstKey = NULL;
ClUint32T firstKeySize = 0;
ClCharT *firstData = NULL;
ClUint32T firstDataSize = 0;
rc = clDbalFirstRecordGet(dbHandle, (ClDBKeyHandleT*)&firstKey,
&firstKeySize,
(ClDBRecordHandleT*)&firstData,
&firstDataSize);
if(CL_OK != rc)
{
printf("Could not retrieve the first record. rc = [0x %x]",
return rc;
}
else
{
printf("Retrieved record %s:%s", key, data);
clDbalKeyFree(dbHandle, (ClDBKeyHandleT)firstKey);
clDbalRecordFree(dbHandle, (ClDBRecordHandleT)firstData);
}

[2] Get the next nine records.

/* Get the 'firstKey' using call to clDbalFirstRecordGet() */
ClCharT *curkey = firstKey;
for(i = 1; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalNextRecordGet(dbHandle, (ClDBKeyHandleT)curKey, curKeySize,
(ClDBKeyHandleT*)&nextKey, &nextKeySize,
(ClDBRecordHandleT*)&nextData, &dataSize);
if(CL_OK != rc)
{
printf("Could not retrieve the next record. rc = %d",
return rc;
}
else
{
printf("Retrieved record %s:%s", nextKey, nextData);
clDbalKeyFree(dbHandle, (ClDBKeyHandleT)curKey);
clDbalRecordFree(dbHandle, (ClDBRecordHandleT)nextData);
curKey = nextKey;
}
}
/*Free The last key */
clDbalKeyFree(dbHandle, (ClDBKeyHandleT)curKey);

Delete all ten records added earlier

for(i = 0; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalRecordDelete(dbHandle, (ClDBKeyHandleT)exmp[i].key,
strlen(exmp[i].key)+1);
if(CL_OK != rc)
{
printf("Could not delete record from DB. rc = [0x %x]",
return rc;
}
else
{
printf("Successfully deleted record with key=%s", exmp[i].key);
}
}

Commit the transaction. Committing a transaction will result in saving all the changes done upto this point to the database.

rc = clDbalTransactionCommit(dbHandle);
if(CL_OK != rc)
{
printf("Could not commit transaction. rc = [0x %x]",
return rc;
}
else
{
printf("Successfully commited transaction");
}
ClRcT clDbalTransactionCommit(CL_IN ClDBHandleT dbHandle)
Commits the transaction on a database instance.

You need to begin the new transaction by calling clDbalTransactionBegin() after every commit or abort.

rc = clDbalTransactionBegin(dbHandle);
if(CL_OK != rc)
{
printf("Could not begin transaction. rc = [0x %x]",
return rc;
}

Add ten records into the database in the new transaction

for(i = 0; i < NUMBER_OF_ITEMS; i++)
{
rc = clDbalRecordInsert(dbHandle, (ClDBKeyHandleT)exmp[i].key,
strlen(exmp[i].key)+1,
(ClDBRecordHandleT)exmp[i].data,
strlen(exmp[i].data)+1);
if(CL_OK != rc)
{
printf("Could not add record into DB, rc = [0x %x]",
return rc;
}
else
{
printf("Successfully added %s:%s", exmp[i].key, exmp[i].data);
}
}

Abort the transaction. Aborting a transaction will result in a rollback upto the point where the transaction was started.

rc = clDbalTransactionAbort(dbHandle);
if(CL_OK != rc)
{
printf("Could not abort transaction. rc = [0x %x]",
return rc;
}
else
{
printf("Successfully aborted transaction");
}
ClRcT clDbalTransactionAbort(CL_IN ClDBHandleT dbHandle)
Aborts a transaction on a database instance.

Close the Database

rc = clDbalClose(dbHandle);
if(CL_OK != rc)
{
printf("Could not close the database");
return rc;
}

Generated on Tue Jan 10 10:29:15 PST 2012 for OpenClovis SDK using Doxygen