TIBCO ActiveSpaces®

TIBCO ActiveSpaces C API

# 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);
tibdgGrid_Connect
TIBDG_API tibdgConnection tibdgGrid_Connect(tibEx e, const char *URL, const char *gridName, tibProperties props)
Create a connection object.
tibdgConnection_CreateSession
TIBDG_API tibdgSession tibdgConnection_CreateSession(tibEx e, tibdgConnection conn, tibProperties props)
Create a session object to perform operations.
tibdgConnection
struct __tibdgConnectionId * tibdgConnection
The connection object provides access to a data grid.
Definition: conn.h:36
tibdgSession_OpenTable
TIBDG_API tibdgTable tibdgSession_OpenTable(tibEx e, tibdgSession session, const char *name, tibProperties props)
Open a table in the data grid.
TIBDG_COMPATIBILITY_VERSION
#define TIBDG_COMPATIBILITY_VERSION
Definition: tibdg.h:38
tibdg_Open
TIBDG_API void tibdg_Open(tibEx e, tibint32_t compatible_version)
Initialize ActiveSpaces.
tibdgTable
struct __tibdgTableId * tibdgTable
A table object contains rows.
Definition: types.h:38
tibdgSession
struct __tibdgSessionId * tibdgSession
A session object provides the context for a thread of operations involving data grid resources.
Definition: types.h:31

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);
tibdgRow_Destroy
TIBDG_API void tibdgRow_Destroy(tibEx e, tibdgRow row)
Destroy a row object.
tibdgRow_Create
TIBDG_API tibdgRow tibdgRow_Create(tibEx e, tibdgTable table)
Create an empty row object.
tibdgRow_SetLong
TIBDG_API void tibdgRow_SetLong(tibEx e, tibdgRow row, const char *columnName, tibint64_t value)
Set a long integer in a column for this row.
tibdgRow_SetString
TIBDG_API void tibdgRow_SetString(tibEx e, tibdgRow row, const char *columnName, const char *value)
Set a string in a column for this row.
tibdgTable_Put
TIBDG_API void tibdgTable_Put(tibEx e, tibdgTable table, tibdgRow keyValue)
Put a row into a table.
tibdgRow
struct __tibdgRow * tibdgRow
A row object contains columns.
Definition: types.h:49

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);
tibdgTable_Get
TIBDG_API tibdgRow tibdgTable_Get(tibEx e, tibdgTable table, tibdgRow key)
Get a row from a table.

If there is no row with the given key, then tibdgTable_Get return will `NULL`. The program must destroy 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);
tibdgIterator_HasNext
TIBDG_API tibbool_t tibdgIterator_HasNext(tibEx e, tibdgIterator iterator)
Inform the caller if the iterator has more rows or not.
tibdgIterator_Next
TIBDG_API tibdgRow tibdgIterator_Next(tibEx e, tibdgIterator iterator)
Advance the iterator to the next row and returns it.
tibdgIterator_Close
TIBDG_API void tibdgIterator_Close(tibEx e, tibdgIterator iterator)
Close an iterator.
tibdgTable_CreateIterator
TIBDG_API tibdgIterator tibdgTable_CreateIterator(tibEx e, tibdgTable table, const char *filter, tibProperties props)
Create an iterator to selectively get rows in the table.
tibdgIterator
struct __tibdgIteratorId * tibdgIterator
An iterator object supports selectively returning a set of matching rows.
Definition: types.h:74

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);
tibdgConnection_Close
TIBDG_API void tibdgConnection_Close(tibEx e, tibdgConnection conn)
Close a connection object.
tibdgSession_Destroy
TIBDG_API void tibdgSession_Destroy(tibEx e, tibdgSession session)
Destroy a session.
tibdgTable_Close
TIBDG_API void tibdgTable_Close(tibEx e, tibdgTable table)
Close a table.
tibdg_Close
TIBDG_API void tibdg_Close(tibEx e)
Cleanup ActiveSpaces.

Finally the program will destroy the `tibEx` object.

tibEx_Destroy(ex);