# Poco::Data::ODBC

# class Preparator

Library: Data/ODBC
Package: ODBC
Header: Poco/Data/ODBC/Preparator.h

## Description

Class used for database preparation where we first have to register all data types with respective memory output locations before extracting data. Extraction works in two-phases: first prepare is called once, then extract n-times. In ODBC, SQLBindCol/SQLFetch is the preferred method of data retrieval (SQLGetData is available, however with numerous driver implementation dependent limitations and inferior performance). In order to fit this functionality into Poco DataConnectors framework, every ODBC SQL statement instantiates its own Preparator object. This is done once per statement execution (from StatementImpl::bindImpl()).

Preparator object is used to :

    1) Prepare SQL statement.
    2) Provide and contain the memory locations where retrieved values are placed during recordset iteration.
    3) Keep count of returned number of columns with their respective datatypes and sizes.

Notes:

- Value datatypes in this interface prepare() calls serve only for the purpose of type distinction. - Preparator keeps its own std::vector<Any> buffer for fetched data to be later retrieved by Extractor. - prepare() methods should not be called when extraction mode is DE_MANUAL

## Inheritance

Direct Base Classes: Poco::Data::AbstractPreparator

All Base Classes: Poco::Data::AbstractPreparator

## Member Summary

Member Functions: actualDataSize, at, bulkSize, columns, getDataExtraction, getMaxFieldSize, maxDataSize, operator [], prepare, setDataExtraction, setMaxFieldSize

Inherited Functions: getLength, isBulk, prepare, setBulk, setLength

## Types

### CharArray

typedef std::vector < char * > CharArray;

### Ptr

typedef SharedPtr < Preparator > Ptr;

## Enumerations

### DataExtraction

DE_MANUAL

DE_BOUND

### DataType

DT_BOOL

DT_BOOL_ARRAY

DT_CHAR

DT_WCHAR

DT_UCHAR

DT_CHAR_ARRAY

DT_WCHAR_ARRAY

DT_UCHAR_ARRAY

DT_DATE

DT_TIME

DT_DATETIME

## Constructors

### Preparator

Preparator(
const Preparator & other
);

Copy constructs the Preparator.

### Preparator

Preparator(
const StatementHandle & rStmt,
const std::string & statement,
std::size_t maxFieldSize,
DataExtraction dataExtraction = DE_BOUND
);

Creates the Preparator.

## Destructor

### ~Preparator

~Preparator() override;

Destroys the Preparator.

## Member Functions

### actualDataSize

std::size_t actualDataSize(
std::size_t col,
std::size_t row = POCO_DATA_INVALID_ROW
) const;

Returns the returned length for the column and row specified. This is usually equal to the column size, except for variable length fields (BLOB and variable length strings). For null values, the return value is -1 (SQL_NO_DATA)

### at

Poco::Any & at(
std::size_t pos
);

Returns reference to column data.

### bulkSize

std::size_t bulkSize(
std::size_t col = 0
) const;

Returns bulk size. Column argument is optional since all columns must be the same size.

### columns

std::size_t columns() const;

Returns the number of columns. Resizes the internal storage iff the size is zero.

### getDataExtraction

DataExtraction getDataExtraction() const;

Returns data extraction mode.

### getMaxFieldSize

std::size_t getMaxFieldSize() const;

### maxDataSize

std::size_t maxDataSize(
std::size_t pos
) const;

Returns max supported size for column at position pos. Returned length for variable length fields is the one supported by this implementation, not the underlying DB.

### operator []

Poco::Any & operator[] (
std::size_t pos
);

Returns reference to column data.

### prepare

void prepare(
std::size_t pos,
const Poco::Int8 & val
) override;

Prepares an Int8.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Int8 > & val
) override;

Prepares an Int8 vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Int8 > & val
) override;

Prepares an Int8 deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Int8 > & val
) override;

Prepares an Int8 list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const Poco::UInt8 & val
) override;

Prepares an UInt8.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::UInt8 > & val
) override;

Prepares an UInt8 vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::UInt8 > & val
) override;

Prepares an UInt8 deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::UInt8 > & val
) override;

Prepares an UInt8 list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const Poco::Int16 & val
) override;

Prepares an Int16.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Int16 > & val
) override;

Prepares an Int16 vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Int16 > & val
) override;

Prepares an Int16 deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Int16 > & val
) override;

Prepares an Int16 list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const Poco::UInt16 & val
) override;

Prepares an UInt16.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::UInt16 > & val
) override;

Prepares an UInt16 vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::UInt16 > & val
) override;

Prepares an UInt16 deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::UInt16 > & val
) override;

Prepares an UInt16 list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const Poco::Int32 & val
) override;

Prepares an Int32.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Int32 > & val
) override;

Prepares an Int32 vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Int32 > & val
) override;

