TIBCO ActiveSpaces®
Functions
table.h File Reference

A table object contains rows. More...

Functions

TIBDG_API void tibdgTable_Close (tibEx e, tibdgTable table)
 Close a table. More...
 
TIBDG_API tibdgIterator tibdgTable_CreateIterator (tibEx e, tibdgTable table, const char *filter, tibProperties props)
 Create an iterator to selectively get rows in the table. More...
 
TIBDG_API tibdgTableListener tibdgTable_CreateListener (tibEx e, tibdgTable table, const char *filter, tibdgTableListenerCallback callback, void *closure, tibProperties properties)
 Create a tablelistener. More...
 
TIBDG_API void tibdgTable_Delete (tibEx e, tibdgTable table, tibdgRow key)
 Delete a row from a table. More...
 
TIBDG_API tibdgRow tibdgTable_Get (tibEx e, tibdgTable table, tibdgRow key)
 Get a row from a table. More...
 
TIBDG_API const char * tibdgTable_GetName (tibEx e, tibdgTable table)
 Get the name of the table. More...
 
TIBDG_API tibdgSession tibdgTable_GetSession (tibEx e, tibdgTable table)
 Get the session object that ws used to create the table. More...
 
TIBDG_API void tibdgTable_Put (tibEx e, tibdgTable table, tibdgRow keyValue)
 Put a row into a table. More...
 

Detailed Description

A table object contains rows.

Function Documentation

TIBDG_API void tibdgTable_Close ( tibEx  e,
tibdgTable  table 
)

Close a table.

Release all resources associated with this table object.

Note that pending operations on this table, e.g., transactional puts, gets or deletes, are marked as "rollback only" if this table is closed before the operations are committed.

Parameters
eThe exception object captures information about failures.
tableThe table to be closed.
Returns
void
TIBDG_API tibdgIterator tibdgTable_CreateIterator ( tibEx  e,
tibdgTable  table,
const char *  filter,
tibProperties  props 
)

Create an iterator to selectively get rows in the table.

This call creates an iterator that returns rows matching the filter. An iterator becomes invalid when the table object that created it becomes invalid.

Note that this function creates the iterator with its cursor set BEFORE the first row. The application MUST call tibdgIterator_Next first.

This call will block while it fetches the first batch of rows. If fetching each batch of rows is expected to take a long time then the TIBDG_ITERATOR_PROPERTY_DOUBLE_FETCH_TIMEOUT property should be set to prevent the fetch requests from timing out. If a value of zero is supplied for this property then there will be no limit to how long the application will wait.

Parameters
eThe exception object captures information about failures.
tableThe table on which this row will be used.
filterA string containing a valid query. Use NULL to iterate over all the rows in the table.
propsOptional. NULL to omit.
Returns
On success, this call returns a new iterator.
On failure, this call returns NULL.
TIBDG_API tibdgTableListener tibdgTable_CreateListener ( tibEx  e,
tibdgTable  table,
const char *  filter,
tibdgTableListenerCallback  callback,
void *  closure,
tibProperties  properties 
)

Create a tablelistener.

Table listeners receive tibdgEvent objects to indicate that the table they are listening on has changed. A filter can be provided so that only events that match the filter will be received. The syntax for the filter is the same as the syntax for the tibdgIterator. An event matches the filter if either its previous or current value match.

Parameters
eThe exception object captures information about failures.
tableThe table on which to create the listener.
filterThe filter string to limit the scope of the events received.
callbackThe function that will be invoked when new events are available.
closureAn object to pass to the listener callback.
propertiesOptional. NULL to omit.
Returns
On success, this call returns a new tablelistener.
On failure, this call returns NULL.
TIBDG_API void tibdgTable_Delete ( tibEx  e,
tibdgTable  table,
tibdgRow  key 
)

Delete a row from a table.

Using the columns in the key, this call deletes the row from the table.

Parameters
eThe exception object captures information about failures.
tableThe table from which the row is to be deleted.
keyThe key information used to identify the row.
Returns
void
TIBDG_API tibdgRow tibdgTable_Get ( tibEx  e,
tibdgTable  table,
tibdgRow  key 
)

Get a row from a table.

Using the columns set in the key, this call fetches the row from the table and returns it.

Note: Do not use a row object obtained from one table for operations in a different table. The schemas of the tables may not be compatible and the operations may fail.

Any row object obtained from this function must be released by calling tibdgRow_Destroy.

Parameters
eThe exception object captures information about failures.
tableThe table from which the row is to be fetched.
keyThe key information used to fetch the row.
Returns
tibdgRow
TIBDG_API const char* tibdgTable_GetName ( tibEx  e,
tibdgTable  table 
)

Get the name of the table.

Parameters
eThe exception object captures information about failures.
tableThe table from which to get the name.
Returns
a table name string
TIBDG_API tibdgSession tibdgTable_GetSession ( tibEx  e,
tibdgTable  table 
)

Get the session object that ws used to create the table.

Parameters
eThe exception object captures information about failures.
tableThe table from which to get the session.
Returns
a session object
TIBDG_API void tibdgTable_Put ( tibEx  e,
tibdgTable  table,
tibdgRow  keyValue 
)

Put a row into a table.

The contents of the row contain the information to be placed into the designated table. This must include the values for the columns that make up the primary key. Values for the other columns are optional.

Parameters
eThe exception object captures information about failures.
tableThe table into which the row is to be placed.
keyValueThe key and value to be placed in the table.
Returns
void