XOOPS Brasil

 

Capítulo 12. Ferramentas de Clientes e APIs do MySQL

Este capítulo 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 MySQL e é a base para a maioria das outras APIs.

12.1. API C do MySQL

O código da API C é distribuído com o MySQL. 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 MySQL 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 MySQL.

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 Seção 4.9, “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. Veja mais informações sobre isto na Seção 5.5.2, “Parâmetros de Sintonia do Servidor”.

O servidor MySQL 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 MySQL externo), veja Seção 12.1.15, “libmysqld, a Biblioteca do Servidor Embutido MySQL”.

12.1.1. Tipos de Dados da API C

  • MYSQL

    Esta estrutura representa um manpulador para uma conexão ao banco de dados. É usada para quase todas as funções MySQL.

  • MYSQL_RES

    Esta estrutura representa o resultado de uma consulta que retorna linhas (SELECT, SHOW, DESCRIBE, EXPLAIN). A informação retornada de uma consulta é chamada conjunto de resultado no resto desta seção.

  • MYSQL_ROW

    Esta é uma representação segura de tipo de uma linha de dados. Ela é implementada atualmente como um vetor de strings de tamanho fixo (Você não pode tratá-los como strings terminadas com null se os valores do campo podem conter dados binários, porque tais valores podem conter um byte null internamente.). Linhas são obtidas pela chamada de mysql_fetch_row().

  • MYSQL_FIELD

    Esta estrutura contém informação sobre um campo, tais como nome, tipo e tamanho do campo. Seus membros são descritos em mais detalhes aqui. Você pode obter a estrutura MYSQL_FIELD para cada campo chamando mysql_fetch_field() repetidamente. Valores de campos não são parte desta estrutura; eles estão contidos na estrutura MYSQL_ROW.

  • MYSQL_FIELD_OFFSET

    Esta é uma representação segura de um offset em uma lista de campos MySQL. (Usado por mysql_field_seek().) Offsets são números de campos em um registro, começando com zero.

  • my_ulonglong

    O tipo usado pelo número de linhas e para mysql_affected_rows(), mysql_num_rows(), e mysql_insert_id(). Este tipo fornece uma faixa de 0 a 1.84e19.

    Em alguns sistemas, tentar imprimir um valor do tipo my_ulonglong não funcionará. Para imprimir tais valores, converta-os para unsigned long e use o formato de impressão %lu. Exemplo:

    printf ("Número de linhas: %lu\n", (unsigned long) mysql_num_rows(resultado));
    

A estrutura MYSQL_FIELD contem os membros listados aqui:

  • char * name

    O nome do campo, como um string terminada com null.

  • char * table

    O nome da tabela contendo este campo, se não for um campo calculado. Para campos calculador, o valor table é uma string vazia.

  • char * def

    O valor padrão para este campo, como um string terminada em null. Ele é atribuido apenas se você utilizar mysql_list_fields().

  • enum enum_field_types tipo

    O tipo do campo. O valor tipo pode ser um dos seguintes:

    Valou tipoDescrição do tipo
    FIELD_TYPE_TINYcampo TINYINT
    FIELD_TYPE_SHORTcampo SMALLINT
    FIELD_TYPE_LONGcampo INTEGER
    FIELD_TYPE_INT24campo MEDIUMINT
    FIELD_TYPE_LONGLONGcampo BIGINT
    FIELD_TYPE_DECIMALcampo DECIMAL ou NUMERIC
    FIELD_TYPE_FLOATcampo FLOAT
    FIELD_TYPE_DOUBLEcampo DOUBLE ou REAL
    FIELD_TYPE_TIMESTAMPcampo TIMESTAMP
    FIELD_TYPE_DATEcampo DATE
    FIELD_TYPE_TIMEcampo TIME
    FIELD_TYPE_DATETIMEcampo DATETIME
    FIELD_TYPE_YEARcampo YEAR
    FIELD_TYPE_STRINGcampo CHAR
    FIELD_TYPE_VAR_STRINGcampo VARCHAR
    FIELD_TYPE_BLOBcampo BLOB ou TEXT (usa max_length para determinar o tamanho máximo)
    FIELD_TYPE_SETcampo SET
    FIELD_TYPE_ENUMcampo ENUM
    FIELD_TYPE_NULLcampo tipo-NULL
    FIELD_TYPE_CHARDeprecado; use FIELD_TYPE_TINY

    Você pode utilizar a macro IS_NUM() para testar se uma campo tem um tipo numérico. Passe o valor tipo para IS_NUM() e ele irá avaliar como VERDADEIRO (TRUE) se o campo for numérico:

    if (IS_NUM(campo->tipo))
    printf("Campo é numérico\n");
    

  • unsigned int length

    A largura de um campo, como especificado nas definições da tabela.

  • unsigned int max_length

    A largura máxima do campo no conjunto de resultados (O tamanho do maior valor do campo para os registro no resultado atual). Se você utilizar mysql_store_result() ou mysql_list_fields(), ele contem o tamanho máximo para o campo. Se você utiliza mysql_use_result(), o valor desta variável é zero.

  • unsigned int param

    Diferentes parâmetros binários para o campo. O valor de param pode ter zero ou mais dos seguintes conjunto de bits:

    Valor paramDescrição param
    NOT_NULL_FLAGCampo não pode ser NULL
    PRI_KEY_FLAGCampo é parte de uma chave primária
    UNIQUE_KEY_FLAGCampo é parte de uma chave única
    MULTIPLE_KEY_FLAGCampo é parte de uma chave não única
    UNSIGNED_FLAGCampo tem o atributo UNSIGNED
    ZEROFILL_FLAGCampo tem o atributo ZEROFILL
    BINARY_FLAGCampo tem o atributo BINARY
    AUTO_INCREMENT_FLAGCampo tem o atributo AUTO_INCREMENT
    ENUM_FLAGCampo é um ENUM (obsoleto)
    SET_FLAGCampo é um SET (obsoleto)
    BLOB_FLAGCampo é um BLOB ou TEXT (obsoleto)
    TIMESTAMP_FLAGCampo é um TIMESTAMP (obsoleto)

    Uso dos parâmetros BLOB_FLAG, ENUM_FLAG, SET_FLAG, e TIMESTAMP_FLAG foram obsoletos porque eles indicavam o tipo de um campo e não um atributo do tipo. É preferível testar campo->tipo para FIELD_TYPE_BLOB, FIELD_TYPE_ENUM, FIELD_TYPE_SET, ou FIELD_TYPE_TIMESTAMP.

    O seguinte exemplo ilustra o uso típico do valor param:

    if (campo->param & NOT_NULL_FLAG)
    printf("Campo não pode ser nulo\n");
    

    Você pode usar as seguintes macros para determinar o status dos valores param:

    Status paramDescrição
    IS_NOT_NULL(param)Verdadeiro se se este campo é definido como NOT NULL
    IS_PRI_KEY(param)Verdadeiro de este campo é uma chave primária
    IS_BLOB(param)Verdadeiro se este campo é um BLOB ou TEXT (obsoleto; teste campo->tipo)
  • unsigned int decimals

    O número de decimais para um campo numérico.

