次の方法で共有


sqlsrv_prepare

PHP ドライバーのダウンロード

指定した接続に関連付けられているステートメントのリソースを作成します。 この関数は、複数のクエリを実行するのに便利です。

構文

  
sqlsrv_prepare(resource $conn, string $tsql [, array $params [, array $options]])  

パラメーター

$conn: 作成したステートメントに関連付けられた接続リソースです。

$tsql: 作成されたステートメントに対応する Transact-SQL 式です。

$params [省略可能]: パラメーター化されたクエリのパラメーターに対応する値の配列です。 配列の各要素には、次のいずれかを指定できます。

  • リテラル値。

  • PHP 変数への参照。

  • 次の構造を持つ 配列

    array(&$value [, $direction [, $phpType [, $sqlType]]])  
    

    Note

    クエリ パラメーターとして渡された変数は、値ではなく参照によって渡される必要があります。 たとえば、 &$myVariable の代わりに、 $myVariableを渡します。 by-value パラメーターを使用してクエリを実行すると、PHP の警告が生成されます。

    次の表では、これらの配列の要素を説明します。

    要素 説明
    &$value リテラル値または PHP の変数への参照。
    $direction[オプション] パラメーターの方向を示すために使用する SQLSRV_PARAM_* 定数 (SQLSRV_PARAM_INSQLSRV_PARAM_OUTSQLSRV_PARAM_INOUT) のいずれか。 既定値は SQLSRV_PARAM_IN です。

    PHP 定数の詳細については、「定数 (Microsoft Drivers for PHP for SQL Server)」を参照してください。
    $phpType[オプション] 戻り値の PHP データ型を指定する SQLSRV_PHPTYPE_* 定数。
    $sqlType[オプション] 入力値の SQL Server データ型を指定する SQLSRV_SQLTYPE_* 定数。

$options [省略可能]: クエリのプロパティを設定する連想配列。 次の表に、サポートされているキーと対応する値を示します。

キー サポートされている値 説明
ClientBufferMaxKBSize 正の整数 クライアント側カーソルの結果セットを保持するバッファーのサイズを設定します。

既定値は 10240 KB です。 詳細については、「Specifying a Cursor Type and Selecting Rows (カーソルの種類の指定と行の選択)」を参照してください。
小数点以下表示桁数 0 から 4 までの整数 フェッチされた通貨値の書式設定時に、小数点以下の桁数を指定します。

負の整数値または 4 を超える値は無視されます。

このオプションは、FormatDecimals が true 場合にのみ機能します。
FormatDecimals true または false

既定値は false です。
該当する場合に 10 進文字列の前にゼロを追加するかどうかを指定し、通貨型を書式設定するための DecimalPlaces オプションを有効にします。

詳細については、「Formatting Decimal Strings and Money Values (SQLSRV Driver) (10 進数文字列と通貨値の書式設定 (SQLSRV ドライバー))」を参照してください。
QueryTimeout 正の整数 クエリのタイムアウト (秒単位) を設定します。 既定で、ドライバーは、結果を無制限に待機します。
ReturnDatesAsStrings true または false

既定値は false です。
日付/時刻型を文字列として取得するようにステートメントを構成します (true)。 詳細については、「方法: SQLSRV ドライバーを使用して日付/時刻型を文字列として取得する」をご覧ください。
スクロール可能 SQLSRV_CURSOR_FORWARD

SQLSRV_CURSOR_STATIC

SQLSRV_CURSOR_DYNAMIC

SQLSRV_CURSOR_KEYSET

SQLSRV_CURSOR_CLIENT_BUFFERED
これらの値の詳細については、「 カーソルの種類を指定し、行を選択する」を参照してください。
SendStreamParamsAtExec true または false

既定値は true です。
実行時にすべてのストリーム データを送信する (true)、またはストリーム データをチャンク単位で送信する (false) ように、ドライバーを構成します。 既定では、この値は trueに設定されています。 詳細については、「 sqlsrv_send_stream_data」を参照してください。

戻り値

ステートメント リソースです。 ステートメント リソースを作成できない場合、 false が返されます。

解説

パラメーターとして変数を使用するステートメントを準備するときに、変数がステートメントにバインドされます。 つまり、変数の値を更新すると、次回ステートメントを実行する際に、更新されたパラメーター値を使用して実行されます。

sqlsrv_preparesqlsrv_execute の組み合わせは、ステートメントの準備とステートメントの実行を 2 つの関数呼び出しに分割し、パラメーター化されたクエリを実行するために使用できます。 この関数は、実行ごとに異なるパラメーター値を使用してステートメントを複数回実行する場合に適しています。

大量の情報の書き込みと読み取りを行う別の手法については、「 Batches of SQL Statements (SQL ステートメントのバッチ) 」と「 BULK INSERT」を参照してください。

詳細については、「SQLSRV ドライバーを使用して出力パラメーターを取得する」を参照してください。

例 1

次の例では、ステートメントを準備して実行します。 このステートメントを実行すると (「sqlsrv_execute」を参照)、AdventureWorks データベースの Sales.SalesOrderDetail テーブルのフィールドが更新されます。 この例では、ローカル コンピューターに SQL Server および AdventureWorks データベースがインストールされていることを前提にしています。 コマンド ラインからこの例を実行すると、すべての出力はコンソールに書き込まれます。

