sqlsrv_prepare

Baixar driver PHP

Cria um recurso de instrução associado à conexão especificada. Essa função é útil para a execução de várias consultas.

Sintaxe

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

Parâmetros

$conn: o recurso de conexão associado à instrução preparada.

$tsql: a expressão Transact-SQL que corresponde à instrução criada.

$params [OPTIONAL]: uma matriz de valores que correspondem aos parâmetros em uma consulta parametrizada. Cada elemento da matriz pode ser um dos seguintes:

• Um valor literal.

• Uma referência a uma variável do PHP.

• Uma matriz com a seguinte estrutura:

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

  Observação

  Variáveis passadas como parâmetros de consulta devem ser passadas por referência em vez de por valor. Por exemplo, passe &$myVariable em vez de $myVariable. Um aviso do PHP será gerado quando uma consulta com parâmetros por valor for executada.

  A tabela a seguir descreve os elementos dessa matriz:

  Elemento	Descrição
  &$value	Um valor literal ou uma referência a uma variável do PHP.
  $direction[OPCIONAL]	Uma destas constantes SQLSRV_PARAM_* é usada para indicar a direção do parâmetro: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. O valor padrão é SQLSRV_PARAM_IN. Para obter mais informações sobre constantes do PHP, confira Constantes (Drivers da Microsoft para PHP para SQL Server).
  $phpType[OPCIONAL]	Uma constante SQLSRV_PHPTYPE_* que especifica o tipo de dados PHP do valor retornado.
  $sqlType[OPCIONAL]	Uma constante SQLSRV_SQLTYPE_* que especifica o tipo de dados do SQL Server do valor de entrada.

$options [OPTIONAL]: Uma matriz associativa que define as propriedades da consulta. A tabela a seguir lista as chaves compatíveis e os valores correspondentes:

Valor retornado

Um recurso de instrução. Se não for possível criar o recurso de instrução, false será retornado.

Comentários

Quando você prepara uma instrução que usa variáveis como parâmetros, as variáveis são associadas à instrução. Isso significa que, se você atualizar os valores das variáveis, da próxima vez que executar a instrução, ela será executada com valores de parâmetros atualizados.

A combinação de sqlsrv_prepare e sqlsrv_execute separa a preparação e a execução da instrução em duas chamadas de função e pode ser usada para executar consultas parametrizadas. Essa função é ideal para executar uma instrução várias vezes com valores de parâmetros diferentes para cada execução.

Para obter estratégias alternativas para gravar e ler grandes quantidades de informações, consulte Batches of SQL Statements e BULK INSERT.

Para obter mais informações, confira Como recuperar parâmetros de saída usando o driver SQLSRV.

Exemplo 1

O exemplo a seguir prepara e executa uma instrução. A instrução, quando executada (veja sqlsrv_execute), atualiza um campo na tabela Sales.SalesOrderDetail do banco de dados AdventureWorks. O exemplo supõe que o SQL Server e o banco de dados AdventureWorks estejam instalados no computador local. Toda a saída será gravada no console quando o exemplo for executado da linha de comando.

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

Exemplo 2

O exemplo a seguir demonstra como preparar uma instrução e executá-la novamente com valores de parâmetros diferentes. O exemplo a seguir atualiza a coluna OrderQty da tabela Sales.SalesOrderDetail no banco de dados AdventureWorks. Depois que as atualizações forem concluídas, o banco de dados será consultado para verificar se as atualizações foram bem-sucedidas. O exemplo supõe que o SQL Server e o banco de dados AdventureWorks estejam instalados no computador local. Toda a saída será gravada no console quando o exemplo for executado da linha de comando.

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

Exemplo 3

Este exemplo de código mostra como associar um valor decimal como um parâmetro de entrada.

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

?>

Consulte Também

Referência da API do driver SQLSRV

Como: Executar consultas parametrizadas

Sobre exemplos de código na documentação

Como: Enviar dados como um fluxo

Usando parâmetros direcionais

Recuperando dados

Atualizar dados (Drivers da Microsoft para PHP para SQL Server)