12.1.2. 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. Veja mais informações sobre isto na Seção 12.1.3, “Descrição das Funções da API C”.

FunçãoDescriçã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 MySQL. 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 MySQL chamada mais recentemente.
mysql_error()Retorna a mensagem de erro para função MySQL 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 MYSQL.
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, utilizadores 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 com sucesso, 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 MySQL 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.

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

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

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().

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

12.1.3.2. mysql_change_user()

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

Descrição

Altera o utilizador é faz com que o banco de dados especificado por db se torne o banco de dados padrão (atual) na conexão especificada por mysql. 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 MySQL.

mysql_change_user() falha a menos que o utilizador conectado possa ser autenticado ou se ele não tiver permissão para utilizar o banco de dodos. Neste caso o utilizador 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 MySQL 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 utilizador 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().

  • CR_COMMANDS_OUT_OF_SYNC

    Comandos forma executados em ordem inapropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL finalizou.

  • CR_SERVER_LOST

    A conexão ao servidor foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

  • ER_UNKNOWN_COM_ERROR

    O servidor MySQL não possui este comando (provavelmente um versão mais antiga)

  • ER_ACCESS_DENIED_ERROR

    O utilizador ou a senha estavam errados.

  • ER_BAD_DB_ERROR

    O banco de dados não existe.

  • ER_DBACCESS_DENIED_ERROR

    O utilizador não tem direitos de acessoa este banco de dados.

  • ER_WRONG_DB_NAME

    O nome de banco de dados é muito grande.

Exemplo

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

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

12.1.3.4. 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 mysql se ele tiver sido alocado automaticamente por mysql_init() ou mysql_connect().

Valor Retornado

Nenhum.

Erros

Nenhum.

12.1.3.5. 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 MySQL 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 MYSQL válido.)

Valor Retornado

O mesmo de mysql_real_connect().

Erros

O mesmo de mysql_real_connect().

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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

Exemplo

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

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

12.1.3.8. 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. Veja mais informações sobre isto na Seção E.1, “Depurando um Servidor MySQL”. Veja mais informações sobre isto na 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");

12.1.3.9. 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 com sucesso. Diferente de zero ocorreu um erro.

Erros

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

Exemplo

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

12.1.3.10. 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 utilizador conectado deve ter pivilégio SUPER.

Valor Retornado

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

Erros

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.3.11. 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 MySQL 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 MySQL:

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));
}

12.1.3.12. mysql_errno()

unsigned int mysql_errno(MYSQL *mysql)

Descrição

Para a conexão especificada pelo mysql, 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 MySQL. Números de mensagem de erros do servidor são listados no arquivo mysqld_error.h. Na distribuição fonte do MySQL 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.

12.1.3.13. mysql_error()

const char *mysql_error(MYSQL *mysql)

Descrição

Para a conexão especificada por mysql, 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. Veja mais informações sobre isto na Seção 4.7.2, “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.

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

12.1.3.15. 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(), MySQL 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 MySQL 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);
}

12.1.3.16. 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);
}

12.1.3.17. 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);
}

12.1.3.18. 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]);
}
}

12.1.3.19. 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()

  • CR_SERVER_LOST

    A conexão com o servidor foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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");
}

