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_IN、SQLSRV_PARAM_OUT、SQLSRV_PARAM_INOUT) のいずれか。 既定値は SQLSRV_PARAM_IN です。 PHP 定数の詳細については、「定数 (Microsoft Drivers for PHP for SQL Server)」を参照してください。
  $phpType[オプション]	戻り値の PHP データ型を指定する SQLSRV_PHPTYPE_* 定数。
  $sqlType[オプション]	入力値の SQL Server データ型を指定する SQLSRV_SQLTYPE_* 定数。

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

戻り値

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

解説

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

sqlsrv_prepare と sqlsrv_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);  
?>  

例 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)