oci_define_by_name

Associates a PHP variable with a column for query fetches

&reftitle.description; `bool` `oci_define_by_name` `resource` `statement` `string` `column` `mixed` `var` `int` `type` 0

Associates a PHP variable with a column for query fetches using `oci_fetch`.

The `oci_define_by_name` call must occur before executing `oci_execute`.

&reftitle.parameters;

`statement`

- &oci.arg.statement.id;

`column`

- The column name used in the query.

  Use uppercase for Oracle's default, non-case sensitive column names. Use the exact column name case for case-sensitive column names.

`var`

- The PHP variable that will contain the returned column value.

`type`

- The data type to be returned. Generally not needed. Note that Oracle-style data conversions are not performed. For example, `SQLT_INT` will be ignored and the returned data type will still be `SQLT_CHR`.

  You can optionally use `oci_new_descriptor` to allocate LOB/ROWID/BFILE descriptors.

&reftitle.returnvalues;

&return.success;

&reftitle.examples;

### `oci_define_by_name` example

    <?php

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $sql = 'SELECT location_id, city FROM locations WHERE location_id < 1200';
    $stid = oci_parse($conn, $sql);

    // The defines MUST be done before executing
    oci_define_by_name($stid, 'LOCATION_ID', $locid);
    oci_define_by_name($stid, 'CITY', $city);

    oci_execute($stid);

    // Each fetch populates the previously defined variables with the next row's data
    while (oci_fetch($stid)) {
        echo "Location id $locid is $city<br>\n";
    }

    // Displays:
    //   Location id 1000 is Roma
    //   Location id 1100 is Venice

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### `oci_define_by_name` with case sensitive column names

    <?php

    /*
      Before running, create the table with a case sensitive column name:
        CREATE TABLE mytab (id NUMBER, "MyDescription" VARCHAR2(30));
        INSERT INTO mytab (id, "MyDescription") values (1, 'Iced Coffee');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // Use uppercase for non case-sensitive column names
    oci_define_by_name($stid, 'ID', $id);

    // Use the exact case for case-sensitive column names
    oci_define_by_name($stid, 'MyDescription', $mydesc);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo "id $id is $mydesc<br>\n";
    }

    // Displays:
    //   id 1 is Iced Coffee

    oci_free_statement($stid);
    oci_close($conn);

    ?>

### `oci_define_by_name` with LOB columns

    <?php

    /*
      Before running, create the table:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // The defines MUST be done before executing
    oci_define_by_name($stid, 'ID', $id);
    oci_define_by_name($stid, 'FRUIT', $fruit);  // $fruit will become a LOB descriptor

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " is " . $fruit->load(100) . "<br>\n";
    }

    // Displays:
    //   1 is apple
    //   2 is orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

### `oci_define_by_name` with an explicit type

    <?php

    /*
      Before running, create the table:
        CREATE TABLE mytab (id NUMBER, fruit CLOB);
        INSERT INTO mytab (id, fruit) values (1, 'apple');
        INSERT INTO mytab (id, fruit) values (2, 'orange');
        COMMIT;
    */

    $conn = oci_connect('hr', 'welcome', 'localhost/XE');
    if (!$conn) {
        $e = oci_error();
        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
    }

    $stid = oci_parse($conn, 'SELECT * FROM mytab');

    // The defines MUST be done before executing
    oci_define_by_name($stid, 'ID', $id);

    $fruit = oci_new_descriptor($conn, OCI_D_LOB);
    oci_define_by_name($stid, 'FRUIT', $fruit, OCI_D_CLOB);

    oci_execute($stid);

    while (oci_fetch($stid)) {
        echo $id . " is " . $fruit->load(100) . "<br>\n";
    }

    // Displays:
    //   1 is apple
    //   2 is orange

    $fruit->free();
    oci_free_statement($stid);
    oci_close($conn);

    ?>

&reftitle.seealso;

- `oci_fetch`
- `oci_new_descriptor`