Ferramentas de Clientes e APIs do MariaDB - Databases - Software - Computers

Ferramentas de Clientes e APIs do MariaDB

Índice

API C do MariaDB
Tipos de Dados da API C
Visão Geral das Função da API C
Descrição das Funções da API C
Instruções Preparadas da API C
Tipos de Dados de Instruções Preparadas da API C
Visão Geral das Funções de Instruções Preparadas da API C
Descrição das Funções de Instrução Preparada da API C
Tratando a Execução de Múltiplas Consultas na API C
Manipulando Valores de Data e Hora na API C
Descrição das Funções de Threads da API C
Descrição das Funções do Servidor Embutido da API C
Dúvidas e problemas comuns ao utilzar a API C
Construindo Programas Clientes
Como Fazer um Cliente em Threads
libmysqld, a Biblioteca do Servidor Embutido MySQL
Suporte ODBC ao MySQL
Como Instalar o MyODBC
Como Preencher os Vários Campos no Programa de Administração do ODBC
Parâmetros de Conexão do MyODBC
Como Relatar Problemas com o MyODBC
Programas que Funcionam com MyODBC
Como Obter o Valor de uma Coluna AUTO_INCREMENT no ODBC
Relatando Problemas com MyODBC
Conectividade Java (JDBC) ao MySQL
API PHP do MariaDB
Problemas Comuns com MariaDB e PHP
API Perl do MariaDB
DBI com DBD::mysql
A interface DBI
Mais Informações DBI/DBD
API C++ do MariaDB
Borland C++
API Python do MariaDB
API Tcl do MariaDB
Eiffel Wrapper do MariaDB

Este descreve as APIs disponíveis para o MySQL, onde consegui-las e como utilizá-las. A API C é a coberta mais estensamente, já que ela foi desenvolvida pela equipe do MariaDB e é a base para a maioria das outras APIs.

API C do MariaDB

Tipos de Dados da API C
Visão Geral das Função da API C
Descrição das Funções da API C
Instruções Preparadas da API C
Tipos de Dados de Instruções Preparadas da API C
Visão Geral das Funções de Instruções Preparadas da API C
Descrição das Funções de Instrução Preparada da API C
Tratando a Execução de Múltiplas Consultas na API C
Manipulando Valores de Data e Hora na API C
Descrição das Funções de Threads da API C
Descrição das Funções do Servidor Embutido da API C
Dúvidas e problemas comuns ao utilzar a API C
Construindo Programas Clientes
Como Fazer um Cliente em Threads
libmysqld, a Biblioteca do Servidor Embutido MySQL

O código da API C é distribuído com o MariaDB. Ele está incluído na biblioteca mysqlclient e permite programas em C a fazer acesso em banco de dados.

Muitos dos clientes na distribuição fonte do MariaDB está escrito em C. Se você estiver procurando por exemplos que demonstrem como utilizar a API C, dê uma olhada neste clientes. Você pode encontrá-los no diretório clients na distribuição fonte do MariaDB.

A maioria das outras clientes API (todos exceto Connector/J) usam a biblioteca mysqlclient para se comunicar com o servidor MySQL. Isto significa que, por exemplo, você pode tirar vantagem das mesmas variáveis de ambientes que são utilizados por outros programas clientes, pois eles referênciados pela biblioteca. Veja 'Utilitários e Scripts do Lado do Cliente MySQL', para uma lista destas variáveis.

O cliente tem um tamanho máximo de buffer de comunicação. O tamanho do buffer que é alocado inicialmente (16K bytes) é automaticamente aumentado para o tamanho máximo (o máximo é 16M). Como o tamanho do buffer é aumentado somente como autorização de demanda, o simples aumento do limite máximo padrão não faz, por si só, que mais recursos sejam usado. Esta verificação de tamanho é na maioria verificações por consultas erradas e pacotes de comunicações.

O buffer de comunicação deve ser grande o suficiente para conter uma única instrução SQL (para tráfego cliente-servidor) e uma linha de dado retornado (para trafico servidor-cliente). Cada buffer de comunicação de thread é dinamicamente aumentado para manipular qualquer consulta ou linha até o limite máximo. Por exemplo, se você tiver valores BLOB que contenham até 16M de dados, você deve ter um limite de buffer de comunicação de pelo menos 16M (no servidor e no cliente). A máximo padrão do cliente '16M. mas o máximo padrão no servidor é 1M. Você pode aumentar iso alterando o valor do parâmetro max_allowed_packet quando o servidor é iniciado. Leia 'Parâmetros de Sintonia do Servidor'.

O servidor MariaDB encolhe cada buffer de comunicação para net_buffer_length bytes depois de cada consulta. Para clientes, o tamanho do buffer associado com um conexão não é reduzido até que a conexão seja fechada, quando a memória de tempo do cliente é recuperada.

Para programação com threads, veja Seção 12.1.14, 'Como Fazer um Cliente em Threads'. Para criar uma aplicação stand-alone que inclua o 'servidor' e o 'cliente' no mesmo programa (e que não comunica com um servidor MariaDB externo), veja Seção 12.1.15, 'libmysqld, a Biblioteca do Servidor Embutido MySQL'.

Tipos de Dados da API C

A estrutura MYSQL_FIELD contem os membros listados aqui:

Visão Geral das Função da API C

As funções disponíveis na API C são resumidas aqui e descritas em maiores detalhes em uma seção posterior. Leia Seção 12.1.3, 'Descrição das Funções da API C'.

Função Descrição
mysql_affected_rows() Retorna o número de linhas alteradas/deletadas/insweridas pela última consulta \ UPDATE, DELETE, ou INSERT.
mysql_change_user() Muda o usuario em um banco de dados em uma conexão aberta.
mysql_character_set_name() Retorna o nome do conjunto de carcters padrão para a conexão.
mysql_close() Fecha ua conexão com o servidor
mysql_connect() Se conecta ao servidro MariaDB. Esta função está deprecad; utilize mysql_real_connect().
mysql_create_db() Cria um banco de dados. Esta função está obsoleta; utiliza o comando SQL CREATE DATABASE.
mysql_data_seek() Busca por uma número de linha arbitrário em um conjunto de resultados de uma consulta.
mysql_debug() Faz um DBUG_PUSH com a string dada.
mysql_drop_db() Apaga um banco de dados; Esta função esta obsoleta; utiliza o comando SQL DROP DATABASE.
mysql_dump_debug_info() Faz o servidor escrever informações de depouração no log.
mysql_eof() Determina quando a ulitma linha de um conjunto de resultados foi lida. Esta função foi obsoleta; Utilize mysql_errno() ou mysql_error()
mysql_errno() Retorna o número de erro para a função MariaDB chamada mais recentemente.
mysql_error() Retorna a mensagem de erro para função MariaDB chamada mais recentemente.
mysql_escape_string() Escapa caracteres especiais em uma string para ser usada em uma instrução SQL.
mysql_fetch_field() Retorna o tipo do próximo campo na tabela.
mysql_fetch_field_direct() Retorna o tipo de um campo da tabela, dado um número do campo.
mysql_fetch_fields() Retorna um vetor de todas as estruturas do campo.
mysql_fetch_lengths() Retorna o tamanho de todas as colunas na linha atual.
mysql_fetch_row() Busca o próximo registro no conjunto de resultados.
mysql_field_seek() Coloca o cursor da coluna em uma coluna específica.
mysql_field_count() Retorna o número de colunas resultantes da consulta mais recente.
mysql_field_tell() Retorna a posição do cursos de campos usado pelo último mysql_fetch_field().
mysql_free_result() Libera a memória usada por um conjunto de resultados.
mysql_get_client_info() Retorna a versão do cliente como uma string.
mysql_get_client_version() Returna a versão do cliente como um inteiro.
mysql_get_host_info() Retorna uma string descrevendo a conexão.
mysql_get_server_version() Retorna o número da versão do servidor como um inteiro (Novo na versão 4.1)
mysql_get_proto_info() Retorna a versão do protovolo usado para a conexão.
mysql_get_server_info() Retorna o número da versão do servidor.
mysql_info() Retorna informação sobre a consulta executada mais recentemente.
mysql_init() Obtem ou inicializa uma estrutura MariaDB.
mysql_insert_id() Retorna o ID gerado para uma coluna AUTO_INCREMENT pela consulta anterior.
mysql_kill() Mata uma thread dada.
mysql_list_dbs() Retorna o nome do banco de dados correspondente a uma expressão regular.
mysql_list_fields() retorna nome de campos coincidindo com uma expressão regular.
mysql_list_processes() Retorna uma lista das threads atuais do servidor.
mysql_list_tables() Retorna os nomes de tabelas correspondente a uma expressão regular.
mysql_num_fields() Retorna o número de coluans em um conjunto de resultados.
mysql_num_rows() Retorna o número de linhas em um conjunto de resultados.
mysql_options() Define opções de conexão para mysql_connect().
mysql_ping() Verifica se a conexão ao servidor está funcionando, reconectando se necessário.
mysql_query() Executa uma consulta SQL especificada com uma string terminada com null.
mysql_real_connect() Conecta ao servidor MySQL.
mysql_real_escape_string() Escapa caracteres especiais em uma string para ser utilizada em uma instrução SQL, olhando na conta o conjunto de caracteres atual da conexão
mysql_real_query() Executa uma consulta SQL especificada como uma string fixa.
mysql_reload() Diz ao servidor pra recarregar a tabela de permissões
mysql_row_seek() Busca por um offset de linha no resultado, usando o valor retornado de mysql_row_tell().
mysql_row_tell() Retorna a posição dio cursor de linhas.
mysql_select_db() Seleciona um banco de dados.
mysql_set_server_option() Define uma opção para a conexão (como multi-statements).
mysql_sqlstate() Retorna o código de erro SQLSTATE para o último erro.
mysql_shutdown() Desliga o servidor de banco de dados.
mysql_stat() Retorna o status do servidor como uma string.
mysql_store_result() Recupera um resultado completo para o cliente.
mysql_thread_id() Retorna a identificação da thread atual.
mysql_thread_safe() Retorna 1 se o cliente foi compilado como thread-safe.
mysql_use_result() Inicia uma resultado recuperado registro por registro.
mysql_warning_count() Retorna a contagem do aviso da instrução SQL anterior.
mysql_commit() Faz um commits na transação (novo na versão 4.1).
mysql_rollback() Faz um roll back na transação (novo na versão 4.1).
mysql_autocommit() Muda o modo autocommit em ligado/desligado (novo na versão 4.1).
mysql_more_results() Verifica se não existem mais resultados (novo na versão 4.1).
mysql_next_result() Retorna/Inicia o próximo resultado em execuções consultas múltiplas (inovo na versão 4.1).

Para se conectar ao servidor, chame mysql_init() para iniciar um manipulador de conexão, então chame mysql_real_connect() com este manipulador (com informações de nome de máquina, usuários e senha). Conectado, mysql_real_connect() define o parâmetro reconnect (parte da estrutura MYSQL) para um valor de 1. Este parâmetro indica, no evento que uma consulta não pode ser realizada por perda de conexão, para tentar reconectar ao servidor ao antes de desistir. Quando não precisar mais da conexão, chame mysql_close() para terminá-la.

Enquanto a conexão estiver ativa, o cliente pode enviar consultas SQL para o servidor usando mysql_query() ou mysql_real_query(). A diferença entre os dois é que mysql_query() espera que a consulta seja especificada como uma string terminada em null, enquanto mysql_real_query() espera um string de tamanho fixa. Se a string conter dados binários (a qual pode incluir bytes null), vocêdeve usar mysql_real_query().

Para cada consulta não-SELECT (por exemplo, INSERT, UPDATE, DELETE), você pode descobrir quantas linhas foram alteradas (afetadas) chamando mysql_affected_rows().

Para consultas SELECT, você retorna os registros selecionados como um resultado. (Note que algumas intruções são como a SELECT ao retornar registros. Elas incluem SHOW, DESCRIBE e EXPLAIN. elas devem ser tratadas da mesma maneira que instruções SELECT.)

Existem dois modos para um cliente processa o resultado. Um mode é recuperar todo o resultado de uma vez chamando mysql_store_result(). Esta função busca no servidor todas as linhas retornadas pela consulta e as armazena no cliente. O segundo modo é o cliente iniciar um retorno do resultado registro por registro chamando mysql_use_result(). Esta função inicia o retorno, mas não busca realmente nenhuma linha do servidor.

Em ambos os casos, acesse registros chamando mysql_fetch_row(). Com mysql_store_result(), mysql_fetch_row() acessa registros que já tenham sido buscado do servidor. Com mysql_use_result(), mysql_fetch_row() recupera, na verdade, o registro do servidor. Informações sobre o tamanho dos dados em cada registro é disponível pela chamada mysql_fetch_lengths().

Depois de finalizar o uso do resultado, chame mysql_free_result() para liberar a memória usada por ele.

Os dois mecanismos de recuperação são complementares. Programas clientes devem escolher a abordagem mais apropriada para suas necessidades. Na prática, clientes tendem a utilizar mysql_store_result().

Uma vantagem de mysql_store_result() é que pelo fato de todos os registros serem trazidos para o cliente, você não só pode acessar registros sequencialmente, mas também pode mover para tarz e para frente no resultado utilizando mysql_data_seek() ou mysql_row_seek() para altera a posição atual do registro no resultado. Você também pode saber quantas linhas existem chamando mysql_num_rows(). Por outro lado, a necessidade de memória para mysql_store_result() pode ser muito alta para resultados grandes e você encontrará como mais facilidade condições de estouro de memória.

Uma vantagem de mysql_use_result() é que o clientes exige menos memória para o resultado porque ele mantem apenas um registro por vez (por haver menor sobrecarga de alocação, mysql_use_result() pode ser mais rápido). As desvantagens são que você deve processar cada registro rapidamente para evitar prender o servidor, você não tem acesso aleatório aos registros no resultado (você só pode acessá-los sequencialmente) e você não sabe quantos registros existem no resultado até que você recupere todos eles. Além disso, você deve recuperar todos os registros mesmo que você já tenham encontrado a informação que procura antes do finalizar o conjunto de resultados.

A API torna possível para os clientes responder apropriadamente as consultas (recuperando somente os regiostros necessários) sem saber se a consulta é uma instrução SELECT ou não. Você pode fazer isto chamando mysql_store_result() depois de cada mysql_query() (ou mysql_real_query()). Se o resultado for obtido corretamente, a consulta foi um SELECT e você pode ler os registros. Se a obtenção do resultado falhar, chame mysql_field_count() para determinar se o resultado era o esperado. Se mysql_field_count() retornar zero, a consulta não retornou nenhum dado (indicando que ela era um INSERT, UPDATE, DELETE, etc.), e não era esperado que retornasse registros. Se mysql_field_count() é diferente de zero, a consulta deveria retornar registros, mas não o fez. Isto indica que a consulta foi um SELECT que falhou. Veja a descrição de mysql_field_count() para um exemplo de como deve ser feito.

mysql_store_result() e mysql_use_result() permitem que você obtenha informação sobre os campos que montam o resultado (o número de campos, os seus nome e tipos, etc.) Você pode acessar informações de campo sequencialmente dentro dos registros chamando mysql_fetch_field() repetidamente, ou pelo número do campo dentro do registro chamando mysql_fetch_field_direct(). A posição atual do cursor de campos pode ser alterada cahamando mysql_field_seek(). Definir o cursor de campo afeta chamadas subsequentes de mysql_fetch_field(). Você também pode conseguir informações de todos os campos de uma só vez chamando mysql_fetch_fields().

Para detectar e relatar problemas, o MariaDB fornace acesso a informações de erro através das funções mysql_errno() e mysql_error(). Elas retornam o código de erro ou a mensagem de erro para a função chamada mais recentemente que tenha tido sucesso ou que tenha falhado, permitindo a você determinar quando um erro ocorreu e qual foi ele.

Descrição das Funções da API C

mysql_affected_rows()
mysql_change_user()
mysql_character_set_name()
mysql_close()
mysql_connect()
mysql_create_db()
mysql_data_seek()
mysql_debug()
mysql_drop_db()
mysql_dump_debug_info()
mysql_eof()
mysql_errno()
mysql_error()
mysql_escape_string()
mysql_fetch_field()
mysql_fetch_fields()
mysql_fetch_field_direct()
mysql_fetch_lengths()
mysql_fetch_row()
mysql_field_count()
mysql_field_seek()
mysql_field_tell()
mysql_free_result()
mysql_get_client_info()
mysql_get_client_version()
mysql_get_host_info()
mysql_get_proto_info()
mysql_get_server_info()
mysql_get_server_version()
mysql_info()
mysql_init()
mysql_insert_id()
mysql_kill()
mysql_list_dbs()
mysql_list_fields()
mysql_list_processes()
mysql_list_tables()
mysql_num_fields()
mysql_num_rows()
mysql_options()
mysql_ping()
mysql_query()
mysql_real_connect()
mysql_real_escape_string()
mysql_real_query()
mysql_reload()
mysql_row_seek()
mysql_row_tell()
mysql_select_db()
mysql_set_server_option()
mysql_shutdown()
mysql_sqlstate()
mysql_ssl_set()
mysql_stat()
mysql_store_result()
mysql_thread_id()
mysql_use_result()
mysql_warning_count()
mysql_commit()
mysql_rollback()
mysql_autocommit()
mysql_more_results()
mysql_next_result()

Nas descrições a seguir, um parâmetro ou valor retornado NULL significa NULL no sentido da linguagem de programação C, não um valor NULL do MariaDB.

Funções que retornam um valor geralmente retornam um ponteiro ou um inteiro. A menos que seja especificado, funcões que retornam um ponteiro, retornam um valor diferente de NULL para indicar sucesso ou um valor NULL para indicar um erro, e funções que retornam um inteiro, retoprnam zero para indicar sucesso ou um valor diferente de zero para indicar um erro. A menos que a descrição da função diga algo diferente, não faça teste com outro valor além do zero.

if (result) /* correct */
 ... error ...
if (result < 0) /* incorrect */
 ... error ...
if (result == -1) /* incorrect */
 ... error ...

Quando uma função retornar um erro, a subsecao Erros de descrição de funções lista os possíveis tipos de erro. Você pode descobrir quais deles ocorreu chamando mysql_errno(). Uma representação string do erro pode ser obtida chamando mysql_error().

mysql_affected_rows()

my_ulonglong mysql_affected_rows(MYSQL *mysql)