Prepares an Int32 deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Int32 > & val
) override;

Prepares an Int32 list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const Poco::UInt32 & val
) override;

Prepares an UInt32.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::UInt32 > & val
) override;

Prepares an UInt32 vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::UInt32 > & val
) override;

Prepares an UInt32 deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::UInt32 > & val
) override;

Prepares an UInt32 list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const Poco::Int64 & val
) override;

Prepares an Int64.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Int64 > & val
) override;

Prepares an Int64 vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Int64 > & val
) override;

Prepares an Int64 deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Int64 > & val
) override;

Prepares an Int64 list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const Poco::UInt64 & val
) override;

Prepares an UInt64.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::UInt64 > & val
) override;

Prepares an UInt64 vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::UInt64 > & val
) override;

Prepares an UInt64 deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::UInt64 > & val
) override;

Prepares an UInt64 list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const bool & val
) override;

Prepares a boolean.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < bool > & val
) override;

Prepares a boolean vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < bool > & val
) override;

Prepares a boolean deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < bool > & val
) override;

Prepares a boolean list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const float & val
) override;

Prepares a float.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < float > & val
) override;

Prepares a float vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < float > & val
) override;

Prepares a float deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < float > & val
) override;

Prepares a float list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const double & val
) override;

Prepares a double.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < double > & val
) override;

Prepares a double vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < double > & val
) override;

Prepares a double deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < double > & val
) override;

Prepares a double list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const char & val
) override;

Prepares a single character.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < char > & val
) override;

Prepares a single character vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < char > & val
) override;

Prepares a single character deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < char > & val
) override;

Prepares a single character list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::string & val
) override;

Prepares a string.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < std::string > & val
) override;

Prepares a string vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < std::string > & val
) override;

Prepares a string deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < std::string > & val
) override;

Prepares a string list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const UTF16String & val
) override;

Prepares a string.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < UTF16String > & val
) override;

Prepares a string vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < UTF16String > & val
) override;

Prepares a string deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < UTF16String > & val
) override;

Prepares a string list.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const Poco::Data::BLOB & val
) override;

Prepares a BLOB.

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Data::BLOB > & val
) override;

Prepares a BLOB vector.

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Data::BLOB > & val
) override;

Prepares a BLOB deque.

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Data::BLOB > & val
) override;

Prepares a BLOB list.

### prepare

void prepare(
std::size_t pos,
const Poco::Data::CLOB & val
) override;

Prepares a CLOB.

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Data::CLOB > & val
) override;

Prepares a CLOB vector.

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Data::CLOB > & val
) override;

Prepares a CLOB deque.

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Data::CLOB > & val
) override;

Prepares a CLOB list.

### prepare

void prepare(
std::size_t pos,
const Poco::Data::Date & val
) override;

Prepares a Date.

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Data::Date > & val
) override;

Prepares a Date vector.

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Data::Date > & val
) override;

Prepares a Date deque.

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Data::Date > & val
) override;

Prepares a Date list.

### prepare

void prepare(
std::size_t pos,
const Poco::Data::Time & val
) override;

Prepares a Time.

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Data::Time > & val
) override;

Prepares a Time vector.

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Data::Time > & val
) override;

Prepares a Time deque.

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Data::Time > & val
) override;

Prepares a Time list.

### prepare

void prepare(
std::size_t pos,
const Poco::DateTime & val
) override;

Prepares a DateTime.

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::DateTime > & val
) override;

Prepares a DateTime vector.

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::DateTime > & val
) override;

Prepares a DateTime deque.

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::DateTime > & val
) override;

Prepares a DateTime list.

### prepare

void prepare(
std::size_t pos,
const Poco::UUID & val
) override;

Prepares a UUID.

### prepare

void prepare(
std::size_t pos,
const Poco::Any & val
) override;

Prepares an Any.

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Any > & val
) override;

Prepares an Any vector.

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Any > & val
) override;

Prepares an Any deque.

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Any > & val
) override;

Prepares an Any list.

### prepare

void prepare(
std::size_t pos,
const Poco::Dynamic::Var & val
) override;

Prepares a Dynamic::Var.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::vector < Poco::Dynamic::Var > & val
) override;

Prepares a Dynamic::Var vector.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::deque < Poco::Dynamic::Var > & val
) override;

Prepares a Dynamic::Var deque.

See also: Poco::Data::AbstractPreparator::prepare()

### prepare

void prepare(
std::size_t pos,
const std::list < Poco::Dynamic::Var > & val
) override;

Prepares a Dynamic::Var list.

See also: Poco::Data::AbstractPreparator::prepare()

### setDataExtraction

void setDataExtraction(
DataExtraction ext
);

Set data extraction mode.

### setMaxFieldSize

void setMaxFieldSize(
std::size_t size
);

Sets maximum supported field size.