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