Descrição

Retorna o número de registros alterados pelo último UPDATE, deletados elo último DELETE ou inseridos pelo último INSERT. Pode ser chamado imediatamente após mysql_query() para instruções UPDATE, DELETE, ou INSERT. Para instruções SELECT, mysql_affected_rows() funciona como mysql_num_rows().

Valor Retornado

Um inteiro maior que zero indica o número de registros afetados ou recuperados. Zero indica que nenhum registro foi atualizado por uma instrução UPDATE, nenhuma linha foi encontrada pela cláusula WHERE na consulta ou a consulta ainda não foi executada. -1 indica que a consulta retornou um erro ou que, para uma consulta SELECT, mysql_affected_rows() foi chamado antes da chamada mysql_store_result().

Erros

Nenhum.

Exemplo

mysql_query(&mysql,'UPDATE products SET cost=cost*1.25 WHERE group=10');
printf('%ld products updated',(long) mysql_affected_rows(&mysql));

Se se for especificado o parâmetro CLIENT_FOUND_ROWS ao conectar no mysqld, mysql_affected_rows() retornará o número de linhas encontardos pela cláusula WHERE para a instrução UPDATE.

Note que quando for utilizado um comando REPLACE, mysql_affected_rows() retornará 2 se o novo registro substituir um mais antigo. Isto é porque neste caso um registro foi inserido e depois os registros duplicados foram deletados.

mysql_change_user()

my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)

Descrição

Altera o usuário é faz com que o banco de dados especificado por db se torne o banco de dados padrão (atual) na conexão especificada por MariaDB. Em consultas subsequentes este banco de dados é o padrão para referências a tabelas que não especificam o banco de dados explicitamente.

Esta função foi introduzida na versão do MariaDB.

mysql_change_user() falha a menos que o usuário conectado possa ser autenticado ou se ele não tiver permissão para utilizar o banco de dodos. Neste caso o usuário e o banco de dados não são alterados.

O parâmetro db pode ser definido como NULL se você não dseseja ter um banco de dados padrão.

A partir da versão 4.0.6 do MariaDB este comando sempre fará ROLLBACK de qualquer transação ativa, fecha todas as tabelas temporárias, destrava todas as tabelas bloqueadas e volta a um estado como se tivesse feito uma inova conexão. Isto irá acontecer mesmo se o usuário não foi alterado.

Valor Retornado

Zero se obteve successo. Diferente de zero se ocorreu um erro.

Erros

O mesmo que pode ser obtido com mysql_real_connect().

Exemplo

if (mysql_change_user(&mysql, 'user', 'password', 'new_database'))
{
 fprintf(stderr, 'Failed to change user. Error: %s\n',
 mysql_error(&mysql));
}

mysql_character_set_name()

const char *mysql_character_set_name(MYSQL *mysql)

Descrição

Retorna o conjunto de caracteres padrão para a conexão atual.

Valor Retornado

O conjunto de carcteres padrão

Erros

Nenhum.

mysql_close()

void mysql_close(MYSQL *mysql)

Descrição

feca uma conexão aberta anteriormente. mysql_close() também desaloca o ponteiro do manipulador da conexão para o MariaDB se ele tiver sido alocado automaticamente por mysql_init() ou mysql_connect().

Valor Retornado

Nenhum.

Erros

Nenhum.

mysql_connect()

MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)

Descrição

A função está obsoleta. É melhor utilizar mysql_real_connect().

mysql_connect() tenta estabelecer uma conexão a um banco de dados MariaDB executando em host. mysql_connect() deve completar com suceso antes que você podssa executar qualquer uma das função da API, com a exceção de mysql_get_client_info().

O significado dos parâmetros são os mesmos que os parâmetros correspondentes para mysql_real_connect() com a diferença que o parâmetro de conexão pode ser NULL. Neste caso a API C aloca memória para a estrutura de conexão automaticamente e a libera quando você chamar mysql_close(). A disvantagem desta abordagem é que você não pode retornar uma mensagem de erro se a conexão falhar. (Para obter informações de erro de mysql_errno() ou mysql_error(), você deve fornecer um ponteiro MariaDB válido.)

Valor Retornado

O mesmo de mysql_real_connect().

Erros

O mesmo de mysql_real_connect().

mysql_create_db()

int mysql_create_db(MYSQL *mysql, const char *db)

Descrição

Cria o banco de dados nomeado pelo parâmetro db.

Esta função está obsoleta. É melhor utilizar mysql_query() para comandar uma instrução SQL CREATE DATABASE.

Valor Retornado

Zero se o banco de dados foi criado com successo. Diferente de zero se ocorreu um erro.

Erros

Exemplo

if(mysql_create_db(&mysql, 'my_database'))
{
 fprintf(stderr, 'Failed to create new database. Error: %s\n',
 mysql_error(&mysql));
}

mysql_data_seek()

void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)

Descrição

Busca um registro arbitrário em um resultado de uma consulta. O valor do offset é um número de linha e deve estar em uma faixa de 0 até mysql_num_rows(stmt)-1.

Esta função exige que a estrutura do resultado contenha todo o resultado da consulta, assim mysql_data_seek() só pode ser usado em conjunto com mysql_store_result(), não com mysql_use_result().

Valor Retornado

Nenhum.

Erros

Nenhum.

mysql_debug()

void mysql_debug(const char *debug)

Descrição

Faz um DBUG_PUSH com a string dada. mysql_debug() usa a biblioteca de depuração Fred Fish. Para utilizar esta função você deve compilar a biblioteca cliente para suportar depuração. See Seção E.1, 'Depurando um Servidor MySQL'. Leia Seção E.2, 'Depurando um cliente MySQL.'.

Valor Retornado

Nenhum.

Erros

Nenhum.

Exemplo

A chamada mostrada aqui faz com que a biblioteca cliente gere um arquivo de rastreamento /tmp/client.trace na máquina cliente:

mysql_debug('d:t:O,/tmp/client.trace');

mysql_drop_db()

int mysql_drop_db(MYSQL *mysql, const char *db)

Descrição

Apaga o banco de dados nomeado pelo parâmetro db.

Esta função está obsoleta. É melhor utilizar mysql_query() para realizar uma instrução SQL DROP DATABASE.

Valor Retornado

Zero se o banco de dados foi apagdo corretamente. Diferente de zero ocorreu um erro.

Erros

Exemplo

if(mysql_drop_db(&mysql, 'my_database'))
 fprintf(stderr, 'Failed to drop the database: Error: %s\n',
 mysql_error(&mysql));

mysql_dump_debug_info()

int mysql_dump_debug_info(MYSQL *mysql)

Descrição

Instrui o servidor a gravar algumas informações de depuração no log. Para funcionar, o usuário conectado deve ter pivilégio SUPER.

Valor Retornado

Zero se o comando obteve sucesso. Diferete de zero se ocorreu um erro.

Erros

mysql_eof()

my_bool mysql_eof(MYSQL_RES *result)

Descrição

Esta função está obsoleta. mysql_errno() ou mysql_error() podem ser usados em seu lugar.

mysql_eof() determina se o último registro de um resultado foi lido.

Se você buscar um resultado com um chamada mysql_store_result() bem sucedida, o cliente recebe todo o resultado em uma operação. Neste caso, é um valor NULL retornado de mysql_fetch_row() sempre significa que o fim do resultado foi atingido e não é necessário chamar mysql_eof(). Quando usado com mysql_store_result(), mysql_eof() sempre retornará verdadeiro.

Por outro lado, se você utilizar mysql_use_result() para iniciar um resultado recuperado, as linhas do conjunto são obtido do servidor uma a uma, chamando mysql_fetch_row() repetidamente. Como pode ocorrer um erro na conexão durante este processo, um valor NULL retornado de mysql_fetch_row() não significa, necessáriaemente, que o fim do resultado fo atingido normalmente. Neste caso, você pode utilizar mysql_eof() para determinar o que aconteceu. mysql_eof() retorna um valor diferente de zero se o fim do resultaod foi atingido e zero se ocorreu um erro.

Historicamente, mysql_eof() é preterido pelas funções de erro padrão do MariaDB mysql_errno() e mysql_error(). Como estas funções de erro fornecem a mesma informação, o uso das duas últimas é preferido sobre mysql_eof(), a qual está obsoleta. (De fato, elas fornecem mais informações, porque mysql_eof() retorna apenas um valor booleano enquanto as funções de erro indicam uma razão para a ocorrência do erro quando ele ocorre).

Valor Retornado

Zero se nenhum erro ocorreu. Diferente de zero o fim do resultado foi atingido.

Erros

Nenhum.

Exemplo

Os exemplos seguintes mostram como você deve usar mysql_eof():

mysql_query(&mysql,'SELECT * FROM some_table');
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
 // faz algo com os dados
}
if(!mysql_eof(result)) // mysql_fetch_row() falha devido a um erro
{
 fprintf(stderr, 'Error: %s\n', mysql_error(&mysql));
}

No entanto, você pode conseguir o mesmo efeito com as funções de erro padrões do MariaDB:

mysql_query(&mysql,'SELECT * FROM some_table');
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
 // faz algo com os dados
}
if(mysql_errno(&mysql)) // mysql_fetch_row() falha devido a um erro
{
 fprintf(stderr, 'Error: %s\n', mysql_error(&mysql));
}

mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

Descrição

Para a conexão especificada pelo MariaDB, mysql_errno() retorna o código de erro para a função API chamada mais recentemente que tenha obtido sucesso ou falhado. Um valor de retorno de zero significa que um erro ocorreu. Números de mensagens de erro de clientes são listados no arquivo de cabeçalho errmsg.h do MariaDB. Números de mensagem de erros do servidor são listados no arquivo mysqld_error.h. Na distribuição fonte do MariaDB você pode encontrar uma lista completa de núeros de mensagens de erro no arquivo Docs/mysqld_error.txt. Os códigos de erros do servidor estão listados em Seção 13.1, 'Erros Retornados'.

Note que algumas funções como mysql_fetch_row() não configuram o mysql_errno() se elas obterem sucesso.

Uma regra do dedão é que todas as funções que precisam perguntar ao servidor por informação irão zerar mysql_errno() se obterem sucesso.

Valor Retornado

Um valor de código de erro para a última chamada mysql_xxx, se ele falhar, Zero significa que nenhum erro ocorreu.

Erros

Nenhum.

mysql_error()

const char *mysql_error(MYSQL *mysql)

Descrição

Para a conexão especificada por MariaDB, mysql_error() retorna um string terminada em null contendo a mensagem de erro para a função de API chamda mais recentemente que tenha falhado. Se a função não falhou, o valor de retorno de mysql_error() pode ser o erro anterior ou uma string vazia para indicar que não ocorreu erro.

Uma regra do dedão é que todas as funções que precisam pedir informação ao servidor irão zerar mysql_error() se obterem sucesso.

Para todas as funções que zeram mysql_errno, os seguintes dois testes são equivalentes:

if(mysql_errno(&mysql))
{
 // ocorreu um erro
}
if(mysql_error(&mysql)[0] != '\0')
{
 // ocorreu um erro
}

A língua da mensagem de erro do cliente pode ser alterada recompilando a biblioteca do cliente MySQL. Atualmente você pode escolher mensagens de erro em várias línguas diferentes. Leia 'Mensagens de Erros em Outras Línguas'.

Valor Retornado

Uma string terminada em null que descreve um erro. Uma string vazia se nenhum erro ocorrer.

Erros

Nenhum.

mysql_escape_string()

Você deve usar mysql_real_escape_string() em seu lugar!

Esta função é identica a mysql_real_escape_string() exceto que mysql_real_escape_string() pega um manipulador de cnexão como seu primeiro argumento e escapa a string de acordo com a conjunto de caracteres padrão. mysql_escape_string() não utiliza um argumento de conexão e não respeita o conjunto de caracteres atual.

mysql_fetch_field()

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

Descrição

Retorna a definição de uma coluna de um resultado como uma estrutura MYSQL_FIELD. Chame esta função repetidamente para retornar informações sobre todas as colunas no resultado. mysql_fetch_field() retorna NULL quando não existirem mais campos.

mysql_fetch_field() é definido para retornar a informação do primeiro campo cada vez que você executar uma nova consulta SELECT. O campo retornado por mysql_fetch_field() também é afetado pela chamadas mysql_field_seek().

Se vovê tiver chamado mysql_query() para realizar um SELECT em uma tabela mas não tiver chamado mysql_store_result(), MariaDB retorna o tamanho padrão do blob (8K bytes) quando chamar mysql_fetch_field() para saber o tamanho de um campo BLOB. (O tamanho de 8 k é escolhido porque o MariaDB não sabe o tamanho máximo do BLOB. Ele pode ser configurado algumas vezes.) Uma vez retornado o resultado, campo->tamanho_max contém o tamanho da maior valor para esta coluna em uma consulta específica.

Valor Retornado

A estrutura MYSQL_FIELD para a coluna atual. NULL não houver mais colunas.

Erros

Nenhum.

Exemplo

MYSQL_FIELD *field;
while((field = mysql_fetch_field(result)))
{
 printf('field name %s\n', field->name);
}

mysql_fetch_fields()

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

Descrição

Retorna um vetor de todas as estruturas MYSQL_FIELD no resultado. Cada estrutura fornece a definição do campo para uma coluna do resultado.

Valor Retornado

Um vetor da estrutura MYSQL_FIELD para todas as colunas no resultado.

Erros

Nenhum.

Exemplo

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *fields;
num_fields = mysql_num_fields(result);
fields = mysql_fetch_fields(result);
for(i = 0; i < num_fields; i++)
{
 printf('Field %u is %s\n', i, fields[i].name);
}

mysql_fetch_field_direct()

MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)

Descrição

Dado um número de campo fieldnr para uma colua em resultado, retorna a informação de campo daquela coluna como uma estrutura MYSQL_FIELD Você pode utilizar esta função para retornar a definição para uma coluna arbitrária. O valor de fieldnr deve estar na faixa de 0 a mysql_num_fields(result)-1.

Valor Retornado

A estrutura MYSQL_FIELD para uma coluna específica.

Erros

Nenhum.

Exemplo

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD *field;
num_fields = mysql_num_fields(result);
for(i = 0; i < num_fields; i++)
{
 field = mysql_fetch_field_direct(result, i);
 printf('Field %u is %s\n', i, field->name);
}

mysql_fetch_lengths()

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

Descrição

Retorna o tamanho da coluna do registro atual em um resultado. Se você planeja copiar calores dos compos, esta informação de tamanho é útil também para a otimização, porque você pode evitar a chamada strlen(). Se o resultado contém dados biários, você deveutilizar esta função para determinar o tamanho dos dados, pois strlen() retorna um valor incorreto para quaquer campo contendo caracteres nulos.

O tamanho para colunas vazias e para colunas contendo valores NULL é zero. Para ver como distnguir este dois casos, veja a descrição de mysql_fetch_row().

Valor Retornado

Um vetor de unsigned long integers (inteiros longos sem sinal) representando o tamanho de cada coluna (não incluindo nenhuma caracter nulo). NULL se ocorrer um erro.

Erros

mysql_fetch_lengths() só é válido para o registro atual no resultado. Ele retorna NULL se você chamá-lo antes de mysql_fetch_row() ou depois de retornar todos os registros em um resultado.

Exemplo

MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;
row = mysql_fetch_row(result);
if (row)
{
 num_fields = mysql_num_fields(result);
 lengths = mysql_fetch_lengths(result);
 for(i = 0; i < num_fields; i++)
 {
 printf('Column %u is %lu bytes in length.\n', i, lengths[i]);
 }
}

mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

Descrição

Recuera o próximo registro do resultado. Quando usado depois de mysql_store_result(), mysql_fetch_row() retorna NULL quando não houver mais registros para retornar. Quando usado depois de mysql_use_result(), mysql_fetch_row() retorna NULL quando não houver mais registros para retornar ou ocorrer um erro.

O número de valores no registro é dado por mysql_num_fields(result). Se row guarda o valor retornado de uma chamada mysql_fetch_row(), apontadores para os valores são acessados como row[0] a row[mysql_num_fields(result)-1]. Valores NULL no registro são indicados por apontadores NULL.

Os tamanhos dos valores do campo no registro poden ser obtidos chamando mysql_fetch_lengths(). Campos vazios e campos contendo NULL tem tamanho 0; você pode distingui-los verificando o apontador para o valor do campo. Se o apontador é NULL, o campo é NULL; senão o campo está vazio.

Valor Retornado

Uma estrutura MYSQL_ROW para o próximo registro. NULL se não houver mais linhas para retornar ou ocorrer um erro.

Erros

Note que o erro não é zerado entre as chamadas a mysql_fetch_row()

Exemplo

MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;
num_fields = mysql_num_fields(result);
while ((row = mysql_fetch_row(result)))
{
 unsigned long *lengths;
 lengths = mysql_fetch_lengths(result);
 for(i = 0; i < num_fields; i++)
 {
 printf('[%.*s] ', (int) lengths[i], row[i] ? row[i] : 'NULL');
 }
 printf('\n');
}

mysql_field_count()

unsigned int mysql_field_count(MYSQL *mysql)

Se você estiver utilizando uma versão anterior a versão 3.22.24 do MariaDB, você deve utilizar unsigned int mysql_num_fields(MYSQL *mysql).

Descrição

Retorna o número de colunas para a consulta mais recente na conexão.

Normalmente esta função é utilizada quando mysql_store_result() retorna NULL (então você não possui um apontador para o resultado). Neste caso, você pode chamar mysql_field_count() para determinar se mysql_store_result() não produziu um resultado vazio. Isto permite que o programa cliente tome a ação aprpriada sem saber se a consulta foi uma instrução SELECT (ou do mesmo tipo). O exemplo mostrado aqui ilustra como isto pode ser feito.

See Seção 12.1.12.1, 'Porque Algumas Vezes mysql_store_result() Retorna NULL Após mysql_query() Returnar com Sucesso?'.

Valor Retornado

Um unsigned integer (inteiro sem sinal) representando o número de campo em um resultado.

Erros

Nenhum.