12.1.3.20. 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 MySQL, 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.

Veja mais informações sobre isto na 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.

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

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

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

12.1.3.24. 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 MySQL.

Erros

Nenhum.

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

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

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

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

12.1.3.29. 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 MySQL 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.

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

  • INSERT INTO ... SELECT ...

    Formato da string: Records: 100 Duplicates: 0 Warnings: 0

  • INSERT INTO ... VALUES (...),(...),(...)...

    Formato da string: Records: 3 Duplicates: 0 Warnings: 0

  • LOAD DATA INFILE ...

    Formato da string: Records: 1 Deleted: 0 Skipped: 0 Warnings: 0

  • ALTER TABLE

    Formato da string: Records: 3 Duplicates: 0 Warnings: 0

  • UPDATE

    Formato da string: Rows matched: 40 Changed: 40 Warnings: 0

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.

12.1.3.31. mysql_init()

MYSQL *mysql_init(MYSQL *mysql)

Descrição

Aloca ou inicializa um objeto MYSQL apropriado para mysql_real_connect(). Se mysql é 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.

12.1.3.32. 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). Veja mais informações sobre isto na Seção 6.3.6.2, “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.

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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.3.38. 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 MySQL. 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.

Veja mais informações sobre isto na 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.

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

12.1.3.40. 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çãoTipo de argumentoFunção
MYSQL_OPT_CONNECT_TIMEOUTunsigned int *Tempo limite de conexão em segundos.
MYSQL_OPT_COMPRESSNão usadoUsa o protocolo cliente/servidor compactado.
MYSQL_OPT_READ_TIMEOUTunsigned int *Limite de tempo para a leitura do servidor (funciona atualmente apenas no Windows em conexões TCP/IP)
MYSQL_OPT_WRITE_TIMEOUTunsigned int *Limite de tempo para a escrita no servidor (funciona atualmente apenas no Windows em conexões TCP/IP)
MYSQL_OPT_LOCAL_INFILEponteiro para unsigned integer opcionalSe nenhum ponteiro for dado ou se apontar para um unsigned int != 0 o comando LOAD LOCAL INFILE está habilitado.
MYSQL_OPT_NAMED_PIPENão usadoUsa named pipes para conectar ao servidor MySQL no NT.
MYSQL_INIT_COMMANDchar *Comando para executar ao conectar ao servidor MySQL. Será automaticamente executado ao se reconectar.
MYSQL_READ_DEFAULT_FILEchar *Lê opções do arquivo de opções definido no lugar de my.cnf.
MYSQL_READ_DEFAULT_GROUPchar *Lê opções do grupo indicado no arquivo my.cnf ou no arquivo especificado com MYSQL_READ_DEFAULT_FILE.
MYSQL_OPT_PROTOCOLunsigned int *Tipo de protocolo usado. Deve ser um dos valores apresentados em mysql_protocol_type definido no mysql.h.
MYSQL_SHARED_MEMORY_BASE_NAMEchar*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çãoDescrição
connect-timeoutTempo limite de conexão em segundos. No Linux este tempo limite também é utilizado para esperar pela primeira resposta do servidor
compressUtiliza o protocolo cliente/servidor compactado.
databaseConecta a este banco de dados se nenhum banco de dados for especificado no comando de conexão.
debugOpções de depuração.
disable-local-infileDisabilita o uso de LOAD DATA LOCAL.
hostNome de máquina padrão.
init-commandComando para executar ao conectar ao servidor MySQL. Será executado automaticamente ao reconectar.
interactive-timeoutO mesmo que o especificado em CLIENT_INTERACTIVE para mysql_real_connect(). Veja mais informações sobre isto na 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_packetTamanho máximo dos pacotes que o cliente pode ler do servidor.
passwordSenha padrão.
pipeUsa named pipes para conectar ao servidor MySQL no NT.
protocol=(TCP | SOCKET | PIPE | MEMORY)Qual protocolo usar ao conectar no servidor (Novo na versão 4.1)
portNúmero padrão da porta.
return-found-rowsDiz ao mysql_info() para retornar registros encontrados no lugar de registros atualizados ao usar UPDATE.
shared-memory-base-name=nameNome da memória comprtilhada utilizada para conectar ao servidor (o padrão é "MySQL"). Novo na versão 4.1.
socketNúmero padrão do socket.
userUtilizador 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 Seção 4.1.2, “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.

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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.3.42. 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. Veja mais informações sobre isto na 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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.3.43. 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 MySQL 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:

  • O primeiro parâmetro deve ser o endereço de uma estrutura MYSQL existente. Antes de chamar mysql_real_connect() você deve chamar mysql_init() para inicializar a estrutura MYSQL. Você pode alterar vária opções de conexão com a chamada mysql_options(). Veja mais informações sobre isto na Seção 12.1.3.40, “mysql_options().

  • O valor de host pode ser tanto um nome de máquivo quanto um endereço IP. Se host é NULL ou a string "localhost", a conexão é feita na máquina local. Se o SO suporta sockets (Unix) ou named pipes (Windows), eles são utilizados em vez de TCP/IP para a conexão ao servidor.

  • O parâmetro user contém a indetificação do utilizador MySQL. Se user é NULL ou a string vazia "", considera-se o utilizador padrão. Sob Unix, ele é o login atual. Sob ODBC no Windows, o utilizador atual deve ser especificado explicitamente. Veja mais informações sobre isto na Seção 12.2.2, “Como Preencher os Vários Campos no Programa de Administração do ODBC”.

  • O parâmetro passwd contém a senha para user. Se passwd é NULL, somente entradas na tabela user para utilizadores que tenham campo de senha em branco (vazia) serão verificados ipor um padrão coincidenete. Isto permite que o admistrador do banco de dados configure o sistema de privilégios do MySQL de tal maneira que utilizadores os utilizadores conseguirão privileios diferentes, dependendo se ele espcificou ou não uma senha.

    Nota: Não tente criptografar a senha antes de chamar mysql_real_connect(); senhas criptografadas são tratadas automaticamente pela API cliente.

  • db é o nome de banco de dados. Se db não é NULL, a conexão definirá o banco de dados padrão com este valor.

  • Se port não é 0, o valor será usado como o número da porta para as conexões TCP/IP. Note que o parâmetro host determina o tipo da conexão.

  • Se unix_socket não é NULL, a string especifica o socket ou named pipe que deve ser usado. Note que o parâmetro host determina o tipo de conexão.

  • O valor de client_flag é normalmente 0, mas pode ser definido como uma combinação dos parâmetro seguintes em circunstâncias especiais:

    Nome do parâmetroDescrição do parâmetro
    CLIENT_COMPRESSUsa protocolo compactado.
    CLIENT_FOUND_ROWSRetorna o número de linhas encontradas (correspondentes a um padrão), não o número de linha efetivo.
    CLIENT_IGNORE_SPACEPermite espaço depois do nome de funções. torna todos os nomes de funções palavras reservadas.
    CLIENT_INTERACTIVEPermite interactive_timeout segundos (no lugar de wait_timeout segundos) de inatividade antes de fechar a conexão.
    CLIENT_LOCAL_FILESHabilita LOAD DATA LOCAL.
    CLIENT_MULTI_STATEMENTSDiz ao servidor que o cliente pode enviar consultas multi linhas (separado com ‘;’). Se este parâmetro não está definido, consultas de multil linhas está disabilitado. (Novo na versão 4.1).
    CLIENT_MULTI_RESULTSDiz ao servidor que o cliente pode tratar multíplos conjuntos de resultados de um multi consulta ou stored procedures. Isto é definido automaticamente se CLIENT_MULTI_STATEMENTS está lidado. Novo na versão 4.1.
    CLIENT_NO_SCHEMANão permite a sintaxe db_name.nome_tabela.nome_coluna. Isto é para o ODBC. Ele faz com que o analizador gere um erro se você utilizar aquela sintaxe. É útil para achar erros em alguns programas ODBC.
    CLIENT_ODBCO cliente é um cliente ODBC. Torna o mysqld mais amigável ao ODBC.
    CLIENT_SSLUsa SSL (protocolo criptografado). Esta opção não deve ser configuração pelo aplicativo; ele é definida internamente na biblioteca cliente.

