Описание

sqlsrv_prepare(
    resource $conn,
    string $sql,
    array $params = ?,
    array $options = ?
): mixed

Подготавливает запрос к исполнению. Функция идеально подходит для подготовки запроса, который будет выполняться несколько раз с разными значениями параметров.

Список параметров

conn

Ресурс подключения, возвращаемый sqlsrv_connect().

sql

Строка, определяющая запрос, который нужно подготовить и выполнить.

params

Массив, определяющий информацию о параметрах при выполнении запроса. Элементы массива могут быть любыми из следующих:

Строковое значение
Переменная PHP
Массив с такой структурой: array($value [, $direction [, $phpType [, $sqlType]]])

В следующей таблице описаны элементы в структуре массива выше:

**Структура массива**
Элемент	Описание
$value	Строковое значение, переменная PHP или переменная PHP, переданная по ссылке.
$direction (необязательный)	Одна из следующих констант SQLSRV, используемых для указания направления параметра: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. Значение по умолчанию - SQLSRV_PARAM_IN.
$phpType (необязательный)	Константа SQLSRV_PHPTYPE_*, указывающая тип данных PHP возвращаемого значения.
$sqlType (необязательный)	Константа SQLSRV_SQLTYPE_*, указывающая тип данных SQL Server входного значения.

options

Массив, определяющий параметры свойств запроса. Поддерживаемые ключи описаны в следующей таблице:

**Опции запроса**
Ключ	Значения	Описание
QueryTimeout	Положительное целочисленное значение.	Устанавливает время ожидания запроса в секундах. По умолчанию драйвер будет ожидать результатов бесконечно.
SendStreamParamsAtExec	`true` или `false` (по умолчанию `true`)	Настраивает драйвер для отправки всех данных потока при выполнении (`true`) или для отправки данных потока частями (`false`). По умолчанию установлено значение `true`. Для получения дополнительной информации смотрите sqlsrv_send_stream_data().
Scrollable	SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, или SQLSRV_CURSOR_KEYSET	Смотрите » Указание типа курсора и выбор строк в документации Microsoft SQLSRV.

Возвращаемые значения

Возвращает ресурс оператора в случае успешного выполнения или false в случае возникновения ошибки.

Примеры

Пример #1 Пример использования sqlsrv_prepare()

В этом примере показано, как подготовить оператор с помощью sqlsrv_prepare() и повторно выполнить его несколько раз (с разными значениями параметров) с помощью sqlsrv_execute().

<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password");
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false) {
    die( print_r( sqlsrv_errors(), true));
}

$sql = "UPDATE Table_1
        SET OrderQty = ?
        WHERE SalesOrderID = ?";

// Инициализация параметров и подготовка запроса.
// Переменные $qty и $id связаны с оператором $stmt.
$qty = 0; $id = 0;
$stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
if( !$stmt ) {
    die( print_r( sqlsrv_errors(), true));
}

// Настройка информации SalesOrderDetailID и OrderQty.
// Этот массив сопоставляет идентификатор заказа с количеством заказа в парах ключ => значение.
$orders = array( 1=>10, 2=>20, 3=>30);

// Выполнение запроса для каждого заказа.
foreach( $orders as $id => $qty) {
    // Поскольку $id и $qty привязаны к $stmt1,
    // их обновлённые значения используются при каждом выполнении запроса.
    if( sqlsrv_execute( $stmt ) === false ) {
          die( print_r( sqlsrv_errors(), true));
    }
}
?>

Примечания

Когда вы подготавливаете запрос, который использует переменные в качестве параметров, переменные привязываются к оператору. Это означает, что если вы обновите значения переменных, в следующий раз, когда вы выполните запрос, он будет работать с обновлёнными значениями параметров. Для операторов, которые вы планируете выполнить только один раз, используйте sqlsrv_query().

Смотрите также

sqlsrv_execute() - Выполняет запрос, подготовленный с помощью sqlsrv_prepare
sqlsrv_query() - Подготавливает и выполняет запрос