Exemplo

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;
if (mysql_query(&mysql,query_string))
{
 // error
}
else // query succeeded, process any data returned by it
{
 result = mysql_store_result(&mysql);
 if (result) // there are rows
 {
 num_fields = mysql_num_fields(result);
 // retrieve rows, then call mysql_free_result(result)
 }
 else // mysql_store_result() returned nothing; should it have?
 {
 if(mysql_field_count(&mysql) == 0)
 {
 // query does not return data
 // (it was not a SELECT)
 num_rows = mysql_affected_rows(&mysql);
 }
 else // mysql_store_result() should have returned data
 {
 fprintf(stderr, 'Error: %s\n', mysql_error(&mysql));
 }
 }
}

Uma alternativa é substituir a chamada mysql_field_count(&mysql) com mysql_errno(&mysql). Neste caso, você está verificando diretamente um erro de mysql_store_result() em vez de conferir o valor de mysql_field_count() se a instrução foi uma SELECT.

mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

Descrição

Define o cursor campo com o offset dado. A próxima chamada para mysql_fetch_field() irá recuperar a definição de campo da coluna associada com o offset.

Para buscar o inicio de um registro, passe zero como valor do offset.

Valor Retornado

O valor anterior do cursor de campo.

Erros

Nenhum.

mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

Descrição

Retorna a posição do cursos do campo usado pelo último mysql_fetch_field(). Este valor pode ser usado como um argumento para mysql_field_seek().

Valor Retornado

O offset atual do cursor de campo.

Erros

Nenhum.

mysql_free_result()

void mysql_free_result(MYSQL_RES *result)

Descrição

Libera a memória alocada para o resultado por mysql_store_result(), mysql_use_result(), mysql_list_dbs(), etc. Quando você finalizar o uso do resultado, você deve liberar a memória utilizada chamando mysql_free_result().

Valor Retornado

Nenhum.

Erros

Nenhum.

mysql_get_client_info()

char *mysql_get_client_info(void)

Descrição

Retorna uam string que representa a versão da biblioteca cliente.

Valor Retornado

Uma string representando a versão da biblioteca cliente do MariaDB.

Erros

Nenhum.

mysql_get_client_version()

unsigned long mysql_get_client_version(void)

Descrição

Retorna um inteiro que representa a versão da biblioteca cliente. O valor tem o formato XYYZZ onde X é a versão principal, YY é o nivel da distribuicão e ZZ é o número da versão dentro do nível da distribuição. Por exemplo, um valor de 40102 representa uma biblioteca cliente na versão 4.1.2.

Valores de Retorno

Um inteiro que representa a versão da biblioteca clientes do mysql.

Erros

Nenhum.

mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

Descrição

Retorna uma string descrevendo o tipo da conexão em uso, incluindo o nome da maquina servidora.

Valor Retornado

Uma string respresntando o nome da máquina servidora e o tipo de conexão.

Erros

Nenhum.

mysql_get_proto_info()

unsigned int mysql_get_proto_info(MYSQL *mysql)

Descrição

Retorna a versão do protocolo usado pela conexão atual.

Valor Retornado

Um unsigned integer (inteiro sem sinal) representando a versão do protocolo usado pela conexão atual.

Erros

Nenhum.

mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

Descrição

Retorna um string que representa o número da versão do servidor.

Valor Retornado

Um string representando o número da versão do servidor.

Erros

Nenhum.

mysql_get_server_version()

unsigned long mysql_get_server_version(MYSQL *mysql)

Descrição

Retorna o número de versão do servidor como um inteiro (novo na versão 4.1)

Valor Retornado

Um número que representa a versão do servidor MariaDB no formato:

versão_principal*10000 + versão_menor*100 + sub_versão

Por exemplo, 4.1.0 é retornado como 40100.

Ela é útil para determinar a versão do servidor rapidamente em um programa cliente para saber se algumas capacidades existem.

Erros

Nenhum.

mysql_info()

char *mysql_info(MYSQL *mysql)

Descrição

Retorna um string fornecendo informação sobre a consulta executada mais recentemente, mas apenas para as instruções listadas aqui. Para outras inastruções, mysql_info() retorna NULL. O formato da string varia dependendo do tipo de consulta, como descrito aqui. Os números são apenas ilustrativos; a string irá conter valores apropriados para a consulta.

Note que mysql_info() retorna um valor não-NULL para INSERT ... VALUES somente na forma de múltiplas linhas da instrução (isto é, apenas se uma lista com vários valores é especificada).

Valor Retornado

Uma string represntando informação adicional sobre a consulta executada mais recentemente. NULL se não houver nenhuma informação disponível para a consulta.

Erros

Nenhum.

mysql_init()

MYSQL *mysql_init(MYSQL *mysql)

Descrição

Aloca ou inicializa um objeto MariaDB apropriado para mysql_real_connect(). Se MariaDB é um ponteiro NULL, a função aloca, inicializa e retorna um novo objeto. Senão o objeto é inicializado e o endereço do objeto é retornado. Se mysql_init() aloca um novo objeto, ele será liberado quando mysql_close() for chamado para fechar a conexão.

Valor Retornado

Um handle MYSQL* inicializado. NULL se não houver memória suficiente para alocar o novo objeto.

Erros

Em caso de memória insuficiente, NULL é retornado.

mysql_insert_id()

my_ulonglong mysql_insert_id(MYSQL *mysql)

Descrição

Retorna o ID gerado para uma coluna AUTO_INCREMENT pela consulta anterior. Use esta função depois de ter realizado um consulta INSERT em uma tabela que contenha um campo AUTO_INCREMENT.

Note que mysql_insert_id() retorna 0 se a consulta anterior não gerar um valor AUTO_INCREMENT. Se você desejar salvar o valor para uso posterior, chame mysql_insert_id() imediatamente depois da consulta que gerou o valor.

Se a consulta anterior retornar um erro, o valor de mysql_insert_id() é indefinido.

mysql_insert_id() é atualizado depois de instruções INSERT e UPDATE que geram um valor AUTO_INCREMENT ou que definem um valor de coluna com LAST_INSERT_ID(expr). Leia 'Funções Diversas'.

Note também que o valor da função SQL LAST_INSERT_ID() sempre contém o o valor AUTO_INCREMENT gerado mais recentemente e não é zerado entre as consultas porque o valor desta função é mantido no servidor.

Valor Retornado

O valor do campo AUTO_INCREMENT que foi atualizado pela consulta anterior. Retorna zero se não houve consultas anteriores na conexão ou se a consulta não atualizou o valor AUTO_INCREMENT.

Erros

Nenhum.

mysql_kill()

int mysql_kill(MYSQL *mysql, unsigned long pid)

Descrição

Diz para o servidor matar um thread especificada pelo pid.

Valor Retornado

Zero em caso de sucesso. Diferente de zero se ocorrer um erro.

Erros

mysql_list_dbs()

MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)

Descrição

Retorna um resultado com nome de banco de dados no servidor que correspondem a uma expressão regular especificada pelo parâmetro wild. wild pode conter o meta caracteres '%' ou '_', ou pode ser um ponteiro NULL para coreesponder a todos os banco de dados. Chamar mysql_list_dbs() é o mesmo que executar a consulta SHOW databases [LIKE wild].

Você deve liberar o resultado com mysql_free_result().

Valor Retornado

Um conjunto de resultados MYSQL_RES no caso de sucesso. NULL se ocorrer um erro.

Erros

mysql_list_fields()

MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)

Descrição

Retorna um resultado contendo nomes de campos de uma tabela dada que correspondam a expressão regular especificada pelo parâmetro wild. wild pode conter os metacaracteres '%' ou '_', ou pode ser um ponteiro NULL para corresponder a todos os campos. Chamar mysql_list_fields() é o mesmo que executar a consulta SHOW COLUMNS FROM nome_tabela [LIKE wild].

Note que é recomendado que você use SHOW COLUMNS FROM nome_tabela em vez de mysql_list_fields().

Você deve liberar o resultado com mysql_free_result().

Valor Retornado

Um conjunto de resultados MYSQL_RES em caso de sucesso. NULL se ocorrer um erro.

Erros

mysql_list_processes()

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

Descrição

Retorna um resultado descrevendo a thread atual do servidor. É o mesmo tipo de informação relatado por mysqladmin processlist ou uma consulta SHOW PROCESSLIST.

Você deve liberar o resultado com mysql_free_result().

Valor Retornado

Um conjunto de resultados MYSQL_RES em caso de sucesso. NULL se ocorrer um erro.

Erros

mysql_list_tables()

MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)

Descrição

Retorna um resultado contendo nomes de tabelas no banco de dados atual que correspondam a expressão regular especificada pelo parâmetro wild. wild pode conter os mets caracteres '%' or '_', ou pode ser uma ponteiro NULL para corresponde a todas as tabelas. Chamar mysql_list_tables() é o mesmo que executar a consulta SHOW tables [LIKE wild].

Você deve liberar o resultado com mysql_free_result().

Valor Retornado

Um conjunto de resultados MYSQL_RES em caso de sucesso. NULL se ocorrer um erro.

Erros

mysql_num_fields()

unsigned int mysql_num_fields(MYSQL_RES *result)

ou

unsigned int mysql_num_fields(MYSQL *mysql)

A segunda forma não funciona na versão 3.22.24 ou mais novas do MariaDB. Para passar um argumento MYSQL* você de utilizar unsigned int mysql_field_count(MYSQL *mysql) em seu lugar.

Descrição

Retorna o número de colunas em um resultado.

Note que você pode obter o número de colunas com um ponteiro para o conjunto de resultados ou para um manipulador (handle) de conexão. Você usaria o manipular de conexão se mysql_store_result() ou mysql_use_result() retorna NULL (então você não tem um ponteiro para o resultado). Neste caso, você pode chamar mysql_field_count() para determinar se mysql_store_result() não produziu um resultado vazio. Isto permite que o programa cliente tome a ação apropriada sem saber se a consulta foi uma instrução SELECT (ou do tipo SELECT). O exemplo mostrado abaixo ilustra como isto pode ser feito.

See Seção 12.1.12.1, 'Porque Algumas Vezes mysql_store_result() Retorna NULL Após mysql_query() Returnar com Sucesso?'.

Valor Retornado

Um unsigned integer (inteiro sem sinal) representando o número de campos no conjunto de resultasdos.

Erros

Nenhum.

Exemplo

MYSQL_RES *result;
unsigned int num_fields;
unsigned int num_rows;
if (mysql_query(&mysql,query_string))
{
 // erro
}
else // query succeeded, process any data returned by it
{
 result = mysql_store_result(&mysql);
 if (result) // existem resgitros
 {
 num_fields = mysql_num_fields(result);
 // retorna registros e chama mysql_free_result(result)
 }
 else // mysql_store_result() retorna vazio; era esperado?
 {
 if (mysql_errno(&mysql))
 {
 fprintf(stderr, 'Error: %s\n', mysql_error(&mysql));
 }
 else if (mysql_field_count(&mysql) == 0)
 {
 // consulta não retora dados
 // (ela não era um SELECT)
 num_rows = mysql_affected_rows(&mysql);
 }
 }
}

Uma alternativa (se você souber qyue a sua consulta retornou um resultado) é substituir a chamada mysql_errno(&mysql) pela verificação de se mysql_field_count(&mysql) é = 0. Isto só acontece se alguma coisa der errado.

mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES *result)

Descrição

Retorna o número de linhas em um resultado.

O uso de mysql_num_rows() depende de se você utiliza mysql_store_result() ou mysql_use_result() para retornar o resultado. Se você usa mysql_store_result(), mysql_num_rows() pode ser chamado imediatamente. Se você usa mysql_use_result(), mysql_num_rows() não retornará o valor correto até que todas as linhas no resultado tenham sido recuperadas.

Valor Retornado

O número de linhas no resultado.

Erros

Nenhum.

mysql_options()

int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)

Descrição

Pode ser usado para definir opções extras de conexão e afetar o comportamento de uma conexão. Esta função pode ser chamada várias vezes para definir diversas opções.

mysql_options() deve ser chamado depois de mysql_init() e antes de mysql_connect() ou mysql_real_connect().

O argumento option é a opção que você que definir; o argumento arg é o valor para a opção. Se a opção é um inteiro, então arg deve apontar para o valor do inteiro.

Valores possíveis para as opções:

Opção Tipo de argumento Função
MYSQL_OPT_CONNECT_TIMEOUT unsigned int * Tempo limite de conexão em segundos.
MYSQL_OPT_COMPRESS Não usado Usa o protocolo cliente/servidor compactado.
MYSQL_OPT_READ_TIMEOUT unsigned int * Limite de tempo para a leitura do servidor (funciona atualmente apenas no Windows em conexões TCP/IP)
MYSQL_OPT_WRITE_TIMEOUT unsigned int * Limite de tempo para a escrita no servidor (funciona atualmente apenas no Windows em conexões TCP/IP)
MYSQL_OPT_LOCAL_INFILE ponteiro para unsigned integer opcional Se nenhum ponteiro for dado ou se apontar para um unsigned int != 0 o comando LOAD LOCAL INFILE está habilitado.
MYSQL_OPT_NAMED_PIPE Não usado Usa named pipes para conectar ao servidor MariaDB no NT.
MYSQL_INIT_COMMAND char * Comando para executar ao conectar ao servidor MySQL. Será automaticamente executado ao se reconectar.
MYSQL_READ_DEFAULT_FILE char * Lê opções do arquivo de opções definido no lugar de my.cnf.
MYSQL_READ_DEFAULT_GROUP char * Lê opções do grupo indicado no arquivo my.cnf ou no arquivo especificado com MYSQL_READ_DEFAULT_FILE.
MYSQL_OPT_PROTOCOL unsigned int * Tipo de protocolo usado. Deve ser um dos valores apresentados em mysql_protocol_type definido no mysql.h.
MYSQL_SHARED_MEMORY_BASE_NAME char* Nome do objeto em meória para comunicação com o servidor. Deve ser o mesmo que a opção -shared-memory-base-name usada para o servidor mysqld no qual você quer se conectar.

Note que o grupo client é sempre lido se você utiliza MYSQL_READ_DEFAULT_FILE ou MYSQL_READ_DEFAULT_GROUP.

O grupo especificado no arquivo de opçõs pode conter as seguintes opções:

Opção Descrição
connect-timeout Tempo limite de conexão em segundos. No Linux este tempo limite também é utilizado para esperar pela primeira resposta do servidor
compress Utiliza o protocolo cliente/servidor compactado.
database Conecta a este banco de dados se nenhum banco de dados for especificado no comando de conexão.
debug Opções de depuração.
disable-local-infile Disabilita o uso de LOAD DATA LOCAL.
host Nome de máquina padrão.
init-command Comando para executar ao conectar ao servidor MySQL. Será executado automaticamente ao reconectar.
interactive-timeout O mesmo que o especificado em CLIENT_INTERACTIVE para mysql_real_connect(). Leia Seção 12.1.3.43, 'mysql_real_connect()'.
local-infile[=(0|1)] Se não houver argumento ou o argumento for diferente de 0 habilita o uso de LOAD DATA LOCAL.
max_allowed_packet Tamanho máximo dos pacotes que o cliente pode ler do servidor.
password Senha padrão.
pipe Usa named pipes para conectar ao servidor MariaDB no NT.
protocol=(TCP | SOCKET | PIPE | MEMORY) Qual protocolo usar ao conectar no servidor (Novo na versão 4.1)
port Número padrão da porta.
return-found-rows Diz ao mysql_info() para retornar registros encontrados no lugar de registros atualizados ao usar UPDATE.
shared-memory-base-name=name Nome da memória comprtilhada utilizada para conectar ao servidor (o padrão é 'MySQL'). Novo na versão 4.1.
socket Número padrão do socket.
user Usuário padrão.

Note que timeout foi substituido por connect-timeout, mas timeout ainda funcionará por enquanto.

Para maiores informações sobre arquivos de opções, veja 'Arquivo de Opções my.cnf'.

Valor Retornado

Zero em caso de sucesso. Diferente de zero se você utilizar uma opção desconhecida.

Exemplo

MYSQL mysql;
mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,'odbc');
if (!mysql_real_connect(&mysql,'host','user','passwd','database',0,NULL,0))
{
 fprintf(stderr, 'Failed to connect to database: Error: %s\n',
 mysql_error(&mysql));
}

O exemplo acima diz ao cliente para usar o protocolo cliente/servidor compactado e ler a opção adicional da seção odbc no arquivo de opções my.cnf.

mysql_ping()

int mysql_ping(MYSQL *mysql)

Descrição

Verifica se a conexão ao servidor está funcionando. Se ela tiver caído é feita uma tentativa de conexão automaticamente.

Esta função pode ser usada pelos clientes que se ficam inativo por um longo tempo para verificar se o servidor fechou a conexão e reconectar se necessário.

Valor Retornado

Zero se o servidor estiver funcionando. Diferente de zero se ocorrer um erro.

Erros

mysql_query()

int mysql_query(MYSQL *mysql, const char *query)

Descrição

Executa uma consulta SQL apontada pela string terminada em null query. A consulta deve deve consistir de uma única instrução SQL. Você não deve adicionar ponto e vírgula (';') ou \g ao fim da instrução.

mysql_query() não pode ser usadas por consultas que contenham dados binários; você deve utilizar mysql_real_query() em seu lugar. (Dados binários podem conter o caracter '\0', que mysql_query() interpreta como o fim a string de consulta.)

Se você quiser saber se a consulta deve retornar um resultado ou não, você pode utilizar mysql_field_count() para verificar isto. Leia Seção 12.1.3.20, 'mysql_field_count()'.

Valor Retornado

Zero se a consulta obteve sucesso. Diferente de zero se ocorreu um erro.

Erros

mysql_real_connect()

MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)

Descrição

mysql_real_connect() tenta estabelecer uma conexão mecanismo MariaDB de banco de dados executando em host. mysql_real_connect() deve completar com suceeso antes que você possa executar qualquer um das outars funçãoes da API, com a excessão de mysql_get_client_info().

Os parâmetros são especificados da seguinte forma:

Valor Retornado

Um handle de conexão MYSQL* se a conexão foi obtida corretamente, NULL se a conexão falhou. Para um conexão estabelecida o valor de retorn é o mesmo que o valor do primeiro parâmetro.

Erros

Exemplo

MYSQL mysql;
mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,'seu_programa');
if (!mysql_real_connect(&mysql,'host','user','passwd','database',0,NULL,0))
{
 fprintf(stderr, 'Failed to connect to database: Error: %s\n',
 mysql_error(&mysql));
}

Usando mysql_options() a biblioteca MariaDB irá ler as seções [client] e [seu_programa] no arquivo my.cnf o qual irá assegurar que seu programa irá funcionar, mesmo se alguem tiver configurado o MariaDB de um modo fora do padrão.

