Namespace Sql
Class CSqlStatement

class CSqlStatement: public CInterface {
public:
    CSqlStatement();
    virtual ~CSqlStatement();
public:
    virtual void Prepare(
        const CString &strSql, 
        const CParamDescr ¶mDescr) = 0;
    virtual void Execute(
        const XArray<CString> &arrParam,
        const CNullParam &nullParam) = 0;
    virtual void ExecuteDirect(const CString &strSql) = 0;
    virtual void Batch(
        int nParamCount,
        const XArray<CString> &arrParam,
        const CNullParam &nullParam) = 0;
    virtual void Select(
        const XArray<CString> &arrParam,
        const CNullParam &nullParam) = 0;
    virtual void SelectDirect(const CString &strSql) = 0;
    virtual void CloseCursor() = 0;
    virtual bool Fetch() = 0;
    virtual bool IsEmpty() = 0;
    virtual CString GetColumn(const CString &strColumn) = 0;
    virtual bool IsColumnNull(const CString &strColumn) = 0;
    virtual CString GetCursorName() = 0;
    virtual bool CanBatch() = 0;
    };

The abstract interface to SQL statements.

For each SQL statement a separate instance of CSqlStatement must be created.

Few member functions provided by this class request execution of SQL statements. When any of these functions is called, the array of actual parameter values and the array of null-indicators must be supplied as function arguments. These two arrays must be empty if the statement does not require parameters.

The actual parameter values must be represented as strings; the database access engine will automatically convert them to the appropriate SQL data types.

The array of null-indicators specifies, which parameter values which must be interpreted as SQL null values. The null-indicator array must be supplied, together with the array of actual parameter values, when a member function of CSqlStatement which requests execution of an SQL statement is called. The size of the null-indicator array must be equal to the number of parameters required by the SQL statement. If the supplied value of the i -th parameter is equal to the i -th element in the null-indicator array, this parameter will be treated as null during execution of the statement.

Since:

1.00.00

Version:

1.00.00

Author:

Alexey Gokhberg

See Also:

CParamDescr

CSqlStatement

CSqlStatement();

Constructs the SQL statement.

~CSqlStatement

virtual ~CSqlStatement();

Destroys the SQL statement.

Prepare

virtual void Prepare(
    const CString &strSql, 
    const CParamDescr ¶mDescr) = 0;

Prepares this SQL statement.

The source text of the SQL statement must be supplied by the caller.

The list of parameter descriptions must be always supplied, even if the statement requires no parameters (in which case the list must be empty).

Parameters:

strSql - the source text of the SQL statement

paramDescr - the list of parameter descriptions; must be empty if the statement requires no parameters

Execute

virtual void Execute(
    const XArray<CString> &arrParam,
    const CNullParam &nullParam) = 0;

Executes the prepared statement.

Parameters:

arrParam - the array of parameter values

nullParam - the array of null-indicators

ExecuteDirect

virtual void ExecuteDirect(const CString &strSql) = 0;

Executes the statement directly (unprepared).

Parameters are not allowed in SQL statements executed directly.

Parameters:

strSql - the source text of the SQL statement

Batch

virtual void Batch(
    int nParamCount,
    const XArray<CString> &arrParam,
    const CNullParam &nullParam) = 0;

Executes the prepared parametrized statement in a batch.

When the parametrized SQL statement is executed in a batch, multiple sets of actual parameter values can be supplied. In a single call, the SQL statement will be sequentially executed with each set of parameter values. The array of parameter values arrParam must have the size equal to the number of parameters in a single set multiplied by the number of sets. The number of parameters in a single set (which must be equal to the number of parameters required by this SQL statement) must be supplied as the separate argument nParamCount . The parameter values corresponding to the n -th set of parameters are located at indexes from nParamCount * n through nParamCount * n + (nParamCount - 1) in the array arrParam .

Note, that the null-indicator array arrNull must have the size equal to the number of parameters in a single set (that is, nParamCount ).

Data sources are not required to support batch execution. Attempt to perform batch execution on the data source which does not support it will result in an exception thrown.

Parameters:

nParamCount - the number of parameters in a single set

arrParam - the array containing parameter values from all sets

nullParam - the array of null-indicators

Select

virtual void Select(
    const XArray<CString> &arrParam,
    const CNullParam &nullParam) = 0;

Executes a prepared SELECT statement.

On successful execution of the statement, the result set is created. Rows in the result set are accessed sequentially using the internal cursor. Initially the cursor is positioned before the start of the result set.

Parameters:

arrParam - the array of parameter values

nullParam - the array of null-indicators

SelectDirect

virtual void SelectDirect(const CString &strSql) = 0;

Executes a SELECT statement directly (unprepared).

On successful execution of the statement, the result set is created. Rows in the result set are accessed sequentially using the internal cursor. Initially the cursor is positioned before the start of the result set.

Parameters are not allowed in SQL statements executed directly.

Parameters:

strSql - the source text of the SQL statement

CloseCursor

virtual void CloseCursor() = 0;

Closes the cursor associated with this statement.

When the SELECT statement is executed using Select or SelectDirect , the internal cursor containing result set data is created. The CloseCursor function closes this cursor, releasing related resources and making result set data inaccessible.

Fetch

virtual bool Fetch() = 0;

Positions the internal cursor on the next row of the result set.

The internal result set must be created by the prior call to Select or SelectDirect . If there is no next row in the result set, the cursor is positioned after the end of the result set.

Returns:

true if the next row in the result set was found; false if the cursor was positioned after the end of the result set

IsEmpty

virtual bool IsEmpty() = 0;

Tests whether the internal result set is empty (contains no rows).

The internal result set must be created by the prior call to Select or SelectDirect .

Returns:

true if the result set is empty; false otherwise

GetColumn

virtual CString GetColumn(const CString &strColumn) = 0;

Returns the string value of the specified column of the result set row pointed by the cursor.

The internal result set must be created by the prior call to Select or SelectDirect .

The column value is converted to a string. If the specified column has null value, the empty string is returned. Column names are treated case-insensitive. The exception is thrown if the column with the specified name is not found in the result set.

Parameters:

strColumn - the column name

Returns:

the string representation of the column value

IsColumnNull

virtual bool IsColumnNull(const CString &strColumn) = 0;

Tests whether the specified column of the result set row pointed by the cursor has null value.

The internal result set must be created by the prior call to Select or SelectDirect .

Column names are treated case-insensitive. The exception is thrown if the column with the specified name is not found in the result set.

Parameters:

strColumn - the column name

Returns:

true is the specified column has null value; false otherwise

GetCursorName

virtual CString GetCursorName() = 0;

Returns a cursor name associated with this statement.

Returns:

the cursor name associated with this statement

CanBatch

virtual bool CanBatch() = 0;

Tests whether batch execution is supported by the data source for this statement.

Returns:

true if batch execution is supported; false otherwise