Valor Retornado

Um handle de conexão MYSQL* se a conexão foi obtida com sucesso, 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

  • CR_CONN_HOST_ERROR

    Falhou ao conectar ao servidor MySQL.

  • CR_CONNECTION_ERROR

    Falhou ao conectar ao servidor MySQL local.

  • CR_IPSOCK_ERROR

    Falhou au criar um socket IP.

  • CR_OUT_OF_MEMORY

    Sem memória.

  • CR_SOCKET_CREATE_ERROR

    Falhou ao criar um socket Unix.

  • CR_UNKNOWN_HOST

    Falhou ao procurar o endereço IP para o nome de maquina.

  • CR_VERSION_ERROR

    Um erro de protocolo resultou da tentativa de conexao a um servidor com uma biblioteca cliente que utiliza uma versão de protocolo diferente. Isto pode acontecer se você utiliza uma biblioteca cliente muito antiga para se conectar a um novo servidor qua não foi iniciado com a opção --old-protocol.

  • CR_NAMEDPIPEOPEN_ERROR

    Falhou ao criar um named pipe no Windows.

  • CR_NAMEDPIPEWAIT_ERROR

    Falhou ao esperar por um named pipe no Windows.

  • CR_NAMEDPIPESETSTATE_ERROR

    Falhou ao conseguir mainpulador do pipe no Windows.

  • CR_SERVER_LOST

    Se connect_timeout > 0 e leva mais que connect_timeout segundos para conectar ao servidor ou se o servidro foi finalizado ao executar o init-command.

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 MySQL 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 MySQL de um modo fora do padrão.

Note que sob a conexão, mysql_real_connect() define o parâmetro reconnect (parte da estrutura MYSQL) 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.

