oci-execute.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 5e41012cfdf8f2eff5fa56de446c7656afac536c Maintainer: irker Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.oci-execute" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>oci_execute</refname>
  <refpurpose>Выполняет подготовленное выражение</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>oci_execute</methodname>
   <methodparam><type>resource</type><parameter>statement</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer><constant>OCI_COMMIT_ON_SUCCESS</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   Выполняет подготовленное выражение <parameter>statement</parameter>, созданное с помощью
   функции <function>oci_parse</function>.
  </para>
  <para>
   Сразу после выполнения выражения подобного <literal>INSERT</literal>,
   по умолчанию все данные сразу будут сохранены в базе данных. Для
   выражений подобных <literal>SELECT</literal>, выполняется только
   логика запроса. Результат же запроса можно получить позже в PHP
   с помощью функций подобных <function>oci_fetch_array</function>.
  </para>
  <para>
   Каждое подготовленное выражение может быть выполнено несколько раз
   для экономии на издержках от повторной подготовки запроса.
   Это чаще всего применяется для выражений <literal>INSERT</literal>,
   когда к ним привязаны данные с помощью <function>oci_bind_by_name</function>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>statement</parameter></term>
     <listitem>
      <para>
       Правильное подготовленное выражение OCI.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
        Необязательный второй параметр с одним из следующих значений:
       <table>
        <title>Режим выполнения</title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Константа</entry>
           <entry>Описание</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>OCI_COMMIT_ON_SUCCESS</constant></entry>
           <entry>Автоматически сохранять все несохраненные изменения,
             произведённые за текущую сессию в случае успешного выполнения выражения.
             Этот режим установлен по умолчанию.</entry>
          </row>
          <row>
           <entry><constant>OCI_DESCRIBE_ONLY</constant></entry>
           <entry>Делает доступными метаданные запроса для функций подобных
             <function>oci_field_name</function>, но не создаёт результат выполнения выражения.
             Любое последующее получение данных, например с помощью
             <function>oci_fetch_array</function> не будет произведено.</entry>
          </row>
          <row>
           <entry><constant>OCI_NO_AUTO_COMMIT</constant></entry>
           <entry>Не сохранять автоматически изменения.</entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <para>
       Использование режима <constant>OCI_NO_AUTO_COMMIT</constant>
       открывает или продолжает транзакцию. Эта транзакция автоматически
       откатывается при закрытии соединения или завершении скрипта. Используйте
       <function>oci_commit</function> для завершения транзакции
       и <function>oci_rollback</function> для её отмены.
      </para>
      <para>
       При вставке и обновлении данных рекомендуется использование транзакций
       для реляционной целостности данных и для улучшения производительности.
      </para>
      <para>
       Если для какого-нибудь выражения используется режим <constant>OCI_NO_AUTO_COMMIT</constant>,
       и впоследствии не используются <function>oci_commit</function> или
       <function>oci_rollback</function>, то OCI8 будет выполнять откат
       при завершении скрипта даже если данные не были изменены.
       Для избежания ненужных откатов большинство скриптов не используют
       режим <constant>OCI_NO_AUTO_COMMIT</constant> для запросов или
       PL/SQL. Будьте внимательны, чтобы обеспечить
       надлежащую согласованность транзакций при использовании <function>oci_execute</function>
       с различными режимами в одном скрипте.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>oci_execute</function> при выполнении запросов</title>
    <programlisting role="php">
<![CDATA[
<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

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

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
    echo "<tr>\n";
    foreach ($row as $item) {
        echo "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "") . "</td>\n";
    }
    echo "</tr>\n";
}
echo "</table>\n";

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_execute</function> без указания определённого режима</title>
    <programlisting role="php">
<![CDATA[
<?php

// Перед выполнением создайте таблицу:
//   CREATE TABLE MYTABLE (col1 NUMBER);

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');

oci_execute($stid); // Строка сохранена и становится видимой для других пользователей

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_execute</function> с <constant>OCI_NO_AUTO_COMMIT</constant></title>
    <programlisting role="php">
<![CDATA[
<?php

// Перед выполнением создайте таблицу:
//   CREATE TABLE MYTABLE (col1 NUMBER);

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (:bv)');
oci_bind_by_name($stid, ':bv', $i, 10);
for ($i = 1; $i <= 5; ++$i) {
    oci_execute($stid, OCI_NO_AUTO_COMMIT);
}
oci_commit($conn);  // сохранение все новых значений: 1, 2, 3, 4, 5

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_execute</function> с различными режимами</title>
    <programlisting role="php">
<![CDATA[
<?php

// Перед выполнением создайте таблицу:
//   CREATE TABLE MYTABLE (col1 NUMBER);

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
oci_execute($stid, OCI_NO_AUTO_COMMIT);  // data not committed

$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (456)');
oci_execute($stid);  // commits both 123 and 456 values

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_execute</function> с
     <constant>OCI_DESCRIBE_ONLY</constant></title>
    <programlisting role="php">
<![CDATA[
<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'SELECT * FROM locations');
oci_execute($s, OCI_DESCRIBE_ONLY);
for ($i = 1; $i <= oci_num_fields($stid); ++$i) {
    echo oci_field_name($stid, $i) . "<br>\n";
}

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Транзакции автоматически откатываются при закрытии соединения или
    завершении выполнения скрипта. Принудительно вызывайте
    <function>oci_commit</function> для завершения транзакции.
   </para>
   <para>
    Любой вызов <function>oci_execute</function>, который принудительно
    использует <constant>OCI_COMMIT_ON_SUCCESS</constant> или по умолчанию
    будет завершать любую предыдущую незакрытую транзакцию.
   </para>
   <para>
    Любое выражение Oracle DDL подобное <literal>CREATE</literal>
    или <literal>DROP</literal> будет автоматически завершать
    любую. незакрытую транзакцию.
   </para>
  </note>
  <note>
   <para>
    Так как функция <function>oci_execute</function> обычно
    отправляет выражения в базу данных, то <function>oci_execute</function>
    может найти некоторые незначительные синтаксические ошибки, когда
    локальная <function>oci_parse</function> их не находит.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>oci_parse</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->