Class Poco::Data::Statement
Author: Applied Informatics Software Engineering GmbH and Contributors

# Poco::Data

# class Statement

Library: Data
Package: DataCore
Header: Poco/Data/Statement.h

## Description

A Statement is used to execute SQL statements. It does not contain code of its own. Its main purpose is to forward calls to the concrete StatementImpl stored inside. Statement execution can be synchronous or asynchronous. Synchronous ececution is achieved through execute() call, while asynchronous is achieved through executeAsync() method call. An asynchronously executing statement should not be copied during the execution.

Note:

Once set as asynchronous through 'async' manipulator, statement remains asynchronous for all subsequent execution calls, both execute() and executeAsync(). However, calling executAsync() on a synchronous statement shall execute asynchronously but without altering the underlying statement's synchronous nature.

Once asynchronous, a statement can be reverted back to synchronous state in two ways:

    1) By calling setAsync(false)
    2) By means of 'sync' or 'reset' manipulators

See individual functions documentation for more details.

Statement owns the RowFormatter, which can be provided externaly through setFormatter() member function. If no formatter is externally supplied to the statement, the SimpleRowFormatter is lazy created and used.

## Inheritance

Known Derived Classes: RecordSet

## Member Summary

Member Functions: addBind, addBinding, addExtract, addExtraction, addExtractions, canModifyStorage, columnsExtracted, dataSetCount, done, execute, executeAsync, extractionCount, extractions, getRowFormatter, getStorage, hasMoreDataSets, impl, initialized, isAsync, isBulkExtraction, isNull, metaColumn, nextDataSet, operator <<, operator =, operator,, paused, previousDataSet, removeBind, reset, rowsExtracted, session, setAsync, setRowFormatter, setStorage, storage, subTotalRowCount, swap, toString, wait

## Types

### AsyncExecMethod

typedef ActiveMethod < std::size_t, bool, StatementImpl > AsyncExecMethod;

### AsyncExecMethodPtr

typedef SharedPtr < AsyncExecMethod > AsyncExecMethodPtr;

### ImplPtr

typedef StatementImpl::Ptr ImplPtr;

### Manipulator

typedef void (* Manipulator)(Statement &);

### Result

typedef ActiveResult < std::size_t > Result;

### ResultPtr

typedef SharedPtr < Result > ResultPtr;

## Enumerations

### Storage

STORAGE_DEQUE = StatementImpl::STORAGE_DEQUE_IMPL

STORAGE_VECTOR = StatementImpl::STORAGE_VECTOR_IMPL

STORAGE_LIST = StatementImpl::STORAGE_LIST_IMPL

STORAGE_UNKNOWN = StatementImpl::STORAGE_UNKNOWN_IMPL

## Constructors

### Statement

Statement(
StatementImpl::Ptr pImpl
);

Creates the Statement.

### Statement

explicit Statement(
Session & session
);

Creates the Statement for the given Session.

The following:

    Statement stmt(sess);
    stmt << "SELECT * FROM Table", ...

is equivalent to:

    Statement stmt(sess << "SELECT * FROM Table", ...);

but in some cases better readable.

### Statement

Statement(
const Statement & stmt
);

Copy constructor. If the statement has been executed asynchronously and has not been synchronized prior to copy operation (i.e. is copied while executing), this constructor shall synchronize it.

## Destructor

### ~Statement

~Statement();

Destroys the Statement.

## Member Functions

### addBind

Statement & addBind(
AbstractBinding::Ptr pBind
);

Registers a single binding with the statement.

### addBinding

template < typename C > Statement & addBinding(
C & bindingCont,
bool reset
);

Registers binding container with the Statement.

### addExtract

Statement & addExtract(
AbstractExtraction::Ptr pExtract
);

Registers a single extraction with the statement.

### addExtraction

template < typename C > Statement & addExtraction(
C & val,
bool reset
);

Registers extraction container with the Statement.

### addExtractions

template < typename C > Statement & addExtractions(
C & val
);

Registers container of extraction containers with the Statement.

### canModifyStorage

bool canModifyStorage();

Returns true if statement is in a state that allows the internal storage to be modified.

### columnsExtracted

std::size_t columnsExtracted(
int dataSet = StatementImpl::USE_CURRENT_DATA_SET
) const;

Returns the number of columns returned for current data set. Default value indicates current data set (if any).

### dataSetCount

std::size_t dataSetCount() const;

Returns the number of data sets associated with the statement.

### done

bool done();

Returns true if the statement was completely executed or false if a range limit stopped it and there is more work to do. When no limit is set, it will always return true after calling execute().

### execute

std::size_t execute(
bool reset = true
);

Executes the statement synchronously or asynchronously. Stops when either a limit is hit or the whole statement was executed. Returns the number of rows extracted from the database (for statements returning data) or number of rows affected (for all other statements). If reset is true (default), associated storage is reset and reused. Otherwise, the results from this execution step are appended. Reset argument has no meaning for unlimited statements that return all rows. If isAsync() returns true, the statement is executed asynchronously and the return value from this function is zero. The result of execution (i.e. number of returned or affected rows) can be obtained by calling wait() on the statement at a later point in time.

### executeAsync

const Result & executeAsync(
bool reset = true
);

Executes the statement asynchronously. Stops when either a limit is hit or the whole statement was executed. Returns immediately. Calling wait() (on either the result returned from this call or the statement itself) returns the number of rows extracted or number of rows affected by the statement execution. When executed on a synchronous statement, this method does not alter the statement's synchronous nature.

### extractionCount

std::size_t extractionCount() const;

Returns the number of extraction storage buffers associated with the current data set.

### getStorage

const std::string & getStorage() const;

Returns the internal storage type for the statement.