12.1.3.44. 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. Veja mais informações sobre isto na Seção 6.1.1.1, “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 Seção 6.1.1, “Literais: Como Gravar Strings e Numerais”). (O MySQL 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.

12.1.3.45. 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(). Veja mais informações sobre isto na 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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.3.46. mysql_reload()

int mysql_reload(MYSQL *mysql)

Descrição

Diz ao servidor MySQL 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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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

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

12.1.3.49. 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 mysql. 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 utilizador 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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.3.50. 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_ONHabilita suporte a multi instruções.
MYSQL_OPTION_MULTI_STATEMENTS_OFFDesabilita suporte a multi instruções.

Valores Retornados

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

Erros

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • ER_UNKNOWN_COM_ERROR

    O servidor não suportou mysql_set_server_option() (que o caso no qual o servidor é mais antigo que 4.1.1) ou o servidor não suportou a opção que se tentou definir.

12.1.3.51. mysql_shutdown()

int mysql_shutdown(MYSQL *mysql)

Descrição

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

Valor Retornado

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

Erros

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.3.52. 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 MySQL 4.1.1.

Valores Retornados

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

Veja Também

Veja mais informações sobre isto na Seção 12.1.3.12, “mysql_errno(). Veja mais informações sobre isto na Seção 12.1.3.13, “mysql_error(). Veja mais informações sobre isto na Seção 12.1.7.18, “mysql_stmt_sqlstate().

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

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

  • key é o caminho para o arquivo de chave.

  • cert é o caminho para o arquivo do certificado.

  • ca é o caminho para o arquivo de autoridade do certificado.

  • capath é o caminho para um diretório que contém certificados SSL CA confiáveis no formato pem.

  • cipher é a lista de cifras permitidas para uso para criptografia SSL.

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.

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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.3.55. 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 com sucesso (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. Veja mais informações sobre isto na 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.

Veja mais informações sobre isto na 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.

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_OUT_OF_MEMORY

    Sem memoria.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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

12.1.3.57. 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 com sucesso (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 utilizador 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.

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_OUT_OF_MEMORY

    Sem memória.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.3.58. 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 MySQL 4.1.

Valores de Retorno

A contagem de avisos.

Errors

Nenhum.

12.1.3.59. mysql_commit()

my_bool mysql_commit(MYSQL *mysql)

Descrição

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

Valor Retornado

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

Erros

Nenhum.

12.1.3.60. mysql_rollback()

my_bool mysql_rollback(MYSQL *mysql)

Descrição

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

Valor Retornado

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

Erros

Nenhum.

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

12.1.3.62. 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 MySQL 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.

Veja mais informações sobre isto na Seção 12.1.8, “Tratando a Execução de Múltiplas Consultas na API C”. Veja mais informações sobre isto na Seção 12.1.3.63, “mysql_next_result().

Erros

Nenhum.

12.1.3.63. 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 MySQL 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.

Veja mais informações sobre isto na 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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada. Por exemplo se você não chamar mysql_use_result() para um resulatdo anterior.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

12.1.4. Instruções Preparadas da API C

A partir da versão 4.1 do MySQL, 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.

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

  • MYSQL_STMT

    Esta estrutura representa uma instrução preparada. Uma instrução é preparada chamando mysql_prepare(), que retorna uma handler da instrução, que é um ponteiro para um MYSQL_STMT. O handler é usado para todas as funções subsequentes relacionadas às instruções.

    A estrutura MYSQL_STMT não possui membros para uso em aplicação.

    Múltiplos handles de instruções podem estar associados com uma única conexão. O limite no número de handlers depende dos recursos de sistemas disponíveis.

  • MYSQL_BIND

    Esta estrutura é usada tanto para a entrada da consulta (valores de dados enviados ao servidor) quanto para saída (valores de resultado retornados do servidor). Para entrada, ela é usada com mysql_bind_param() para ligar os valores os dados dos parâmetros para armazenar em buffers para uso pelo mysql_execute(). Para saída, ela é usada com mysql_bind_result() para ligar o buffer de resultado para uso na busca de registros com mysql_fetch().

    A estrutura MYSQL_BIND contém os seguintes membros para uso em aplicativos. Cada um deles utiliza tanto a entrada quanto a saída, embora algumas vezes sejam para diferentes propósitos dependendo da direção da transfer6encia de dados:

    • enum enum_field_types buffer_type

      O tipo do buffer. Os valores de buffer_type estão listados posteriormente nesta seção. Para entrada, buffer_type indica que tipo de valor você está ligando a um parâmetro de uma consulta. Para a saída, ele indica que tipo de valor você espera receber em um buffer de resultado.

    • void *buffer

      Para entrada, este é um ponteiro para o buffer no qual os dados de parâmetros de uma consulta, estão armazenados. Para saída, ele é um ponteiro para o buffer no qual se deve retornar o valor de uma coluna do resultado. Para tipos numéricos, o buffer deve apontar para uma variável do tipo C apropriado. (Se você estiver associando a variável com uma coluna que tem o atributo UNSIGNED, a variável deve ser um tipo C unsigned.) Para colunas de tipo data e hora, o buffer deve apontar para uma estrutura MYSQL_TIME. Para colunas do tipo caracter e string binária, o buffer aponta para um buffer de caracter.

    • unsigned long buffer_length

      O tamanho atual de *buffer em bytes. Ele indica a quantidade máxima de dados que pode ser armazenado no buffer. Para caracteres e dados C binários, o valor buffer_length especifica o tamanho do *buffer quando utilizado com mysql_bind_param(), ou o número máximo de bytes de dados que pode ser buscado em um buffer quando usado com mysql_bind_result().

    • unsigned long *length

      Um ponteiro para uma variável unsigned long que indica o número atual de bytes de dados armazenado em *buffer. length é usado é usado para caracteres e dados C binários. Para a ligação dos dados do parâmetro de entrada, length aponta para uma variável unsigned long que indica o tamanho do valor do parâmetro armazenado em *buffer; isto é usado pelo mysql_execute(). Se o tamanho é um ponteiro nulo, o protocolo assume que todos os caracteres e dados binários são terminados com null.

      Para ligação dos valores de saída, mysql_fetch() coloca o tamanho dos valores de coluna retornados na variável para onde o *length aponta.

      length é ignorado por tipos de dados numéricos e trmporais porque o tamanho do valord dos dados é determinado pelo valor buffer_type.

    • bool *is_null

      Este membro aponta para uma variável my_bool que é verdadeiro se um valor é NULL, falso se ele não é NULL. Para entrada, defina *IS_NULL como verdadeiro para indicar que você está passando um valor NULL como um parâmetro. Para saída, este valor é verdadeiro se o valor de um resultado retornado de uma consulta é NULL.

  • MYSQL_TIME

    Esta estrutura é utilizada para enviar e receber dados DATE, TIME, DATETIME e TIMESTAMP diretamente de e para o servidor. Isto é feito configurando o membro buffer_type de uma estrutura MYSQL_BIND para um dos tipos temporais e configurando o membro buffer para apontar para uma estrutura MYSQL_TIME.

    A estrutura MYSQL_TIME contém os seguintes membros:

    • unsigned int year

      O ano.

    • unsigned int month

      O mês do ano.

    • unsigned int day

      O dia do mês.

    • unsigned int hour

      A hora do dia.

    • unsigned int minute

      O minuto da hora.

    • unsigned int second

      Os segundos.

    • my_bool neg

      Um parâmetrio booleano para indicar se o tempo é negativo.

    • unsigned long second_part

      A parte fracionária do segundo. Este membro não é atualmente usado.

    Apenas aquelas partes de uma estrutura MYSQL_TIME que se aplica a um dado tipo de valor temporal são usados: Os elementos year, month e day são usados para valores DATE, DATETIME e TIMESTAMP. Os elementos hour, minute e second são usados para valores TIME, DATETIME e TIMESTAMP. Veja mais informações sobre isto na Seção 12.1.9, “Manipulando Valores de Data e Hora na API C”.

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 ValorTipo SQLTipo C
MYSQL_TYPE_TINYTINYINTchar
MYSQL_TYPE_SHORTSMALLINTshort int
MYSQL_TYPE_LONGINTlong int
MYSQL_TYPE_LONGLONGBIGINTlong long int
MYSQL_TYPE_FLOATFLOATfloat
MYSQL_TYPE_DOUBLEDOUBLEdouble
MYSQL_TYPE_TIMETIMEMYSQL_TIME
MYSQL_TYPE_DATEDATEMYSQL_TIME
MYSQL_TYPE_DATETIMEDATETIMEMYSQL_TIME
MYSQL_TYPE_TIMESTAMPTIMESTAMPMYSQL_TIME
MYSQL_TYPE_STRINGCHAR 
MYSQL_TYPE_VAR_STRINGVARCHAR 
MYSQL_TYPE_TINY_BLOBTINYBLOB/TINYTEXT 
MYSQL_TYPE_BLOBBLOB/TEXT 
MYSQL_TYPE_MEDIUM_BLOBMEDIUMBLOB/MEDIUMTEXT 
MYSQL_TYPE_LONG_BLOBLONGBLOB/LONGTEXT 

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

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

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

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

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

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

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

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

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

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

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

Execution Steps:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_OUT_OF_MEMORY

    Falta de memória

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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().

12.1.7.2. 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().

12.1.7.3. 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:

  • mysql_num_fields()

  • mysql_fetch_field()

  • mysql_fetch_field_direct()

  • mysql_fetch_fields()

  • mysql_field_count()

  • mysql_field_seek()

  • mysql_field_tell()

  • mysql_free_result()

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

  • CR_OUT_OF_MEMORY

    Falta de memória

  • CR_UNKNOWN_ERROR

    Ocorreu um erro desconhecido

Exemplo

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

12.1.7.4. 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 com sucesso. Diferente de zero se ocorrer um erro.

Erros

  • CR_NO_PREPARE_STMT

    Não existem instruções preparadas

  • CR_NO_PARAMETERS_EXISTS

    Não existem parâmetros para ligar

  • CR_INVALID_BUFFER_USE

    Indica se a ligação forncerá dados longos em bolcos e se o tipo de buffer é binário ou não é uma string.

  • CR_UNSUPPORTED_PARAM_TYPE

    A conversão não é suportada. Possivelmente o valor de buffer_type é inválido ou não é um dos tipos suportados listados acima.

  • CR_OUT_OF_MEMORY

    Falta de memória

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

Exemplo

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

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

  • CR_NO_PREPARE_QUERY

    Nenhuma consulta preprada previamente para execução

  • CR_ALL_PARAMS_NOT_BOUND

    Não forma fornecidos todos os dados de parâmetros.

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_OUT_OF_MEMORY

    Falta de memória

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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 mysql é 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.

12.1.7.6. 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().

12.1.7.7. 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 MySQL 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

  • CR_NO_PREPARE_STMT

    Não existe instruções preparadas

  • CR_UNSUPPORTED_PARAM_TYPE

    A conversão não é suportada. Possivelmente o buffer_type é inválido ou não na lista dos tipos de buffers suportados

  • CR_OUT_OF_MEMORY

    Falta de memória

  • CR_UNKNOWN_ERROR

    Ocorreu um erro desconhecido

Exemplo

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

12.1.7.8. 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 com sucesso (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 com sucesso ou Diferente de zero em caso de erro.

Erros

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_OUT_OF_MEMORY

    Falta de memoria.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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

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

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

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

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

TypeLength
MYSQL_TYPE_TINY1
MYSQL_TYPE_SHORT2
MYSQL_TYPE_LONG4
MYSQL_TYPE_LONGLONG8
MYSQL_TYPE_FLOAT4
MYSQL_TYPE_DOUBLE8
MYSQL_TYPE_TIMEsizeof(MYSQL_TIME)
MYSQL_TYPE_DATEsizeof(MYSQL_TIME)
MYSQL_TYPE_DATETIMEsizeof(MYSQL_TIME)
MYSQL_TYPE_STRINGtam_dado
MYSQL_TYPE_BLOBtam_dado

Valor Retornado

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

Erros

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_OUT_OF_MEMORY

    Falta de memoria.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_SERVER_LOST

    A conexão ao servidor MySQL foi perdida durante a consulta.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

  • CR_UNSUPPORTED_PARAM_TYPE

    O tipo de buffer é MYSQL_TYPE_DATE, MYSQL_TYPE_TIME, MYSQL_TYPE_DATETIME, ou MYSQL_TYPE_TIMESTAMP, mas o tipo de dado não é DATE, TIME, DATETIME ou TIMESTAMP.

  • Todos os outros erros de conversão não suportada são retornados de mysql_bind_result().

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 mysql ç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, " MySQL 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);
}

12.1.7.14. 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 com sucesso para o servidir. Diferente de zero se ocorrer um erro.

Erros

  • CR_INVALID_PARAMETER_NO

    Número de parâmetro inválido

  • CR_COMMANDS_OUT_OF_SYNC

    Os comando foram executados em uma ordem inpropriada.

  • CR_OUT_OF_MEMORY

    Falta de memoria.

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_UNKNOWN_ERROR

    Um erro desconhecido ocorreu.

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 mysql é 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);
}

12.1.7.15. 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 com sucesso. Diferente de zero se ocorrer um erro.

Erros

  • CR_SERVER_GONE_ERROR

    O servidor MySQL foi finalizado.

  • CR_UNKNOWN_ERROR

    Ocorreu um erro desconhecido.

Exemplo

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

12.1.7.16. 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 MySQL. Números de mensagens de erro do servidor estão listado no arquivo mysqld_error.h. Na distribuição fonte do MySQL 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

12.1.7.17. 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 MySQL. 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

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

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

A partir da versão 4.1, o MySQL 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))

