TIBCO ActiveSpaces®

Functions
statement.h File Reference

A statement object is used to execute SQL and return a resultset. More...

## Functions
TIBDG_API void | tibdgStatement_ClearParameters (tibEx e, tibdgStatement statement)
| Clears all of the parameter values set on the statement object. More...
TIBDG_API void | tibdgStatement_Close (tibEx e, tibdgStatement statement)
| Close the statement object. More...
TIBDG_API tibdgResultSet | tibdgStatement_ExecuteQuery (tibEx e, tibdgStatement statement, tibProperties props)
| Executes the query on the statement object and returns the resultset object. More...
TIBDG_API tibint64_t | tibdgStatement_ExecuteUpdate (tibEx e, tibdgStatement statement, tibProperties props)
| Executes the update on the statement object and returns the number of rows updated. More...
TIBDG_API tibint64_t | tibdgStatement_GetParameterCount (tibEx e, tibdgStatement statement)
TIBDG_API tibdgResultSetMetadata | tibdgStatement_GetResultSetMetadata (tibEx e, tibdgStatement statement)
| Get the metadata associated with a statement. More...
TIBDG_API void | tibdgStatement_SetDateTime (tibEx e, tibdgStatement statement, tibint32_t parameterIndex, const tibDateTime *dt)
| Sets a datetime value to a parameter number in a statement object. More...
TIBDG_API void | tibdgStatement_SetDouble (tibEx e, tibdgStatement statement, tibint32_t parameterIndex, tibdouble_t dvalue)
| Sets a double value to a parameter number in a statement object. More...
TIBDG_API void | tibdgStatement_SetLong (tibEx e, tibdgStatement statement, tibint32_t parameterIndex, tibint64_t lvalue)
| Sets a long value to a parameter number in a statement object. More...
TIBDG_API void | tibdgStatement_SetNull (tibEx e, tibdgStatement statement, tibint32_t parameterIndex)
| Sets an empty value for a parameter number in a statement object. More...
TIBDG_API void | tibdgStatement_SetOpaque (tibEx e, tibdgStatement statement, tibint32_t parameterIndex, const void *ovalue, tibint32_t size)
| Sets an opaque value to a parameter number in a statement object. More...
TIBDG_API void | tibdgStatement_SetString (tibEx e, tibdgStatement statement, tibint32_t parameterIndex, const char *svalue)
| Sets a string value to a parameter number in a statement object. More...

## Detailed Description

A statement object is used to execute SQL and return a resultset.

A program that creates a statement object must explicitly call tibdgStatement_Close to reclaim its resources.

## Function Documentation

## ◆ tibdgStatement_ClearParameters()

TIBDG_API void tibdgStatement_ClearParameters | ( | tibEx | e,
|  | tibdgStatement | statement
| ) |  |

Clears all of the parameter values set on the statement object.

After calling this function, all parameters must be set again before calling ExecuteQuery. A partially bound statement object may be closed without calling this function.

Parameters

  e | The exception object captures information about failures.
  statement | The statement to clear bindings

Returns
  void

## ◆ tibdgStatement_Close()

TIBDG_API void tibdgStatement_Close | ( | tibEx | e,
|  | tibdgStatement | statement
| ) |  |

Close the statement object.

Note that all resultset objects must also be closed to allow for the statement's resources to also be reclaimed.

Parameters

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

Returns
  void

## ◆ tibdgStatement_ExecuteQuery()

TIBDG_API tibdgResultSet tibdgStatement_ExecuteQuery | ( | tibEx | e,
|  | tibdgStatement | statement,
|  | tibProperties | props
| ) |  |

Executes the query on the statement object and returns the resultset object.

Cannot be called if there are any open resultsets on the statement object.

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_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT property should be set to prevent the fetch requests from timing out. If this property is set when the statement is created, it will apply be applied to all executions of the statement. If you wish to override the value that was set when the statement was created for a particular execution, it can be set when calling tibdgStatement_ExecuteQuery. 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.

Parameters

  e | The exception object captures information about failures.
  statement | The statement from which to execute the query.
  props | Optional. `NULL` to omit. TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT

Returns
  tibdgResultSet

## ◆ tibdgStatement_ExecuteUpdate()

TIBDG_API tibint64_t tibdgStatement_ExecuteUpdate | ( | tibEx | e,
|  | tibdgStatement | statement,
|  | tibProperties | props
| ) |  |

Executes the update on the statement object and returns the number of rows updated.

This call will block while the statement is executed. If updating a table is expected to take a long time, the property TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT should be set to prevent the update from timing out. This property can be set when a statement is first created. If set when ExecuteUpdate is invoked, the ExecuteUpdate property will override the statement property. For Statements with a <where clause>, the optional properties TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH, TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY and TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT can be specified to affect how the table is queried to discover the rows to update.

