PHP 8.4.1 Released!

sqlsrv_prepare

(No version information available, might only be in Git)

sqlsrv_preparePrepara uma consulta para execução

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

adicione uma nota

Notas Enviadas por Usuários (em inglês) 2 notes

up
4
tuxedobob
9 years ago
Be careful with your variables once you bind them to a statement with sqlsrv_prepare.

Consider the following:

<?php
$dude
= '';
$time = new DateTime();
$sql = "INSERT INTO my_table (person, timein) VALUES (?, ?)";
$stmt = sqlsrv_prepare($conn, $sql, array(&$dude, &$time));

...
// many lines later

foreach ($times as &$time) {
//do stuff
}

// later still...
$time = $times['start'];
if(
sqlsrv_execute( $stmt ) === false ) {
die(
print_r( sqlsrv_errors(), true));
}
?>

I did something like this. I prepared a statement at the start, used the variable again in the middle, and then set the value I wanted before running the query.

Trouble is, I used the variable as an iterator instead of a simple scalar. This caused PHP to use a different location in memory, and the location it was previously bound to was invalid. So SQL simply inserted a default date/time.

Worse, because SQL just inserted a default, it didn't throw any errors, and in trying to debug it, I did something like this:

<?php
var_dump
($time);
sqlsrv_execute($stmt);
$q = "SELECT * FROM my_table WHERE id=@@IDENTITY";
$r = sqlsrv_query($conn, $q);
$row = sqlsrv_fetch_array($r); $id = $row[0];
var_dump($row['time']);
?>

Having it appear as though you're sending SQL the correct data, and seeing it spitting back something else entirely is absolutely maddening.

So if SQL seems to be inserting garbage with prepared statements, MAKE SURE YOU'RE NOT USING THE VARIABLES ANYWHERE ELSE.
up
-2
matt at bigbadweb dot co dot uk
10 years ago
Example of how to formally specify the params, AND get output.
<?php

// Setup connection
$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));
}

// specify params - MUST be a variable that can be passed by reference!
$myparams['Item_ID'] = intval(-2);
$myparams['Item_Name'] = "Foo";

// Set up the proc params array - be sure to pass the param by reference
$procedure_params = array(
array(&
$myparams['Item_ID'], SQLSRV_PARAM_OUT),
array(&
$myparams['Item_Name'], SQLSRV_PARAM_OUT)
);

// EXEC the procedure, {call stp_Create_Item (@Item_ID = ?, @Item_Name = ?)} seems to fail with various errors in my experiments
$sql = "EXEC stp_Create_Item @Item_ID = ?, @Item_Name = ?";

$stmt = sqlsrv_prepare($conn, $sql, $procedure_params);

if( !
$stmt ) {
die(
print_r( sqlsrv_errors(), true));
}

if(
sqlsrv_execute($stmt)){
while(
$res = sqlsrv_next_result($stmt)){
// make sure all result sets are stepped through, since the output params may not be set until this happens
}
// Output params are now set,
print_r($params);
print_r($myparams);
}else{
die(
print_r( sqlsrv_errors(), true));
}
?>
To Top