12.1.9. Manipulando Valores de Data e Hora na API C

O novo protocolo binário disponível no MySQL 4.1 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 mysql é 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);
..

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

Você precisa utilizar as seguintes funções quando quiser criar um cliente em uma thread. Veja mais informações sobre isto na Seção 12.1.14, “Como Fazer um Cliente em Threads”.

12.1.10.1. 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 MySQL. Ela inicializa algumas varáveis globais que o MySQL 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

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

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

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

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

Você deve utilizar as seguints funções se você quiser permitir que a sua aplicação seja ligada a biblicoteca de servidor MySQL embutido. Veja mais informações sobre isto na 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 MySQL embutido e um servidor stand-alone sem modificar nenhum código.

12.1.11.1. 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 MySQL. 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. Veja mais informações sobre isto na Seção 4.1.2, “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 MySQL API functions here */
mysql_server_end();
return EXIT_SUCCESS;
}

Valor Retornado

0 se okay, 1 se ocorrer um erro.

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

12.1.12. Dúvidas e problemas comuns ao utilzar a API C

12.1.12.1. 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 com sucesso ao mysql_query(). Quando isto acontece, significa que uma da seguintes condições ocorreu:

  • Existe um falha no malloc() (por exemplo, se o resultado for muito grande).

  • Os dados não podem ser lidos (ocorreu um erro na conexão).

  • A consulta não retornou dados (por exemplo, ela era um INSERT, UPDATE, ou DELETE).

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().

