## Class TDbCommand

Description

TDbCommand class.

TDbCommand represents an SQL statement to execute against a database. It is usually created by calling TDbConnection::createCommand. The SQL statement to be executed may be set via Text.

To execute a non-query SQL (such as insert, delete, update), call execute. To execute an SQL statement that returns result data set (such as select), use query or its convenient versions queryRow and queryScalar.

If an SQL statement returns results (such as a SELECT SQL), the results can be accessed via the returned TDbDataReader.

TDbCommand supports SQL statment preparation and parameter binding. Call bindParameter to bind a PHP variable to a parameter in SQL. Call bindValue to bind a value to an SQL parameter. When binding a parameter, the SQL statement is automatically prepared. You may also call prepare to explicitly prepare an SQL statement.

- since: 3.0
- version: $Id: TDbCommand.php 2386 2008-03-06 15:25:32Z xue $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Data/TDbCommand.php (line 39)

    TComponent
       |
       --TDbCommand

Method Summary
TDbCommand __construct (TDbConnection $connection, string $text)
void bindParameter (mixed $name, mixed &$value, [int $dataType = null], [int $length = null])
void bindValue (mixed $name, mixed $value, [int $dataType = null])
void cancel ()
integer execute ()
TDbConnection getConnection ()
String getDebugStatementText ()
PDOStatement getPdoStatement ()
string getText ()
void prepare ()
TDbDataReader query ()
array queryColumn ()
array queryRow ([boolean $fetchAssociative = true])
mixed queryScalar ()
void setText (string $value)
void __sleep ()
Methods
Constructor __construct (line 50)

Constructor.

- access: public

TDbCommand __construct (TDbConnection $connection, string $text)

- TDbConnection $connection: the database connection
- string $text: the SQL statement to be executed

bindParameter (line 142)

Binds a parameter to the SQL statement to be executed.

- access: public
- see: http://www.php.net/manual/en/function.PDOStatement-bindParam.php

void bindParameter (mixed $name, mixed &$value, [int $dataType = null], [int $length = null])

- mixed $name: Parameter identifier. For a prepared statement using named placeholders, this will be a parameter name of the form :name. For a prepared statement using question mark placeholders, this will be the 1-indexed position of the parameter.
- mixed &$value: Name of the PHP variable to bind to the SQL statement parameter
- int $dataType: SQL data type of the parameter
- int $length: length of the data type

bindValue (line 163)

Binds a value to a parameter.

- access: public
- see: http://www.php.net/manual/en/function.PDOStatement-bindValue.php

void bindValue (mixed $name, mixed $value, [int $dataType = null])

- mixed $name: Parameter identifier. For a prepared statement using named placeholders, this will be a parameter name of the form :name. For a prepared statement using question mark placeholders, this will be the 1-indexed position of the parameter.
- mixed $value: The value to bind to the parameter
- int $dataType: SQL data type of the parameter

cancel (line 126)

Cancels the execution of the SQL statement.

- access: public

void cancel ()
execute (line 179)

Executes the SQL statement.

This method is meant only for executing non-query SQL statement. No result set will be returned.

- return: number of rows affected by the execution.
- access: public
- throws: TDbException execution failed

integer execute ()
getConnection (line 87)

- return: the connection associated with this command
- access: public

TDbConnection getConnection ()
getDebugStatementText (line 203)

- return: prepared SQL text for debugging purposes.
- access: public

String getDebugStatementText ()
getPdoStatement (line 96)

- return: the underlying PDOStatement for this command It could be null if the statement is not prepared yet.
- access: public

PDOStatement getPdoStatement ()
getText (line 68)

- return: the SQL statement to be executed
- access: public

string getText ()
prepare (line 108)

Prepares the SQL statement to be executed.

For complex SQL statement that is to be executed multiple times, this may improve performance. For SQL statement with binding parameters, this method is invoked automatically.

- access: public

void prepare ()
query (line 217)

Executes the SQL statement and returns query result.

This method is for executing an SQL query that returns result set.

- return: the reader object for fetching the query result
- access: public
- throws: TDbException execution failed

TDbDataReader query ()
queryColumn (line 298)

Executes the SQL statement and returns the first column of the result.

This is a convenient method of query when only the first column of data is needed. Note, the column returned will contain the first element in each row of result.

- return: the first column of the query result. Empty array if no result.
- access: public
- since: 3.1.2
- throws: TDbException execution failed

array queryColumn ()
queryRow (line 242)

Executes the SQL statement and returns the first row of the result.

This is a convenient method of query when only the first row of data is needed.

- return: the first row of the query result, false if no result.
- access: public
- throws: TDbException execution failed

array queryRow ([boolean $fetchAssociative = true])

- boolean $fetchAssociative: whether the row should be returned as an associated array with column names as the keys or the array keys are column indexes (0-based).

queryScalar (line 268)

Executes the SQL statement and returns the value of the first column in the first row of data.

This is a convenient method of query when only a single scalar value is needed (e.g. obtaining the count of the records).

- return: the value of the first column in the first row of the query result. False is returned if there is no value.
- access: public
- throws: TDbException execution failed

mixed queryScalar ()
setText (line 78)

Specifies the SQL statement to be executed.

Any previous execution will be terminated or cancel.

- access: public

void setText (string $value)

- string $value: the SQL statement to be executed

__sleep (line 59)

Set the statement to null when serializing.

- access: public

void __sleep ()

#### Inherited Methods

Inherited From TComponent

> TComponent::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Documentation generated on Mon, 21 Apr 2008 11:34:51 -0400 by phpDocumentor 1.3.0RC4