Introduction to the TIBCO ActiveSpaces C API

The following sections briefly describe how to use the C API. Refer to the Concepts guide for more details on the concepts employed.

Note: The code fragments are simplified for illustrative purposes. In particular, there is no error checking. See the operations.c sample program for a more complete example.

Setting up the Connection, Session and Table

The first thing any program will need to do is create a tibEx object to catch errors:

*   <BR>
*   tibEx ex = tibEx_Create();
*   if (ex == NULL)
*   {
*       printf( "memory failure\n");
*       exit(-1);
*   }
*
* 

Next the program needs to initialize ActiveSpaces and create tibdgConnection, tibdgSession and tibdgTable objects:

*
*   tibdg_Open(ex, TIBDG_COMPATIBILITY_VERSION);
*   
*   tibdgConnection conn = tibdgGrid_Connect(ex, "http://localhost:8080", NULL, NULL);
*   tibdgSession sess = tibdgConnection_CreateSession(ex, conn, NULL);
*   tibdgTable table = tibdgSession_OpenTable(ex, sess, "t1", NULL);
*
* 

In the code above, the type of tibdgSession that is created is a non-transactional one, so any operations on the tibdgTable will be applied immediately rather than requiring the program to call tibdgSession_Commit.

Putting a Row into a table

To add data to the table the program creates a tibdgRow containing the appropriate data and then calls tibdgTable_Put to put the data into the table. In the code fragment below, two rows are put into the table:

*
*   tibdgRow putRow = tibdgRow_Create(ex, table);
*
*   tibdgRow_SetLong(ex, putRow, "key", 1);
*   tibdgRow_SetString(ex, putRow, "value", "Hello");
*
*   tibdgTable_Put(ex, table, putRow);
*
*   tibdgRow_SetLong(ex, putRow, "key", 2);
*   tibdgRow_SetString(ex, putRow, "value", "World");
*
*   tibdgTable_Put(ex, table, putRow);
*
*   tibdgRow_Destroy(ex, putRow);
*
* 

Once the row has been put into the table, the tibdgRow can either be re-used or destroyed. A tibdgRow object should only be used with the tibdgTable object that created it.

Getting a Row from a table

To retrieve a row from a table the program creates a tibdgRow object and sets the primary key fields to match those of the row to be fetched. This "key row" is then passed to tibdgTable_Get, which returns a new tibdgRow containing the data retrieved from the table.

*
*   tibdgRow keyRow = tibdgRow_Create(ex, table);
*
*   tibdgRow_SetLong(ex, keyRow, "key", 1);
*
*   tibdgRow getRow = tibdgTable_Get(ex, table, keyRow);
*   if (getRow)
*   {
*       //
*       // process the row...
*       //
*
*       tibdgRow_Destroy(ex, getRow);
*   }
*
*   tibdgRow_Destroy(ex, keyRow);
*
* 

If there is no row with the given key, then tibdgTable_Get return will NULL. The program must destory both tibdgRow objects.

Querying a table

To retrieve multiple rows from the table the program uses a tibdgIterator created with a filter expression that is used to match the rows to be returned:

*
*   tibdgIterator iterator = tibdgTable_CreateIterator(ex, table, "key = 1 OR key = 2", NULL);
*           
*   tibdgRow row = NULL;
*   int rowCount = 0;
*   while (tibdgIterator_HasNext(ex, iterator))
*   {
*       row = tibdgIterator_Next(ex, iterator);
*       rowCount++;
*       tibdgRow_Destroy(ex, row);
*   }
*
*   printf("Iterated over %d rows in the table \n", rowCount);
*
*   tibdgIterator_Close(ex, iterator);
*
* 

To iterate over all the rows in the table specify NULL for the filter.

Destroying the Table and Session, then closing the Connection

When the program has completed all its operations on a given table, it should close the table. When all processing is complete, the program should destroy the session, close the connection and then close the library:

*
*   tibdgTable_Close(ex, table);
*
*   tibdgSession_Destroy(ex, sess);
*   tibdgConnection_Close(ex, conn);
*
*   tibdg_Close(ex);    
*
* 

Finally the program will destroy the tibEx object.

*
*   tibEx_Destroy(ex);
*
* 