### hasMoreDataSets

bool hasMoreDataSets() const;

Returns false if the current data set index points to the last data set. Otherwise, it returns true.

### initialized

bool initialized();

Returns true if the statement was initialized (i.e. not executed yet).

### isAsync

bool isAsync() const;

Returns true if statement was marked for asynchronous execution.

### nextDataSet

std::size_t nextDataSet();

Returns the index of the next data set.

### operator <<

template < typename T > Statement & operator << (
const T & t
);

Concatenates data with the SQL statement string.

### operator =

Statement & operator = (
const Statement & stmt
);

Assignment operator.

### operator,

Statement & operator, (
Manipulator manip
);

Handles manipulators, such as now, async, etc.

### operator,

Statement & operator, (
AbstractBinding::Ptr pBind
);

Registers the Binding with the Statement by calling addBind().

### operator,

Statement & operator, (
AbstractBindingVec & bindVec
);

Registers the Binding vector with the Statement.

### operator,

Statement & operator, (
AbstractExtraction::Ptr extract
);

Registers objects used for extracting data with the Statement by calling addExtract().

### operator,

Statement & operator, (
AbstractExtractionVec & extVec
);

Registers the extraction vector with the Statement. The vector is registered at position 0 (i.e. for the first returned data set).

### operator,

Statement & operator, (
AbstractExtractionVecVec & extVecVec
);

Registers the vector of extraction vectors with the Statement.

### operator,

Statement & operator, (
const Bulk & bulk
);

Sets the bulk execution mode (both binding and extraction) for this statement.Statement must not have any extractors or binders set at the time when this operator is applied. Failure to adhere to the above constraint shall result in InvalidAccessException.

### operator,

Statement & operator, (
BulkFnType
);

Sets the bulk execution mode (both binding and extraction) for this statement.Statement must not have any extractors or binders set at the time when this operator is applied. Additionally, this function requires limit to be set in order to determine the bulk size. Failure to adhere to the above constraints shall result in InvalidAccessException.

### operator,

Statement & operator, (
const Limit & extrLimit
);

Sets a limit on the maximum number of rows a select is allowed to return.

Set per default to zero to Limit::LIMIT_UNLIMITED, which disables the limit.

### operator,

Statement & operator, (
RowFormatter::Ptr pRowFformatter
);

Sets the row formatter for the statement.

### operator,

Statement & operator, (
const Range & extrRange
);

Sets a an extraction range for the maximum number of rows a select is allowed to return.

Set per default to Limit::LIMIT_UNLIMITED which disables the range.

### operator,

Statement & operator, (
char value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
Poco::UInt8 value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
Poco::Int8 value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
Poco::UInt16 value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
Poco::Int16 value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
Poco::UInt32 value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
Poco::Int32 value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
Poco::UInt64 value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
Poco::Int64 value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
double value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
float value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
bool value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
const std::string & value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### operator,

Statement & operator, (
const char * value
);

Adds the value to the list of values to be supplied to the SQL string formatting function.

### paused

bool paused();

Returns true if the statement was paused (a range limit stopped it and there is more work to do).

### previousDataSet

std::size_t previousDataSet();

Returns the index of the previous data set.

### removeBind

void removeBind(
const std::string & name
);

Removes the all the bindings with specified name from the statement.

### reset

Statement & reset(
Session & session
);

Resets the Statement so that it can be filled with a new SQL command.

### rowsExtracted

std::size_t rowsExtracted(
int dataSet = StatementImpl::USE_CURRENT_DATA_SET
) const;

Returns the number of rows returned for current data set during last statement execution. Default value indicates current data set (if any).

### setAsync

void setAsync(
bool async = true
);

Sets the asynchronous flag. If this flag is true, executeAsync() is called from the now() manipulator. This setting does not affect the statement's capability to be executed synchronously by directly calling execute().

### setRowFormatter

void setRowFormatter(
RowFormatter::Ptr pRowFormatter
);

Sets the row formatter for this statement. Statement takes the ownership of the formatter.

### setStorage

void setStorage(
const std::string & storage
);

Sets the internal storage type for the statement.

### storage

Storage storage() const;

Returns the internal storage type for the statement.

### subTotalRowCount

std::size_t subTotalRowCount(
int dataSet = StatementImpl::USE_CURRENT_DATA_SET
) const;

Returns the number of rows extracted so far for the data set. Default value indicates current data set (if any).

### swap

void swap(
Statement & other
);

Swaps the statement with another one.

### toString

const std::string & toString() const;

Creates a string from the accumulated SQL statement.

### wait

std::size_t wait(
long milliseconds = WAIT_FOREVER
);

Waits for the execution completion for asynchronous statements or returns immediately for synchronous ones. The return value for asynchronous statement is the execution result (i.e. number of rows retrieved). For synchronous statements, the return value is zero.

### extractions

const AbstractExtractionVec & extractions() const;

Returns the extractions vector.

### getRowFormatter

const RowFormatter::Ptr & getRowFormatter();

Returns the row formatter for this statement.

### impl

ImplPtr impl() const;

Returns pointer to statement implementation.

### isBulkExtraction

bool isBulkExtraction() const;

Returns true if this statement extracts data in bulk.

### isNull

bool isNull(
std::size_t col,
std::size_t row
) const;

Returns true if the current row value at column pos is null.

### metaColumn

const MetaColumn & metaColumn(
std::size_t pos
) const;

Returns the type for the column at specified position.

### metaColumn

const MetaColumn & metaColumn(
const std::string & name
) const;

Returns the type for the column with specified name.

### session

Session session();

Returns the underlying session.

## Variables

### WAIT_FOREVER

static const int WAIT_FOREVER = - 1;