Note que sob a conexão, mysql_real_connect() define o parâmetro reconnect (parte da estrutura MariaDB) para um valor de 1. Este parâmetro indica, no evento em que uma consulta não pode ser realizada devido a perda de conexão, para tentar se reconectar ao servidor antes de esgotar as tentativas.

mysql_real_escape_string()

unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)

Descrição

A função é usada para criar um string SQL válida que você pode usar em uma instrução SQL. Leia 'Strings'.

A string em from é codificada para uma string SQL com escape, levando em conta o conjunto de caracteres atual da conexãon. O resultado é colocada em to e uma byte nulo de terminção é adcionado. Caracteres codificados são NUL (ASCII 0), '\n', '\r', '\', ''', ''' e Control-Z (see 'Literais: Como Gravar Strings e Numerais'). (O MariaDB precisa que apenas a barra invertida e as aspas utilizadas para citar a consulta sejam escapadas. Esta função coloca os outros caracteres entre aspas para torná-lo mais fácil de ser lido em arquivos log.)

A string apontada por from deve ter o tamanho de length bytes. Você deve alocar o buffer to para o tamanho de pelo menos length*2+1 bytes. (No pior caso, cada caracter pode precisar de ser codificado como se utilizasse dois bytes, e você preciria de espaço para o byte null de terminação.) Quando mysql_real_escape_string() retornar, o conteúdo de to será uma string terminada em null. O valor é o tamanho da string codificada. não incluindo o caracter nulo usado para terminar a string.

Exemplo

char query[1000],*end;
end = strmov(query,'INSERT INTO test_table values(');
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,'What's this',11);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,'binary data: \0\r\n',16);
*end++ = '\'';
*end++ = ')';
if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
 fprintf(stderr, 'Failed to insert row, Error: %s\n',
 mysql_error(&mysql));
}

A função strmov() usada no exemplo está incluída na biblioteca mysqlclient e funciona como strcpy() mas retorna um ponteiro para null de terminação do primeiro parâmetro.

Valor Retornado

O tamanho do valor colocado em to, não incluindo o caracter null de terminação.

Erros

Nenhum.

mysql_real_query()

int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length)

Descrição

Executa a consulta SQL apontada por query, que deve ser uma string de length bytes. A consulta deve consistir de uma instrução SQL simples. Você não deve adicionar um ponto e virgula (';') ou \g no fim da instrução.

Você deve utilizar mysql_real_query() em lugar de mysql_query() para consultas que contenham dados binários, pois eles podem conter o caracter '\0'. Além disso, mysql_real_query() é mais rápido que mysql_query() pois ele não faz chamadas strlen() na string de consulta.

Se você quiser saber se a consulta retornou um resultado ou não, você pode usar mysql_field_count(). Leia Seção 12.1.3.20, 'mysql_field_count()'.

Valor Retornado

Zero se a consulta obteve sucesso. Deiferente de zero se ocorrer um erro.

Erros

mysql_reload()

int mysql_reload(MYSQL *mysql)

Descrição

Diz ao servidor MariaDB para recarregar a tabela de ables. The connected user must have the RELOAD privilege.

This function is deprecated. It is preferable to use mysql_query() to issue a SQL FLUSH PRIVILEGES statement instead.

Valor Retornado

Zero for success. Non-zero if an error occurred.

Erros

mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

Descrição

Atribui ao cursor de linha um registro arbitrário em resultado de uma consulta. O valor do offset é um offset do registro que deve ser um valor retornado de mysql_row_tell() ou mysql_row_seek(). Este valor não simplesmente um número de linha; se você quiser buscar um registro em um resultado usando o número de linha utilize mysql_data_seek().

Esta função exige que a estrutura do resultado contenha todo o resultado da consulta, assim mysql_row_seek() pode ser um usado em conjunto apenas com mysql_store_result(), e não com mysql_use_result().

Valor Retornado

O valor anterior do cursor de linha. Este valor pode ser passado a uma chamada subsequente mysql_row_seek().

Erros

Nenhum.

mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

Descrição

Retorna a posição atual do cursor de linha para a última mysql_fetch_row(). Este valor pode ser utilizado como argumento para mysql_row_seek().

Você deve utilizar mysql_row_tell() somente depois de mysql_store_result(), e não depois de mysql_use_result().

Valor Retornado

O offset atual do cursos de linha.

Erros

Nenhum.

mysql_select_db()

int mysql_select_db(MYSQL *mysql, const char *db)

Descrição

Faz com que o banco de dados espexcificado por db se torne o padrão (atual) na conexão especificada por MariaDB. Nas consultas seguintes este banco de dados é o padrão para tabelas que não incluem uma especificação explicita para o banco de dados.

mysql_select_db() falha a menos que o usuário conectado possa ser autenticado com permissão para utilizar o banco de dados.

Valor Retornado

Zero em caso de sucesso. Deiferente de zero se ocorrer um erro.

Erros

mysql_set_server_option()

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

Descrição

Habilita ou desabilita uma opção para a conexão. option por ter um dos seguintes valores:

MYSQL_OPTION_MULTI_STATEMENTS_ON Habilita suporte a multi instruções.
MYSQL_OPTION_MULTI_STATEMENTS_OFF Desabilita suporte a multi instruções.

Valores Retornados

Zero em caso de sucesso. Deiferente de zero se ocorrer um erro.

Erros

mysql_shutdown()

int mysql_shutdown(MYSQL *mysql)

Descrição

Diz ao servidor de banco de dados para finalizar. O usuário conectado deve ter privilégio SHUTDOWN.

Valor Retornado

Zero em caso de sucesso. Deiferente de zero se ocorrer um erro.

Erros

mysql_sqlstate()

const char *mysql_sqlstate(MYSQL *mysql)

Descrição

Retorna uma string terminada em null contendo o código de erro SQLSTATE para o último erro. O código de erro consiste de cinco caracteres. 00000 significa sem erros. Os valores são especificados pelo ANSI SQL e ODBC. Para uma lista de valores possíveis, veja Seção 13.1, 'Erros Retornados'.

Note que nem todos os erros já estão mapeados para SQLSTATE. O valor 'HY000' (erro geral) é usado para erros não mapeados.

Esta função foi adicionada ao MariaDB.

Valores Retornados

Uma string terminada em null contendo o código de erro SQLSTATE.

Veja Também

See Seção 12.1.3.12, 'mysql-errno()'. Leia Seção 12.1.3.13, 'mysql_error()'. Leia Seção 12.1.7.18, 'mysql_stmt_sqlstate()'.

mysql_ssl_set()

int mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)

Descrição

mysql_ssl_set() é usado para estabelecer conexão segura usando SSL. Ela deve ser chamada antes de mysql_real_connect().

mysql_ssl_set() não faz nada a mesno que o suporte OpenSSL esteja habilitado na biblioteca cliente.

MariaDB e o handler da conexão retornado de mysql_init(). Os outros parâmetros são especificados como a seguir:

Qualquer parâmetro SSL não utilizado pode ser dado com NULL.

Valores Retornados

Esta função sempre retorna 0. Se a configuração SSL está incorreta, mysql_real_connect() retornará um erro quando você tentar se conectar.

mysql_stat()

char *mysql_stat(MYSQL *mysql)

Descrição

Retorna uma string contendo informações sinmilares a aquelas fornecidas pelo comando mysqladmin status. Isto inclui o tempo de conexão em segundos e o número de threads em execução, recargas e tabelas abertas.

Valor Retornado

Uma string descrevendo o status do servidor. NULL se um erro ocorrer.

Erros

mysql_store_result()

MYSQL_RES *mysql_store_result(MYSQL *mysql)

Descrição

Você deve chamar mysql_store_result() ou mysql_use_result() para cada consulta que retorne dados corretamente (SELECT, SHOW, DESCRIBE, EXPLAIN).

Você não precisa chamar mysql_store_result() ou mysql_use_result() para outras consultas, mas ele não causará nenhum dano ou nenhuma queda notel de desempenho se você chamar mysql_store_result() em todos os casos. Você pode detectar se a consulta não obteve resultado verificando se mysql_store_result() retornou 0.

Se você quiser saber se a consulta devia retornar algum resultado, você pode utilizar mysql_field_count() para fazer a verificação. Leia Seção 12.1.3.20, 'mysql_field_count()'.

mysql_store_result() lê todo o resultado de uma consulta para um cliente, aloca uma estrutura MYSQL_RES e coloca o resultado nesta estrutura.

mysql_store_result() retorna um ponteiro para null se a consulta não retornar um resultado (se a consulta foi, por exemplo, uma instrução INSERT).

mysql_store_result() também retorna um ponterio para null se a leitura do resultado falhar. Você pode verficar se você obteve um erro verificando se mysql_error() não retornou um ponterio para null, se mysql_errno() retorna <> 0, ou se mysql_field_count() retorna <> 0.

Um resultado vazio é retornado se não houver registros a retornar. (Um resultado vazio é diferente de um ponteiro para null em um valor de retorno).

Uma vez que você tenha chamado mysql_store_result() e tenha retornado um resultado que não é uma apontador para null, você pode chamar mysql_num_rows() para descobrir quantas linhas existem no resultado.

Você pode chamar mysql_fetch_row() para buscar registros no resultado ou mysql_row_seek() e mysql_row_tell() para obter ou definir a poição atual do registro dentro do resultado.

Você deve chamar mysql_free_result() quando tiver terminado com o resultado.

See Seção 12.1.12.1, 'Porque Algumas Vezes mysql_store_result() Retorna NULL Após mysql_query() Returnar com Sucesso?'.

Valor Retornado

Uma estrutura de resultado MYSQL_RES com o resultado. NULL se um erro ocorreu.

Erros

mysql_store_result() zera mysql_error e mysql_errno se ela obter sucesso.

mysql_thread_id()

unsigned long mysql_thread_id(MYSQL *mysql)

Descrição

Retorna a ID da thread da conexão atual. Este valor pode ser usado como um argumento para mysql_kill() para finalizar a thread.

Se a conexão for perdida e você reconectar com mysql_ping(), a ID da thread irá alterar. Isto significa que você deve obter a ID da thread e guardá-la para uso posterior. Você deve obtê-la quando precisar dela.

Valor Retornado

A ID da thread da conexão atual.

Erros

Nenhum.

mysql_use_result()

MYSQL_RES *mysql_use_result(MYSQL *mysql)

Descrição

Você deve chamar mysql_store_result() ou mysql_use_result() para cada consulta que retornar data corretamente (SELECT, SHOW, DESCRIBE, EXPLAIN).

mysql_use_result() inicicia a recuperação de um resultado mas não lê realmente o resultado no cliente como mysql_store_result() faz. Cada regiostro deve ser recuperado individualmente fazendo chamadas a mysql_fetch_row(). Ele lê o resultado de uma consulta diretamente do servidor sem armazenar em uma tabela temporária ou em um buffer local, o o que é mais rápido e utiliza menos memória que mysql_store_result(). O cliente sío irá alocar memória para o registro atual para o buffer de comunicação que pode crescer para max_allowed_packet bytes.

Por outro lado , você não deve utilizar mysql_use_result() se você estiver fazendo vários processamentos para cada registros no lado do cliente, ou se a saída é enviada para a tela, na qual o usuário de digitar um ^S (parada de tela). Isto irá prender o servidor e impedir outras threads de atualizar qualquer tabela na qual o dados esteja sendo buascado.

Ao usar mysql_use_result(), você deve executar mysql_fetch_row() até um valor NULL ser retornado, senão, os registros não buscados retornarão como part do resultado de sua próxima consulta. A API C fornecerá o erro Commands out of sync; you can't run this command now se você esquecer de fazê-lo.

Você não pode utilizar mysql_data_seek(), mysql_row_seek(), mysql_row_tell(), mysql_num_rows(), ou mysql_affected_rows() com m resultado retornado de mysql_use_result(), nem pode executar outras consultas até que mysql_use_result() tenha finalizado. (No entanto, depois de buscar todos os regitros, mysql_num_rows() retornará corretamente o número de regiostros buscados).

Você deve chamar mysql_free_result() após terminar de utilizar o resultado.

Valor Retornado

Uma estrutura de resultado MYSQL_RES. NULL se ocorrer um erro.

Erros

mysql_use_result() zera mysql_error e mysql_errno se ela obter sucesso.

mysql_warning_count()

unsigned int mysql_warning_count(MYSQL *mysql)

Descrição

Retorna o número de avisos gerados durante a execução da instrução SQL anterior. Disponível a partir do MariaDB 4.1.

Valores de Retorno

A contagem de avisos.

Errors

Nenhum.

mysql_commit()

my_bool mysql_commit(MYSQL *mysql)

Descrição

Faz um commits na transação atual. Disponível no MariaDB 4.1

Valor Retornado

Zero em caso de sucesso. Deiferente de zero se ocorrer um erro.

Erros

Nenhum.

mysql_rollback()

my_bool mysql_rollback(MYSQL *mysql)

Descrição

Faz um rollback na transação atual. Disponível no MariaDB 4.1

Valor Retornado

Zero em caso de sucesso. Deiferente de zero se ocorrer um erro.

Erros

Nenhum.

mysql_autocommit()

my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

Descrição

Define o modo autocommit como ligado se mode é 1, desligado se mode é 0.

Valor Retornado

Zero em caso de sucesso. Deiferente de zero se ocorrer um erro.

Erros

Nenhum.

mysql_more_results()

my_bool mysql_more_results(MYSQL *mysql)

Descrição

Retorna verdade se mais resultados da consulta atualmente em execução existem, e a aplicação deve chamar mysql_next_result() para buscar os resultados. Disponível no MariaDB 4.1

Valor Retornado

TRUE (1) se existem mais resultados. FALSE (0) se não existem mais resultados.

Note que na maioria dos casos chama-se mysql_next_result() para se mais de um resultado existe e inicia o próximo resultado se ele existir.

See Seção 12.1.8, 'Tratando a Execução de Múltiplas Consultas na API C'. Leia Seção 12.1.3.63, 'mysql_next_result()'.

Erros

Nenhum.

mysql_next_result()

int mysql_next_result(MYSQL *mysql)

Descrição

Se existem mais resultados da consulta, mysql_next_result() lê o próximo resultado da consulta e retorna o status a aplicação. Disponível no MariaDB 4.1

Note que você deve chamar mysql_free_result() para a consulta anterior se ela retornar um resultado.

Depois de chamar mysql_next_result() o estado da conexão é como se tivesse chamado mysql_real_query() para a prima consulta. Isto significa que você agora pode chamar mysql_store_result(), mysql_warning_count(), mysql_affected_rows() ... na conexão.

Se mysql_next_result() retorna um erro, nenhuma outra instrução será executada e não haverá mais resultado para buscar.

See Seção 12.1.8, 'Tratando a Execução de Múltiplas Consultas na API C'.

Valor Retornado

0 em caso de sucesso e haver mais resultados. -1 se não houver mais resultados. > 0 se ocorrer um erro.

Erros

Instruções Preparadas da API C

A partir da versão 4.1 do MariaDB, o protocolo cliente/servidor fornece o uso de instruções preparadas. E capacidade utilizam estruturas de dados de tratamento de instruções MYSQL_STMT.

Execução preparada é um modo eficiente de executar uma instrução mais de uma vez. A instrução é primeiramente analizada para prepará-la para a execução. Então é executada uma ou mais vezes posteriormente, utilizando o manipulador de instruções retornado pela função preparada.

Execução preparada é mais rápida que a execução direta para instruções executadas mais que uma vez, pois a consulta é analizada apenas uma vez. No caso de execução direta , a consulta é analisada todas as vezes que ela é executada. Execução preparada também pode fornecer uma redução de tráfico de rede porque para cada execução das instruções preparadas, é necessário enviar dados apenas os parâmetros.

Outra vantagem de instruções preparadas é que ela utiliza um protocolo binário, que faz a transferência dos dados entre clinete e servidor de forma mais eficiente. Instruções preparadas também podem suportar ligação de entrada e saída com a execução de cnsultas múltiplas.

Tipos de Dados 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.

Instrução preparadas utilizam principalmente as estruturas de dados MYSQL_STMT e MYSQL_BIND seguintes. Uma terceira estrutura, MYSQL_TIME, é usada para tranferir dados temporais.

A seguinte tabela mostra os valores permitidos que podem ser especificados no membro buffer_type da estrutura MYSQL_BIND. A tabela também mostra aqueles tipos SQL que correspondem mais proximamente a cada valor buffer_type, e, para tipos numéricos e temporais, o tipo C correspondente.

buffer_type Valor Tipo SQL Tipo C
MYSQL_TYPE_TINY TINYINT char
MYSQL_TYPE_SHORT SMALLINT short int
MYSQL_TYPE_LONG INT long int
MYSQL_TYPE_LONGLONG BIGINT long long int
MYSQL_TYPE_FLOAT FLOAT float
MYSQL_TYPE_DOUBLE DOUBLE double
MYSQL_TYPE_TIME TIME MYSQL_TIME
MYSQL_TYPE_DATE DATE MYSQL_TIME
MYSQL_TYPE_DATETIME DATETIME MYSQL_TIME
MYSQL_TYPE_TIMESTAMP TIMESTAMP MYSQL_TIME
MYSQL_TYPE_STRING CHAR
MYSQL_TYPE_VAR_STRING VARCHAR
MYSQL_TYPE_TINY_BLOB TINYBLOB/TINYTEXT
MYSQL_TYPE_BLOB BLOB/TEXT
MYSQL_TYPE_MEDIUM_BLOB MEDIUMBLOB/MEDIUMTEXT
MYSQL_TYPE_LONG_BLOB LONGBLOB/LONGTEXT

Uma conversão de tipo implcita pode ser realizada em ambas as direções.

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 Seçã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 MariaDB realiza as seguintes ações:

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

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

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.

Descrição das Funções de Instrução Preparada da API C

mysql_prepare()
mysql_param_count()
mysql_get_metadata()
mysql_bind_param()
mysql_execute()
mysql_stmt_affected_rows()
mysql_bind_result()
mysql_stmt_store_result()
mysql_stmt_data_seek()
mysql_stmt_row_seek()
mysql_stmt_row_tell()
mysql_stmt_num_rows()
mysql_fetch()
mysql_send_long_data()
mysql_stmt_close()
mysql_stmt_errno()
mysql_stmt_error()
mysql_stmt_sqlstate()

Para preparar e executar consultas use as seguites funçoes.

mysql_prepare()

MYSQL_STMT * mysql_prepare(MYSQL *mysql, const char *query, unsigned long length)

Descrição

Prepara a consulta SQL apontada pela string com terminação em nulo query, e retorna um handle da instrução para ser usado por operações adicionais na instrução. A consulta deve consistir de uma única instrução SQL. Você não deve adicionar ponto e virgula (';') ou \g a instrução.

A aplicação pode incluir um ou mais marcadores de parâmetro na instrução SQL, embutindo interrogações ('?') na string SQL na posição aprpriada.

Os marcadores só são válidos em certos lugares na instrução SQL. Por exemplo, eles não são permitidos em lista VALUES() de uma instrução INSERT (para especificar valores para uma linha ou em uma comparação com uma coluna em uma cláusula WHERE para especificar uma valor de comparação. No entanto, eles não são permitidos como identificadores (tais como nomes de colunas ou tabelas), na lista select que indica as colunas a serem retornadas por uma instrução SELECT), ou para especificar ambos operandos de um operador binário como o sinal de igual =. A última restrição é necessária porque seria impossível determinar o tipo do parâmetro. Em geral, parâmetros são válidos somente em instrução de Linguagem de Manipulação de Dados (Data Manipulation Languange-DML), e não em instruções de Linguagem de Definição de Dados (Data Defination Language-DDL).

Os marcadores de parâmetro devem limitar variáveis de aplicações utilizando mysql_bind_param() antes de executar a instrução.

Valor Retornado

Um ponteiro para uma estrutura MYSQL_STMT se o preparo obteve sucesso. NULL se ocorreu um erro.

Erros

Se o preparo não obteve sucesso (isto é, mysql_prepare() retorna um ponteiro NULL), as mensagens de erros podem ser obtidas chamando mysql_error().

Exemplo

Para o uso de mysql_prepare() consulte o exemplo de Seção 12.1.7.5, 'mysql_execute()'.

mysql_param_count()

unsigned long mysql_param_count(MYSQL_STMT *stmt)

Descrição

Retorna o número de marcadores de parâmetros presentes na consulta preparada.

Valor Retornado

Um unsigned long (inteiro sem sinal) representando o número de parâmetros em uma instrução.

Erros

Nenhum.

Exemplo

Para utilizar mysql_param_count() consulte o exemplo de Seção 12.1.7.5, 'mysql_execute()'.

mysql_get_metadata()

MYSQL_RES *mysql_get_metadata(MYSQL_STMT *stmt)

Descrição

Se uma instrução passada para mysql_prepare() rproduziu um resultado, mysql_get_metadata() retorna o resultado dos meta dados na forma de um ponteiro para uma estrutura MYSQL_RES que também pode ser usada para processar a meta informação como o número total de campos e informação de campos indivíduais. Este ponteriro para o resultado pode ser passado como um argumento para qualquer um dos campos com base na API que processam o resultado dos metadados, como:

A estrutura do resultado deve estar liberada quando você acabar de usá-lo. Você pode fazê-lo passando para mysql_free_result(). É semelhante ao modo que você libera um resulatdo chamado com mysql_store_result().

O resultado retornado por mysql_get_metadata() contém apenas metadados. Ele não contém qualquer resultado de registro. As linhas são obtidas usando o handle de instrução com mysql_fetch().

Valor Retornado

Uma estrutura de resultado MYSQL_RES. NULL se nenhuma meta informação existe para a consulta preparada.

Erros

Exemplo

Para utilizar mysql_get_metadata() consulte o exemplo de Seção 12.1.7.13, 'mysql_fetch()'

mysql_bind_param()

my_bool mysql_bind_param(MYSQL_STMT *stmt, MYSQL_BIND *bind)

Descrição

mysql_bind_param() é utilizado para ligar dados para os marcadores de parâmetros na instrução SQL que foi passada para mysql_prepare(). Ele utiliza a estrutura MYSQL_BIND para fornecer os dados. bind é o endereço de um vetor de estruturas MYSQL_BIND. A biblioteca cliente espera que o vetor deve contenha um elemento para cada marcador de parâmetro ? que está presente na consulta.

Suponha que você prepare a seguinte instrução:

INSERT INTO mytbl VALUES(?,?,?)

Quando você ligar os parâmetros, o vetor da estrutura MYSQL_BIND deve conter três elementos e pode estar declarado assim:

MYSQL_BIND bind[3];

O membro de cada elemento MYSQL_BIND que deve estar configurado está descrito em Seção 12.1.5, 'Tipos de Dados de Instruções Preparadas da API C'.

Valor Retornado

Zeros se a ligação foi obtida corretamente. Diferente de zero se ocorrer um erro.

Erros

Exemplo

Para utilizar mysql_bind_param() consulte o exemplo de Seção 12.1.7.5, 'mysql_execute()'.

mysql_execute()

int mysql_execute(MYSQL_STMT *stmt).

Descrição

mysql_execute() executa a consulta preparada associada ao controlador de instruções. O valor atual do marcador de parâmetros é enviado para o servidor durante esta chamada, e o servidor substituir marcadores com os novos dados fornecidos.

Se a instrução é um UPDATE, DELETE ou INSERT, o número total de registros altrados, deletados ou inseridos pode ser encontrado chamando mysql_stmt_affected_rows(). Se este é um resultado de uma consulta como SELECT, deve se chamar mysql_fetch() para buscar dados previamente para fazer qualquer outra função que resulte em um processamento de consulta. Para mais informações sobre como buscar os resultados, consulte Seção 12.1.7.13, 'mysql_fetch()'

Valor Retornado

Zero se a execução obteve sicesso. Diferente de zero se ocorreu um erro. O código de erro e a mensagem podem ser obtidas chamando mysql_stmt_errno() e mysql_stmt_error().

Erros

Exemplo

O seguinte exemplo demonstra como criar e preencher uma tabela usando mysql_prepare(), mysql_param_count(), mysql_bind_param(), mysql_execute() e mysql_stmt_affected_rows(). A variável MariaDB é considerada como um controlador de conexão válido.

#define STRING_SIZE 50
#define DROP_SAMPLE_TABLE 'DROP TABLE IF EXISTS test_table'
#define CREATE_SAMPLE_TABLE 'CREATE TABLE test_table(col1 INT,\
 col2 VARCHAR(40),\
 col3 SMALLINT,\
 col4 TIMESTAMP)'
#define INSERT_SAMPLE 'INSERT INTO test_table(col1,col2,col3) VALUES(?,?,?)'
MYSQL_STMT *stmt;
MYSQL_BIND bind[3];
my_ulonglong affected_rows;
int param_count;
short small_data;
int int_data;
char str_data[STRING_SIZE];
unsigned long str_length;
my_bool is_null;
if (mysql_query(mysql, DROP_SAMPLE_TABLE))
{
 fprintf(stderr, ' DROP TABLE failed\n');
 fprintf(stderr, ' %s\n', mysql_error(mysql));
 exit(0);
}
if (mysql_query(mysql, CREATE_SAMPLE_TABLE))
{
 fprintf(stderr, ' CREATE TABLE failed\n');
 fprintf(stderr, ' %s\n', mysql_error(mysql));
 exit(0);
}
/* Prepare an INSERT query with 3 parameters */
/* (the TIMESTAMP column is not named; it will */
/* be set to the current date and time) */
stmt = mysql_prepare(mysql, INSERT_SAMPLE, strlen(INSERT_SAMPLE));
if (!stmt)
{
 fprintf(stderr, ' mysql_prepare(), INSERT failed\n');
 fprintf(stderr, ' %s\n', mysql_error(mysql));
 exit(0);
}
fprintf(stdout, ' prepare, INSERT successful\n');
/* Get the parameter count from the statement */
param_count= mysql_param_count(stmt);
fprintf(stdout, ' total parameters in INSERT: %d\n', param_count);
if (param_count != 3) /* validate parameter count */
{
 fprintf(stderr, ' invalid parameter count returned by MySQL\n');
 exit(0);
}
/* Bind the data for all 3 parameters */
/* INTEGER PARAM */
/* This is a number type, so there is no need to specify buffer_length */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&int_data;
bind[0].is_null= 0;
bind[0].length= 0;
/* STRING PARAM */
bind[1].buffer_type= MYSQL_TYPE_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= 0;
bind[1].length= &str_length;
/* SMALLINT PARAM */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&small_data;
bind[2].is_null= &is_null;
bind[2].length= 0;
/* Bind the buffers */
if (mysql_bind_param(stmt, bind))
{
 fprintf(stderr, ' mysql_bind_param() failed\n');
 fprintf(stderr, ' %s\n', mysql_stmt_error(stmt));
 exit(0);
}
/* Specify the data values for the first row */
int_data= 10; /* integer */
strncpy(str_data, 'MySQL', STRING_SIZE); /* string */
str_length= strlen(str_data);
/* INSERT SMALLINT data as NULL */
is_null= 1;
/* Execute the INSERT statement - 1*/
if (mysql_execute(stmt))
{
 fprintf(stderr, ' mysql_execute(), 1 failed\n');
 fprintf(stderr, ' %s\n', mysql_stmt_error(stmt));
 exit(0);
}
/* Get the total number of affected rows */
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, ' total affected rows(insert 1): %ld\n', affected_rows);
if (affected_rows != 1) /* validate affected rows */
{
 fprintf(stderr, ' invalid affected rows by MySQL\n');
 exit(0);
}
/* Specify data values for second row, then re-execute the statement */
int_data= 1000;
strncpy(str_data, 'The most popular open source database', STRING_SIZE);
str_length= strlen(str_data);
small_data= 1000; /* smallint */
is_null= 0; /* reset */
/* Execute the INSERT statement - 2*/
if (mysql_execute(stmt))
{
 fprintf(stderr, ' mysql_execute, 2 failed\n');
 fprintf(stderr, ' %s\n', mysql_stmt_error(stmt));
 exit(0);
}
/* Get the total rows affected */
affected_rows= mysql_stmt_affected_rows(stmt);
fprintf(stdout, ' total affected rows(insert 2): %ld\n', affected_rows);
if (affected_rows != 1) /* validate affected rows */
{
 fprintf(stderr, ' invalid affected rows by MySQL\n');
 exit(0);
}
/* Close the statement */
if (mysql_stmt_close(stmt))
{
 fprintf(stderr, ' failed while closing the statement\n');
 fprintf(stderr, ' %s\n', mysql_stmt_error(stmt));
 exit(0);
}

Nota: Para exemplos completos do uso das funções de instruções preparadas, veja tests/mysql_client_test.c. Este arquivo pode ser obtido em uma distribuição fonte ou do repositório do Bitkeeper.

mysql_stmt_affected_rows()

my_ulonglong mysql_stmt_affected_rows(MYSQL_STMT *stmt)

Descrição

Retorna o número total de registros alterados, deletados ou inseridos pela última instrução executada. Pode ser chamada imediatamente depois de mysql_execute() para instruções UPDATE, DELETE ou INSERT. Para instruções SELECT, mysql_stmt_affected_rows() funciona como mysql_num_rows().

Valor Retornado

Um integer (inteiro) maior que zero indica o número de registros afetados ou retornados. Zero indica que nenhum registro foi atualizado em uma instrução UPDATE, nenhum regitro coincidiu com a cláusula WHERE na consulta ou que nenhuma consulta foi exeutada ainda. −1 indica que a consulta retornou um erro ou que, para uma consulta SELECT, mysql_stmt_affected_rows() foi chamado antes de chamra mysql_fetch().

Erros

Nenhum.

Exemplo

Para utilizar mysql_stmt_affected_rows() consulte o exemplo de Seção 12.1.7.5, 'mysql_execute()'.

mysql_bind_result()

my_bool mysql_bind_result(MYSQL_STMT *stmt, MYSQL_BIND *bind)

Descrição

mysql_bind_result() é usado para associar (ligar) colunas no resultados ao buffer de dados e buffer de tamanho. Quando mysql_fetch() é chamado para buscar dados, o protocolo cliente/servidor MariaDB os coloca os dados para as colunas limite no buffer especificado.

Note que todas as colunas devem ser limitadas por buffers antes da chamada de mysql_fetch(). bind é o endereço de um vetor de estruturas MYSQL_BIND. A biblioteca cliente espera que o vetor contenha um elemento para cada coluna no resultado. Senão mysql_fetch() simplesmente ignorado os dados trazidos; os buffers devem se suficientemente grande para guardar os dados, porque o protocolo não retorna dados em blocos.

Uma coluna pode ser limitada a qualquer hora, mesmo depois do resultado ter sido parcialmente recuperado. A nova ligação tem efeito ba próxima vez em que mysql_fetch() é chamado. Suponha que uma aplicação liga a coluna em um resultado e chama mysql_fetch(). O protocolo cliente/servidor retorna dados em buffers limitados. Agora suponha que a aplicação ligue a coluna a um diferente cojunto de buffers, então o protocolo não coloca os dados em um novo buffer limitado até que a próxima chamada mysql_fetch() ocorra.

Para ligar uma coluna, uma aplicação chama mysql_bind_result() e passa o tipo, o endereço e o endereço do buffer do tamanho. Os membros de cada elemento MYSQL_BIND que deve ser configurado estão descritos em Seção 12.1.5, 'Tipos de Dados de Instruções Preparadas da API C'.

Valor Retornado

Zero se a ligação obteve sucesso. Diferente de zero se ocorreu um erro.

Erros

Exemplo

Para utilizar mysql_bind_result() consulta o exemplo de Seção 12.1.7.13, 'mysql_fetch()'

mysql_stmt_store_result()

int mysql_stmt_store_result(MYSQL_STMT *stmt)

Descrição

Você deve chamar mysql_stmt_store_result() para cada consulta que produz um resultado corretamente (SELECT,SHOW,DESCRIBE, EXPLAIN), e só se você quiser armazenar todo o resultado no buffer no cliente, assim que a chamada mysql_fetch() subsequente retornar os dados em buffers.

Você é necessário chamar mysql_stmt_store_result() para outras consultas, mas se você o fizer, não causará nenhum dano ou queda de performance em todo caso. Você pode detectar se a consulta produziu um resultado verificado se mysql_get_metadata() retorna NULL. Para mais informações consulte Seção 12.1.7.3, 'mysql_get_metadata()'.

Valor Retornado

Zero se o resultado foi armazenado em buffer corretamente ou Diferente de zero em caso de erro.

Erros

mysql_stmt_data_seek()

void mysql_stmt_data_seek(MYSQL_STMT *stmt, my_ulonglong offset)

Descrição

Busca um registro arbitrário no resultado de uma instrução. O valor do offset é um número de registro e deve estar na faixa de 0 a mysql_stmt_num_rows(stmt)-1.

Esta função exige que a estrutura do resultado da instrução contenha todo o resultado da última consulta executada, assim mysql_stmt_data_seek() pode ser usada em conjunto apenas com mysql_stmt_store_result().

Valor Retornado

Nenhum.

Erros

Nenhum.

mysql_stmt_row_seek()

MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT *stmt, MYSQL_ROW_OFFSET offset)

Descrição

Define o cursor de linha com um registro arbitrário em um resultado de instrução. O valor do offset é um offset de registro e deve ser um valor retornado de mysql_stmt_row_tell() ou mysql_stmt_row_seek(). Este valor não é um número de linha; se você quiser buscar um registro em um resultado usando um número de linha, utilize mysql_stmt_data_seek().

Esta função exige que a estrutura do resultado contenha todo o resultado da consulta, assim mysql_stmt_row_seek() pode ser usado em conjunto apenas com mysql_stmt_store_result().

Valor Retornado

O valor anterior do cursor de linha. Este valor pode ser passado a uma chamada subsequente de mysql_stmt_row_seek().

Erros

Nenhum.

mysql_stmt_row_tell()

MYSQL_ROW_OFFSET mysql_stmt_row_tell(MYSQL_STMT *stmt)

Descrição

Retorna a posição corrente do cursor de linha para o último mysql_fetch(). Este valor pode ser usado como um argumento para mysql_stmt_row_seek().

Você deve usar mysql_stmt_row_tell() somente depois de mysql_stmt_store_result().

Valor Retornado

O offset atual do cursor de linha.

Erros

Nenhum.

mysql_stmt_num_rows()

my_ulonglong mysql_stmt_num_rows(MYSQL_STMT *stmt)

Descrição

Rertorna o número de registros no resultado.

O uso de mysql_stmt_num_rows() depende de se você utilizou ou não mysql_stmt_store_result() para armazenar todo o resultado no manipulador de instruções.

Se você utilizou mysql_stmt_store_result(), mysql_stmt_num_rows() pode ser chamado imediatamente.

Valor Retornado

O número de linhas no resultado.

Erros

Nenhum.

mysql_fetch()

int mysql_fetch(MYSQL_STMT *stmt)

Descrição

mysql_fetch() retorna o próximo registro no resultado. Ele pode ser chamado apenas enquanto existir o conjunto de resultados. Per exemplo, depois de uma chamada de mysql_execute() que cria o resultado ou depois de mysql_stmt_store_result(), que é chamado depois de mysql_execute() para armazenar todo o resultado.

mysql_fetch retorna os dados de uma linha usando o buffers limitado por mysql_bind_result(). Ele retorna os dados neste buffer para todas as colunas no registro atual e os tamanhos são retornados para o apontador length.

Note que, todas as colunas devem ser limitadas pela aplicação antes de chamar mysql_fetch().

Se um valor do dado buscado é um valor NULL, o valor *is_null da estrutura MYSQL_BIND correspondente contém VERDADEIRO (1). Senão, o dado e seu tamanho é retornado nos elementos *buffer e *length baseados no tipo de buffer especificado pela aplicação. Cada tipo numérico e temporal tem um tamanho fixo como mostrado na tabela a seguir. O tamano dos tipos strings dependem do tasmanho do valor dos dados atual, como indicado por data_length.

Type Length
MYSQL_TYPE_TINY 1
MYSQL_TYPE_SHORT 2
MYSQL_TYPE_LONG 4
MYSQL_TYPE_LONGLONG 8
MYSQL_TYPE_FLOAT 4
MYSQL_TYPE_DOUBLE 8
MYSQL_TYPE_TIME sizeof(MYSQL_TIME)
MYSQL_TYPE_DATE sizeof(MYSQL_TIME)
MYSQL_TYPE_DATETIME sizeof(MYSQL_TIME)
MYSQL_TYPE_STRING tam_dado
MYSQL_TYPE_BLOB tam_dado

Valor Retornado

Valor retornado Descrição
0 Sucesso, o dado foi buscado para o buffers de dados da aplicação.
1 Ocorreu um erro. O código e a mensagem de erro podem ser obtidos chamando mysql_stmt_errno() e mysql_stmt_error().
MYSQL_NO_DATA Não existem mais registros/dados

Erros

Exemplo

O seguinte exemplo demonstra como buscar dados de uma tabela usando mysql_get_metadata(), mysql_bind_result() e mysql_fetch(). (Este exemplo espera recuperar as duas linahs inseridas pelo exemplo mostrado em Seção 12.1.7.5, 'mysql_execute()'.) A variável MariaDB çonsiderada como um handle de conexão válido handle.

#define STRING_SIZE 50
#define SELECT_SAMPLE 'SELECT col1, col2, col3, col4 FROM test_table'
MYSQL_STMT *stmt;
MYSQL_BIND bind[4];
MYSQL_RES *prepare_meta_result;
MYSQL_TIME ts;
unsigned long length[4];
int param_count, column_count, row_count;
short small_data;
int int_data;
char str_data[STRING_SIZE];
my_bool is_null[4];
/*
 Sample which is incorporated directly in the manual under Prepared
 statements section (Example from mysql_fetch()
*/
/* Prepare a SELECT query to fetch data from test_table */
stmt = mysql_prepare(mysql, SELECT_SAMPLE, strlen(SELECT_SAMPLE));
if (!stmt)
{
 fprintf(stderr, ' mysql_prepare(), SELECT failed\n');
 fprintf(stderr, ' %s\n', mysql_error(mysql));
 exit(0);
}
fprintf(stdout, ' prepare, SELECT successful\n');
/* Get the parameter count from the statement */
param_count= mysql_param_count(stmt);
fprintf(stdout, ' total parameters in SELECT: %d\n', param_count);
if (param_count != 0) /* validate parameter count */
{
 fprintf(stderr, ' invalid parameter count returned by MySQL\n');
 exit(0);
}
/* Fetch result set meta information */
prepare_meta_result = mysql_get_metadata(stmt);
if (!prepare_meta_result)
{
 fprintf(stderr, ' mysql_get_metadata(), returned no meta information\n');
 fprintf(stderr, ' %s\n', mysql_stmt_error(stmt));
 exit(0);
}
/* Get total columns in the query */
column_count= mysql_num_fields(prepare_meta_result);
fprintf(stdout, ' total columns in SELECT statement: %d\n', column_count);
if (column_count != 4) /* validate column count */
{
 fprintf(stderr, ' invalid column count returned by MySQL\n');
 exit(0);
}
/* Execute the SELECT query */
if (mysql_execute(stmt))
{
 fprintf(stderr, ' mysql_execute(), failed\n');
 fprintf(stderr, ' %s\n', mysql_stmt_error(stmt));
 exit(0);
}
/* Bind the result buffers for all 3 columns before fetching them */
/* INTEGER COLUMN */
bind[0].buffer_type= MYSQL_TYPE_LONG;
bind[0].buffer= (char *)&int_data;
bind[0].is_null= &is_null[0];
bind[0].length= &length[0];
/* STRING COLUMN */
bind[1].buffer_type= MYSQL_TYPE_STRING;
bind[1].buffer= (char *)str_data;
bind[1].buffer_length= STRING_SIZE;
bind[1].is_null= &is_null[1];
bind[1].length= &length[1];
/* SMALLINT COLUMN */
bind[2].buffer_type= MYSQL_TYPE_SHORT;
bind[2].buffer= (char *)&small_data;
bind[2].is_null= &is_null[2];
bind[2].length= &length[2];
/* TIMESTAMP COLUMN */
bind[3].buffer_type= MYSQL_TYPE_TIMESTAMP;
bind[3].buffer= (char *)&ts;
bind[3].is_null= &is_null[3];
bind[3].length= &length[3];
/* Bind the result buffers */
if (mysql_bind_result(stmt, bind))
{
 fprintf(stderr, ' mysql_bind_result() failed\n');
 fprintf(stderr, ' %s\n', mysql_stmt_error(stmt));
 exit(0);
}
/* Now buffer all results to client */
if (mysql_stmt_store_result(stmt))
{
 fprintf(stderr, ' mysql_stmt_store_result() failed\n');
 fprintf(stderr, ' %s\n', mysql_stmt_error(stmt));
 exit(0);
}
/* Fetch all rows */
row_count= 0;
fprintf(stdout, 'Fetching results ...\n');
while (!mysql_fetch(stmt))
{
 row_count++;
 fprintf(stdout, ' row %d\n', row_count);
 /* column 1 */
 fprintf(stdout, ' column1 (integer) : ');
 if (is_null[0])
 fprintf(stdout, ' NULL\n');
 else
 fprintf(stdout, ' %d(%ld)\n', int_data, length[0]);
 /* column 2 */
 fprintf(stdout, ' column2 (string) : ');
 if (is_null[1])
 fprintf(stdout, ' NULL\n');
 else
 fprintf(stdout, ' %s(%ld)\n', str_data, length[1]);
 /* column 3 */
 fprintf(stdout, ' column3 (smallint) : ');
 if (is_null[2])
 fprintf(stdout, ' NULL\n');
 else
 fprintf(stdout, ' %d(%ld)\n', small_data, length[2]);
 /* column 4 */
 fprintf(stdout, ' column4 (timestamp): ');
 if (is_null[3])
 fprintf(stdout, ' NULL\n');
 else
 fprintf(stdout, ' %04d-%02d-%02d %02d:%02d:%02d (%ld)\n',
 ts.year, ts.month, ts.day,
 ts.hour, ts.minute, ts.second,
 length[3]);
 fprintf(stdout, '\n');
}
/* Validate rows fetched */
fprintf(stdout, ' total rows fetched: %d\n', row_count);
if (row_count != 2)
{
 fprintf(stderr, ' MariaDB failed to return all rows\n');
 exit(0);
}
/* Free the prepared result metadata */
mysql_free_result(prepare_meta_result);
/* Close the statement */
if (mysql_stmt_close(stmt))
{
 fprintf(stderr, ' failed while closing the statement\n');
 fprintf(stderr, ' %s\n', mysql_stmt_error(stmt));
 exit(0);
}

mysql_send_long_data()

my_bool mysql_send_long_data(MYSQL_STMT *stmt, unsigned int parameter_number, const char *data, ulong length)

Descrição

Permite que um aplicação envie os dados dos parâmetros para o servidor em partes (ou blocos). Esta função pode ser chamada várias vezes parar enviar partes de valores de dados binários e caracteres para uma coluna, que deve do tipo TEXT ou BLOB.

parameter_number indica a qual parâmetro o dado é associado. Os parâmetros são numerados começando com 0. data é um ponteiro para um buffer contendo dados a serem enviados, e length indica a quantidade de bytes no buffer.

Valor Retornado

Zero se os dados são enviados corretamente para o servidir. Diferente de zero se ocorrer um erro.

Erros

Example

O exemplo seguinte demonstra como enviar os dados para um coluna do tipo TEXT em blocos. Ele insere o dado MySQL - The most popular open source database na coluna text_column. A variável MariaDB é considerada como um handle de conexão válido.

#define INSERT_QUERY 'INSERT INTO test_long_data(text_column) VALUES(?)'
MYSQL_BIND bind[1];
long length;
if (!mysql_prepare(mysql, INSERT_QUERY, strlen(INSERT_QUERY))
{
 fprintf(stderr, '\n prepare failed');
 fprintf(stderr, '\n %s', mysql_error(mysql));
 exit(0);
}
 memset(bind, 0, sizeof(bind));
 bind[0].buffer_type= MYSQL_TYPE_STRING;
 bind[0].length= &length;
 bind[0].is_null= 0;
 /* Bind the buffers */
 if (mysql_bind_param(stmt, bind))
 {
 fprintf(stderr, '\n param bind failed');
 fprintf(stderr, '\n %s', mysql_stmt_error(stmt));
 exit(0);
 }
 /* Supply data in chunks to server */
 if (!mysql_send_long_data(stmt,0,'MySQL',5))
 {
 fprintf(stderr, '\n send_long_data failed');
 fprintf(stderr, '\n %s', mysql_stmt_error(stmt));
 exit(0);
 }
 /* Supply the next piece of data */
 if (mysql_send_long_data(stmt,0,' - The most popular open source database',40))
 {
 fprintf(stderr, '\n send_long_data failed');
 fprintf(stderr, '\n %s', mysql_stmt_error(stmt));
 exit(0);
 }
 /* Now, execute the query */
 if (mysql_execute(stmt))
 {
 fprintf(stderr, '\n mysql_execute failed');
 fprintf(stderr, '\n %s', mysql_stmt_error(stmt));
 exit(0);
 }

mysql_stmt_close()

my_bool mysql_stmt_close(MYSQL_STMT *)

Descrição

Fecha a instrução preparada. mysql_stmt_close() também desaloca o manipulador de instruções apontado por stmt.

Se a instrução atual tiver resultados pendentes ou não lidos, esta função os cancela para que a próxima consulta possa ser executada.

Valor Retornado

Zero se a instrução for liberada corretamente. Diferente de zero se ocorrer um erro.

Erros

Exemplo

Para utilizar mysql_stmt_close() consulte o exemplo de Seção 12.1.7.5, 'mysql_execute()'.

mysql_stmt_errno()

unsigned int mysql_stmt_errno(MYSQL_STMT *stmt)

Descrição

Para a instrução especificada por stmt, mysql_stmt_errno() retorna o código de erro para a função de instruções da API chamada mais recentemente. Um valor de retorno de zero significa que não ocorreu nenhum erro. Números de mensagens de erro do cliente estão listadas no arquivo cabeçlho errmsg.h do MariaDB. Números de mensagens de erro do servidor estão listado no arquivo mysqld_error.h. Na distribuição fonte do MariaDB você pode encontrar uma lista completa de mensagens de erros e número de erros no arquivo Docs/mysqld_error.txt. Os códigos de erros do servidor também estão listados em Seção 13.1, 'Erros Retornados'.

Valor Retornado

Um valor de código de erro. Zero se não ocorreu erro.

Erros

Nenhum

mysql_stmt_error()

const char *mysql_stmt_error(MYSQL_STMT *stmt)

Descrição

Para a instrução especificada por stmt, mysql_stmt_error() retorna uma string terminada em null contendo a mensagem de erro para a função de instrução da API chamada mais recentemente. Um string vazia ('') é retornado se não ocorreu nenhum erro. Isto significa que os seguintes comandos são equivalentes:

if (mysql_stmt_errno(stmt))
{
 // an error occured
}
if (mysql_stmt_error(stmt)[0])
{
 // an error occured
}

A linguagem da mensagem de erro do cliente pode ser alterada recompilando a biblioteca cliente do MariaDB. Atualmente você pode escolher mensagem de erros em diversas linguagens.

Valor Retornado

Um string contendo a descrição do erro. Uma string vazia se não ocorrer erros.

Erros

Nenhum

mysql_stmt_sqlstate()

const char *mysql_stmt_sqlstate(MYSQL_STMT *stmt)

Descrição

Para a intrução especificada por stmt, mysql_stmt_sqlstate(), retorna uma string terminada em null contendo o código de erro SQLSTATE para função API de instruções preparadas mais recentemente chamada que tenha obtido sucesso ou falhado. O código de erro consiste de cinco caracteres. '00000' significa sem erros. Os valores são especificados pelo ANSI SQL e ODBC. Para uma lista de valores possíveis, veja Seção 13.1, 'Erros Retornados'.

Note que nem todos os erros já estão mapeados para SQLSTATE. O valor 'HY000' (erro geral) é usado para erros não mapeados.

Valores Retornados

Uma string terminada em null contendo o código de erro SQLSTATE.

Tratando a Execução de Múltiplas Consultas na API C

A partir da versão 4.1, o MariaDB suporta a execução de multiplas instruções especificadas em uma única string de consulta. Para utilizá-lo com uma dada conexão, você deve especificar a opção CLIENT_MULTI_STATEMENTS no parâmetro do mysql_real_connect() quando abrir a conexão. Você também pode configurá-la para uma conexão chamando mysql_set_server_option(MYSQL_OPTION_MULTI_STATEMENTS_ON)

Por padrão mysql_query() ou mysql_real_query() retornam apenas o status da primeira consulta e o status das consultas subsequentes podem ser processados usando mysql_more_results() e mysql_next_result().

 /* Connect to server with option CLIENT_MULTI_STATEMENTS */
 mysql_real_connect(..., CLIENT_MULTI_STATEMENTS);
 /* Now execute multiple queries */
 mysql_query(mysql,'DROP TABLE IF EXISTS test_table;\
 CREATE TABLE test_table(id INT);\
 INSERT INTO test_table VALUES(10);\
 UPDATE test_table SET id=20 WHERE id=10;\
 SELECT * FROM test_table;\
 DROP TABLE test_table';
 do
 {
 /* Process all results */
 ...
 printf('total affected rows: %lld', mysql_affected_rows(mysql));
 ...
 if (!(result= mysql_store_result(mysql)))
 {
 printf(stderr, 'Got fatal error processing query\n');
 exit(1);
 }
 process_result_set(result); /* client function */
 mysql_free_result(mysql);
}while (!mysql_more_results(mysql))

Manipulando Valores de Data e Hora na API C

O novo protocolo binário disponível no MariaDB e acima lhe permite enviar e receber dados de hora e data (DATE, TIME, DATETIME e TIMESTAMP) utilizando a estrutura MYSQL_TIME. Os membros desta estrutura estão em Seção 12.1.5, 'Tipos de Dados de Instruções Preparadas da API C'.

Para enviar um valor de dado temporal, você cria uma instrução preparada com mysql_prepare(). Então, antes de chamar mysql_execute() para executar a instrução, use o seguinte procedimento para configurar cada parâmetro temporal:

  1. Na estrutura MYSQL_BIND associado com o valor do dado, configure o membro buffer_type para o tipo que indique qual tipo de valor temporal você está enviando. Para valores DATE, TIME, DATETIME, ou TIMESTAMP configure buffer_type para MYSQL_TYPE_DATE, MYSQL_TYPE_TIME, MYSQL_TYPE_DATETIME, ou MYSQL_TYPE_TIMESTAMP repectivamente.
  2. Configure o membro buffer da estrutura MYSQL_BIND com o endereço da estrutura MYSQL_TIME na qual você passrá o valor temporal.
  3. Preencha os membros da estrutura MYSQL_TIME que são apropriadas para o tipo de valor temporal que você está passando.

Use mysql_bind_param() para ligar os dados do parâmetro a instrução. Então chame mysql_execute().

Para recuperar valores temporais, o procedimento é similar, exceto pelo fato de que você configura o membro buffer_type com o valor que você espera receber e o membro buffer com o endereço de uma estrutura MYSQL_TIME na qual o valor retornado deve ser colocado. Use mysql_bind_results() para ligar o buffer a instrução depois da chamada de mysql_execute() e antes de buscar os resultados.

Aqui está um exemplo simples que insere dados DATE, TIME e TIMESTAMP. A variável MariaDB é considerada como um handle de conexão válido.

MYSQL_TIME ts;
MYSQL_BIND bind[3];
MYSQL_STMT *stmt;
 strmov(query, 'INSERT INTO test_table(date_field, time_field,
 timestamp_field) VALUES(?,?,?');
 stmt= mysql_prepare(mysql, query, strlen(query)));
 /* define a entrada do buffer com 3 parâmetros */
 bind[0].buffer_type= MYSQL_TYPE_DATE;
 bind[0].buffer= (char *)&ts;
 bind[0].is_null= 0;
 bind[0].length= 0;
 ..
 bind[1]= bind[2]= bind[0];
 ..
 mysql_bind_param(stmt, bind);
 /* fornece os dados a serme enviados na estrutura ts */
 ts.year= 2002;
 ts.month= 02;
 ts.day= 03;
 ts.hour= 10;
 ts.minute= 45;
 ts.second= 20;
 mysql_execute(stmt);
 ..

Descrição das Funções de Threads da API C

my_init()
mysql_thread_init()
mysql_thread_end()
mysql_thread_safe()

Você precisa utilizar as seguintes funções quando quiser criar um cliente em uma thread. Leia Seção 12.1.14, 'Como Fazer um Cliente em Threads'.

my_init()

void my_init(void)

Descrição

Esta função precisa ser chamada uma vez pelo programa antes de se chamar qualquer função do MariaDB. Ela inicializa algumas varáveis globais que o MariaDB precisa. se você está usando uma biblioteca cliente de thread segura, também será feita uma chamada a mysql_thread_init() para esta thread.

Ela é chamada automaticamente por mysql_init(), mysql_server_init() e mysql_connect().

Valor Retornado

Nenhum

mysql_thread_init()

my_bool mysql_thread_init(void)

Descrição

Esta função preisa aser chamada para cada thread criada para inicializar variáveis específicas de threads.

Ela é automaticamente chamada por my_init() e mysql_connect().

Valor Retornado

Zero se obtver sucesso. Diferente de zero se ocorrer um erro.

mysql_thread_end()

void mysql_thread_end(void)

Descrição

Esta função precisa ser chamada antes da chamada de pthread_exit() para liberar a memória alocada por mysql_thread_init().

Note que a função não é chamada automaticamente pela biblioteca cliente. Deve ser chamada explicitamente para evitar perda de memória.

Valor Retornado

Nenhum.

mysql_thread_safe()

unsigned int mysql_thread_safe(void)

Descrição

Esta função indica se o cliente é compilado como uma thread segura.

Valor Retornado

1 se o cliente possui thread segura, 0 em outro caso.

Descrição das Funções do Servidor Embutido da API C

mysql_server_init()
mysql_server_end()

Você deve utilizar as seguints funções se você quiser permitir que a sua aplicação seja ligada a biblicoteca de servidor MariaDB embutido. Leia Seção 12.1.15, 'libmysqld, a Biblioteca do Servidor Embutido MySQL'.

Se o programa é ligado com -lmysqlclient em vez de -lmysqld, estas funções não farão nada. Isto torna possível escolher entre usar o servidor MariaDB embutido e um servidor stand-alone sem modificar nenhum código.

mysql_server_init()

int mysql_server_init(int argc, char **argv, char **groups)

Descrição

Esta função deve ser chamada uma vez no program usando o servidor embutido antes de se chamar qualquer iutra função do MariaDB. Ela inicia o servidor e inicializa qualquer subsistema (mysys, InnoDB, etc.) que o servidor utilize. Se esta função não for chamada, o programa irá falhar. Se você estiver usando o pacote DBUG que vem com o MySQL, você deve chamar esta função depois de ter chamado MY_INIT().

Os argumentos argc e argv são análogos ao argumentos para o main(). O primeiro elemento de argv é ignorado (ele contém normalmente, o nome do programa). por conveniência, argc pode ser 0 (zero) se não houver argumentos de linha de comando para o servidor. mysql_server_init() faz uma copia dos argumentos, assim é seguro destruir argv ou groups depois da chamada.

A lista de strings terminadas em NULL em groups seleciona qual grupo no arquivo de opções será ativado. Leia 'Arquivo de Opções my.cnf'. Por conveniência, groups deve ser NULL, caso no qual os grupos [server] d [emedded] estarão ativos.

Exemplo

#include <mysql.h>
#include <stdlib.h>
static char *server_args[] = {
 'this_program', /* this string is not used */
 '--datadir=.',
 '--key_buffer_size=32M'
};
static char *server_groups[] = {
 'embedded',
 'server',
 'this_program_SERVER',
 (char *)NULL
};
int main(void) {
 mysql_server_init(sizeof(server_args) / sizeof(char *),
 server_args, server_groups);
 /* Use any MariaDB API functions here */
 mysql_server_end();
 return EXIT_SUCCESS;
}

Valor Retornado

0 se okay, 1 se ocorrer um erro.

mysql_server_end()

void mysql_server_end(void)

Descrição

Esta função deve ser chamada no programa depois de todas outra funções MySQL. Ela finaliza o srvidor embutido.

Valor Retornado

Nenhum.

Dúvidas e problemas comuns ao utilzar a API C

Porque Algumas Vezes mysql_store_result() Retorna NULL Após mysql_query() Returnar com Sucesso?
Que Resultados Posso Onbetr de uma Consulta?
Como Posso Obter a ID Única para a Última Linha Inserida?
Problemas com Ligação na API C

Porque Algumas Vezes mysql_store_result() Retorna NULL Após mysql_query() Returnar com Sucesso?

É possível para mysql_store_result() retornar NULL seguida de uma chamda corretamente ao mysql_query(). Quando isto acontece, significa que uma da seguintes condições ocorreu:

Você sempre pode verificar se a instrução devia produzir um resultado não vazio chamando mysql_field_count(). Se mysql_field_count() retornar zero, o resultado está vazio e a última consulta era uma instrução que não devia retorbar valor (por exemplo, um INSERT ou um DELETE). Se mysql_field_count() retorna um valor diferente se zero, a instrução devia ter produzido um resultado não vazio. Veja a descrição da função mysql_field_count() para um exemplo.

Você pode testar um erro chamando mysql_error() ou mysql_errno().

Que Resultados Posso Onbetr de uma Consulta?

Sobre o resultado restornado de uma consulta, você pode obter as seguintes informaçãoes:

Como Posso Obter a ID Única para a Última Linha Inserida?

Se você inserir um registro em uma tabela contendo uma coluna que tiver o atributo AUTO_INCREMENT, você pode obter o ID gerado mais recentemente chamando a função mysql_insert_id().

Você também pode recuperar o ID utilizando a função LAST_INSERT_ID() em uma string de consulta que foi passada a mysql_query().

Você pode verificar se um índice AUTO_INCREMENT é usado executando o seguinte código. Ele também verifica se a consulta era um INSERT com um índice AUTO_INCREMENT:

if (mysql_error(&mysql)[0] == 0 &&
 mysql_num_fields(result) == 0 &&
 mysql_insert_id(&mysql) != 0)
{
 used_id = mysql_insert_id(&mysql);
}

O ID gerado mais recentemente é mantido no servidor em uma base por conexão. Ele não será alterado por outro cliente. Ele não será alterado mesmo se você atualizar outra coluna AUTO_INCREMENT com um valor não mágico (isto é, um valor que não é NULL e nem 0).

Se você quiser utilizar o ID que foi gerado por uma tabela e inserido em uma segunda tabela, você ode utilizar instruções SQL como esta:

INSERT INTO foo (auto,text)
 VALUES(NULL,'text'); # gera ID inserindo NULL INSERT INTO foo2 (id,text)
 VALUES(LAST_INSERT_ID(),'text'); # usa ID na segunda tabela

Problemas com Ligação na API C

Ar ligar com a API C, os segintes error podem ocorrem em alguns sistemas:

gcc -g -o client test.o -L/usr/local/lib/mysql -lmysqlclient -lsocket -lnsl Undefined first referenced
 symbol in file floor /usr/local/lib/mysql/libmysqlclient.a(password.o)
ld: fatal: Symbol referencing errors. No output written to client

Se isto acontecer em seu sistema, você deve incluir a biblioteca math adiconando -lm ao fim da linha de compilação/ligação.

Construindo Programas Clientes

Se você compilar clientes MariaDB escritos por você mesmo ou obtido de terceiros, else devem ser ligados utilizando a opção -lmysqlclient -lz no comando de ligação. Você também pode prcisar de especificar uma opção -L para dizer ao ligado onde encntrar a biblioteca. Por exemplo, se a biblioteca é instalada em /usr/local/mysql/lib, use -L/usr/local/mysql/lib -lmysqlclient -lz no comando de ligação.

Para clientes que utilizam arquivos de cabeçalho do MariaDB, pode ser necessário especificar a opção -I ao compilá-los, (por exemplo, -I/usr/local/mysql/include), assim o compilador pode encontrar o arquivo de cabeçalho.

Para o mostrado acima de forma simples no Unix, fornecemos o script mysql_config para você. Leia 'mysql_config, Opções para compilação do cliente MySQL'.

Você pode utilizá-lo para compila o cliente MariaDB como a seguir:

CFG=/usr/local/mysql/bin/mysql_config sh -c 'gcc -o progname `$CFG --cflags` progname.c `$CFG --libs`'

sh -c é necessário para fazer com que a sheel não trate a saída de mysql_config como uma palavra.

Como Fazer um Cliente em Threads

A biblioteca cliente é quase segura com threads. O maior problema é que a subrotinas em net.c que leem dos sockets não são seguras a interrupções. Isto foi feito pesando que você pudesse desejar ter o seu próprio alarme que possa quebrar uma longa leitura no servidor. Se você instalar manipuladores de interrupção para a interrupção SIGPIPE, o manipulador socket deve ser segura com threads.

Nos binários antigos que distribuímos em nosso web site (http://www.mysql.com/), as bibliotecas clientes não estão normalmente compiladas com a opção de segurança com thread (os binários são complados com segurança com thread por padrão). Distribuições binárias mais novas devem ter uma biblioteca normal e uma segura com threads.

Para termos um cliente em threads onde você pode interromper o cliente a partir de outras threads a definir tempo limites ao falar com o servidor MySQL, você deve utilizar as bibliotecas -lmysys, -lmystrings, e -ldbug e o código net_serv.o que o servidor utiliza.

Se você não precisar de insterrupções ou de tempos limites, você pode apenas compilar um biblioteca cliente (mysqlclient_r) segura com threads e utilizá-las. Leia Seção 12.1, 'API C do MariaDB'. Neste caso você não precisa se preocupar com o arquivo objeto net_serv.o ou outras bibliotecas MySQL.

Quando usar um cliente em thread e você quiser utilizar tempos limite e interrupções, você pode ter um grande uso das rotinas no arquivo thr_alarm.c. Se você estiver utilizando rotinas da biblioteca mysys, a única coisa que você deve lembrar é de chamar primeiro my_init()! Leia Seção 12.1.10, 'Descrição das Funções de Threads da API C'.

Todas as funções com excessão de mysql_real_connect() são seguras com thread por padrão. As anotações seguintes descrevem como compilar uma biblioteca cliente segura com thread e utilizá-la de maneira segura. (As anotações abaixo para mysql_real_connect() na verdade se aplicam também a mysql_connect(), mas como mysql_connect() está obsoleto, você deve utilizar mysql_real_connect().)

Para tornar mysql_real_connect() seguro com thread, você deve recompilar a biblioteca cliente com este comando:

shell> ./configure --enable-thread-safe-client

Isto irá criar uma biblioteca cliente libmysqlclient_r. (Assumindo que o seu SO tenha a função gethostbyname_r() segura com thread). Esta biblioteca é segura com thread por conexão. Você pode deixar duas threads compartilharem a mesma conexão com os seguintes cuidados:

Você precisa saber o seguinte se você tiver uma thread que estiver chamando funções MariaDB que não criaram a conexão ao Banco de Dados MariaDB:

Quando você chamar mysql_init() ou mysql_connect(), MariaDB irá criar um variável especica da thread para a thread que é utilizada pela bibklioteca de depuração (entre outra coisas).

Se você chamar uma função MySQL, antes da thread chamar mysql_init() ou mysql_connect(), a thread não terá as variáveis específicas de thread necessárias alocadas e você acabará finalizando com uma descarga de memória mais cedo ou mais tarde.

Para fazer que as coisas funcionem suavemente você tem que fazer o seguinte:

  1. Chama my_init() no início do seu programa se for chamar qualquer outra função MariaDB antes de chamar mysql_real_connect().
  2. Chame mysql_thread_init() no manipulador de thread antes de chamar qualquer outra função MariaDB.
  3. Na thread, chame mysql_thread_end() antes de chamar pthread_exit(). Isto irá liberar a memória usada pelas variáveis específicas da thread do MariaDB.

Você pode obter alguns erros devido a símbolos indefinidos ao ligar seu cliente com libmysqlclient_r. Na maioria dos casos isto ocorre por não estar incluída a biblioteca de threads na linha de ligação/compilação.

libmysqld, a Biblioteca do Servidor Embutido MariaDB

Visão Geral da Biblioteca do Servidor MariaDB Embutido
Compilando Programas com libmysqld
Restrições no Uso de um Servidor MariaDB Embutido
Usando Arquivo de Opções com o Servidor Embutido
Itens a Fazer no Servidor Embutido (TODO)
Um Exemplo Simples de Servidor Embutido
Licensiando o Servidor Embutido

Visão Geral da Biblioteca do Servidor MariaDB Embutido

A biblioteca do servidor MariaDB embutido torna possível executar um servidor MariaDB com todos os recursos dentro de uma aplicação cliente. Os principais benefícios são o aumento de velocidade e o gerenciamento mais simples de aplicações embutidas.

A biblioteca do servidor embutido é baseada na versão cliente/servidor do MariaDB, que é escrita em C/C++. Consequentemente, o servidor embutido também é escrito em C/C++. Não há nenhum servidor embutido disponível em outra linguagem.

A API é idêntica para a versão embutida do MariaDB e a versão cliente/servidor. Para alterar uma aplicação em thread antiga para utilizar a biblioteca embutida, você normalmente só precisa adicionar chamadas as seguintes funções:

Função Quando chamar
mysql_server_init() Deve ser chamada antes de qualquer outra função MySQL, de preferência no inicio da função main().
mysql_server_end() Deve ser chamada antes da saída do programa.
mysql_thread_init() Deve ser chamada em cada thread que você criar que acessará o MariaDB.
mysql_thread_end() Deve ser chamada antes de se chamar pthread_exit()

Você deve ligar seu código com libmysqld.a em vez de libmysqlclient.a.

As funções acima mysql_server_xxx também estão incluídas em libmysqlclient.a para permitir a troca entre a versão embutida e a clienete/servidor apenas ligando sua aplicação na biblioteca certa. Leia Seção 12.1.11.1, 'mysql_server_init()'.

Compilando Programas com libmysqld

Para obter uma biblioteca libmysqld você deve configurar o MariaDB com a opção --with-embedded-server.

Quando você liga o seu programa com libmysqld, você também deve incluir a biblioteca específica do sistema pthread e algumas bibliotecas que o servidor MariaDB utiliza. Você pode conseguir a lista completa de bibliotecas executando mysql_config --libmysqld-libs.

Os parâmetros corretos para compilar e ligar um programa em thread devem ser usados, mesmo se você não chamar nenhuma função thread diretamente em seu código.

Restrições no Uso de um Servidor MariaDB Embutido

O servidor embutido tem as seguintes limitações:

Algumas desta limitações podem ser alteradas editando o arquivo mysql_embed.h e recompilando o MariaDB.

Usando Arquivo de Opções com o Servidor Embutido

O descrito abaixo é o modo recomendado de utilizar arquivos de opções para facilitar a troca entre uma aplicação cliente/servidor é uma onde o MariaDB está embutido. Leia 'Arquivo de Opções my.cnf'.

Itens a Fazer no Servidor Embutido (TODO)

Um Exemplo Simples de Servidor Embutido

Este programa e makefile exemplo devem funcionar sem nenhuma alteração em um sistema Linux ou FreeBSD. Para outros sistemas operacionais, pequenas mudanças serão necessárias. Este exemplo é feito para dar detalhes suficientes para enteder o problema, sem a desordem que é uma parte necessária de uma aplicação real.

Para experimentar o exemplo, crie um diretório test_libmysqld no mesmo nível que o diretório fonte do mysql-4.0. Salve o fonte test_libmysqld.c e o GNUmakefile no diretório e execute GNU make de dentro do diretório test_libmysqld.

test_libmysqld.c

/*
 * A simple example client, using the embedded MariaDB server library
 */
#include <mysql.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
MYSQL *db_connect(const char *dbname);
void db_disconnect(MYSQL *db);
void db_do_query(MYSQL *db, const char *query);
const char *server_groups[] = {
 'test_libmysqld_SERVER', 'embedded', 'server', NULL
};
int main(int argc, char **argv)
{
 MYSQL *one, *two;
 /* mysql_server_init() devve ser chamado antes de qualquer
 * função mysql.
 *
 * Você pode usar mysql_server_init(0, NULL, NULL), e iniciar
 * o servidor usando os grupos = {
 * 'server', 'embedded', NULL
 * }.
 *
 * Em seu arquivo $HOME/.my.cnf file, você provavelmente deseja colocar:
[test_libmysqld_SERVER]
language = /path/to/source/of/mysql/sql/share/english
 * É claro que você poderia modifcar argc e argv antes de passá-los
 * a esta função. Ou poderá criar novos do modo que preferir. Mas
 * todos os argumentos em argv (exceto argv[0], que é o nome do
 * programa) devem ser opções válidas para o servidor MySQL.
 *
 * Se você ligar este cliente em um biblioteca mysqlclient
 * normal, esta função não fará nada.
 */
 mysql_server_init(argc, argv, (char **)server_groups);
 one = db_connect('test');
 two = db_connect(NULL);
 db_do_query(one, 'SHOW TABLE STATUS');
 db_do_query(two, 'SHOW DATABASES');
 mysql_close(two);
 mysql_close(one);
 /* Isto deve ser chamado depois de todas outras funções mysql*/
 mysql_server_end();
 exit(EXIT_SUCCESS);
}
static void die(MYSQL *db, char *fmt, ...)
{
 va_list ap;
 va_start(ap, fmt);
 vfprintf(stderr, fmt, ap);
 va_end(ap);
 (void)putc('\n', stderr);
 if (db)
 db_disconnect(db);
 exit(EXIT_FAILURE);
}
MYSQL *
db_connect(const char *dbname)
{
 MYSQL *db = mysql_init(NULL);
 if (!db)
 die(db, 'mysql_init failed: no memory');
 /*
 * Certifique-se que o cliente e o servidor utilizam grupos diferentes.
 * Isto é critico pois o servidor não aceitará as opções do
 * cliente e vice versa.
 */
 mysql_options(db, MYSQL_READ_DEFAULT_GROUP, 'test_libmysqld_CLIENT');
 if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0))
 die(db, 'mysql_real_connect failed: %s', mysql_error(db));
 return db;
}
void db_disconnect(MYSQL *db)
{
 mysql_close(db);
}
void db_do_query(MYSQL *db, const char *query)
{
 if (mysql_query(db, query) != 0)
 goto err;
 if (mysql_field_count(db) > 0)
 {
 MYSQL_RES *res;
 MYSQL_ROW row, end_row;
 int num_fields;
 if (!(res = mysql_store_result(db)))
 goto err;
 num_fields = mysql_num_fields(res);
 while ((row = mysql_fetch_row(res)))
 {
 (void)fputs('>> ', stdout);
 for (end_row = row + num_fields; row < end_row; ++row)
 (void)printf('%s\t', row ? (char*)*row : 'NULL');
 (void)fputc('\n', stdout);
 }
 (void)fputc('\n', stdout);
 mysql_free_result(res);
 }
 else
 (void)printf('Affected rows: %lld\n', mysql_affected_rows(db));
 return;
err:
 die(db, 'db_do_query failed: %s [%s]', mysql_error(db), query);
}

GNUmakefile

# This assumes the MariaDB software is installed in /usr/local/mysql inc := /usr/local/mysql/include/mysql lib := /usr/local/mysql/lib
# If you have not installed the MariaDB software yet, try this instead
#inc := $(HOME)/mysql-4.0/include
#lib := $(HOME)/mysql-4.0/libmysqld CC := gcc CPPFLAGS := -I$(inc) -D_THREAD_SAFE -D_REENTRANT CFLAGS := -g -W -Wall LDFLAGS := -static
# You can change -lmysqld to -lmysqlclient to use the
# client/server library LDLIBS = -L$(lib) -lmysqld -lz -lm -lcrypt ifneq (,$(shell grep FreeBSD /COPYRIGHT 2>/dev/null))
# FreeBSD LDFLAGS += -pthread else
# Assume Linux LDLIBS += -lpthread endif
# This works for simple one-file test programs sources := $(wildcard *.c)
objects := $(patsubst %c,%o,$(sources))
targets := $(basename $(sources))
all: $(targets)
clean:
 rm -f $(targets) $(objects) *.core

Licensiando o Servidor Embutido

O código fonte do MariaDB é coberto pela licenção GNU GPL (see Apêndice H, GPL - Licença Pública Geral do GNU). Um resultado disto é que qualquer programa que incluam, na ligação com libmysqld, o código fonte do MariaDB deve ser distribuído como software livre. (sob uma licença compatível com a GPL).

Nós encorajamos a todos a promover o software livre distribuindo o código sob a GPL ou uma licença compatível. Para aqueles que não puderem fazê-lo, outra opção é comprar um licença comercial para o código MariaDB da MariaDB Foundation. Para maiores detalhes, consulte 'Licenças do MariaDB'.

Suporte ODBC ao MariaDB

Como Instalar o MyODBC
Como Preencher os Vários Campos no Programa de Administração do ODBC
Parâmetros de Conexão do MyODBC
Como Relatar Problemas com o MyODBC
Programas que Funcionam com MyODBC
Como Obter o Valor de uma Coluna AUTO_INCREMENT no ODBC
Relatando Problemas com MyODBC

O MariaDB fornece suporte para ODBC através do programa MyODBC. Este lhe ensinará como instalar o MyODBC, e como usá-lo. Aqui, você também encontrará uma lista de programas comuns que são conhecidos por funcionar com MyODBC.

Como Instalar o MyODBC

MyODBC 2.50 é um driver de nível 0 (com recursos de nível 1 e 2) e especificação de ODBC 2.50 de 32 bits para conectar um programa ODBC ao MariaDB. MyODBC funciona nos Windows 9x/Me/NT/2000/XP e na maioria da plataformas Unix. MyODBC 3.51 é uma versão melhorada com nível 1 (core API completo + recursos de nível 2) e especificação de ODBC 3.5x.

MyODBC é Open Source, e você pode encontrar a versão mais nova em http://www.mysql.com/downloads/api-myodbc.html. Note que a versão 2.50.x utiliza a licença LGPL, enquanto a versão 3.51.x utiliza a licença GPL.

Se vcê tiver problemas com o MyODBC e seu programa também funciona com OLEDB, você deve experimentar o driver OLEDB.

Normalmente você só precisa instalar o MyODBC em másquinas Windows. Você só precisará de MyODBC para Unix se tiver um programa como ColdFusion que roda em máquinas Unix e utilizam ODBC para conectar ao banco de dados.

Se você quiser instalar MyODBC em um Unix, você precisará de um gerenciador ODBC. MyODBC funciona com a maioria dos gerenciadores ODBC para Unix.

Para instalar MyODBC no Windows, você deve baixar o arquivo MyODBC .zip apropriado, descompactá-lo com WinZip ou algum programa parecido e executar o arquivo SETUP.EXE.

No Windows/NT/XP você pode obter o seguinte erro ao tentar instalar o MyODBC:

An error occurred while copying C:\WINDOWS\SYSTEM\MFC30.DLL. Restart Windows and try installing again (before running any applications which use ODBC)

O problema neste caso é que algum outro progrma está utilizando ODBC e pela forma que como o Windows é feito, você pode, neste caso, não estar apto a instalar um novo driver ODBC com programa de instação do ODBC da Microsoft. Neste caso você pode continuar selecionando Ignore para copiar o resto dos aerquivos ODBC e a instalação final deve funcionar. Se não funcionar, a solução é reinicializar seu computador em modo seguro (Escolhendo-o ao pressionar F8 assim que seu computador iniciar o Windows durante a reinicialização), instalar MyODBC, e reiniciar em modo normal.

Verifique se há outra opção de configuração na tela do MariaDB (trace, não pergunta ao conectar, etc) que você possa tentar se ocorrerem problemas.

Como Preencher os Vários Campos no Programa de Administração do ODBC

Existem três maneiras possíveis de especificar o nome de servidor no Windows95:

Exemplo de como preencher a configuração do ODBC.

Windows DSN name: test Description: This is my test database MariaDB Database: test Server: 194.216.84.21
User: monty Password: my_password Port:

O valor para o campo Windows DSN name é qualquer nome que seja único em sua configuração ODBC Windows.

Você não precisa especificar valores para os campos Server, User, Password, ou Port ina tela de configuração do ODBC. No entanto, se você o fizer, os valores serão utilizados como padrão posteriormente ao se tentar fazer uma nova conexão. Você tem a opção de alterar os valores neste momento.

Se o número da porta não é dado, a porta padrão (3306) é utilizada.

Se você especificar a opção Read options from C:\my.cnf, os grupos client e odbc serão lidos do arquivo C:\my.cnf. Você pode utilizar todas as opções que são úteis a mysql_options(). Leia Seção 12.1.3.40, 'mysql_options()'.

Parâmetros de Conexão do MyODBC

Pode-se especificar os seguintes parâmetros para MyODBC na seção [Servername] de um arquivo ODBC.INI ou através do argumento InConnectionString na chamada SQLDriverConnect().

Parâmetro Valor padrão Comentário
user ODBC (on Windows) O nome do usuário usado para se conectar ao MariaDB.
server localhost O nme de máquina do servidor MySQL.
database O banco de dados padrão.
option 0 Um inteiro com o qual você pode especificar como o MyODBC deve tarbalhar. Veja abaixo.
port 3306 A porta TCP/IP usada se o servidor (server) não for localhost.
stmt Uma instrução que será executada ao conectar ao MariaDB.
password A senha para a combinação servidor(server)-usuário(user).
socket O socket ou pipe Windows para se conectar.

O argumento option é usado para dizer ao MyODBC que o cliente não é 100% compatível com ODBC. No Windows, o parâmetro option normalmente é definido mudando as diferentes opções na tela de conexão mas também podem ser definidas no argumento option. As seguintes opções estão listadas na mesma ordem em que aparecem na tela de conexão do MyODBC:

Bit Descrição
1 O cliente não pode aceitar que MyODBC retorne a largura real de uma coluna.
2 O clinete nã pode aceitr que MariaDB retorne o valor real de colunas afetadas. Se este parâmetro for definido o MariaDB retornará 'registros encontrados'. É necessáriop o MariaDB 3.21.14 ou posterior para funcionar.
4 Faz um log de depuração em c:\myodbc.log. É o mesmo que colocar MYSQL_DEBUG=d:t:O,c::\myodbc.log no AUTOEXEC.BAT
8 Não define nenhum limite de pacote para resultados e parâmetros.
16 Não faz perguntas mesmo se o driver quisesse.
32 Simula um driver ODBC 1.0 em alguns contextos.
64 Ignora o uso do nome de banco de dados 'bancodedados.tabela.coluna'
128 Força o usa de cursores de gerenciadores ODBC (experimental).
256 Disabilita o uso de busca estendida (experimental).
512 Completa campos CHAR para tamanho de coluna cheias.
1024 SQLDescribeCol() retrnará nome de colunas totalmente qualificados.
2048 Usa o protocolo cliente/servidor comprimido.
4096 Diz ao seridor para ignorar espaços após nome de funções e antes de '(' (necessário para PowerBuilder). Torna todos os nomes de funções palavras-chaves!
8192 Conecta com named pipes ao servidor mysqld executando no NT.
16384 Altera colunas LONGLONG para colunas INT (algumas aplicações não podem tratar LONGLONG).
32768 Retorna 'user' como Table_qualifier e Table_owner para SQLTables (experimental)
65536 Lê paraâmetros dos grupos client e odbc no my.cnf
131072 Adiciona algumas verificações extras de segurança (não deve ser necessário, mas...)

Se você quiser ter muitas opções, você deve somar os parâmetros acima! Por exemplo, definir a opção como 12 (4+8) lhe permite debugar sem limite de pacotes.

O MYODBC.DLL padrão é compilado para um rendimento otimizado. Se você quiser depurar o MyODBC (por exemplo, habiliatr o trace), você deve utilizar MYODBCD.DLL. Para instalar este arquivo copie MYODBCD.DLL sobre o arquivo MYODBC.DLL instalado.

Como Relatar Problemas com o MyODBC

MyODBC tem sido testado com Access, Admndemo.exe, C++-Builder, Borland Builder 4, Equipe de Desenvovimento Centura (formalmente Gupta SQL/Windows), ColdFusion (em Solaris e NT com svc pack 5), Crystal Reports, DataJunction, Delphi, ERwin, Excel, iHTML, FileMaker Pro, FoxPro, Notes 4.5/4.6, SBSS, Perl DBD-ODBC, Paradox, Powerbuilder, Powerdesigner 32 bit, VC++, e Visual Basic.

Se você souber de qualquer outra aplicação que funcione com MyODBC, envie-nos email para lista de email odbc do MariaDB sobre isto! Leia 'As Listas de Discussão do MariaDB'.

Com alguns programas você pode obter um erro como este: Another user has modifies the record that you have modified. Na maioria dos casos ele pode ser resolvido fazendo o especificado abaixo:

Se o exposto acima não ajudar, você deve fazer um arquivo de rastreamento do MyODBC e tentar encontrar o que está dando errado.

Programas que Funcionam com MyODBC

A maioria dos programas devem funcionar com MyODBC, mas para cada um dos listados aqui, nós mesmos testamos e recebemos confirmação de alguns usuários que eles funcionam:

Como Obter o Valor de uma Coluna AUTO_INCREMENT no ODBC

Um problema comum é como obter o valor de um ID gerado automaticamente em um INSERT. Com ODBC, você pode fazer algo assim (considerando que auto é um campo AUTO_INCREMENT):

INSERT INTO foo (auto,text) VALUES(NULL,'text');
SELECT LAST_INSERT_ID();

Ou, se você estiver prestes a insrir o ID em outra tabela, você pode fazer assim:

INSERT INTO foo (auto,text) VALUES(NULL,'text');
INSERT INTO foo2 (id,text) VALUES(LAST_INSERT_ID(),'text');

See Seção 12.1.12.3, 'Como Posso Obter a ID Única para a Última Linha Inserida?'.

Para o benefício de alguns aplicativos ODBC (pelo menos Delphi e Access), a seguinte consulta pode ser utilizada para encontrar um registro récem inserido:

SELECT * FROM nome_tabela WHERE auto IS NULL;

Relatando Problemas com MyODBC

Se você encontrar dificuldades com MyODBC, você deve iniciar fazendo um arquivo log pelo gerenciador ODBC (o log obtido ao requisitar logs do ODBCADMIN) e um log MyODBC.

Para obter um log MyODBC, você precisa fazer o seguinte:

  1. Esteja certo de que você está utilizando myodbcd.dll e não myodbc.dll. O modo mais fácil de se fazer isto é obter myodbcd.dll da distribuição MyODBC e copiá-la sobre o myodbc.dll, o qual estará, provavelmente, em seu diretório C:\Windows\system32 ou C:\winnt\system32.

    Note que você provavelmente deseja restaurar o myodbc.dll antigo ao finalizar o teste, já que ele é bem mais rpido que myodbcd.dll.

  2. Marque a opção `Trace MyODBC' na tela de conexão/configuração do MyODBC. O logo será escrito no arquivo C:\myodbc.log.

    Se a opção de ratreamento não for lembrada quando você retornar a tela acima, significa que você não está utilizando o driver myodbcd.dll (veja o item acima).

  3. Inicie sua aplicação e tente fazê-la falhar.

Verifique o arquivo de rastreamento do MyODBC, para saber o que pode estar errado. Viocê deve estar apto a encontrar as consultas executadas buscando após a string >mysql_real_query no arquivo myodbc.log.

Você também devev tentar duplicar as consultas no monitor MariaDB ou admndemo para descobrir se o erro é do MyODBC ou do MariaDB.

Se você encontar algo errado, envie-nos somente os registros relevantes (max 40 registros) para a lista de email odbc do MariaDB. Leia 'As Listas de Discussão do MariaDB'. Por favor, nunca envie todo o arquivo log do MyODBC ou ODBC!

Se você não puder encontrar o que está errado, a última opção é fazer um arquivo (tar ou zip) que contenha um arquivo de rastreamento do MyODBC, o arquivo log do ODBC, e um arquivo README que explique o problema. Você pode enviá-lo para ftp://support.mysql.com/pub/mysql/secret/. Somente nós da MariaDB Foundation teremos acesso ao arquivo que você enviar, a seremos bem discretos com os dados!

Se você pode criar um programa que também mostre este problema, nos envie ele também.

Se o programa funciona com algum outro servidor MySQL, você deve fazer um arquivo de log do MyODBC onde você faz exatamente a mesma coisa no ouuto servidor SQL.

Lembre-se que quanto mais informações você nos fornecer, mais satisfatória será a solução encontrada para o problema!

Conectividade Java (JDBC) ao MariaDB

Existem 2 drivers JDBC suportados pelo MySQL:

Para informação, consulte qualquer documentação JDBC, além das documentação dos proprietários de cada driver para recursos específicos do MariaDB.

API PHP do MariaDB

Problemas Comuns com MariaDB e PHP

PHP é uma linguagem script do lado do servidor embutida em HTML que pode ser usada para criar páginas web dinâmicas. Ele contém suporte para acesso a diversos banco de dados, incluindo o MariaDB. PHP pode ser executado como um programa separado ou compilado como um módulo para uso com o servidro web Apache.

A distribuição e documentação está disponível no web site PHP (http://www.php.net/).

Problemas Comuns com MariaDB e PHP

API Perl do MariaDB

DBI com DBD::mysql
A interface DBI
Mais Informações DBI/DBD

Esta seção documenta a interface Perl DBI. A interface anterior era chamada mysqlperl. DBI/DBD é a intrface Perl recomendada atual;mente, assim mysqlperl está obsoleta e não será documentada aqui.

DBI com DBD::mysql

DBI é uma interface genérica para muitos bancos de dados. Isto significa que voccê pode escrever um script que funciona com diferentes mecanismos de banco de dados sem nenhuma mudança. Você precisa de um DataBase Driver - Driver de Banco de Dados (DBD) definido para cada tipo de banco de dados, para o MariaDB este driver é chamado DBD::mysql.

Para mais informação sobre Perl5 DBI, visite a pagina web do DBI e leia a documentação:

http://dbi.perl.org/

Note que se você quiser usar transações com Perl, você precisa ter o DBD-mysql versão 1.2216 ou posterior. Recomendamos usar a versão 2.1022 ou mais nova.

Installation instructions for MariaDB Perl support are given in 'Comentários de Instalação do Perl'.

Se você tiver o modulo MariaDB instalado, você pode achar informação sobre as funcionalidades especificas do MariaDB com um dos seguintes comandos:

shell> perldoc DBD/mysql
shell> perldoc mysql

A interface DBI

Métodos e Atributos DBI Portáteis

Método/Atributo Descrição
connect Estabelece uma conexão ao servidor de banco de dados.
disconnect Disconecta de um servidor de banco de dados.
prepare Prepara uma instrução SQL para ser executada.
execute Executa instruções preparadas.
do Prepara e executa uma instrução SQL.
quote Coloca valores string ou BLOB entre aspas para serem inseridos.
fetchrow_array Busca a próxima linha como um vetor de campos.
fetchrow_arrayref Busca a próxima linha como um vetor referência de campos.
fetchrow_hashref Busca a prima linha como uma referência a uma tabela hash.
fetchall_arrayref Busca todos os dados como um vetor de vetor (matriz).
finish Finaliza uma instrução e deixa os recursos do sistema livres.
rows Retorna o número de linhas afetadas.
data_sources Retorna um vetor de banco de dados disponíves ne localhost.
ChopBlanks Controla de o método fetchrow_* elimina os espaços em branco.
NUM_OF_PARAMS O número de colchetes em uma instrução preparada.
NULLABLE Quais colunas podem ser NULL.
trace Realiza rastreamento para depuração.

Métodos e Atributos específicos do MariaDB

Método/Atributos Descrição
mysql_insertid O último valor AUTO_INCREMENT.
is_blob Quais colunas são valores BLOB.
is_key Quais colunas são chaves.
is_num Quais colunas são numéricas.
is_pri_key Quais colunas são chaves primárias.
is_not_null Quais colunas NÃO PODEM ser NULL. Veja NULLABLE.
length O tamanho máximo das colunas.
max_length O tamanho máximo das colunas presentes no resultado.
NAME Nomes de colunas.
NUM_OF_FIELDS Número de campos retornados.
table Nome de tabelas no resultado.
type Todos os tipos de colunas

Os métodos Perl são descritos em maiores detalhes nas seções seguintes. Variáveis usadas em métodos que retornam valor tem estes significados:

Métodos e Atributos DBI Portáteis

Métodos e Atributos Especificos do MariaDB

Os métodos mostrados aqui são específicso do MariaDB e não são parte do padrão DBI. Diversos métodos já estão obsoletos: is_blob, is_key, is_num, is_pri_key, is_not_null, length, max_length, e table. Quando existir uma alternativa no padrão DBI, ela será listada aqui:

Mais Informações DBI/DBD

Você pode utilizar o comando perldoc para conseguir mais informação sobre DBI.

perldoc DBI perldoc DBI::FAQ perldoc DBD::mysql

Voê também pode utilizar as ferramentas pod2man, pod2html, etc., para traduzir para outro formato.

Você pode encontrar as últimas informações sobre DBI na pagina web DBI: http://dbi.perl.org/.

API C++ do MariaDB

Borland C++

MySQL Connector/C++ (ou MySQL++) é a API oficiaL do MariaDB para C++. Mais informações podem ser encontradas em http://www.mysql.com/products/mysql++/.

Borland C++

Você pode compilar o fonte do MariaDB Windows com Borland C++ 5.02. (O fonte Windows só incluem projetos para Microsoft VC++, para Borland C++ você mesmo tem que fazer os arquivos de projetos.)

Um problema conhecido copm o Borland C++ é que ele usa uam estrutura de alinhamento diferente do VC++. Isto significa que você terá problema se você tentar utilizar as bibliotecas libmysql.dll padrões (que foi compilado com VC++) com Borland C++. Você pode fazer o seguinte para ebitar este problema.

API Python do MariaDB

MySQLdb fornece suporte MariaDB para Python, compatível com a API Python DB version 2.0. Ela pode ser encontrada em http://sourceforge.net/projects/mysql-python/.

API Tcl do MariaDB

MySQLtcl é uma API simples para aceeso ao servidor de banco de dados MariaDB a partir da linguagem de programação Tcl. Ela pode ser encontrada em http://www.xdobry.de/mysqltcl/.

Eiffel Wrapper do MariaDB

Eiffel MariaDB é uma interface para o servidor de Banco de Dados MariaDB, utilizando a linguagem de programação Eiffel, escrita por Michael Ravits. Ela pode ser encontrada em http://efsa.sourceforge.net/archive/ravits/mysql.htm.

Anterior Próximo
Stored Procedures e Funções Início Tratamento de Erros no MySQL