TIBCO ActiveSpaces®

Functions
sess.h File Reference

A session object provides the context for a thread of operations involving data grid resources. More...

## Functions
TIBDG_API void | tibdgSession_Commit (tibEx e, tibdgSession session)
| Commit the current transaction on this session and begin a new transaction. More...
TIBDG_API tibdgStatement | tibdgSession_CreateStatement (tibEx e, tibdgSession session, const char *sqlString, tibProperties props)
| Create a SQL statement object. More...
TIBDG_API tibdgBatchResult | tibdgSession_DeleteRows (tibEx e, tibdgSession session, tibdgRow *rows, tibint32_t numRows, tibProperties properties)
| DELETE a batch of rows from the datagrid. More...
TIBDG_API void | tibdgSession_Destroy (tibEx e, tibdgSession session)
| Destroy a session. More...
TIBDG_API tibint64_t | tibdgSession_ExecuteUpdate (tibEx e, tibdgSession session, const char *sqlString, tibProperties props)
| Execute a SQL Update. More...
TIBDG_API tibdgConnection | tibdgSession_GetConnection (tibEx e, tibdgSession session)
| Get the connection object was used to create the session. More...
TIBDG_API tibdgBatchResult | tibdgSession_GetRows (tibEx e, tibdgSession session, tibdgRow *rows, tibint32_t numRows, tibProperties properties)
| GET a batch of rows from the datagrid. More...
TIBDG_API void | tibdgSession_Interrupt (tibEx e, tibdgSession session)
| Interrupt a session object. More...
TIBDG_API tibdgTable | tibdgSession_OpenTable (tibEx e, tibdgSession session, const char *name, tibProperties props)
| Open a table in the data grid. More...
TIBDG_API tibdgBatchResult | tibdgSession_PutRows (tibEx e, tibdgSession session, tibdgRow *rows, tibint32_t numRows, tibProperties properties)
| PUT a batch of rows into the datagrid. More...
TIBDG_API void | tibdgSession_Rollback (tibEx e, tibdgSession session)
| Rollback a transaction on this session. More...
TIBDG_API tibdgBatchResult | tibdgSession_UpdateRows (tibEx e, tibdgSession session, tibdgRow *rows, tibint32_t numRows, tibProperties properties)
| Update a batch of rows in the datagrid. More...

## Detailed Description

A session object provides the context for a thread of operations involving data grid resources.

Two types of sessions are supported: transacted and non-transacted.

A non-transacted session (the default) executes operations one at a time. Each operation is complete as soon as the function returns.

A transacted session combines operations into a transaction, and completes work when tibdgSession_Commit or tibdgSession_Rollback is called.

Sessions are not thread-safe. Applications should guarantee that only one thread performs operations on a session at a time.

## Function Documentation

## ◆ tibdgSession_Commit()

TIBDG_API void tibdgSession_Commit | ( | tibEx | e,
|  | tibdgSession | session
| ) |  |

Commit the current transaction on this session and begin a new transaction.

Committing a transaction causes the data grid to make permanent all table operations performed since the start of the current transaction.

Parameters

  e | The exception object captures information about failures.
  session | The session on which to commit the transaction.

Returns
  void

## ◆ tibdgSession_CreateStatement()

TIBDG_API tibdgStatement tibdgSession_CreateStatement | ( | tibEx | e,
|  | tibdgSession | session,
|  | const char * | sqlString,
|  | tibProperties | props
| ) |  |

Create a SQL statement object.

The tibdgStatement_ExecuteQuery call will block while it fetches the first batch of rows. If fetching each batch of rows is always expected to take a long time then the TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT property should be set when the statement is created to prevent the fetch requests from timing out. The value provided when the statement is created can also be overridden each time the Statement is executed. 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 query takes to execute so that a meaningful timeout can be set in production. The tibdgStatement_ExecuteUpdate call will block waiting for the result of the update. If updating a table is expected to take a long time then the TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT property should be set when the statement is created to prevent the updates from timing out. The value provided when the statement is created can also be overridden each time the Statement is executed.

Parameters

  e | The exception object captures information about failures.
  session | The session from which to create to the statement object.
  sqlString | The sql string used to create the statement.
  props | Optional. `NULL` to omit. TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT *

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

## ◆ tibdgSession_DeleteRows()

TIBDG_API tibdgBatchResult tibdgSession_DeleteRows | ( | tibEx | e,
|  | tibdgSession | session,
|  | tibdgRow * | rows,
|  | tibint32_t | numRows,
|  | tibProperties | properties
| ) |  |

DELETE a batch of rows from the datagrid.

DELETE numRows rows whose primary keys are contained in the rows array from the datagrid. If all rows were successfully deleted, calling tibdgBatchResult_AllSucceeded with the returned batchResult will return true. In this case, the application may call the following functions to get additional information from the returned batchResult.

- tibdgBatchResult_GetSize - get the number of rows ( numRows )

If any failures occur, calling tibdgBatchResult_AllSucceeded with the returned batchResult will return false.

Note: the rows may be on different tables. Not valid for transacted sessions

Parameters

  e | The exception object captures information about failures.
  session | The session from which to DELETE the rows
  rows | The array of rows to DELETE
  numRows | The length of the rows array
  properties | Optional. `NULL` to omit.

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

## ◆ tibdgSession_Destroy()

TIBDG_API void tibdgSession_Destroy | ( | tibEx | e,
|  | tibdgSession | session
| ) |  |

Destroy a session.

Release all the resources associated with this session.

If a transaction was started on this session, this call automatically rolls back the transaction.

Parameters

  e | The exception object captures information about failures.
  session | The session to be destroyed.

Returns
  void

## ◆ tibdgSession_ExecuteUpdate()