12.1.12.2. Que Resultados Posso Onbetr de uma Consulta?

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

  • mysql_affected_rows() retorna o número de registros afetados pela última consulta ao se fazer uma INSERT, UPDATE, ou DELETE. Uma exceção é que se for utilizado DELETE sem uma cláusula WHERE, a tabela é recriada vazia, o que é mais rápido! Neste caso, mysql_affected_rows() retorna zero para o número de registros afetados.

  • mysql_num_rows() retorna o número de registros em um resultado. Com mysql_store_result(), mysql_num_rows() pode ser chamado assim que mysql_store_result() retornar. Com mysql_use_result(), mysql_num_rows() só pode ser chamado depois de ter buscado todos os registros com mysql_fetch_row().

  • mysql_insert_id() retorna o ID gerado pela última consulta que inseriu um registro em uma tabela com índice AUTO_INCREMENT. Veja mais informações sobre isto na Seção 12.1.3.32, “mysql_insert_id().

  • Algumas consultas (LOAD DATA INFILE ..., INSERT INTO ... SELECT ..., UPDATE) retornam informações adcionais. O resultado é retornado por mysql_info(). Veja a descrição de mysql_info() para o formato da string que ela returnou. mysql_info() retorna um ponteiro NULL se não houver informações adicionais.

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

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

