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

# Poco::Data

# class StatementImpl

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

## Description

StatementImpl interface that subclasses must implement to define database dependent query execution.

StatementImpl's are noncopyable.

## Inheritance

Known Derived Classes: Poco::Data::MySQL::MySQLStatementImpl, Poco::Data::ODBC::ODBCStatementImpl, Poco::Data::SQLite::SQLiteStatementImpl

## Member Summary

Member Functions: activateNextDataSet, activatePreviousDataSet, add, addBind, addExtract, affectedRowCount, bindImpl, binder, bindings, canBind, canCompile, columnsExtracted, columnsReturned, compileImpl, currentDataSet, dataSetCount, execute, extractionCount, extractionLimit, extractions, extractor, fixupBinding, fixupExtraction, getExtractionLimit, getState, getStorage, hasMoreDataSets, hasNext, isStoredProcedure, makeExtractors, metaColumn, next, removeBind, reset, resetBinding, rowsExtracted, session, setExtractionLimit, setStorage, subTotalRowCount, toString

## Types

### Ptr

typedef Poco::SharedPtr < StatementImpl > Ptr;

## Enumerations

### BulkType

BULK_UNDEFINED

Bulk mode not defined yet.

BULK_BINDING

Binding in bulk mode. If extraction is present in the same statement, it must also be bulk.

BULK_EXTRACTION

Extraction in bulk mode. If binding is present in the same statement, it must also be bulk.

BULK_FORBIDDEN

Bulk forbidden. Happens when the statement has already been configured as non-bulk.

### State

ST_INITIALIZED

ST_COMPILED

ST_BOUND

ST_PAUSED

ST_DONE

ST_RESET

### Storage

STORAGE_DEQUE_IMPL

STORAGE_VECTOR_IMPL

STORAGE_LIST_IMPL

STORAGE_UNKNOWN_IMPL

## Constructors

### StatementImpl

StatementImpl(
SessionImpl & rSession
);

Creates the StatementImpl.

## Destructor

### ~StatementImpl

virtual ~StatementImpl();

Destroys the StatementImpl.

## Member Functions

### add

template < typename T > void add(
const T & t
);

Appends SQL statement (fragments).

### addBind

void addBind(
AbstractBinding::Ptr pBinding
);

Registers the Binding with the StatementImpl.

### addExtract

void addExtract(
AbstractExtraction::Ptr pExtraction
);

Registers objects used for extracting data with the StatementImpl.

### dataSetCount

std::size_t dataSetCount() const;

Returns the number of data sets associated with the statement.

### execute

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

Executes a statement. Returns the number of rows extracted for statements returning data or number of rows affected for all other statements (insert, update, delete). If reset is true (default), the underlying bound storage is reset and reused. In case of containers, this means they are cleared and resized to accomodate the number of rows returned by this execution step. When reset is false, data is appended to the bound containers during multiple execute calls.

### extractionCount

std::size_t extractionCount() const;

Returns the number of extraction storage buffers associated with the statement.

### getState

State getState() const;

Returns the state of the Statement.

### getStorage

Storage getStorage() const;

Returns the storage type for this statement.

### removeBind

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

Unregisters all the bindings having specified name with the StatementImpl. Bindings are released and, if this class was the sole owner, deleted.

### reset

void reset();

Resets the statement, so that we can reuse all bindings and re-execute again.

### setExtractionLimit

void setExtractionLimit(
const Limit & extrLimit
);

Changes the extractionLimit to extrLimit. Per default no limit (EXTRACT_UNLIMITED) is set.

### setStorage

void setStorage(
Storage storage
);

Sets the storage type for this statement;

### setStorage

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

Sets the storage type for this statement;

### toString

std::string toString() const;

Create a string version of the SQL statement.

### activateNextDataSet

std::size_t activateNextDataSet();

Returns the next data set index, or throws NoDataException if the last data set was reached.

### activatePreviousDataSet

std::size_t activatePreviousDataSet();

Returns the previous data set index, or throws NoDataException if the last data set was reached.

### affectedRowCount

virtual int affectedRowCount() const = 0;

Returns the number of affected rows. Used to find out the number of rows affected by insert, delete or update.