TIBDG_API tibint64_t tibdgSession_ExecuteUpdate | ( | tibEx | e,
|  | tibdgSession | session,
|  | const char * | sqlString,
|  | tibProperties | props
| ) |  |

Execute a SQL Update.

A SQL update can be Create Table, Create Index, Drop Table, or Drop Index

Parameters

  e | The exception object captures information about failures.
  session | The session from which to execute the SQL Update
  sqlString | The sql string representing the update to execute
  props | Optional. `NULL` to omit.

Returns
  On success, this call returns the number of rows modified by the update.
  On failure, this call returns `0`.

## ◆ tibdgSession_GetConnection()

TIBDG_API tibdgConnection tibdgSession_GetConnection | ( | tibEx | e,
|  | tibdgSession | session
| ) |  |

Get the connection object was used to create the session.

Parameters

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

Returns
  a connection object

## ◆ tibdgSession_GetRows()

TIBDG_API tibdgBatchResult tibdgSession_GetRows | ( | tibEx | e,
|  | tibdgSession | session,
|  | tibdgRow * | rows,
|  | tibint32_t | numRows,
|  | tibProperties | properties
| ) |  |

GET a batch of rows from the datagrid.

GET numRows rows whose primary keys are contained in the rows array from the datagrid. If all rows were successfully read, calling tibdgBatchResult_AllSucceeded with the returned batchResult will return true. In this case, the application may call the following functions to get additional information from the returned batchResult.

- tibdgBatchResult_GetSize - get the number of rows ( numRows )
- tibdgBatchResult_GetRow - get a row from the results array. If the row did not exist, this will return NULL.

If any failures occur, calling tibdgBatchResult_AllSucceeded with the returned batchResult will return false.

Note: the rows may be on different tables. Not valid for transacted sessions

Parameters

  e | The exception object captures information about failures.
  session | The session from which to GET the rows
  rows | The array of rows to GET
  numRows | The length of the rows array
  properties | Optional. `NULL` to omit.

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

## ◆ tibdgSession_Interrupt()

TIBDG_API void tibdgSession_Interrupt | ( | tibEx | e,
|  | tibdgSession | session
| ) |  |

Interrupt a session object.

Interrupts any outstanding request on the session forcing it to return an interrupted error (TIB_INTR).

Use this call to interrupt long-running requests such as executions of queries with long or unlimited fetch timeouts. This can be helpful prior to closing the session or its connection.

Parameters

  e | The exception object captures information about failures.
  session | The session from which to DELETE the rows

Returns
  void

## ◆ tibdgSession_OpenTable()

TIBDG_API tibdgTable tibdgSession_OpenTable | ( | tibEx | e,
|  | tibdgSession | session,
|  | const char * | name,
|  | tibProperties | props
| ) |  |

Open a table in the data grid.

A table object contains rows and columns.

Parameters

  e | The exception object captures information about failures.
  session | The session on which to create this table.
  name | The name of the table to be opened. This table must already be defined in the data grid.
  props | Optional. `NULL` to omit. TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME

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

## ◆ tibdgSession_PutRows()

TIBDG_API tibdgBatchResult tibdgSession_PutRows | ( | tibEx | e,
|  | tibdgSession | session,
|  | tibdgRow * | rows,
|  | tibint32_t | numRows,
|  | tibProperties | properties
| ) |  |

PUT a batch of rows into the datagrid.

PUT numRows rows from the rows array into the datagrid. If all rows were successfully written, calling tibdgBatchResult_AllSucceeded with the returned batchResult will return true. In this case, the application may call the following functions to get additional information from the returned batchResult.

- tibdgBatchResult_GetSize - get the number of rows ( numRows )

If any failures occur, calling tibdgBatchResult_AllSucceeded with the returned batchResult will return false. In this case, some or all of the rows may have been successfully written to the data grid. The application should handle failures with this in mind.

Note: the rows may be on different tables. Not valid for transacted sessions

Parameters

  e | The exception object captures information about failures.
  session | The session from which to PUT the rows
  rows | The array of rows to PUT
  numRows | The length of the rows array
  properties | Optional. `NULL` to omit.

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

## ◆ tibdgSession_Rollback()

TIBDG_API void tibdgSession_Rollback | ( | tibEx | e,
|  | tibdgSession | session
| ) |  |

Rollback a transaction on this session.

Rolling back a transaction causes the data grid to discard all table operations performed since the start of the transaction.

Parameters

  e | The exception object captures information about failures.
  session | The session on which to rollback the transaction.

Returns
  void

## ◆ tibdgSession_UpdateRows()

TIBDG_API tibdgBatchResult tibdgSession_UpdateRows | ( | tibEx | e,
|  | tibdgSession | session,
|  | tibdgRow * | rows,
|  | tibint32_t | numRows,
|  | tibProperties | properties
| ) |  |

Update a batch of rows in the datagrid.

Update numRows rows whose primary keys and columns to be updated are contained in the rows array in the datagrid.

Each row contains 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.

If all rows were successfully updated, calling tibdgBatchResult_AllSucceeded with the returned batchResult will return true.
In this case, the application may call the following functions to get additional information from the returned batchResult.

- tibdgBatchResult_GetSize - get the number of rows ( numRows )
- tibdgBatchResult_GetRowUpdateCount - get the number of rows (0 or 1) that were updated for the row in the input

If any failures occur, calling tibdgBatchResult_AllSucceeded with the returned batchResult will return false. In this case, some or all of the rows may have been successfully updated in the data grid. The application should handle failures with this in mind.

Note: the rows may be on different tables. Not valid for transacted sessions

Parameters

  e | The exception object captures information about failures.
  session | The session from which to update the rows
  rows | The array of rows to update
  numRows | The length of the rows array
  properties | Optional. `NULL` to omit.

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