12.1.13. Construindo Programas Clientes

Se você compilar clientes MySQL 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 MySQL, 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ê. Veja mais informações sobre isto na Seção 4.9.11, “mysql_config, Opções para compilação do cliente MySQL”.

Você pode utilizá-lo para compila o cliente MySQL 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.

12.1.14. 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 (MySQL), 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. Veja mais informações sobre isto na Seção 12.1, “API C do MySQL”. 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()! Veja mais informações sobre isto na 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:

  • Duas threads não podem enviar uma consaulta ao servidor MySQL ao mesmo tempo na mesma conexão. Em particular, você deve assegurar que entre um mysql_query() e mysql_store_result() nenhuma outra thread está usando a mesma conexão.

  • Várias threads podem acessár resultados diferentes que são recuperados com mysql_store_result().

  • Se você utilizar mysql_use_result, você terá que assegurar que nenhuma outra thread está usando a mesma conexão até que o resultado seja fechado. No entanto, é melhor para clientes em threads que compartilham a mesma conexão utilizar mysql_store_result().

  • Se você quiser utilizar múltiplas threads na mesma conexão, você deve ter uma trava mutex na combinação das chamadas mysql_query() e mysql_store_result(). Uma vez que mysql_store_result() esteja pronto, a trva pode ser liberada e outras threads podem utilizar a mesma conexão.

  • Se você programa com threads POSIX, você pode utilizar pthread_mutex_lock() e pthread_mutex_unlock() para estabelecer e liberar uma trava mutex.

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

Quando você chamar mysql_init() ou mysql_connect(), MySQL 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 MySQL antes de chamar mysql_real_connect().

  2. Chame mysql_thread_init() no manipulador de thread antes de chamar qualquer outra função MySQL.

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

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.

12.1.15. libmysqld, a Biblioteca do Servidor Embutido MySQL

12.1.15.1. Visão Geral da Biblioteca do Servidor MySQL Embutido

A biblioteca do servidor MySQL embutido torna possível executar um servidor MySQL 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 MySQL, 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 MySQL 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çãoQuando 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 MySQL.
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. Veja mais informações sobre isto na Seção 12.1.11.1, “mysql_server_init().

12.1.15.2. Compilando Programas com libmysqld

Para obter uma biblioteca libmysqld você deve configurar o MySQL 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 MySQL 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.

12.1.15.3. Restrições no Uso de um Servidor MySQL Embutido

O servidor embutido tem as seguintes limitações:

  • Não tem suporte a tabelas ISAM. (Isto é feito para tornar a biblioteca menor)

  • No possui funções definidas pelo utilizador (UDF).

  • Não ratreia pilha em caso de descarga de memória.

  • Sem suporte a RAID interno. (Normalmente não é necessário já que a maioria dos SO possui suporte a arquivos grandes).

  • Você pode configurá-lo como servidor ou master (sem replicação).

  • Você não pode conectar ao servidor embutido de um processo externo com sockets ou TCP/IP.

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

12.1.15.4. 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 MySQL está embutido. Veja mais informações sobre isto na Seção 4.1.2, “Arquivo de Opções my.cnf.

  • Coloque as seções comuns na seção [server]. Ela será lida por ambas as versões do MySQL.

  • Coloque a opcões específicas do cliente/servidor na seção [mysqld].

  • Coloque as opções específicas do MySQL embutido na seção [embedded].

  • Coloque as opções específicas da aplicação na seção [ApplicationName_SERVER].

12.1.15.5. Itens a Fazer no Servidor Embutido (TODO)

  • Estamos fornecendo opções para deixar de fora algumas partes do MySQL para tornar a biblioteca menor.

  • Ainda há muita otimização de velocidade a se fazer.

  • O erros são escritos no stderr. Adicionaremos uma opção para especificar um nome de arquivo para eles.

  • Temos que alterar o InnoDB para não ser tão descritivo quando usado em um servidor embutido.

12.1.15.6. 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 MySQL 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 MySQL software is installed in /usr/local/mysql
inc := /usr/local/mysql/include/mysql
lib := /usr/local/mysql/lib
# If you have not installed the MySQL 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

12.1.15.7. Licensiando o Servidor Embutido

O código fonte do MySQL é 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 MySQL 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 MySQL da MySQL AB. Para maiores detalhes, consulte Seção 1.4.3, “Licenças do MySQL”.