<?php  
/* Connect to the local server using Windows Authentication and  
specify the AdventureWorks database as the database in use. */  
$serverName = "(local)";  
$connectionInfo = array("Database"=>"AdventureWorks");  
$conn = sqlsrv_connect($serverName, $connectionInfo);  
if ($conn === false) {  
    echo "Could not connect.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Set up Transact-SQL query. */  
$tsql = "UPDATE Sales.SalesOrderDetail   
         SET OrderQty = ?   
         WHERE SalesOrderDetailID = ?";  
  
/* Assign parameter values. */  
$param1 = 5;  
$param2 = 10;  
$params = array(&$param1, &$param2);  
  
/* Prepare the statement. */  
if ($stmt = sqlsrv_prepare($conn, $tsql, $params)) {
    echo "Statement prepared.\n";  
} else {  
    echo "Statement could not be prepared.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Execute the statement. */  
if (sqlsrv_execute($stmt)) {  
    echo "Statement executed.\n";  
} else {  
    echo "Statement could not be executed.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Free the statement and connection resources. */  
sqlsrv_free_stmt($stmt);  
sqlsrv_close($conn);  
?>  

例 2

次の例では、ステートメントを準備し、異なるパラメーター値で再実行する方法を示します。 この例では、AdventureWorks データベースの Sales.SalesOrderDetail テーブルの OrderQty 列を更新します。 更新されたら、更新プログラムが成功したことを確認するため、データベースが照会されます。 この例では、ローカル コンピューターに SQL Server および AdventureWorks データベースがインストールされていることを前提にしています。 コマンド ラインからこの例を実行すると、すべての出力はコンソールに書き込まれます。

<?php  
/* Connect to the local server using Windows Authentication and  
specify the AdventureWorks database as the database in use. */  
$serverName = "(local)";  
$connectionInfo = array("Database"=>"AdventureWorks");  
$conn = sqlsrv_connect($serverName, $connectionInfo);  
if ($conn === false) {  
     echo "Could not connect.\n";  
     die(print_r(sqlsrv_errors(), true));  
}  
  
/* Define the parameterized query. */  
$tsql = "UPDATE Sales.SalesOrderDetail  
         SET OrderQty = ?  
         WHERE SalesOrderDetailID = ?";  
  
/* Initialize parameters and prepare the statement. Variables $qty  
and $id are bound to the statement, $stmt1. */  
$qty = 0; $id = 0;  
$stmt1 = sqlsrv_prepare($conn, $tsql, array(&$qty, &$id));  
if ($stmt1) {  
    echo "Statement 1 prepared.\n";  
} else {  
    echo "Error in statement preparation.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Set up the SalesOrderDetailID and OrderQty information. This array  
maps the order ID to order quantity in key=>value pairs. */  
$orders = array(1=>10, 2=>20, 3=>30);  
  
/* Execute the statement for each order. */  
foreach ($orders as $id => $qty) {  
    // Because $id and $qty are bound to $stmt1, their updated  
    // values are used with each execution of the statement.   
    if (sqlsrv_execute($stmt1) === false) {  
        echo "Error in statement execution.\n";  
        die(print_r(sqlsrv_errors(), true));  
    }  
}  
echo "Orders updated.\n";  
  
/* Free $stmt1 resources.  This allows $id and $qty to be bound to a different statement.*/  
sqlsrv_free_stmt($stmt1);  
  
/* Now verify that the results were successfully written by selecting   
the newly inserted rows. */  
$tsql = "SELECT OrderQty   
         FROM Sales.SalesOrderDetail   
         WHERE SalesOrderDetailID = ?";  
  
/* Prepare the statement. Variable $id is bound to $stmt2. */  
$stmt2 = sqlsrv_prepare($conn, $tsql, array(&$id));  
if ($stmt2) {  
    echo "Statement 2 prepared.\n";  
} else {  
    echo "Error in statement preparation.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Execute the statement for each order. */  
foreach (array_keys($orders) as $id)  
{  
    /* Because $id is bound to $stmt2, its updated value   
    is used with each execution of the statement. */  
    if (sqlsrv_execute($stmt2)) {  
        sqlsrv_fetch($stmt2);  
        $quantity = sqlsrv_get_field($stmt2, 0);  
        echo "Order $id is for $quantity units.\n";  
    } else {  
        echo "Error in statement execution.\n";  
        die(print_r(sqlsrv_errors(), true));  
    }  
}  
  
/* Free $stmt2 and connection resources. */  
sqlsrv_free_stmt($stmt2);  
sqlsrv_close($conn);  
?>  

Note

値を 10 進数列または数値列にバインドするときは、有効桁数と精度を保持するために、入力として文字列を使用することをお勧めします。これは、PHP には浮動小数点数の有効桁数に制限があるためです。 値が整数の範囲外にある場合は特に、同じことが bigint 列にも適用されます。

例 3

このコード サンプルでは、入力パラメーターとして 10 進数値をバインドする方法を示しています。

<?php
$serverName = "(local)";
$connectionInfo = array("Database"=>"YourTestDB");  
$conn = sqlsrv_connect($serverName, $connectionInfo);  
if ($conn === false) {  
    echo "Could not connect.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  

// Assume TestTable exists with a decimal field 
$input = "9223372036854.80000";
$params = array($input);
$stmt = sqlsrv_prepare($conn, "INSERT INTO TestTable (DecimalCol) VALUES (?)", $params);
sqlsrv_execute($stmt);

sqlsrv_free_stmt($stmt);  
sqlsrv_close($conn);  

?>

参照

SQLSRV ドライバー API リファレンス

方法: パラメーター化クエリを実行する」を参照してください。

ドキュメントのコード例について

方法: ストリームとしてデータを送信する

方向パラメーターを使用する

データの取得

データの更新 (Microsoft Drivers for PHP for SQL Server)