Descrição

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

Prepara uma consulta para execução. Esta função é ideal para preparar uma consulta que será executada várias vezes com diferentes valores de parâmetro.

Parâmetros

conn

Um recurso de conexão retornado por sqlsrv_connect().

sql

A string que define a consulta a ser preparada e executada.

params

Um array especificando informações de parâmetro ao executar uma consulta parametrizada. Os elementos do array podem ser um dos seguintes:

Um valor literal
Uma variável PHP
Um array com esta estrutura: array($valor [, $direção [, $tipoPHP [, $tipoSQL]]])

A tabela a seguir descreve os elementos na estrutura do array acima:

**Estrutura do array**
Elemento	Descrição
$value	Um valor literal, uma variável PHP ou uma variável PHP por referência.
$direction (opcional)	Uma das constantes SQLSRV usadas para indicar a direção do parâmetro: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. O valor padrão é SQLSRV_PARAM_IN.
$phpType (opcional)	Uma constante SQLSRV_PHPTYPE_* que especifica o tipo de dado PHP do valor retornado.
$sqlType (opcional)	Uma constante SQLSRV_SQLTYPE_* que especifica o tipo de dado do SQL Server do valor de entrada.

options

Um array especificando opções de propriedade da consulta. As chaves suportadas são descritas na tabela a seguir:

**Opções de Consulta**
Chave	Valores	Descrição
QueryTimeout	Um valor inteiro positivo.	Define o tempo limite da consulta em segundos. Por padrão, o driver aguardará indefinidamente por resultados.
SendStreamParamsAtExec	`true` ou `false` (o padrão é `true`)	Configura o driver para enviar todos os dados de fluxo na execução (`true`), ou para enviar os dados de fluxo em blocos (`false`). Por padrão, o valor é `true`. Para mais informações, consulte sqlsrv_send_stream_data().
Scrollable	SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, ou SQLSRV_CURSOR_KEYSET	Veja » Especificar um Tipo de Cursor e Selecionar Linhas na documentação do Microsoft SQLSRV.

Valor Retornado

Retorna um recurso de declaração em caso de sucesso e false se ocorrer um erro.

Exemplos

Exemplo #1 Exemplo de sqlsrv_prepare()

Este exemplo demonstra como preparar uma declaração com sqlsrv_prepare() e reexecutá-la várias vezes (com diferentes valores de parâmetro) usando 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 = ?";

// Inicializa os parâmetros e prepara a instrução.
// As variáveis $qty e $id estão vinculadas à instrução $stmt.
$qty = 0; $id = 0;
$stmt = sqlsrv_prepare( $conn, $sql, array( &$qty, &$id));
if( !$stmt ) {
    die( print_r( sqlsrv_errors(), true));
}

// Configure as informações de SalesOrderDetailID e OrderQty.
// Este array mapeia o ID do pedido para a quantidade do pedido em pares chave=>valor.
$orders = array( 1=>10, 2=>20, 3=>30);

//Executa a instrução para cada pedido.
foreach( $orders as $id => $qty) {
    // Como $id e $qty estão vinculados a $stmt1, seus valores atualizados
    // valores são usados em cada execução da instrução.
    if( sqlsrv_execute( $stmt ) === false ) {
          die( print_r( sqlsrv_errors(), true));
    }
}
?>

Notas

Ao preparar uma declaração que usa variáveis como parâmetros, as variáveis são vinculadas à declaração. Isso significa que se você atualizar os valores das variáveis, na próxima vez que executar a declaração, ela será executada com valores de parâmetro atualizados. Para declarações que você planeja executar apenas uma vez, use sqlsrv_query().

Veja Também

sqlsrv_execute() - Executa uma declaração preparada com sqlsrv_prepare
sqlsrv_query() - Prepara e executa uma consulta