Class Query.

This class represents a single database query.

A Query is typically created by (or for, or with) a EventHandler, has parameter values bound to it with bind(), and is execute()d (or enqueue()d as part of a Transaction).

To accommodate queries that need to feed multiple lines of input to a COPY statement, a series of bind() calls may be followed by a call to submitLine() to form one line of input. This sequence can be repeated as many times as required, and execute() called as usual afterwards. (All parameters to a COPY must be bound in the Query::Binary format.)

Once the Query is executed, the Database informs its owner() of any interesting events (e.g. the arrival of results, timeouts, failures, or successful completion) by calling notify(). The Query's state() reflects its progress, as do the done() and failed() functions.

Each Query contains a list of rows (Row objects) of data received in response to itself. The hasResults() function tells you if there are any rows, which can be read and removed from the list by calling nextRow(). The query keeps track of the total number of rows() received.

A Query can be part of a Transaction.

Query::Query( EventHandler * ev )

Constructs a new empty Query handled by ev, which may be 0 to disable callbacks. (This form is provided for use by subclasses.)

Query::Query( const PreparedStatement & ps, EventHandler * ev )

Constructs a Query for ev from the prepared statement ps. If ev is 0, the query will run without notifying its owner of progress or completion.

Query::Query( const String & s, EventHandler * ev )

Constructs a Query for ev containing the SQL statement s. If ev is 0, the query will run without notifying its owner of progress or completion.

void Query::addRow( Row * r )

For each Row r received in response to this query, the Database calls this function to append it to the list of results.

void Query::allowFailure()

If this function is called before execute(), Postgres will not log an error if the Query fails. The query continues to be processed as it would be otherwise.

This is not communicated to the server, so if this query is part of a Transaction, its failure aborts the Transaction.

void Query::allowSlowness()

If this function is called before execute(), Postgres will not apply the default query timeout to this Query. The query continues to be processed as it would otherwise.

void Query::bind( uint n, const List<uint> * l )

Binds the array of integers l to the parameter n of this Query.

void Query::bind( uint n, const String & s, Format f )

Binds the String value s to the parameter n of this Query in the specified format f (or the default format for this query if f is left at the default value of Unknown).

void Query::bind( uint n, const StringList & l )

This version binds each string in l as parameter n.

void Query::bind( uint n, const UString & s )

Converts s to the database's unicode encoding and binds the result to the parameter n of this Query.

void Query::bind( uint n, const class MessageSet & set )

This version binds each number in set as parameter n.

void Query::bind( uint n, int s )

Binds the integer value s to the parameter n of this Query.

void Query::bind( uint n, int64 s )

Binds the 64-bit integer value s to the parameter n of this Query.

void Query::bind( uint n, uint s )

Binds the unsigned 32-bit integer value s to the parameter n of this Query. s may not be larger than INT_MAX.

void Query::bindNull( uint n )

Binds NULL to the parameter n of this Query.

bool Query::canBeSlow() const

Returns true only if allowSlowness() has been called for this query, signifying that the query may take a long time, and that the default query timeout should not apply.

This function exists only so that Postgres can avoid timing out when it should just wait instead.

bool Query::canFail() const

Returns true only if allowFailure() has been called for this query, signifying that this query is known to run the risk of failure (e.g. the Injector's "insert into bodyparts..." query may violate a unique constraint).

This function exists only so that Postgres can avoid logging unimportant errors.

String Query::description()

Returns a description of this query and its parameters, if any, that is suitable for logging and debugging.

bool Query::done() const

Returns true only if this Query has either succeeded or failed, and false if it is still awaiting completion.

String Query::error() const

This function returns an error message if the Query has failed(), and an empty string otherwise.

void Query::execute()

This function submits this Query to the Database for processing. The owner() of the query will be informed of any activity via notify().

bool Query::failed() const

Returns true if this Query failed, and false if it succeeded, or if it is not yet done().

Format Query::format() const

Returns this Query's format, which may be Text (the default) or Binary (set for "copy ... with binary" statements).

bool Query::hasResults() const

Returns true if any rows of data received in response to this Query have not yet been read and removed by calling nextRow().

List< Query::InputLine > * Query::inputLines() const

Returns a pointer to the List of InputLines created with bind() and submitLine(). Will return 0 if submitLine() has never been called for this Query.

(Should calling this function clear the List?)

class Log * Query::log() const

Returns a pointer to the Log object that's most appropriate to use when logging information pertaining to this Query. This is usually the Log object belonging to the owner().

String Query::name() const

Returns the name of a prepared statement that represents this Query, or an empty string if the Query was not created from a previously prepared statement.

Row * Query::nextRow()

This function returns a pointer to the first unread Row of results received in response to this Query, and removes it from the list. If there are no rows left to read, it returns 0.

void Query::notify()

The Database calls this function to inform the owner() of this Query about any interesting activity, such as the arrival of rows from the server, or the completion of the query.

EventHandler * Query::owner() const

Returns a pointer to the owner of this Query, as specified during construction or with setOwner().

uint Query::rows() const

Returns the number of rows processed by this Query. This is normally the number of rows received from the server in response to this Query, but can also be e.g. the number of rows injected.

void Query::setError( const String & s )

Stores the error message s in response to this Query, and sets the Query state to Failed. If the Query belongs to a Transaction, the Transaction's error message set too.

This function is intended for use by the Database.

void Query::setOwner( EventHandler * ev )

Sets the owner of this Query to ev.

void Query::setRows( uint r )

Informs this Query that the proper value of rows() is r. Should not be called unless the Query is completely processed.

Used by Postgres to help queries like "insert into ... select ..." return a helpful value of rows().

void Query::setState( State s )

Sets the state of this object to s. The initial state of each Query is Inactive, and the Database changes it to indicate the query's progress.

void Query::setString( const String & s )

This function sets the contents of this Query to s. It is used (e.g. by Selector) when arguments need to be bound before the SQL statement is completely constructed.

It has no effect on queries that have already been submitted to the database.

void Query::setTransaction( Transaction * t )

Sets this Query's parent transaction to t.

State Query::state() const

Returns the state of this object, which may be one of the following:

Inactive: This query has not yet been submitted to the Database. Submitted: The query has been submitted to the Database. Executing: The query has been sent to the server. Completed: The query completed successfully. Failed: The query has failed.

String Query::string() const

This virtual function is expected to return the complete SQL query as a string. Subclasses may reimplement this function to compose a query from individual parameters, rather than requiring the entire query to be specified during construction.

This function is intended for use by the Database.

void Query::submitLine()

Uses the Values bound to this query so far to form one line of input to COPY. The bind() functions can then be reused to compose the next line of input.

Transaction * Query::transaction() const

Returns a pointer to the Transaction that this Query is associated with, or 0 if this Query is self-contained.

Query::InputLine * Query::values() const

Returns a pointer to the list of Values bound to this Query.

Query::~Query()

This virtual destructor exists only so that subclasses can define their own.