db2-prepare.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 871b71764cdca8238069f27436d96011a6a2cb36 Maintainer: takagi Status: ready -->
<refentry xml:id="function.db2-prepare" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>db2_prepare</refname>
  <refpurpose>
   実行する SQL 文を準備する
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>resource</type><type>false</type></type><methodname>db2_prepare</methodname>
   <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
   <methodparam><type>string</type><parameter>statement</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>


  <para>
   <function>db2_prepare</function> は、プリペアドステートメントを作成します。
   このプリペアドステートメントには、入力パラメータ・出力パラメータ
   あるいは入出力パラメータを表すパラメータマーカ (<literal>?</literal>)
   を含めることができます。プリペアドステートメントにパラメータを渡すには
   <function>db2_bind_param</function> を使用します。
   入力パラメータの場合についてのみ、<function>db2_execute</function>
   に渡す配列で指定することも可能です。
  </para>
  <para>
   アプリケーション内でプリペアドステートメントを使用する利点は、
   以下の 3 つです。
   <itemizedlist>
    <listitem>
     <para>
      <emphasis>パフォーマンス</emphasis>: 事前に文を準備しておくと、
      その文によってデータを取得するための実行計画をデータベースサーバーが
      最適化します。その後 <function>db2_execute</function>
      でプリペアドステートメントを実行する際にはこの実行計画が再利用され、
      実行時に実行計画を毎回作成することによるオーバーヘッドを避けられます。
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis>セキュリティ</emphasis>: 事前に文を準備する際に、
      入力値にパラメータマーカを含めることができます。
      入力値にプレースホルダを使用してプリペアドステートメントを実行すると、
      入力値の型がカラム定義あるいはパラメータ定義と一致することを
      データベースサーバーがチェックします。
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis>高機能</emphasis>: パラメータマーカの機能は、
      単に入力値をプリペアドステートメントに渡すだけではありません。
      <function>db2_bind_param</function> を使用すると、
      ストアドプロシージャの OUT パラメータおよび INOUT パラメータから
      値を取得することも可能です。
     </para>
    </listitem>
   </itemizedlist>
  </para>

 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>connection</parameter></term>
     <listitem>
      <para>
       <function>db2_connect</function> あるいは <function>db2_pconnect</function>
       が返した有効なデータベース接続リソース。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>statement</parameter></term>
     <listitem>
      <para>
       ひとつ以上のパラメータマーカを含む SQL 文。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       文のオプションを含む連想配列。
       データベースサーバーがその機能をサポートしている場合に、
       このパラメータを使用してスクロール可能なカーソルの使用を
       要求することができます。
      </para>
      <para>
       オプションについての説明は
       <function>db2_set_option</function> を参照ください。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   SQL 文のパースに成功し、データベースサーバー内で正しく準備された場合に
   ステートメントリソースを返します。データベースサーバーがエラーを返した場合に
   &false; を返します。返されたエラーの詳細を調べるには、
   <function>db2_stmt_error</function> あるいは <function>db2_stmt_errormsg</function>
   をコールします。
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>パラメータマーカを使用した SQL 文の準備と実行</title>
    <para>
     以下の例では、4 つのパラメータマーカを含む INSERT 文を準備し、
     入力値の配列を含む配列を順に処理しながら
     <function>db2_execute</function> に値を渡します。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$animals = array(
    array(0, 'cat', 'Pook', 3.2),
    array(1, 'dog', 'Peaches', 12.3),
    array(2, 'horse', 'Smarty', 350.0),
);

$insert = 'INSERT INTO animals (id, breed, name, weight)
    VALUES (?, ?, ?, ?)';
$stmt = db2_prepare($conn, $insert);
if ($stmt) {
    foreach ($animals as $animal) {
        $result = db2_execute($stmt, $animal);
    }
}
?>
]]>
    </programlisting>
   </example>
   <!--
   <example>
    <title>Preventing SQL injection attacks using parameter markers</title>
     <para>
      Parameter markers make it impossible for a malicious user of your
      application to pass input values that map to more than one database
      field or stored procedure parameter. The following example demonstrates
      a common tactic for attacking database-driven Web applications, SQL
      injection, which takes advantage of applications that often simply
      interpolate the input values from a user directly into an SQL statement
      rather than defining parameter markers and binding the input values to
      those parameter markers.
     </para>
     <para>
      In the following example, assume that the PHP script has been placed on
      a publically accessible Web server and the application provides
      different levels of access for different users. We shall also assume
      that the application issues an SQL statement that updates the privilege
      level of a newly registered user to the lowest level, taking the user ID
      from a GET input variable. In the following example, a malicious user
      can pass <userinput>userid=0+OR+1=1</userinput> (instead of the expected
      <userinput>userid=0</userinput>) to trick your application into
      setting the privilege level of every user in the database to the lowest
      level.
     </para>
    <programlisting role="php">
<![CDATA[
<?php
 
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
]]>
    </screen>
   </example>
   -->
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>db2_bind_param</function></member>
    <member><function>db2_execute</function></member>
    <member><function>db2_stmt_error</function></member>
    <member><function>db2_stmt_errormsg</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
-->