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...
TIBDG_API tibint64_t | tibdgTable_Update (tibEx e, tibdgTable table, tibdgRow keyValue)
| Update a row in the table. More...

## Detailed Description

A table object contains rows.

## Function Documentation

## ◆ tibdgTable_Close()

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

  e | The exception object captures information about failures.
  table | The table to be closed.

Returns
  void

## ◆ 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.

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. The use of an unlimited timeout is NOT advised in production environments because there are certain error situations that can result in the application waiting forever for a response that will not come. An unlimited timeout could be used in testing/development to discover how long a given iterator takes to execute so that a meaningful timeout can be set in production.

Parameters

  e | The exception object captures information about failures.
  table | The table on which this row will be used.
  filter | A string containing a valid query. Use `NULL` to iterate over all the rows in the table.
  props | Optional. `NULL` to omit. TIBDG_ITERATOR_PROPERTY_LONG_PREFETCH TIBDG_ITERATOR_PROPERTY_STRING_CONSISTENCY TIBDG_ITERATOR_PROPERTY_DOUBLE_FETCH_TIMEOUT

Returns
  On success, this call returns a new iterator.
  On failure, this call returns `NULL`.

## ◆ tibdgTable_CreateListener()

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

  e | The exception object captures information about failures.
  table | The table on which to create the listener.
  filter | The filter string to limit the scope of the events received.
  callback | The function that will be invoked when new events are available.
  closure | An object to pass to the listener callback.
  properties | Optional. `NULL` to omit.

Returns
  On success, this call returns a new tablelistener.
  On failure, this call returns `NULL`.

## ◆ tibdgTable_Delete()

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

  e | The exception object captures information about failures.
  table | The table from which the row is to be deleted.
  key | The key information used to identify the row.

Returns
  void

## ◆ tibdgTable_Get()

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

  e | The exception object captures information about failures.
  table | The table from which the row is to be fetched.
  key | The key information used to fetch the row.

Returns
  tibdgRow

## ◆ tibdgTable_GetName()

TIBDG_API const char* tibdgTable_GetName | ( | tibEx | e,
|  | tibdgTable | table
| ) |  |

Get the name of the table.

Parameters

  e | The exception object captures information about failures.
  table | The table from which to get the name.

Returns
  a table name string

## ◆ tibdgTable_GetSession()

TIBDG_API tibdgSession tibdgTable_GetSession | ( | tibEx | e,
|  | tibdgTable | table
| ) |  |

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

Parameters

  e | The exception object captures information about failures.
  table | The table from which to get the session.

Returns
  a session object

## ◆ tibdgTable_Put()

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

  e | The exception object captures information about failures.
  table | The table into which the row is to be placed.
  keyValue | The key and value to be placed in the table.

Returns
  void

## ◆ tibdgTable_Update()

TIBDG_API tibint64_t tibdgTable_Update | ( | tibEx | e,
|  | tibdgTable | table,
|  | tibdgRow | keyValue
| ) |  |

Update a row in the 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. Will not edit columns not set. No effect if row does not exist.

Parameters

  e | The exception object captures information about failures.
  table | The table into which the row is to be placed.
  keyValue | The key and value to be placed in the table.

Returns
  number of rows modified as a result of the operation