API Usage Examples

Code Examples. More...

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

ClDBHandleT dbHandle    = CL_HANDLE_INVALID_VALUE; 
ClDBFileT   dbFile      = "/tmp/my_db_file";
ClDBNameT   dbName      = "/tmp/myDB.db";
ClUint32T   maxKeySize  = 5;
ClUint32T   maxRecSize  = 30;
ClDBFlagT   dbFlag      = CL_DB_CREAT;

rc = clDbalOpen(dbName, dbFile, dbFlag, maxKeySize, 
                maxRecSize, &dbHandle);  
if(CL_OK != rc) 
{  
    printf("Create: could not create database. rc = [0x %x]", 
           CL_GET_ERROR_CODE(rc));  
    return rc;
}  

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]", 
               CL_GET_ERROR_CODE(rc));  
        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,  
                         (ClDBRecordHandleT*)&data, 
                         &dataSize);  
    if(CL_OK != rc)
    {  
        printf("Could not get record from DB. rc = [0x %x]", 
               CL_GET_ERROR_CODE(rc));  
        return rc;  
    }  
    else 
    {  
        printf("Successfully retrieved record with key=%s:%s", 
                exmp[i].key, data);  
        clDbalRecordFree(dbHandle, (ClDBRecordHandleT)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]", 
                CL_GET_ERROR_CODE(rc));  
        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]", 
            CL_GET_ERROR_CODE(rc));  
    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", 
              CL_GET_ERROR_CODE(rc));  
      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]", 
               CL_GET_ERROR_CODE(rc));  
        return rc;  
    }  
    else 
    {  
        printf("Successfully deleted record with key=%s", exmp[i].key);  
    }  
}  

Close the Database

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

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.

ClDBHandleT dbHandle    = CL_HANDLE_INVALID_VALUE; 
ClDBFileT   dbFile      = "/tmp/my_db_file";
ClDBNameT   dbName      = "/tmp/myDB.db";
ClUint32T   maxKeySize  = 5;
ClUint32T   maxRecSize  = 30;
ClDBFlagT   dbFlag      = CL_DB_CREAT;

rc = clDbalTxnOpen(dbName, dbFile, dbFlag, maxKeySize, maxRecSize, 
                   &dbHandle);  
if(CL_OK != rc) 
{  
    printf("Create: could not create database. rc = [0x %x]", 
            CL_GET_ERROR_CODE(rc));  
    return rc;
}  

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]", 
            CL_GET_ERROR_CODE(rc));  
    return rc;
}  

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]", 
                CL_GET_ERROR_CODE(rc));  
        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,  
                         (ClDBRecordHandleT*)&data, 
                         &dataSize);  
    if(CL_OK != rc)
    {  
        printf("Could not get record from DB. rc = [0x %x]", 
                CL_GET_ERROR_CODE(rc));  
        return rc;  
    }  
    else 
    {  
        printf("Successfully retrieved record with key=%s:%s", 
                exmp[i].key, data);  
        clDbalRecordFree(dbHandle, (ClDBRecordHandleT)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]", 
                CL_GET_ERROR_CODE(rc));  
        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]", 
            CL_GET_ERROR_CODE(rc));  
    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", 
              CL_GET_ERROR_CODE(rc));  
      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]", 
                CL_GET_ERROR_CODE(rc));  
        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]", 
            CL_GET_ERROR_CODE(rc));  
    return rc;  
}  
else 
{  
    printf("Successfully commited transaction");  
}  

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]", 
            CL_GET_ERROR_CODE(rc));  
    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]", 
                CL_GET_ERROR_CODE(rc));  
        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]", 
            CL_GET_ERROR_CODE(rc));  
    return rc;  
}  
else 
{  
    printf("Successfully aborted transaction");  
}  

Close the Database

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