The ITQuery class

Base class: ITErrorManager

Manages query processing, including errors that occur as a result of queries. ITQuery is derived from ITErrorManager. Results are returned as binary data encapsulated by value objects. To obtain a text version of the results, you must use conversion methods such as ITValue::Printable.

For details about using the different query methods, see When to use the different ITQuery methods.

For the ExecOneRow, ExecToSet, and NextRow methods, the unknwn argument is the address of a pointer to an ITEssential interface of an object that will be the parent of any subobjects that might be created by the method. The newly created subobject returns its own ITEssential interface pointer in the same argument (which is an argument of type in/out) if the object delegation was successful. The subobject reference count is 1 after the call. The default argument is NULL to indicate that no object delegation is to be performed.

An ITQuery is always created in the context of the server connection.

The ITQuery::ExecOneRow method returns NULL if an error occurred, but also returns NULL if the query returns no rows but is not in error. To check if there was a DBMS error, use the Error method.

This class provides the following methods.


Method	Description
ITQuery(const ITConnection &)	Constructor.
ITBool ExecForStatus(const ITString &)	Issues a query for which the caller is only interested in result status such as whether the query succeeded, the number of rows affected, and results. No result rows are returned. Specify the query in the ITString parameter. ExecForStatus() takes as an argument an ITString object, which must be a single valid SQL statement.
ITRow ExecOneRow(const ITString &, ITEssential *unknwn = NULL)	Issues a query for which a single result row is expected and returned. Returns a null pointer if an error occurs. If the query returns more than one row, the additional rows are discarded and no error is returned. Specify the query in the ITString parameter. ExecForStatus() takes as an argument an ITString object, which must be a single valid SQL statement.
ITSet ExecToSet(const ITString &, ITEssential *unknwn = NULL)	Issues a query and returns results by using a rowset object that has an ITSet interface. Returns a null pointer if an error occurs. Specify the query in the ITString parameter. ExecForStatus() takes as an argument an ITString object, which must be a single valid SQL statement.
ITBool ExecForIteration(const ITString &)	Issues a query. Returns `TRUE` if the query was accepted, `FALSE` if an immediate problem (such as a syntax error) was found. If the query is accepted, this call returns `TRUE`, and the user must call NextRow to fetch the results in order. NextRow must be called repeatedly until it returns `NULL` (meaning all rows are read) before your application can issue another query or perform other database operations on the connection. Specify the query in the ITString parameter. ExecForStatus() takes as an argument an ITString object, which must be a single valid SQL statement.
long RowCount()	Returns the number of rows affected by the last query issued on the ITQuery.
const ITString &Command()	Returns the type of SQL statement (select, create, update, and other statements).
ITRow NextRow(ITEssential *unknwn = NULL)	Returns the next result row, if any. Used with ExecForIteration to process results. Returns `NULL` when the last result row has been returned. If a query was issued with ExecForIteration, the RowCount and Command methods are not valid until NextRow returns `NULL`. The result row value must be released when done. The underlying connection remains checked out until the last row is received.
const ITTypeInfo *RowType()	Returns server type information about the row that will be fetched. Used with ExecForIteration to get the type of results before actually getting the first row.
const ITString &QueryText()	Returns the text of an SQL query.
ITBool Finish()	Finishes processing the query results without retrieving all rows. Use this method with ExecForIteration to terminate a query without retrieving all the resulting rows.