Skip navigation links
Manual de Referência do MySQL 4.1 :: 12 Ferramentas de Clientes e APIs do MySQL :: 12.1 API C do MySQL :: 12.1.6 Visão Geral das Funções de Instruções Preparadas da API C
12.1.7 Descrição das Funções de Instrução Preparada da API C »
Section Navigation      [Toggle]

12.1.6. Visão Geral das Funções de Instruções Preparadas da API C

Note: A API para instruções preparadas ainda é assunto de revisão. Esta informação é fornecida para os adeptos, mas esteja ciente que a API pode alterar.

As funções disponíveis nas instruções preparadas estão resumidas aqui e desctias em maiores detalhes em um seção posterior. See Secção 12.1.7, “Descrição das Funções de Instrução Preparada da API C”.

Função Descrição
mysql_prepare() Prepara uma string SQL para execução.
mysql_param_count() Retorna o número de parâmetros em uma instrução SQL preparada.
mysql_get_metadata() Retorna metadados de instruções preparadas em forma de um conjunto de resultados.
mysql_bind_param() Associa o buffers de dados da aplicação com o parâmetro marcado na instrução SQL preparada.
mysql_execute() Executa a instrução preparada.
mysql_stmt_affected_rows() Retorna o número de registros alteradosi, deletados ou inseridos pela última consulta UPDATE, DELETE, ou INSERT.
mysql_bind_result() Associa o buffers de dados da aplicação com colunas no resultado.
mysql_stmt_store_result() Retorna o resultado completo para o cliente.
mysql_stmt_data_seek() Busca um número de registro arbitrário no resultado de uma consulta.
mysql_stmt_row_seek() Busca por um offset de registro no resultado de uma busca, utilizando o valor reotornado de mysql_stmt_row_tell().
mysql_stmt_row_tell() Retorna a posição do cursor de registro.
mysql_stmt_num_rows() Retorna o total de registros do resultado de uma instrução armazenada.
mysql_fetch() Busca o próximo conjunto de dados do resultado e retorna os dados para todas as colunas limites.
mysql_stmt_close() Libera a memória usada pela instrução preparada.
mysql_stmt_errno() Retorna o número de erro para a última instrução executada.
mysql_stmt_error() Retorna a mensagem de erro para a última instrução executada.
mysql_stmt_sqlstate() Retorna o código de erro SQLSTATE para a execução da última instrução.
mysql_send_long_data() Envia dados longos em blocos para o servidor.

Chama mysql_prepare() para preparar e iniciar o manipulador de instruções, mysql_bind_param() para fornecer os dados do parâmetro e mysql_execute() para executar a consulta. Você pode repetir o mysql_execute() alterando o valor do parâmetro no buffer respectivo fornecido por mysql_bind_param().

Se a consulta é uma instrução SELECT ou qualquer outra consulta que produz um resultado, mysql_prepare() também retornará a informação dos meta dados do resultado na forma de um resultado MYSQL_RES através de um mysql_get_metadata().

Você pode forncer o buffer de resultado usando mysql_bind_result(), assim mysql_fetch() retornará automaticamente os dados para este buffer. Esta busca é feita registro a registro.

Você também pode enviar o texto ou dado binário em blocos para o servidor utilizando mysql_send_long_data(), especficando a opção is_long_data=1 ou length=MYSQL_LONG_DATA ou -2 na estrutura MYSQL_BIND fornecida com mysql_bind_param().

Quando a execução for completada, o handler da instrução deve ser fechado usando mysql_stmt_close() para que todos os recursos associados a ele sejam liberados.

Se você obteve os metadados de um resultado de uma instrução SELECT chamando mysql_get_metadata(), você também deve liberá-lo usando mysql_free_result().

Execution Steps:

Para prepara e executar uma instrução, uma aplicação:

  1. Chama mysql_prepare() e passa uma string contendo uma instrução SQL. Em uma operação de preparo bem sucedida, o mysql_prepare retorna o manipulador de instrução válido para a aplicação.

  2. Se a consulta produz um resultado, chama mysql_get_metadata para obter o conjunto de resultado de metadados. Este metadado está na forma de um resultado, embora um separado daqueles que contém as linhas retornadas pela consulta. O resultado de metadados indica quantos colunas estão no resultado e contém informações sobre cada coluna.

  3. Define o valor de qualquer parâmetro usando mysql_bind_param. Todos os parâmetros devem ser definidos. De outra forma a execução da consulta retornará um erro ou produzirá resultados inesperados.

  4. Chama mysql_execute() para executar a instrução.

  5. Se a consulta produz um resultado, liga o buffer de dados usado para retornar o valor do registro chamando mysql_bind_result().

  6. Busca os dados no buffer, registro a registro chamando mysql_fetch() repetidas vezes até não haver mais registros.

  7. Repete os passos de 3 a 6 como necessário, alterando o valor dos parâmetros e re-executando a instrução.

Quando mysql_prepare() é chamado, o protocolo cliente/servidor do MySQL realiza as seguintes ações:

  • O servidor analiza a consulta e envia o status de OK de volta para o cliente atribuindo uma identificação de instrução. Ele também envia um número total de parâmetros, uma contagem de colunas e sua meta informação se for um resultado orientado a consulta. Toda a sintaxe e semântica da consulta é verificada pelo servidor durante a chamada.

  • O cliente utiliza esta identificação da instrução para as operações adicionais, assim o servidor pode identificar a instrução dentre outras existentes. O cliente também aloca um manipulador de instruções com esta identificação e o retorna para a aplicação.

Quando o mysql_execute() é chamado, no protocolo cliente/servidor do MySQL realiza as seguintes operações:

  • O cliente utiliza o manipulador de instruções e envia o dado do parâmetro para o servidor.

  • O servidor identifica a instrução usando a identificação fornecida pelo cliente, substitui o marcador do parâmetro com o dado fornecido mais recente e executa a consulta. Se a consulta produz um resultado, o servidor envia o dado de volta para o cliente. Senão envia o status de OK como número total de registros alterados, deletados ou inseridos.

Quando mysql_fetch() é chamado, no protocolo cliente/servidor do MySQL realiza as seguintes ações:

  • O cliente lê os dados do pacote registro por registro e o coloca no buffer de dados da aplicação fazendo as conversões necessárias. Se o tipo do buffer de aplicação é o mesmo do tipo do campo retornado do servidor, as conversões são diretas.

Você pode obter o código de erro, mensagens e o valor SQLSTATE da instrução utilizando mysql_stmt_errno(), mysql_stmt_error() e mysql_stmt_sqlstate() respectivamente.

This is a translation of the MySQL Reference Manual that can be found at dev.mysql.com. The original Reference Manual is in English, and this translation is not necessarily as up to date as the English version.