db2_prepare

(PECL ibm_db2 >= 1.0.0)

db2_prepare — Prepara uma instrução SQL para ser executada

Descrição

db2_prepare(resource $connection, string $statement, array $options = []): resource|false

db2_prepare() cria uma instrução SQL preparada que pode incluir 0 ou mais marcadores de parâmetros (caracteres ?) representando parâmetros para entrada, saída ou entrada/saída. Pode-se passar parâmetros para a instrução preparada usando db2_bind_param(), ou apenas para valores de entrada, como um array passado para db2_execute().

Existem três vantagens principais em usar instruções preparadas em uma aplicação:

Desempenho: quando uma instrução é preparada, o servidor de banco de dados cria um plano de acesso otimizado para recuperar dados com essa instrução. Subsequentemente, emitir a instrução preparada com db2_execute() permite que as instruções reutilizem esse plano de acesso e evita a sobrecarga de criar dinamicamente um novo plano de acesso para cada instrução emitida.
Segurança: quando uma instrução é preparada, podem ser incluídos marcadores de parâmetros para valores de entrada. Quando uma instrução preparada é executada com valores de entrada para marcadores, o servidor de banco de dados verifica cada valor de entrada para garantir que o tipo corresponda à definição da coluna ou definição do parâmetro.
Funcionalidade avançada: Os marcadores de parâmetros não apenas permitem que sejam passados valores de entrada para instruções SQL preparadas, eles também permitem que sejam recuperados parâmetros OUT e INOUT de procedimentos armazenados usando db2_bind_param().

Parâmetros

connection: Uma variável de recurso de conexão de banco de dados válida, conforme retornada de db2_connect() ou db2_pconnect().
statement: Uma instrução SQL, contendo opcionalmente um ou mais marcadores de parâmetros.
options: Um array associativo contendo opções de instrução. Você pode usar este parâmetro para solicitar um cursor rolável em servidores de banco de dados que suportam esta funcionalidade. Para uma descrição das opções de instrução válidas, consulte db2_set_option().

Valor Retornado

Retorna um recurso de instrução se a instrução SQL foi analisada com sucesso e preparada pelo servidor de banco de dados. Retorna false se o servidor de banco de dados retornou um erro. Pode-se determinar qual erro foi retornado chamando db2_stmt_error() ou db2_stmt_errormsg().

Exemplos

Exemplo #1 Preparando e executando uma instrução SQL com marcadores de parâmetros

O exemplo a seguir prepara uma instrução INSERT que aceita quatro marcadores de parâmetros e, em seguida, itera sobre um array de arrays contendo os valores de entrada a serem passados para db2_execute().

<?php
$animals = array(
    array(0, 'cat', 'Pook', 3.2),
    array(1, 'dog', 'Peaches', 12.3),
    array(2, 'horse', 'Smarty', 350.0),
);

$insert = 'INSERT INTO animals (id, breed, name, weight)
    VALUES (?, ?, ?, ?)';
$stmt = db2_prepare($conn, $insert);
if ($stmt) {
    foreach ($animals as $animal) {
        $result = db2_execute($stmt, $animal);
    }
}
?>

Veja Também

db2_bind_param() - Vincula uma variável PHP a um parâmetro de instrução SQL
db2_execute() - Executa uma instrução SQL preparada
db2_stmt_error() - Retorna uma string contendo o SQLSTATE retornado por uma instrução SQL
db2_stmt_errormsg() - Retorna uma string contendo a última mensagem de erro da instrução SQL