Parameters

  e | The exception object captures information about failures.
  statement | The statement from which to execute the update.
  props | Optional. `NULL` to omit. TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT

Returns
  tibint64_t The number of rows updated.

## ◆ tibdgStatement_GetParameterCount()

TIBDG_API tibint64_t tibdgStatement_GetParameterCount | ( | tibEx | e,
|  | tibdgStatement | statement
| ) |  |

Returns the number of parameters that the statement contains.

Parameters

  e | The exception object captures information about failures.
  statement | The statement.

Returns
  On success, this call returns the number of parameters in the statement
  On failure, this call returns 0.

## ◆ tibdgStatement_GetResultSetMetadata()

TIBDG_API tibdgResultSetMetadata tibdgStatement_GetResultSetMetadata | ( | tibEx | e,
|  | tibdgStatement | statement
| ) |  |

Get the metadata associated with a statement.

Parameters

  e | The exception object captures information about failures.
  statement | The statement to get metadata

Returns
  On success, this call returns the resultset Metadata
  On failure, this call returns `NULL`.

## ◆ tibdgStatement_SetDateTime()

TIBDG_API void tibdgStatement_SetDateTime | ( | tibEx | e,
|  | tibdgStatement | statement,
|  | tibint32_t | parameterIndex,
|  | const tibDateTime * | dt
| ) |  |

Sets a datetime value to a parameter number in a statement object.

Copies the datetime parameter so that the program is allowed to free or modify it after the function returns.

Note that parameter numbers start from 1. Setting the same parameter number multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

Parameters

  e | The exception object captures information about failures.
  statement | The statement from which to bind the value.
  parameterIndex | The parameter number to set.
  dt | The datetime value to set into the statement.

Returns
  void

## ◆ tibdgStatement_SetDouble()

TIBDG_API void tibdgStatement_SetDouble | ( | tibEx | e,
|  | tibdgStatement | statement,
|  | tibint32_t | parameterIndex,
|  | tibdouble_t | dvalue
| ) |  |

Sets a double value to a parameter number in a statement object.

Note that parameter numbers start from 1. Setting the same parameter number multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

Parameters

  e | The exception object captures information about failures.
  statement | The statement from which to bind the value.
  parameterIndex | The parameter number to set.
  dvalue | The double value to set into the statement.

Returns
  void

## ◆ tibdgStatement_SetLong()

TIBDG_API void tibdgStatement_SetLong | ( | tibEx | e,
|  | tibdgStatement | statement,
|  | tibint32_t | parameterIndex,
|  | tibint64_t | lvalue
| ) |  |

Sets a long value to a parameter number in a statement object.

Note that parameter numbers start from 1. Setting the same parameter number multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

Parameters

  e | The exception object captures information about failures.
  statement | The statement from which to bind the value.
  parameterIndex | The parameter number to set.
  lvalue | The long value to set into the statement.

Returns
  void

## ◆ tibdgStatement_SetNull()

TIBDG_API void tibdgStatement_SetNull | ( | tibEx | e,
|  | tibdgStatement | statement,
|  | tibint32_t | parameterIndex
| ) |  |

Sets an empty value for a parameter number in a statement object.

Note that parameter numbers start from 1. Setting the same parameter number multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

Parameters

  e | The exception object captures information about failures.
  statement | The statement containing the parameter.
  parameterIndex | The parameter number to set.

Returns
  void

## ◆ tibdgStatement_SetOpaque()

TIBDG_API void tibdgStatement_SetOpaque | ( | tibEx | e,
|  | tibdgStatement | statement,
|  | tibint32_t | parameterIndex,
|  | const void * | ovalue,
|  | tibint32_t | size
| ) |  |

Sets an opaque value to a parameter number in a statement object.

Copies the opaque parameter so that the program is allowed to free or modify it after the function returns.

Note that parameter numbers start from 1. Setting the same parameter number multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

Parameters

  e | The exception object captures information about failures.
  statement | The statement from which to bind the value.
  parameterIndex | The parameter number to set.
  ovalue | The opaque value to set into the statement.
  size | The size of the opaque in bytes.

Returns
  void

## ◆ tibdgStatement_SetString()

TIBDG_API void tibdgStatement_SetString | ( | tibEx | e,
|  | tibdgStatement | statement,
|  | tibint32_t | parameterIndex,
|  | const char * | svalue
| ) |  |

Sets a string value to a parameter number in a statement object.

Copies the string parameter so that the program is allowed to free or modify it after the function returns.

Note that parameter numbers start from 1. Setting the same parameter number multiple times is allowed, even with different types, as long as when ExecuteQuery is called all parameters are set and have the correct types.

Parameters

  e | The exception object captures information about failures.
  statement | The statement from which to bind the value.
  parameterIndex | The parameter number to set.
  svalue | The string value to set into the statement.

Returns
  void