PEAR Manual
Prev |  | Next

# DB_common::getCol()

DB_common::getCol() -- Runs a query and returns the data from a single column

## Synopsis

``array &getCol` (string $query [, mixed $col = 0 [, mixed $params = array()]])`

## Description

Runs the query provided and puts the first column of data into an array then frees the result set.

## Parameter

string `$query`

  the SQL query or the statement to prepare

mixed `$col`

  which column to return (integer [column number, starting at 0] or string [column name])

mixed `$params`

  array, string or numeric data to be added to the prepared statement. Quantity of items passed must match quantity of placeholders in the prepared statement: meaning 1 placeholder for non-array parameters or 1 placeholder per array element.

  If supplied, prepare()/ execute() is used.

## Return value

array - an ordered array containing data from a result set column or a DB_Error object on failure. The array's index starts at 0.

## Throws

Table 33-1. Possible PEAR_Error values

Error code | Error message | Reason | Solution
--- | --- | --- | ---
`DB_ERROR_INVALID` | invalid | SQL statment for preparing is not valid. | See the prepare() documentation, if you want to use a SQL statemt using placeholders.
`DB_ERROR_MISMATCH` | mismatch | Quantity of parameters didn't match quantity of placeholders in the prepared statment. | Check that the number of placeholders in the prepare() statement passed to `$query` equals the count of entries passed to `$params`.
`DB_ERROR_NOSUCHFIELD` | no such field | Invalid column number/name passed to `$col` | Use a column number or name that exists in the query result.
`DB_ERROR_NODBSELECTED` | no database selected | No database was choosen. | Check the DSN in connect().
every other error code |  | Database specific error | Check the database related section of PHP Manual to detect the reason for this error. In most cases a malformed SQL statement is the cause of the error. (Ie. using LIMIT in a SQL-Statment for an Oracle database.)

## Note

This function can not be called statically.

## Example

Example 33-1. Using getCol()
    <?php
    // Once you have a valid DB object named $db...
    $data =& $db->getCol('SELECT cf, df FROM foo');

    if (PEAR::isError($data)) {
        die($data->getMessage());
    }

    print_r($data);
    ?>
Output:
    Array
    (
        [0] => Juan
        [1] => Kyu
    )

Example 33-2. Using getCol() to retrieve a numerically specified column
    <?php
    // Once you have a valid DB object named $db...
    $data =& $db->getCol('SELECT cf, df FROM foo', 1);

    if (PEAR::isError($data)) {
        die($data->getMessage());
    }

    print_r($data);
    ?>
Output:
    Array
    (
        [0] => 1991-01-11 21:31:41
        [1] => 1992-02-12 22:32:42
    )

Example 33-3. Using getCol() to retrieve a named column
    <?php
    // Once you have a valid DB object named $db...
    $data =& $db->getCol('SELECT cf, df FROM foo', 'df');

    if (PEAR::isError($data)) {
        die($data->getMessage());
    }

    print_r($data);
    ?>
Output:
    Array
    (
        [0] => 1991-01-11 21:31:41
        [1] => 1992-02-12 22:32:42
    )

Example 33-4. Using getCol() in prepare/execute mode with one placeholder
    <?php
    // Once you have a valid DB object named $db...
    $data =& $db->getCol('SELECT cf, df FROM foo WHERE nf = ?',
            'df', 5);

    if (PEAR::isError($data)) {
        die($data->getMessage());
    }

    print_r($data);
    ?>
Output:
    Array
    (
        [0] => 1991-01-11 21:31:41
    )

Example 33-5. Using getCol() in prepare/execute mode with two placeholders
    <?php
    // Once you have a valid DB object named $db...
    $data =& $db->getCol('SELECT cf, df FROM foo WHERE nf IN (?, ?)',
            'df', array(5, 10));

    if (PEAR::isError($data)) {
        die($data->getMessage());
    }

    print_r($data);
    ?>
Output:
    Array
    (
        [0] => 1991-01-11 21:31:41
        [1] => 1992-02-12 22:32:42
    )

## See

getOne(), getRow(), getAssoc(), getAll(), query(), "Intro - Prepare & Execute"

Prev | Home | Next
DB_common::getAssoc() | Up | DB_common::getListOf()