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

## Detailed Description

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

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

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.

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.

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.

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