statement.h File Reference

A statment object is used 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 statment object is used 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.

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.

Parameters

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

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