php man page for oci_define_by_name

OCI_DEFINE_BY_NAME(3)													     OCI_DEFINE_BY_NAME(3)

oci_define_by_name - Associates a PHP variable with a column for query fetches

SYNOPSIS
       bool oci_define_by_name (resource  $statement, string  $column_name, mixed  &$variable, [int  $type = SQLT_CHR])

DESCRIPTION
	Associates a PHP variable with a column for query fetches using oci_fetch(3).

	The oci_define_by_name(3) call must occur before executing oci_execute(3).

PARAMETERS
	      o $statement
		-A valid OCI8 statement identifier created by oci_parse(3) and executed by oci_execute(3), or a REF CURSOR statement identifier.

	      o $column_name
		-  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.

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

	      o $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(3) to allo-
		cate LOB/ROWID/BFILE descriptors.

RETURN VALUES
	Returns TRUE on success or FALSE on failure.

EXAMPLES
       Example #1

	      oci_define_by_name(3) 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>
";
	      }

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

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

	      ?>

       Example #2

	      oci_define_by_name(3) 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>
";
	      }

	      // Displays:
	      //   id 1 is Iced Coffee

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

	      ?>

       Example #3

	      oci_define_by_name(3) 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>
";
	      }

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

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

	      ?>

       Example #4

	      oci_define_by_name(3) 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>
";
	      }

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

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

	      ?>

SEE ALSO
       oci_fetch(3), oci_new_descriptor(3).

PHP Documentation Group 												     OCI_DEFINE_BY_NAME(3)