Some back-ends may return a negative number in certain circumstances (e.g. some ODBC drivers when this function is called after a select statement execution).

### bindImpl

virtual void bindImpl() = 0;

Binds parameters.

### binder

virtual AbstractBinding::BinderPtr binder() = 0;

Returns the concrete binder used by the statement.

### bindings

const AbstractBindingVec & bindings() const;

Returns the const reference to bindings vector.

### bindings

AbstractBindingVec & bindings();

Returns the reference to bindings.

### canBind

virtual bool canBind() const = 0;

Returns true if another bind is possible.

### canCompile

virtual bool canCompile() const = 0;

Returns true if another compile is possible.

### columnsExtracted

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

Returns the number of columns that the extractors handle.

### columnsReturned

virtual std::size_t columnsReturned() const = 0;

Returns number of columns returned by query.

### compileImpl

virtual void compileImpl() = 0;

Compiles the statement, doesn't bind yet.

### currentDataSet

std::size_t currentDataSet() const;

Returns the current data set.

### extractionLimit

const Limit & extractionLimit() const;

Returns the extraction limit.

### extractions

const AbstractExtractionVec & extractions() const;

Returns the const reference to extractions vector.

### extractions

AbstractExtractionVec & extractions();

Returns the reference to extractions vector.

### extractor

virtual AbstractExtraction::ExtractorPtr extractor() = 0;

Returns the concrete extractor used by the statement.

### fixupBinding

void fixupBinding();

Sets the AbstractBinder at the bindings.

### fixupExtraction

void fixupExtraction();

Sets the AbstractExtractor at the extractors.

### getExtractionLimit

Limit::SizeT getExtractionLimit();

Returns the extraction limit value.

### hasMoreDataSets

bool hasMoreDataSets() const;

Returns true if there are data sets not activated yet.

### hasNext

virtual bool hasNext() = 0;

Returns true if a call to next() will return data.

Note that the implementation must support several consecutive calls to hasNext without data getting lost, ie. hasNext(); hasNext(); next() must be equal to hasNext(); next();

### isStoredProcedure

virtual bool isStoredProcedure() const;

Returns true if the statement is stored procedure. Used as a help to determine whether to automatically create the internal extractions when no outside extraction is supplied. The reason for this function is to prevent unnecessary internal extraction creation in cases (behavior exhibited by some ODBC drivers) when there is data available from the stored procedure call statement execution but no external extraction is supplied (as is usually the case when stored procedures are called). In such cases no storage is needed because output parameters serve as storage. At the Data framework level, this function always returns false. When connector-specific behavior is desired, it should be overriden by the statement implementation.

### makeExtractors

void makeExtractors(
std::size_t count
);

Determines the type of the internal extraction container and calls the extraction creation function (addInternalExtract) with appropriate data type and container type arguments.

This function is only called in cases when there is data returned by query, but no data storage supplied by user.

The type of the internal container is determined in the following order: 1. If statement has the container type set, the type is used. 2. If statement does not have the container type set,

    session is queried for container type setting. If the
    session container type setting is found, it is used.

3. If neither session nor statement have the internal

    container type set, std::deque is used.

Supported internal extraction container types are: - std::deque (default) - std::vector - std::list

### metaColumn

virtual const MetaColumn & metaColumn(
std::size_t pos
) const = 0;

Returns column meta data.

### metaColumn

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

Returns column meta data.

### next

virtual std::size_t next() = 0;

Retrieves the next row or set of rows from the resultset and returns the number of rows retreved.

Will throw, if the resultset is empty. Expects the statement to be compiled and bound.

### resetBinding

void resetBinding();

Resets binding so it can be reused again.

### rowsExtracted

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

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

### session

SessionImpl & session();

Rteurns session associated with this statement.

### subTotalRowCount

std::size_t subTotalRowCount(
int dataSet = 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).

## Variables

### DEQUE

static const std::string DEQUE;

### LIST

static const std::string LIST;

### UNKNOWN

static const std::string UNKNOWN;

### USE_CURRENT_DATA_SET

static const int USE_CURRENT_DATA_SET = - 1;

### VECTOR

static const std::string VECTOR;