sqlsrv_prepare

Télécharger le pilote PHP

Crée une ressource d’instruction associée à la connexion spécifiée. Cette fonction est utile pour exécuter plusieurs requêtes.

Syntaxe

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

Paramètres

$conn: ressource de connexion associée à l’instruction créée.

$tsql : expression Transact-SQL qui correspond à l’instruction créée.

$params [FACULTATIF] : objet array de valeurs qui correspondent aux paramètres d’une requête paramétrable. Chaque élément du tableau peut être l’un des éléments suivants :

• Une valeur littérale

• Référence à une variable PHP

• Un objet array avec la structure suivante :

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

  Notes

  Les variables passées en tant que paramètres de requête doivent être passées par référence plutôt que par valeur. Par exemple, passez &$myVariable plutôt que $myVariable. Un avertissement PHP est déclenché quand une requête avec des paramètres par valeur est exécutée.

  Le tableau suivant décrit ces éléments de tableau :

  Élément	Description
  &$value	Valeur littérale ou référence à une variable PHP.
  $direction[FACULTATIF]	Une des constantes SQLSRV_PARAM_* utilisées pour indiquer la direction du paramètre : SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. La valeur par défaut est SQLSRV_PARAM_IN. Pour plus d’informations sur les constantes PHP, consultez Constantes (Pilotes Microsoft pour PHP pour SQL Server).
  $phpType[FACULTATIF]	Constante SQLSRV_PHPTYPE_* qui spécifie le type de données PHP de la valeur retournée.
  $sqlType[FACULTATIF]	Constante SQLSRV_SQLTYPE_* qui spécifie le type de données SQL Server de la valeur d’entrée.

$options [FACULTATIF] : tableau associatif qui définit les propriétés de la requête. Le tableau suivant liste les clés prises en charge et les valeurs correspondantes :

Valeur de retour

Ressource d’instruction. Si la ressource d’instruction ne peut pas être créée, la valeur false est retournée.

Notes

Quand vous préparez une instruction qui utilise des variables comme paramètres, les variables sont liées à l’instruction. Cela signifie que si vous mettez à jour les valeurs des variables, la prochaine fois que vous exécuterez l’instruction elle s’exécutera avec les valeurs de paramètres mises à jour.

La combinaison de sqlsrv_prepare et sqlsrv_execute sépare la préparation et l’exécution de l’instruction en deux appels de fonction. De plus, elle peut être utilisée pour exécuter des requêtes paramétrables. Cette fonction est idéale pour exécuter une instruction plusieurs fois avec différentes valeurs de paramètres pour chaque exécution.

Pour découvrir d’autres stratégies d’écriture et de lecture de grandes quantités d’informations, consultez Batches of SQL Statements et BULK INSERT.

Pour plus d’informations, consultez Procédure : Récupérer des paramètres de sortie à l’aide du pilote SQLSRV.

Exemple 1

L’exemple suivant prépare et exécute une instruction. L’instruction, quand elle est exécutée (voir sqlsrv_execute), met à jour un champ dans la table Sales.SalesOrderDetail de la base de données AdventureWorks. L’exemple part du principe que SQL Server et la base de données AdventureWorks sont installés sur l’ordinateur local. Toute la sortie est écrite dans la console quand l’exemple est exécuté à partir de la ligne de commande.

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

Exemple 2

L’exemple suivant montre comment préparer une instruction puis la réexécuter avec des valeurs de paramètres différentes. L’exemple met à jour la colonne OrderQty de la table Sales.SalesOrderDetail dans la base de données AdventureWorks. Une fois les mises à jour effectuées, la base de données est interrogée pour vérifier que les mises à jour ont réussi. L’exemple part du principe que SQL Server et la base de données AdventureWorks sont installés sur l’ordinateur local. Toute la sortie est écrite dans la console quand l’exemple est exécuté à partir de la ligne de commande.

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

Exemple 3

Cet exemple de code montre comment lier une valeur décimale comme paramètre d’entrée.

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

?>

Voir aussi

Informations de référence sur l’API du pilote SQLSRV

Procédure : Exécuter des requêtes paramétrables

À propos des exemples de code dans la documentation

Procédure : Envoyer des données sous forme de flux

Utilisation de paramètres directionnels

Récupération de données

Mise à jour des données (Pilotes Microsoft pour PHP pour SQL Server)