mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-20 19:08:54 +00:00
3bb76a726a
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@256135 c90b9560-bf6c-de11-be94-00142212c4b1
309 lines
9.7 KiB
XML
309 lines
9.7 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
||
<!-- $Revision: 1.13 $ -->
|
||
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
|
||
<refentry xml:id="function.db2-bind-param" xmlns="http://docbook.org/ns/docbook">
|
||
<refnamediv>
|
||
<refname>db2_bind_param</refname>
|
||
<refpurpose>
|
||
Binds a PHP variable to an SQL statement parameter
|
||
</refpurpose>
|
||
</refnamediv>
|
||
<refsect1 role="description">
|
||
&reftitle.description;
|
||
<methodsynopsis>
|
||
<type>bool</type><methodname>db2_bind_param</methodname>
|
||
<methodparam><type>resource</type><parameter>stmt</parameter></methodparam>
|
||
<methodparam><type>int</type><parameter>parameter-number</parameter></methodparam>
|
||
<methodparam><type>string</type><parameter>variable-name</parameter></methodparam>
|
||
<methodparam choice="opt"><type>int</type><parameter>parameter-type</parameter></methodparam>
|
||
<methodparam choice="opt"><type>int</type><parameter>data-type</parameter></methodparam>
|
||
<methodparam choice="opt"><type>int</type><parameter>precision</parameter></methodparam>
|
||
<methodparam choice="opt"><type>int</type><parameter>scale</parameter></methodparam>
|
||
</methodsynopsis>
|
||
|
||
<para>
|
||
Binds a PHP variable to an SQL statement parameter in a statement resource
|
||
returned by <function>db2_prepare</function>. This function gives you more
|
||
control over the parameter type, data type, precision, and scale for the
|
||
parameter than simply passing the variable as part of the optional input
|
||
array to <function>db2_execute</function>.
|
||
</para>
|
||
|
||
</refsect1>
|
||
<refsect1 role="parameters">
|
||
&reftitle.parameters;
|
||
<para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><parameter>stmt</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
A prepared statement returned from <function>db2_prepare</function>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>parameter-number</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the 1-indexed position of the parameter in the prepared
|
||
statement.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>variable-name</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
A string specifying the name of the PHP variable to bind to the
|
||
parameter specified by <parameter>parameter-number</parameter>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>parameter-type</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
A constant specifying whether the PHP variable should be bound to the
|
||
SQL parameter as an input parameter (<literal>DB2_PARAM_IN</literal>),
|
||
an output parameter (<literal>DB2_PARAM_OUT</literal>), or as a
|
||
parameter that accepts input and returns output
|
||
(<literal>DB2_PARAM_INOUT</literal>). To avoid memory overhead, you can
|
||
also specify <literal>DB2_PARAM_FILE</literal> to bind the PHP variable
|
||
to the name of a file that contains large object (BLOB, CLOB, or DBCLOB)
|
||
data.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>data-type</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
A constant specifying the SQL data type that the PHP variable should be
|
||
bound as: one of <literal>DB2_BINARY</literal>,
|
||
<literal>DB2_CHAR</literal>, <literal>DB2_DOUBLE</literal>, or
|
||
<literal>DB2_LONG</literal> .
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>precision</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the precision with which the variable should be bound to the
|
||
database. This parameter can also be used for retrieving XML output values
|
||
from stored procedures. A non-negative value specifies the maximum size of
|
||
the XML data that will be retrieved from the database. If this parameter
|
||
is not used, a default of 1MB will be assumed for retrieving the XML
|
||
output value from the stored procedure.<2E>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>scale</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Specifies the scale with which the variable should be bound to the
|
||
database.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</refsect1>
|
||
<refsect1 role="returnvalues">
|
||
&reftitle.returnvalues;
|
||
<para>
|
||
&return.success;
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="examples">
|
||
&reftitle.examples;
|
||
<para>
|
||
<example>
|
||
<title>Binding PHP variables to a prepared statement</title>
|
||
<para>
|
||
The SQL statement in the following example uses two input parameters in
|
||
the WHERE clause. We call <function>db2_bind_param</function> to bind two
|
||
PHP variables to the corresponding SQL parameters. Notice that the PHP
|
||
variables do not have to be declared or assigned before the call to
|
||
<function>db2_bind_param</function>; in the example,
|
||
<literal>$lower_limit</literal> is assigned a value before the call to
|
||
<function>db2_bind_param</function>, but <literal>$upper_limit</literal>
|
||
is assigned a value after the call to
|
||
<function>db2_bind_param</function>. The variables must be bound and, for
|
||
parameters that accept input, must have any value assigned, before calling
|
||
<function>db2_execute</function>.
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
$sql = 'SELECT name, breed, weight FROM animals
|
||
WHERE weight > ? AND weight < ?';
|
||
$conn = db2_connect($database, $user, $password);
|
||
$stmt = db2_prepare($conn, $sql);
|
||
|
||
// We can declare the variable before calling db2_bind_param()
|
||
$lower_limit = 1;
|
||
|
||
db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
|
||
db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);
|
||
|
||
// We can also declare the variable after calling db2_bind_param()
|
||
$upper_limit = 15.0;
|
||
|
||
if (db2_execute($stmt)) {
|
||
while ($row = db2_fetch_array($stmt)) {
|
||
print "{$row[0]}, {$row[1]}, {$row[2]}\n";
|
||
}
|
||
}
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
&example.outputs;
|
||
<screen>
|
||
<![CDATA[
|
||
Pook, cat, 3.2
|
||
Rickety Ride, goat, 9.7
|
||
Peaches, dog, 12.3
|
||
]]>
|
||
</screen>
|
||
</example>
|
||
<example>
|
||
<title>Calling stored procedures with IN and OUT parameters</title>
|
||
<para>
|
||
The stored procedure match_animal in the following example accepts
|
||
three different parameters:
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
an input (IN) parameter that accepts the name of the first animal as
|
||
input
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
an input-output (INOUT) parameter that accepts the name of the second
|
||
animal as input and returns the string <literal>TRUE</literal> if an
|
||
animal in the database matches that name
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
an output (OUT) parameter that returns the sum of the weight of the
|
||
two identified animals
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
In addition, the stored procedure returns a result set consisting of the
|
||
animals listed in alphabetic order starting at the animal corresponding
|
||
to the input value of the first parameter and ending at the animal
|
||
corresponding to the input value of the second parameter.
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
|
||
$sql = 'CALL match_animal(?, ?, ?)';
|
||
$conn = db2_connect($database, $user, $password);
|
||
$stmt = db2_prepare($conn, $sql);
|
||
|
||
$name = "Peaches";
|
||
$second_name = "Rickety Ride";
|
||
$weight = 0;
|
||
|
||
db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
|
||
db2_bind_param($stmt, 2, "second_name", DB2_PARAM_INOUT);
|
||
db2_bind_param($stmt, 3, "weight", DB2_PARAM_OUT);
|
||
|
||
print "Values of bound parameters _before_ CALL:\n";
|
||
print " 1: {$name} 2: {$second_name} 3: {$weight}\n\n";
|
||
|
||
if (db2_execute($stmt)) {
|
||
print "Values of bound parameters _after_ CALL:\n";
|
||
print " 1: {$name} 2: {$second_name} 3: {$weight}\n\n";
|
||
|
||
print "Results:\n";
|
||
while ($row = db2_fetch_array($stmt)) {
|
||
print " {$row[0]}, {$row[1]}, {$row[2]}\n";
|
||
}
|
||
}
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
&example.outputs;
|
||
<screen>
|
||
<![CDATA[
|
||
Values of bound parameters _before_ CALL:
|
||
1: Peaches 2: Rickety Ride 3: 0
|
||
|
||
Values of bound parameters _after_ CALL:
|
||
1: Peaches 2: TRUE 3: 22
|
||
|
||
Results:
|
||
Peaches, dog, 12.3
|
||
Pook, cat, 3.2
|
||
Rickety Ride, goat, 9.7
|
||
]]>
|
||
</screen>
|
||
</example>
|
||
<example>
|
||
<title>Inserting a binary large object (BLOB) directly from a file</title>
|
||
<para>
|
||
The data for large objects are typically stored in files, such as XML
|
||
documents or audio files. Rather than reading an entire file into a PHP
|
||
variable, and then binding that PHP variable into an SQL statement, you
|
||
can avoid some memory overhead by binding the file directly to the input
|
||
parameter of your SQL statement. The following example demonstrates how
|
||
to bind a file directly into a BLOB column.
|
||
</para>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
$stmt = db2_prepare($conn, "INSERT INTO animal_pictures(picture) VALUES (?)");
|
||
|
||
$picture = "/opt/albums/spook/grooming.jpg";
|
||
$rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
|
||
$rc = db2_execute($stmt);
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
</example>
|
||
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1 role="seealso">
|
||
&reftitle.seealso;
|
||
<para>
|
||
<simplelist>
|
||
<member><function>db2_execute</function></member>
|
||
<member><function>db2_prepare</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:"../../../../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
|
||
-->
|