sqlsrv_prepare

Descarregar o driver PHP

Cria um recurso de instrução associado à ligação especificada. Esta função é útil para a execução de múltiplas consultas.

Syntax

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

Parameters

$conn: O recurso de ligação associado à declaração criada.

$tsql: A expressão Transact-SQL que corresponde à afirmação criada.

$params [OPCIONAL]: Um array de valores que correspondem a parâmetros numa consulta parametrizada. Cada elemento do array pode ser um dos seguintes:

• Um valor literal.

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

• Um array com a seguinte estrutura:

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

  Note

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

  A tabela seguinte descreve estes elementos do array:

  Elemento	Description
  &$value	Um valor literal ou uma referência a uma variável PHP.
  $direction[OPCIONAL]	Uma das seguintes 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 mais informações sobre constantes PHP, consulte Constantes (Microsoft Drivers for PHP for SQL Server).
  $phpType[OPCIONAL]	Uma constante SQLSRV_PHPTYPE_* que especifica o tipo de dado PHP do valor devolvido.
  $sqlType[OPCIONAL]	Uma constante SQLSRV_SQLTYPE_* que especifica o tipo de dado SQL Server do valor de entrada.

$options [OPCIONAL]: Um array associativo que define propriedades de consulta. A tabela seguinte lista as chaves suportadas e os valores correspondentes:

Valor de retorno

Um recurso para declarações. Se o recurso da instrução não puder ser criado, o false é devolvido.

Remarks

Quando se prepara uma instrução que usa variáveis como parâmetros, as variáveis estão ligadas à sentença. Isto significa que, se atualizar os valores das variáveis, da próxima vez que executar a instrução será executada com valores de parâmetros atualizados.

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

Para estratégias alternativas para escrever e ler grandes quantidades de informação, veja Lotes de Instruções SQL e BULK INSERT.

Para mais informações, veja Como: Recuperar Parâmetros de Saída Usando o Driver SQLSRV.

Exemplo 1

O exemplo seguinte prepara e executa uma instrução. A instrução, quando executada (ver sqlsrv_execute), atualiza um campo na tabela Sales.SalesOrderDetail da base de dados AdventureWorks. O exemplo assume que o SQL Server e a base de dados AdventureWorks estão instalados no computador local. Toda a saída é escrita para a consola quando o exemplo é executado a partir da linha de comandos.

<?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 seguinte demonstra como preparar uma instrução e depois reexecutá-la com diferentes valores de parâmetro. O exemplo atualiza a coluna OrderQty da tabela Sales.SalesOrderDetail na base de dados AdventureWorks. Após as atualizações, a base de dados é consultada para verificar se as atualizações foram bem-sucedidas. O exemplo assume que o SQL Server e a base de dados AdventureWorks estão instalados no computador local. Toda a saída é escrita para a consola quando o exemplo é executado a partir da linha de comandos.

<?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 atribuir um valor decimal como 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);  

?>

Ver também

Referência da API do Driver SQLSRV

Como: Realizar Consultas Parametrizadas

Sobre Exemplos de Código na Documentação

Como: Enviar Dados como Fluxo

Usando parâmetros direcionais

Recuperação de Dados

Atualização de Dados (Microsoft Drivers para PHP para SQL Server)