db2_bind_param

(PECL ibm_db2 >= 1.0.0)

db2_bind_param — Associe une variable PHP à un paramètre d'une requête SQL

Description

function db2_bind_param(
    resource $stmt,
    int $parameter_number,
    string $variable_name,
    int $parameter_type = DB2_PARAM_IN,
    int $data_type = 0,
    int $precision = -1,
    int $scale = 0
): bool

Associe une variable PHP à un paramètre d'une requête SQL dans une ressource de requête retournée par db2_prepare(). Cette fonction donne plus de contrôle sur le type de paramètre, le type de données, la précision et l'échelle du paramètre que le simple fait de passer la variable comme élément du tableau d'entrée optionnel de db2_execute().

Liste de paramètres

stmt: Une requête préparée retournée par db2_prepare().
parameter_number: Spécifie la position du paramètre commençant à l'indice 1 dans la requête préparée.
variable_name: Une chaîne spécifiant le nom de la variable PHP à associer au paramètre spécifié par parameter_number.
parameter_type: Une constante spécifiant si la variable PHP devrait être associée au paramètre SQL en tant que paramètre entrant (DB2_PARAM_IN), que paramètre sortant (DB2_PARAM_OUT) ou en tant que paramètre qui accepte les entrées et les sorties (DB2_PARAM_INOUT). Pour éviter une surconsommation de la mémoire, il est aussi possible de spécifier DB2_PARAM_FILE pour attacher la variable PHP au nom du fichier qui contient les données de l'objet large (BLOB, CLOB ou DBCLOB).
data_type: Une constante spécifiant le type de données SQL auquel la variable PHP devrait être associée : l'une des valeurs DB2_BINARY, DB2_CHAR, DB2_DOUBLE ou DB2_LONG.
precision: Spécifie la précision à laquelle la variable devrait être associée à la base de données. Ce paramètre peut également être utilisé pour récupérer des valeurs de sortie XML pour les procédures stockées. Une valeur non négative spécifie la taille maximale des données XML qui seront récupérées depuis la base de données. Si ce paramètre n'est pas utilisé, une taille par défaut de 1 Mo sera définie pour récupérer les valeurs de sortie XML depuis la procédure stockée.
scale: Spécifie l'échelle à laquelle la variable devrait être associée à la base de données.

Valeurs de retour

Cette fonction retourne true en cas de succès ou false si une erreur survient.

Exemples

Exemple #1 Association de variables PHP à une requête préparée

La requête SQL dans l'exemple suivant utilise deux paramètres d'entrée dans la clause WHERE. Nous appelons db2_bind_param() pour associer deux variables PHP aux paramètres SQL correspondants. Il est à noter que les variables PHP n'ont pas besoin d'être déclarées ou assignées avant l'appel à db2_bind_param() ; dans cet exemple, $lower_limit est assignée avant l'appel à db2_bind_param(), mais $upper_limit est assignée après l'appel à db2_bind_param(). Les variables doivent être associées et, pour les paramètres qui acceptent une entrée, une valeur doit leur être assignée, avant d'appeler db2_execute().

<?php

$sql = 'SELECT name, breed, weight FROM animals
    WHERE weight > ? AND weight < ?';
$conn = db2_connect($database, $user, $password);
$stmt = db2_prepare($conn, $sql);

// Nous pouvons déclarer la variable avant d'appeler db2_bind_param()
$lower_limit = 1;

db2_bind_param($stmt, 1, "lower_limit", DB2_PARAM_IN);
db2_bind_param($stmt, 2, "upper_limit", DB2_PARAM_IN);

// Nous pouvons aussi déclarer la variable après l'appel de db2_bind_param()
$upper_limit = 15.0;

if (db2_execute($stmt)) {
    while ($row = db2_fetch_array($stmt)) {
        print "{$row[0]}, {$row[1]}, {$row[2]}\n";
    }
}
?>

L'exemple ci-dessus va afficher :

Pook, cat, 3.2
Rickety Ride, goat, 9.7
Peaches, dog, 12.3

Exemple #2 Appel de procédures stockées avec des paramètres IN et OUT

La procédure stockée match_animal dans l'exemple suivant accepte trois paramètres différents :

un paramètre d'entrée (IN) qui accepte le nom du premier animal en entrée
un paramètre d'entrée-sortie (INOUT) qui accepte le nom du second animal en entrée et retourne la chaîne TRUE si un animal de la base de données correspond à ce nom
un paramètre de sortie (OUT) qui retourne la somme des poids des deux animaux identifiés

De plus, la procédure stockée retourne un jeu de résultats contenant les animaux listés par ordre alphabétique, en commençant par l'animal correspondant à la valeur d'entrée du premier paramètre et en terminant par l'animal correspondant à la valeur d'entrée du second paramètre.

<?php

$sql = 'CALL match_animal(?, ?, ?)';
$conn = db2_connect($database, $user, $password);
$stmt = db2_prepare($conn, $sql);

$name = "Peaches";
$second_name = "Rickety Ride";
$weight = 0;

db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
db2_bind_param($stmt, 2, "second_name", DB2_PARAM_INOUT);
db2_bind_param($stmt, 3, "weight", DB2_PARAM_OUT);

print "Valeurs des paramètres associés _avant_ CALL :\n";
print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

if (db2_execute($stmt)) {
    print "Valeurs des paramètres associés _après_ CALL :\n";
    print "  1: {$name} 2: {$second_name} 3: {$weight}\n\n";

    print "Résultats :\n";
    while ($row = db2_fetch_array($stmt)) {
        print "  {$row[0]}, {$row[1]}, {$row[2]}\n";
    }
}
?>

L'exemple ci-dessus va afficher :

Valeurs des paramètres associés _avant_ CALL :
  1: Peaches 2: Rickety Ride 3: 0

Valeurs des paramètres associés _après_ CALL :
  1: Peaches 2: TRUE 3: 22

Résultats :
  Peaches, dog, 12.3
  Pook, cat, 3.2
  Rickety Ride, goat, 9.7

Exemple #3 Insertion d'un objet large binaire (BLOB) provenant directement d'un fichier

Les données pour les objets larges sont normalement enregistrées dans des fichiers, comme des documents XML ou des fichiers audio. Plutôt que de lire le fichier en entier dans une variable de PHP et ensuite associer la variable PHP dans la requête SQL, il est possible d'éviter certains surcoûts de mémoire en associant le fichier directement au paramètre d'entrée de la requête SQL. L'exemple suivant démontre comment associer un fichier directement dans une colonne BLOB.

<?php
$stmt = db2_prepare($conn, "INSERT INTO animal_pictures(picture) VALUES (?)");

$picture = "/opt/albums/spook/grooming.jpg";
$rc = db2_bind_param($stmt, 1, "picture", DB2_PARAM_FILE);
$rc = db2_execute($stmt);
?>

Voir aussi

db2_execute() - Exécute une requête SQL préparée
db2_prepare() - Prépare une requête SQL à être exécutée