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

e	The exception object captures information about failures.
table	The 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

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.

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.

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

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

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

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

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