The Ora++ Library
PrevChapter 3. The Database ClassesNext

3.3. The Stmt Class

The Stmt is an abstract base class for Select_Stmt and Non_Sel_Stmt.

Figure 3-2. class Stmt

namespace Oracle
{
    class Stmt: public ostringstream
    {
        public:
            // types
            enum stmt_t { Unknown, Select, Non_Select };
            enum state_t { Invalid, Closed, Initialized, Prepared,
                Executed, Defined, Fetched };

            // destructor
            virtual ~Stmt();

            // implementors
            virtual void prepare();
            virtual void prepare(const string&);
            virtual void bind(Nullable&);
            virtual void bind(Nullable&, const string&);
            virtual void bind_q(Nullable&);
            virtual void bind_q(Rowtype&);
            virtual void exec() = 0;
            virtual void close();

            // accessors
            int nrows() const;
            string str() const;
            state_t state() const;
            virtual stmt_t type() const = 0;
            int oci_type() const;
            int sql_fcode() const;

            friend class Rowtype;
            friend ostream& operator<<(ostream& s, const Stmt_Null_Manip& m);
            friend ostream& operator<<(ostream& s, const Stmt_Row_Manip& m);
    };
}

You cannot create a Stmt object, but a Stmt pointer is useful for statements whose types are unknown at compile time, such as for an interactive SQL executor. When you use this approach, you must use dynamic_cast to access the Select_Stmt-specific methods, as shown in Example 3-1.

Example 3-1. Using dynamic_cast with Stmt*

Stmt* st = db.prepare("select * from thetable");
st->exec();
Rowtype row(*dynamic_cast<Select_Stmt*>(st));
dynamic_cast<Select_Stmt*>(st)->bind_col(row);
while(dynamic_cast<Select_Stmt*>(st)->fetch())
	cout << row << endl;

3.3.1. Public Member Functions

3.3.1.1. Constructor

All constructors for the class are protected since Stmt objects are only constructed by friend classes, such as Connection and the derived statement classes.

3.3.1.2. bind()

void bind(Nullable& host_variable);

void bind(Nullable& host_variable, const string& placeholder_name);

This method provides the base functionality for binding a host variable to an input or output placeholder. The first version binds to the next placeholder not previously bound. The second version binds to the placeholder with the specified name. Mixing the use of these two functions will give unpredictable results.

3.3.1.3. bind_q()

void bind_q(Nullable& host_variable);

void bind_q(Rowtype& host_collection);

This method provides the functionality used by the bind() manipulator. The first version adds a single placeholder to the statement text and a single Nullable-derived object to the bind queue. The second version adds placeholders for each object in the Rowtype collection and all of those objects to the bind queue.

When the statement is executed, and the bind queue is non-empty, the bind() method is called for each object to bind it to the appropriate placeholder. (This is done by placeholder name, not position.) Then the statement is executed.

This method is not intended to be called in any other circumstance and may be protected in future releases.

3.3.1.4. close()

void close(void);

This method closes the statement and releases all resources held by the statement's data members. Note that for Stmt objects created by Connection::prepare(), the statement object itself is not released. A delete must be performed on the pointer to the Stmt object.

3.3.1.5. exec()

void exec(void);

This method is overridden by the derived classes to provide the functionality for executing the statement.

3.3.1.6. oci_type()

int oci_type(void);

This method returns the OCI SQL statement type code (OCI attribute OCI_ATTR_STMT_TYPE).

3.3.1.7. prepare()

void prepare(void);

void prepare(const string& statement_text);

This method parses the statement text. The first version prepares the text which has been built using the stream functionality. Once prepared, the text cannot be modified. The second version prepares the specified text. This may only be used on uninitialized statements which have had no text streamed into them.

3.3.1.8. sql_fcode()

int sql_fcode(void);

This method returns the OCI SQL function code (OCI attribute OCI_ATTR_SQLFNCODE).

3.3.1.9. state()

state_t state(void);

This method returns the state of the statement.

3.3.1.10. str()

string str(void);

This method returns the text of the statement.

3.3.1.11. type()

stmt_t type(void);

This method is overridden by the derived statement classes to return the statement type.

3.3.2. Non-Member Functions

3.3.2.1. operator<<()

ostream& operator<<(ostream& output_stream, const Stmt_Null_Manip& manipulator_object);

ostream& operator<<(ostream& output_stream, const Stmt_Row_Manip& manipulator_object);

The insertion operator outputs a Nullable-derived object using its string representation, as if str() were used.

3.3.3. Helper Classes

3.3.3.1. The Stmt_Null_Manip Class

to come

Figure 3-3. class Stmt_Null_Manip

namespace Oracle
{
    struct Stmt_Null_Manip
    {
        // constructor/destructor
        Stmt_Null_Manip(ostream& (*f)(ostream&, Nullable&), Nullable& o);
        ~Stmt_Null_Manip();
    
        // data members
        ostream& (*func)(ostream&, Nullable&);
        Nullable& obj;
    };
}

3.3.3.2. The Stmt_Row_Manip Class

to come

Figure 3-4. class Stmt_Row_Manip

namespace Oracle
{
    struct Stmt_Row_Manip
    {
        // constructor/destructor
        Stmt_Row_Manip(ostream& (*f)(ostream&, Rowtype&), Rowtype& o);
        ~Stmt_Row_Manip();
    
        // data members
        ostream& (*func)(ostream&, Rowtype&);
        Rowtype& obj;
    };
}
PrevHomeNext
The Connection ClassUpThe Select_Stmt Class