sqlsrv_prepare

项目
06/02/2023

创建与指定连接相关联的语句资源。此函数对于执行多个查询非常有用。

语法

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

参数

$conn：与创建的语句相关联的连接资源。

$tsql：对应于已创建语句的 Transact-SQL 表达式。

$params [可选]：对应于参数化查询中参数的值的阵列。该阵列的每个元素可以是以下项之一：

文字值。
对 PHP 变量的引用。

具有以下结构的阵列：

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

注意

作为查询参数传递的变量应通过引用传递，而不是通过值传递。例如，传递 &$myVariable 而不是 $myVariable。当执行带有通过值传递的参数的查询时，引发 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[可选]	SQLSRV_PHPTYPE_* 常量，用于指定返回的值的 PHP 数据类型。
$sqlType[可选]	SQLSRV_SQLTYPE_* 常量，用于指定输入值的 SQL Server 数据类型。

$options [可选]：设置查询属性的关联阵列。下表列出了受支持的键和相应值：

键	支持的值	说明
ClientBufferMaxKBSize	正整数	配置保留客户端游标的结果集的缓冲区大小。默认值为 10240 KB。有关详细信息，请参阅指定游标类型和选择行。
DecimalPlaces	介于 0 和 4 之间（含 0 和 4）的整数	指定设置提取的 Money 值格式时的小数位数。将忽略任何负整数或大于 4 的值。仅当 FormatDecimals 为 true 时，此选项才可用。
FormatDecimals	true 或 false 默认值是 false秒。	指定是否在合适时向十进制字符串添加前导零，并启用用于设置 Money 类型格式的 `DecimalPlaces` 选项。有关详细信息，请参阅设置十进制字符串和 Money 值格式（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_prepare 和 sqlsrv_execute 的组合将语句准备和语句执行分成了两个函数调用，并且可用来执行参数化查询。如果要对每次执行使用不同的参数值来多次执行语句，该函数是理想之选。

有关写入和读取大量信息的备用策略，请参阅 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);  
?>

注意

当由于 PHP 的浮点数具有有限精确度而将值绑定到十进制或数值列以确保精确度和准确度时，建议将字符串用作输入。这同样适用于 bigint 列，尤其是在值超出整数范围的情况下。

示例 3

此代码示例演示如何将十进制值作为输入参数进行绑定。

<?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);  

?>