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. Leia "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 MariaDB 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 MariaDB 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 MariaDB 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.

Retornar