Índice
AUTO_INCREMENT
no ODBCEste 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.
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 Secçã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. See Secçã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 Secçã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 Secção 12.1.15, “libmysqld, a Biblioteca do Servidor Embutido MySQL”.
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 tipo | Descrição do tipo |
FIELD_TYPE_TINY | campo TINYINT |
FIELD_TYPE_SHORT | campo SMALLINT |
FIELD_TYPE_LONG | campo INTEGER |
FIELD_TYPE_INT24 | campo MEDIUMINT |
FIELD_TYPE_LONGLONG | campo BIGINT |
FIELD_TYPE_DECIMAL | campo DECIMAL ou NUMERIC |
FIELD_TYPE_FLOAT | campo FLOAT |
FIELD_TYPE_DOUBLE | campo DOUBLE ou REAL |
FIELD_TYPE_TIMESTAMP | campo TIMESTAMP |
FIELD_TYPE_DATE | campo DATE |
FIELD_TYPE_TIME | campo TIME |
FIELD_TYPE_DATETIME | campo DATETIME |
FIELD_TYPE_YEAR | campo YEAR |
FIELD_TYPE_STRING | campo CHAR |
FIELD_TYPE_VAR_STRING | campo VARCHAR |
FIELD_TYPE_BLOB | campo BLOB ou TEXT (usa
max_length para determinar o
tamanho máximo) |
FIELD_TYPE_SET | campo SET |
FIELD_TYPE_ENUM | campo ENUM |
FIELD_TYPE_NULL | campo tipo-NULL |
FIELD_TYPE_CHAR | Deprecado; 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 param | Descrição param |
NOT_NULL_FLAG | Campo não pode ser NULL |
PRI_KEY_FLAG | Campo é parte de uma chave primária |
UNIQUE_KEY_FLAG | Campo é parte de uma chave única |
MULTIPLE_KEY_FLAG | Campo é parte de uma chave não única |
UNSIGNED_FLAG | Campo tem o atributo UNSIGNED |
ZEROFILL_FLAG | Campo tem o atributo ZEROFILL |
BINARY_FLAG | Campo tem o atributo BINARY |
AUTO_INCREMENT_FLAG | Campo tem o atributo AUTO_INCREMENT |
ENUM_FLAG | Campo é um ENUM (obsoleto) |
SET_FLAG | Campo é um SET (obsoleto) |
BLOB_FLAG | Campo é um BLOB ou TEXT
(obsoleto) |
TIMESTAMP_FLAG | Campo é 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 param | Descriçã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.
As funções disponíveis na API C são resumidas aqui e descritas em maiores detalhes em uma seção posterior. See Secção 12.1.3, “Descrição das Funções da API C”.
Função | Descrição |
mysql_affected_rows() | Retorna o número de linhas alteradas/deletadas/insweridas pela última
consulta \ UPDATE ,
DELETE , ou INSERT . |
mysql_change_user() | Muda o usuario em um banco de dados em uma conexão aberta. |
mysql_character_set_name() | Retorna o nome do conjunto de carcters padrão para a conexão. |
mysql_close() | Fecha ua conexão com o servidor |
mysql_connect() | Se conecta ao servidro 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,
usuários e senha). Conectado,
mysql_real_connect()
define o parâmetro
reconnect
(parte da estrutura MYSQL) para um
valor de 1
. Este parâmetro indica, no evento
que uma consulta não pode ser realizada por perda de conexão,
para tentar reconectar ao servidor ao antes de desistir. Quando
não precisar mais da conexão, chame
mysql_close()
para terminá-la.
Enquanto a conexão estiver ativa, o cliente pode enviar
consultas SQL para o servidor usando
mysql_query()
ou
mysql_real_query()
. A diferença entre os
dois é que mysql_query()
espera que a
consulta seja especificada como uma string terminada em null,
enquanto mysql_real_query()
espera um string
de tamanho fixa. Se a string conter dados binários (a qual pode
incluir bytes null), vocêdeve usar
mysql_real_query()
.
Para cada consulta não-SELECT
(por exemplo,
INSERT
, UPDATE
,
DELETE
), você pode descobrir quantas linhas
foram alteradas (afetadas) chamando
mysql_affected_rows()
.
Para consultas SELECT
, você retorna os
registros selecionados como um resultado. (Note que algumas
intruções são como a SELECT
ao retornar
registros. Elas incluem SHOW
,
DESCRIBE
e EXPLAIN
. elas
devem ser tratadas da mesma maneira que instruções
SELECT
.)
Existem dois modos para um cliente processa o resultado. Um mode
é recuperar todo o resultado de uma vez chamando
mysql_store_result()
. Esta função busca no
servidor todas as linhas retornadas pela consulta e as armazena
no cliente. O segundo modo é o cliente iniciar um retorno do
resultado registro por registro chamando
mysql_use_result()
. Esta função inicia o
retorno, mas não busca realmente nenhuma linha do servidor.
Em ambos os casos, acesse registros chamando
mysql_fetch_row()
. Com
mysql_store_result()
,
mysql_fetch_row()
acessa registros que já
tenham sido buscado do servidor. Com
mysql_use_result()
,
mysql_fetch_row()
recupera, na verdade, o
registro do servidor. Informações sobre o tamanho dos dados em
cada registro é disponível pela chamada
mysql_fetch_lengths()
.
Depois de finalizar o uso do resultado, chame
mysql_free_result()
para liberar a memória
usada por ele.
Os dois mecanismos de recuperação são complementares.
Programas clientes devem escolher a abordagem mais apropriada
para suas necessidades. Na prática, clientes tendem a utilizar
mysql_store_result()
.
Uma vantagem de mysql_store_result()
é que
pelo fato de todos os registros serem trazidos para o cliente,
você não só pode acessar registros sequencialmente, mas
também pode mover para tarz e para frente no resultado
utilizando mysql_data_seek()
ou
mysql_row_seek()
para altera a posição
atual do registro no resultado. Você também pode saber quantas
linhas existem chamando mysql_num_rows()
. Por
outro lado, a necessidade de memória para
mysql_store_result()
pode ser muito alta para
resultados grandes e você encontrará como mais facilidade
condições de estouro de memória.
Uma vantagem de mysql_use_result()
é que o
clientes exige menos memória para o resultado porque ele mantem
apenas um registro por vez (por haver menor sobrecarga de
alocação, mysql_use_result()
pode ser mais
rápido). As desvantagens são que você deve processar cada
registro rapidamente para evitar prender o servidor, você não
tem acesso aleatório aos registros no resultado (você só pode
acessá-los sequencialmente) e você não sabe quantos registros
existem no resultado até que você recupere todos eles. Além
disso, você deve recuperar
todos os registros mesmo que você já tenham encontrado a
informação que procura antes do finalizar o conjunto de
resultados.
A API torna possível para os clientes responder apropriadamente
as consultas (recuperando somente os regiostros necessários)
sem saber se a consulta é uma instrução
SELECT
ou não. Você pode fazer isto
chamando mysql_store_result()
depois de cada
mysql_query()
(ou
mysql_real_query()
). Se o resultado for
obtido 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.
mysql_affected_rows()
mysql_change_user()
mysql_character_set_name()
mysql_close()
mysql_connect()
mysql_create_db()
mysql_data_seek()
mysql_debug()
mysql_drop_db()
mysql_dump_debug_info()
mysql_eof()
mysql_errno()
mysql_error()
mysql_escape_string()
mysql_fetch_field()
mysql_fetch_fields()
mysql_fetch_field_direct()
mysql_fetch_lengths()
mysql_fetch_row()
mysql_field_count()
mysql_field_seek()
mysql_field_tell()
mysql_free_result()
mysql_get_client_info()
mysql_get_client_version()
mysql_get_host_info()
mysql_get_proto_info()
mysql_get_server_info()
mysql_get_server_version()
mysql_info()
mysql_init()
mysql_insert_id()
mysql_kill()
mysql_list_dbs()
mysql_list_fields()
mysql_list_processes()
mysql_list_tables()
mysql_num_fields()
mysql_num_rows()
mysql_options()
mysql_ping()
mysql_query()
mysql_real_connect()
mysql_real_escape_string()
mysql_real_query()
mysql_reload()
mysql_row_seek()
mysql_row_tell()
mysql_select_db()
mysql_set_server_option()
mysql_shutdown()
mysql_sqlstate()
mysql_ssl_set()
mysql_stat()
mysql_store_result()
mysql_thread_id()
mysql_use_result()
mysql_warning_count()
mysql_commit()
mysql_rollback()
mysql_autocommit()
mysql_more_results()
mysql_next_result()
Nas descrições a seguir, um parâmetro ou valor retornado
NULL
significa NULL
no
sentido da linguagem de programação C, não um valor
NULL
do 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()
.
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.
my_bool mysql_change_user(MYSQL *mysql, const char
*user, const char *password, const char *db)
Descrição
Altera o usuário é faz com que o banco de dados especificado
por db
se torne o banco de dados padrão
(atual) na conexão especificada por 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
usuário conectado possa ser autenticado ou se ele não tiver
permissão para utilizar o banco de dodos. Neste caso o
usuário e o banco de dados não são alterados.
O parâmetro db
pode ser definido como
NULL
se você não dseseja ter um banco de
dados padrão.
A partir da versão 4.0.6 do 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 usuário não foi
alterado.
Valor Retornado
Zero se obteve successo. Diferente de zero se ocorreu um erro.
Erros
O mesmo que pode ser obtido com
mysql_real_connect()
.
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 usuário ou a senha estavam errados.
ER_BAD_DB_ERROR
O banco de dados não existe.
ER_DBACCESS_DENIED_ERROR
O usuário 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)); }
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.
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.
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()
.
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)); }
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.
void mysql_debug(const char *debug)
Descrição
Faz um DBUG_PUSH
com a string dada.
mysql_debug()
usa a biblioteca de
depuração Fred Fish. Para utilizar esta função você deve
compilar a biblioteca cliente para suportar depuração. See
Secção E.1, “Depurando um Servidor MySQL”. See
Secçã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");
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));
int mysql_dump_debug_info(MYSQL *mysql)
Descrição
Instrui o servidor a gravar algumas informações de
depuração no log. Para funcionar, o usuário conectado deve
ter pivilégio SUPER
.
Valor Retornado
Zero se o comando obteve sucesso. Diferete de zero se ocorreu um erro.
Erros
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.
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)); }
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
Secçã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.
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. See Secçã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.
Você deve usar mysql_real_escape_string()
em seu lugar!
Esta função é identica a
mysql_real_escape_string()
exceto que
mysql_real_escape_string()
pega um
manipulador de cnexão como seu primeiro argumento e escapa a
string de acordo com a conjunto de caracteres padrão.
mysql_escape_string()
não utiliza um
argumento de conexão e não respeita o conjunto de caracteres
atual.
MYSQL_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); }
MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES
*result)
Descrição
Retorna um vetor de todas as estruturas
MYSQL_FIELD
no resultado. Cada estrutura
fornece a definição do campo para uma coluna do resultado.
Valor Retornado
Um vetor da estrutura MYSQL_FIELD
para
todas as colunas no resultado.
Erros
Nenhum.
Exemplo
unsigned int num_fields; unsigned int i; MYSQL_FIELD *fields; num_fields = mysql_num_fields(result); fields = mysql_fetch_fields(result); for(i = 0; i < num_fields; i++) { printf("Field %u is %s\n", i, fields[i].name); }
MYSQL_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); }
unsigned long *mysql_fetch_lengths(MYSQL_RES
*result)
Descrição
Retorna o tamanho da coluna do registro atual em um resultado.
Se você planeja copiar calores dos compos, esta informação
de tamanho é útil também para a otimização, porque você
pode evitar a chamada strlen()
. Se o
resultado contém dados biários, você
deveutilizar esta função
para determinar o tamanho dos dados, pois
strlen()
retorna um valor incorreto para
quaquer campo contendo caracteres nulos.
O tamanho para colunas vazias e para colunas contendo valores
NULL
é zero. Para ver como distnguir este
dois casos, veja a descrição de
mysql_fetch_row()
.
Valor Retornado
Um vetor de unsigned long integers (inteiros longos sem sinal)
representando o tamanho de cada coluna (não incluindo nenhuma
caracter nulo). NULL
se ocorrer um erro.
Erros
mysql_fetch_lengths()
só é válido para o
registro atual no resultado. Ele retorna
NULL
se você chamá-lo antes de
mysql_fetch_row()
ou depois de retornar
todos os registros em um resultado.
Exemplo
MYSQL_ROW row; unsigned long *lengths; unsigned int num_fields; unsigned int i; row = mysql_fetch_row(result); if (row) { num_fields = mysql_num_fields(result); lengths = mysql_fetch_lengths(result); for(i = 0; i < num_fields; i++) { printf("Column %u is %lu bytes in length.\n", i, lengths[i]); } }
MYSQL_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"); }
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.
Valor Retornado
Um unsigned integer (inteiro sem sinal) representando o número de campo em um resultado.
Erros
Nenhum.
Exemplo
MYSQL_RES *result; unsigned int num_fields; unsigned int num_rows; if (mysql_query(&mysql,query_string)) { // error } else // query succeeded, process any data returned by it { result = mysql_store_result(&mysql); if (result) // there are rows { num_fields = mysql_num_fields(result); // retrieve rows, then call mysql_free_result(result) } else // mysql_store_result() returned nothing; should it have? { if(mysql_field_count(&mysql) == 0) { // query does not return data // (it was not a SELECT) num_rows = mysql_affected_rows(&mysql); } else // mysql_store_result() should have returned data { fprintf(stderr, "Error: %s\n", mysql_error(&mysql)); } } }
Uma alternativa é substituir a chamada
mysql_field_count(&mysql)
com
mysql_errno(&mysql)
. Neste caso, você
está verificando diretamente um erro de
mysql_store_result()
em vez de conferir o
valor de mysql_field_count()
se a
instrução foi uma SELECT
.
MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES
*result, MYSQL_FIELD_OFFSET offset)
Descrição
Define o cursor campo com o offset dado. A próxima chamada
para mysql_fetch_field()
irá recuperar a
definição de campo da coluna associada com o offset.
Para buscar o inicio de um registro, passe zero como valor do
offset
.
Valor Retornado
O valor anterior do cursor de campo.
Erros
Nenhum.
MYSQL_FIELD_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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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)
. See
Secçã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.
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.
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.
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.
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.
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.
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.
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.
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.
int mysql_options(MYSQL *mysql, enum mysql_option
option, const char *arg)
Descrição
Pode ser usado para definir opções extras de conexão e afetar o comportamento de uma conexão. Esta função pode ser chamada várias vezes para definir diversas opções.
mysql_options()
deve ser chamado depois de
mysql_init()
e antes de
mysql_connect()
ou
mysql_real_connect()
.
O argumento option
é a opção que você
que definir; o argumento arg
é o valor
para a opção. Se a opção é um inteiro, então
arg
deve apontar para o valor do inteiro.
Valores possíveis para as opções:
Opção | Tipo de argumento | Função |
MYSQL_OPT_CONNECT_TIMEOUT | unsigned int * | Tempo limite de conexão em segundos. |
MYSQL_OPT_COMPRESS | Não usado | Usa o protocolo cliente/servidor compactado. |
MYSQL_OPT_READ_TIMEOUT | unsigned int * | Limite de tempo para a leitura do servidor (funciona atualmente apenas no Windows em conexões TCP/IP) |
MYSQL_OPT_WRITE_TIMEOUT | unsigned int * | Limite de tempo para a escrita no servidor (funciona atualmente apenas no Windows em conexões TCP/IP) |
MYSQL_OPT_LOCAL_INFILE | ponteiro para unsigned integer opcional | Se nenhum ponteiro for dado ou se apontar para um unsigned int
!= 0 o comando LOAD LOCAL
INFILE está habilitado. |
MYSQL_OPT_NAMED_PIPE | Não usado | Usa named pipes para conectar ao servidor MySQL no NT. |
MYSQL_INIT_COMMAND | char * | Comando para executar ao conectar ao servidor MySQL. Será automaticamente executado ao se reconectar. |
MYSQL_READ_DEFAULT_FILE | char * | Lê opções do arquivo de opções definido no lugar de
my.cnf . |
MYSQL_READ_DEFAULT_GROUP | char * | Lê opções do grupo indicado no arquivo my.cnf ou
no arquivo especificado com
MYSQL_READ_DEFAULT_FILE . |
MYSQL_OPT_PROTOCOL | unsigned int * | Tipo de protocolo usado. Deve ser um dos valores apresentados em
mysql_protocol_type definido no
mysql.h . |
MYSQL_SHARED_MEMORY_BASE_NAME | char* | Nome do objeto em meória para comunicação com o servidor. Deve ser o
mesmo que a opção
-shared-memory-base-name usada para
o servidor mysqld no qual você quer se conectar. |
Note que o grupo client
é sempre lido se
você utiliza MYSQL_READ_DEFAULT_FILE
ou
MYSQL_READ_DEFAULT_GROUP
.
O grupo especificado no arquivo de opçõs pode conter as seguintes opções:
Opção | Descrição |
connect-timeout | Tempo limite de conexão em segundos. No Linux este tempo limite também é utilizado para esperar pela primeira resposta do servidor |
compress | Utiliza o protocolo cliente/servidor compactado. |
database | Conecta a este banco de dados se nenhum banco de dados for especificado no comando de conexão. |
debug | Opções de depuração. |
disable-local-infile | Disabilita o uso de LOAD DATA LOCAL . |
host | Nome de máquina padrão. |
init-command | Comando para executar ao conectar ao servidor MySQL. Será executado automaticamente ao reconectar. |
interactive-timeout | O mesmo que o especificado em CLIENT_INTERACTIVE para
mysql_real_connect() . See
Secção 12.1.3.43, “mysql_real_connect() ”. |
local-infile[=(0|1)] | Se não houver argumento ou o argumento for diferente de 0 habilita o
uso de LOAD DATA LOCAL . |
max_allowed_packet | Tamanho máximo dos pacotes que o cliente pode ler do servidor. |
password | Senha padrão. |
pipe | Usa named pipes para conectar ao servidor MySQL no NT. |
protocol=(TCP | SOCKET | PIPE | MEMORY) | Qual protocolo usar ao conectar no servidor (Novo na versão 4.1) |
port | Número padrão da porta. |
return-found-rows | Diz ao mysql_info() para retornar registros
encontrados no lugar de registros atualizados ao usar
UPDATE . |
shared-memory-base-name=name | Nome da memória comprtilhada utilizada para conectar ao servidor (o padrão é "MySQL"). Novo na versão 4.1. |
socket | Número padrão do socket. |
user | Usuário padrão. |
Note que timeout
foi substituido por
connect-timeout
, mas
timeout
ainda funcionará por enquanto.
Para maiores informações sobre arquivos de opções, veja
Secçã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
.
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.
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.
See Secçã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.
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()
. See
Secçã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 usuário MySQL. Se
user
é NULL
ou a
string vazia ""
, considera-se o
usuário padrão. Sob Unix, ele é o login atual. Sob ODBC
no Windows, o usuário atual deve ser especificado
explicitamente. See Secçã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 usuários 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 usuários os usuários 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âmetro | Descrição do parâmetro |
CLIENT_COMPRESS | Usa protocolo compactado. |
CLIENT_FOUND_ROWS | Retorna o número de linhas encontradas (correspondentes a um padrão), não o número de linha efetivo. |
CLIENT_IGNORE_SPACE | Permite espaço depois do nome de funções. torna todos os nomes de funções palavras reservadas. |
CLIENT_INTERACTIVE | Permite interactive_timeout segundos (no lugar de
wait_timeout segundos) de
inatividade antes de fechar a conexão. |
CLIENT_LOCAL_FILES | Habilita LOAD DATA LOCAL . |
CLIENT_MULTI_STATEMENTS | Diz 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_RESULTS | Diz 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_SCHEMA | Nã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_ODBC | O cliente é um cliente ODBC. Torna o mysqld mais
amigável ao ODBC. |
CLIENT_SSL | Usa 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.
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. See Secçã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
Secçã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.
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()
.
See Secçã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.
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.
MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result,
MYSQL_ROW_OFFSET offset)
Descrição
Atribui ao cursor de linha um registro arbitrário em
resultado de uma consulta. O valor do
offset
é um offset do registro que deve
ser um valor retornado de mysql_row_tell()
ou mysql_row_seek()
. Este valor não
simplesmente um número de linha; se você quiser buscar um
registro em um resultado usando o número de linha utilize
mysql_data_seek()
.
Esta função exige que a estrutura do resultado contenha todo
o resultado da consulta, assim
mysql_row_seek()
pode ser um usado em
conjunto apenas com mysql_store_result()
, e
não com mysql_use_result()
.
Valor Retornado
O valor anterior do cursor de linha. Este valor pode ser
passado a uma chamada subsequente
mysql_row_seek()
.
Erros
Nenhum.
MYSQL_ROW_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.
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
usuário conectado possa ser autenticado com permissão para
utilizar o banco de dados.
Valor Retornado
Zero em caso de sucesso. Deiferente de zero se ocorrer um erro.
Erros
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.
int mysql_set_server_option(MYSQL *mysql, enum
enum_mysql_set_option option)
Descrição
Habilita ou desabilita uma opção para a conexão.
option
por ter um dos seguintes valores:
MYSQL_OPTION_MULTI_STATEMENTS_ON | Habilita suporte a multi instruções. |
MYSQL_OPTION_MULTI_STATEMENTS_OFF | Desabilita suporte a multi instruções. |
Valores Retornados
Zero em caso de sucesso. Deiferente de zero se ocorrer um erro.
Erros
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.
int mysql_shutdown(MYSQL *mysql)
Descrição
Diz ao servidor de banco de dados para finalizar. O usuário
conectado deve ter privilégio SHUTDOWN
.
Valor Retornado
Zero em caso de sucesso. Deiferente de zero se ocorrer um erro.
Erros
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.
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
Secçã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
See Secção 12.1.3.12, “mysql_errno()
”. See
Secção 12.1.3.13, “mysql_error()
”. See
Secção 12.1.7.18, “mysql_stmt_sqlstate()
”.
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.
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.
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. See Secçã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.
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.
unsigned long mysql_thread_id(MYSQL *mysql)
Descrição
Retorna a ID da thread da conexão atual. Este valor pode ser
usado como um argumento para mysql_kill()
para finalizar a thread.
Se a conexão for perdida e você reconectar com
mysql_ping()
, a ID da thread irá alterar.
Isto significa que você deve obter a ID da thread e
guardá-la para uso posterior. Você deve obtê-la quando
precisar dela.
Valor Retornado
A ID da thread da conexão atual.
Erros
Nenhum.
MYSQL_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 usuário de
digitar um ^S
(parada de tela). Isto irá
prender o servidor e impedir outras threads de atualizar
qualquer tabela na qual o dados esteja sendo buascado.
Ao usar mysql_use_result()
, você deve
executar mysql_fetch_row()
até um valor
NULL
ser retornado, senão, os registros
não buscados retornarão como part do resultado de sua
próxima consulta. A API C fornecerá o erro Commands
out of sync; you can't run this command now
se você
esquecer de fazê-lo.
Você não pode utilizar mysql_data_seek()
,
mysql_row_seek()
,
mysql_row_tell()
,
mysql_num_rows()
, ou
mysql_affected_rows()
com m resultado
retornado de mysql_use_result()
, nem pode
executar outras consultas até que
mysql_use_result()
tenha finalizado. (No
entanto, depois de buscar todos os regitros,
mysql_num_rows()
retornará corretamente o
número de regiostros buscados).
Você deve chamar mysql_free_result()
após
terminar de utilizar o resultado.
Valor Retornado
Uma estrutura de resultado MYSQL_RES
.
NULL
se ocorrer um erro.
Erros
mysql_use_result()
zera
mysql_error
e
mysql_errno
se ela obter sucesso.
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.
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.
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.
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.
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.
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.
See Secção 12.1.8, “Tratando a Execução de Múltiplas Consultas na API C”. See
Secção 12.1.3.63, “mysql_next_result()
”.
Erros
Nenhum.
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.
See Secçã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.
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.
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
. See
Secçã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 Valor | Tipo SQL | Tipo C |
MYSQL_TYPE_TINY | TINYINT | char |
MYSQL_TYPE_SHORT | SMALLINT | short int |
MYSQL_TYPE_LONG | INT | long int |
MYSQL_TYPE_LONGLONG | BIGINT | long long int |
MYSQL_TYPE_FLOAT | FLOAT | float |
MYSQL_TYPE_DOUBLE | DOUBLE | double |
MYSQL_TYPE_TIME | TIME | MYSQL_TIME |
MYSQL_TYPE_DATE | DATE | MYSQL_TIME |
MYSQL_TYPE_DATETIME | DATETIME | MYSQL_TIME |
MYSQL_TYPE_TIMESTAMP | TIMESTAMP | MYSQL_TIME |
MYSQL_TYPE_STRING | CHAR | |
MYSQL_TYPE_VAR_STRING | VARCHAR | |
MYSQL_TYPE_TINY_BLOB | TINYBLOB/TINYTEXT | |
MYSQL_TYPE_BLOB | BLOB/TEXT | |
MYSQL_TYPE_MEDIUM_BLOB | MEDIUMBLOB/MEDIUMTEXT | |
MYSQL_TYPE_LONG_BLOB | LONGBLOB/LONGTEXT |
Uma conversão de tipo implcita pode ser realizada em ambas as direções.
Note: A API para instruções preparadas ainda é assunto de revisão. Esta informação é fornecida para os adeptos, mas esteja ciente que a API pode alterar.
As funções disponíveis nas instruções preparadas estão resumidas aqui e desctias em maiores detalhes em um seção posterior. See Secção 12.1.7, “Descrição das Funções de Instrução Preparada da API C”.
Função | Descrição |
mysql_prepare() | Prepara uma string SQL para execução. |
mysql_param_count() | Retorna o número de parâmetros em uma instrução SQL preparada. |
mysql_get_metadata() | Retorna metadados de instruções preparadas em forma de um conjunto de resultados. |
mysql_bind_param() | Associa o buffers de dados da aplicação com o parâmetro marcado na instrução SQL preparada. |
mysql_execute() | Executa a instrução preparada. |
mysql_stmt_affected_rows() | Retorna o número de registros alteradosi, deletados ou inseridos pela
última consulta UPDATE ,
DELETE , ou INSERT . |
mysql_bind_result() | Associa o buffers de dados da aplicação com colunas no resultado. |
mysql_stmt_store_result() | Retorna o resultado completo para o cliente. |
mysql_stmt_data_seek() | Busca um número de registro arbitrário no resultado de uma consulta. |
mysql_stmt_row_seek() | Busca por um offset de registro no resultado de uma busca, utilizando o
valor reotornado de
mysql_stmt_row_tell() . |
mysql_stmt_row_tell() | Retorna a posição do cursor de registro. |
mysql_stmt_num_rows() | Retorna o total de registros do resultado de uma instrução armazenada. |
mysql_fetch() | Busca o próximo conjunto de dados do resultado e retorna os dados para todas as colunas limites. |
mysql_stmt_close() | Libera a memória usada pela instrução preparada. |
mysql_stmt_errno() | Retorna o número de erro para a última instrução executada. |
mysql_stmt_error() | Retorna a mensagem de erro para a última instrução executada. |
mysql_stmt_sqlstate() | Retorna o código de erro SQLSTATE para a execução da última instrução. |
mysql_send_long_data() | Envia dados longos em blocos para o servidor. |
Chama mysql_prepare()
para preparar e iniciar
o manipulador de instruções,
mysql_bind_param()
para fornecer os dados do
parâmetro e mysql_execute()
para executar a
consulta. Você pode repetir o
mysql_execute()
alterando o valor do
parâmetro no buffer respectivo fornecido por
mysql_bind_param()
.
Se a consulta é uma instrução SELECT
ou
qualquer outra consulta que produz um resultado,
mysql_prepare()
também retornará a
informação dos meta dados do resultado na forma de um
resultado MYSQL_RES
através de um
mysql_get_metadata()
.
Você pode forncer o buffer de resultado usando
mysql_bind_result()
, assim
mysql_fetch()
retornará automaticamente os
dados para este buffer. Esta busca é feita registro a registro.
Você também pode enviar o texto ou dado binário em blocos
para o servidor utilizando
mysql_send_long_data()
, especficando a
opção is_long_data=1
ou
length=MYSQL_LONG_DATA
ou
-2
na estrutura MYSQL_BIND
fornecida com mysql_bind_param()
.
Quando a execução for completada, o handler da instrução
deve ser fechado usando mysql_stmt_close()
para que todos os recursos associados a ele sejam liberados.
Se você obteve os metadados de um resultado de uma instrução
SELECT
chamando
mysql_get_metadata()
, você também deve
liberá-lo usando mysql_free_result()
.
Execution Steps:
Para prepara e executar uma instrução, uma aplicação:
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.
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.
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.
Chama mysql_execute()
para executar a
instrução.
Se a consulta produz um resultado, liga o buffer de dados
usado para retornar o valor do registro chamando
mysql_bind_result()
.
Busca os dados no buffer, registro a registro chamando
mysql_fetch()
repetidas vezes até não
haver mais registros.
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.
mysql_prepare()
mysql_param_count()
mysql_get_metadata()
mysql_bind_param()
mysql_execute()
mysql_stmt_affected_rows()
mysql_bind_result()
mysql_stmt_store_result()
mysql_stmt_data_seek()
mysql_stmt_row_seek()
mysql_stmt_row_tell()
mysql_stmt_num_rows()
mysql_fetch()
mysql_send_long_data()
mysql_stmt_close()
mysql_stmt_errno()
mysql_stmt_error()
mysql_stmt_sqlstate()
Para preparar e executar consultas use as seguites funçoes.
MYSQL_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 Secção 12.1.7.5, “mysql_execute()
”.
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 Secção 12.1.7.5, “mysql_execute()
”.
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 Secção 12.1.7.13, “mysql_fetch()
”
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
Secçã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 Secção 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
Secçã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.
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 Secção 12.1.7.5, “mysql_execute()
”.
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
Secçã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 Secção 12.1.7.13, “mysql_fetch()
”
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
Secçã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.
void mysql_stmt_data_seek(MYSQL_STMT *stmt,
my_ulonglong offset)
Descrição
Busca um registro arbitrário no resultado de uma instrução.
O valor do offset
é um número de registro
e deve estar na faixa de 0 a
mysql_stmt_num_rows(stmt)-1
.
Esta função exige que a estrutura do resultado da
instrução contenha todo o resultado da última consulta
executada, assim mysql_stmt_data_seek()
pode ser usada em conjunto apenas com
mysql_stmt_store_result()
.
Valor Retornado
Nenhum.
Erros
Nenhum.
MYSQL_ROW_OFFSET mysql_stmt_row_seek(MYSQL_STMT
*stmt, MYSQL_ROW_OFFSET offset)
Descrição
Define o cursor de linha com um registro arbitrário em um
resultado de instrução. O valor do offset
é um offset de registro e deve ser um valor retornado de
mysql_stmt_row_tell()
ou
mysql_stmt_row_seek()
. Este valor não é
um número de linha; se você quiser buscar um registro em um
resultado usando um número de linha, utilize
mysql_stmt_data_seek()
.
Esta função exige que a estrutura do resultado contenha todo
o resultado da consulta, assim
mysql_stmt_row_seek()
pode ser usado em
conjunto apenas com
mysql_stmt_store_result()
.
Valor Retornado
O valor anterior do cursor de linha. Este valor pode ser
passado a uma chamada subsequente de
mysql_stmt_row_seek()
.
Erros
Nenhum.
MYSQL_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.
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.
int mysql_fetch(MYSQL_STMT *stmt)
Descrição
mysql_fetch()
retorna o próximo registro
no resultado. Ele pode ser chamado apenas enquanto existir o
conjunto de resultados. Per exemplo, depois de uma chamada de
mysql_execute()
que cria o resultado ou
depois de mysql_stmt_store_result()
, que é
chamado depois de mysql_execute()
para
armazenar todo o resultado.
mysql_fetch
retorna os dados de uma linha
usando o buffers limitado por
mysql_bind_result()
. Ele retorna os dados
neste buffer para todas as colunas no registro atual e os
tamanhos são retornados para o apontador
length
.
Note que, todas as colunas devem ser limitadas pela
aplicação antes de chamar mysql_fetch()
.
Se um valor do dado buscado é um valor
NULL
, o valor *is_null
da estrutura MYSQL_BIND
correspondente
contém VERDADEIRO (1). Senão, o dado e seu tamanho é
retornado nos elementos *buffer
e
*length
baseados no tipo de buffer
especificado pela aplicação. Cada tipo numérico e temporal
tem um tamanho fixo como mostrado na tabela a seguir. O tamano
dos tipos strings dependem do tasmanho do valor dos dados
atual, como indicado por data_length
.
Type | Length |
MYSQL_TYPE_TINY | 1 |
MYSQL_TYPE_SHORT | 2 |
MYSQL_TYPE_LONG | 4 |
MYSQL_TYPE_LONGLONG | 8 |
MYSQL_TYPE_FLOAT | 4 |
MYSQL_TYPE_DOUBLE | 8 |
MYSQL_TYPE_TIME | sizeof(MYSQL_TIME) |
MYSQL_TYPE_DATE | sizeof(MYSQL_TIME) |
MYSQL_TYPE_DATETIME | sizeof(MYSQL_TIME) |
MYSQL_TYPE_STRING | tam_dado |
MYSQL_TYPE_BLOB | tam_dado |
Valor Retornado
Valor retornado | Descrição |
0 | Sucesso, o dado foi buscado para o buffers de dados da aplicação. |
1 | Ocorreu um erro. O código e a mensagem de erro podem ser obtidos
chamando mysql_stmt_errno() e
mysql_stmt_error() . |
MYSQL_NO_DATA | Não existem mais registros/dados |
Erros
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
Secçã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); }
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); }
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 Secção 12.1.7.5, “mysql_execute()
”.
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
Secção 13.1, “Erros Retornados”.
Valor Retornado
Um valor de código de erro. Zero se não ocorreu erro.
Erros
Nenhum
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
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
Secçã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.
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))
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
Secçã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:
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.
Configure o membro buffer
da estrutura
MYSQL_BIND
com o endereço da estrutura
MYSQL_TIME
na qual você passrá o valor
temporal.
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); ..
Você precisa utilizar as seguintes funções quando quiser criar um cliente em uma thread. See Secção 12.1.14, “Como Fazer um Cliente em Threads”.
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
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.
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.
Você deve utilizar as seguints funções se você quiser permitir que a sua aplicação seja ligada a biblicoteca de servidor MySQL embutido. See Secçã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.
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. See Secçã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.
É 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()
.
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
. See
Secçã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.
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
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.
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ê. See
Secçã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.
A biblioteca cliente é quase segura com threads. O maior
problema é que a subrotinas em net.c
que
leem dos sockets não são seguras a interrupções. Isto foi
feito pesando que você pudesse desejar ter o seu próprio
alarme que possa quebrar uma longa leitura no servidor. Se você
instalar manipuladores de interrupção para a interrupção
SIGPIPE
, o manipulador socket deve ser segura
com threads.
Nos binários antigos que distribuímos em nosso web site (http://www.mysql.com/), as bibliotecas clientes não estão normalmente compiladas com a opção de segurança com thread (os binários são complados com segurança com thread por padrão). Distribuições binárias mais novas devem ter uma biblioteca normal e uma segura com threads.
Para termos um cliente em threads onde você pode interromper o
cliente a partir de outras threads a definir tempo limites ao
falar com o servidor MySQL, você deve utilizar as bibliotecas
-lmysys
, -lmystrings
, e
-ldbug
e o código
net_serv.o
que o servidor utiliza.
Se você não precisar de insterrupções ou de tempos limites,
você pode apenas compilar um biblioteca cliente
(mysqlclient_r)
segura com threads e
utilizá-las. See Secçã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()
! See
Secçã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:
Chama my_init()
no início do seu
programa se for chamar qualquer outra função MySQL antes
de chamar mysql_real_connect()
.
Chame mysql_thread_init()
no manipulador
de thread antes de chamar qualquer outra função MySQL.
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.
libmysqld
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ção | Quando chamar |
mysql_server_init() | Deve ser chamada antes de qualquer outra função MySQL, de preferência
no inicio da função main() . |
mysql_server_end() | Deve ser chamada antes da saída do programa. |
mysql_thread_init() | Deve ser chamada em cada thread que você criar que acessará o 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. See Secção 12.1.11.1, “mysql_server_init()
”.
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.
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 usuário (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.
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. See
Secçã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]
.
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.
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
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
Secção 1.4.3, “Licenças do MySQL”.
AUTO_INCREMENT
no ODBC
O MySQL fornece suporte para ODBC através do programa
MyODBC
. Este capítulo lhe ensinará como
instalar o MyODBC
, e como usá-lo. Aqui, você
também encontrará uma lista de programas comuns que são
conhecidos por funcionar com MyODBC
.
MyODBC
2.50 é um driver de nível 0 (com
recursos de nível 1 e 2) e especificação de ODBC 2.50 de 32
bits para conectar um programa ODBC ao MySQL.
MyODBC
funciona nos Windows 9x/Me/NT/2000/XP
e na maioria da plataformas Unix. MyODBC
3.51
é uma versão melhorada com nível 1 (core API completo +
recursos de nível 2) e especificação de ODBC 3.5x.
MyODBC
é Open Source
, e
você pode encontrar a versão mais nova em
http://www.mysql.com/downloads/api-myodbc.html.
Note que a versão 2.50.x utiliza a licença
LGPL
, enquanto a versão 3.51.x utiliza a
licença GPL
.
Se vcê tiver problemas com o MyODBC
e seu
programa também funciona com OLEDB, você deve experimentar o
driver OLEDB.
Normalmente você só precisa instalar o
MyODBC
em másquinas Windows. Você só
precisará de MyODBC
para Unix se tiver um
programa como ColdFusion que roda em máquinas Unix e utilizam
ODBC para conectar ao banco de dados.
Se você quiser instalar MyODBC
em um Unix,
você precisará de um gerenciador ODBC.
MyODBC
funciona com a maioria dos
gerenciadores ODBC para Unix.
Para instalar MyODBC
no Windows, você deve
baixar o arquivo MyODBC
.zip
apropriado, descompactá-lo com
WinZip
ou algum programa parecido e executar
o arquivo SETUP.EXE
.
No Windows/NT/XP você pode obter o seguinte erro ao tentar
instalar o MyODBC
:
An error occurred while copying C:\WINDOWS\SYSTEM\MFC30.DLL. Restart Windows and try installing again (before running any applications which use ODBC)
O problema neste caso é que algum outro progrma está
utilizando ODBC e pela forma que como o Windows é feito, você
pode, neste caso, não estar apto a instalar um novo driver ODBC
com programa de instação do ODBC da Microsoft. Neste caso
você pode continuar selecionando Ignore
para
copiar o resto dos aerquivos ODBC e a instalação final deve
funcionar. Se não funcionar, a solução é reinicializar seu
computador em ``modo seguro'' (Escolhendo-o ao pressionar F8
assim que seu computador iniciar o Windows durante a
reinicialização), instalar MyODBC
, e
reiniciar em modo normal.
Para conectar a uma máquina Unix de uma máquina Windows,
com uma aplicação ODBC (uma que não tenha suporte nativo
as MySQL), você deve primeiro instalar
MyODBC
em uma máquina Windows.
O usuário é máquina Windows devem ter privilégios para
acessar o servidor MySQL na máquina Unix. Isto pode ser
feito om o comando GRANT
. See
Secção 4.4.1, “A Sintaxe de GRANT
e REVOKE
”.
Você deve criar uma entrada ODBC DSN como a seguir:
Abra o painel de controle na máquina Windows.
Dê um duplo clique no ícone Fonte de Dados ODBC 32-bit.
Clique na seção Usuário DSN.
Clique no botão Adicionar.
Selecione MySQL na tela Criar Nova Fonte de Dados e clique no botão Finalizar.
A tela de configuração padrão do Driver MySQL é mostrada. See Secção 12.2.2, “Como Preencher os Vários Campos no Programa de Administração do ODBC”.
Agora inicie a sua aplicação e selcione o driver ODBC com o DSN que você especificou no adminitrador ODBC.
Verifique se há outra opção de configuração na tela do MySQL (trace, não pergunta ao conectar, etc) que você possa tentar se ocorrerem problemas.
Existem três maneiras possíveis de especificar o nome de servidor no Windows95:
Use o endereço IP no servidor.
Adicione um arquivo \Windows\lmhosts
com a seguinte informação:
ip nome_maquina
Por exemplo:
194.216.84.21 meu_nome_maquina
Configure o PC para utilizar DNS.
Exemplo de como preencher a configuração do
ODBC
.
Windows DSN name: test Description: This is my test database MySQL Database: test Server: 194.216.84.21 User: monty Password: my_password Port:
O valor para o campo Windows DSN name
é
qualquer nome que seja único em sua configuração ODBC
Windows.
Você não precisa especificar valores para os campos
Server
, User
,
Password
, ou Port
ina tela
de configuração do ODBC. No entanto, se você o fizer, os
valores serão utilizados como padrão posteriormente ao se
tentar fazer uma nova conexão. Você tem a opção de alterar
os valores neste momento.
Se o número da porta não é dado, a porta padrão (3306) é utilizada.
Se você especificar a opção Read options from
C:\my.cnf
, os grupos client
e
odbc
serão lidos do arquivo
C:\my.cnf
. Você pode utilizar todas as
opções que são úteis a mysql_options()
.
See Secção 12.1.3.40, “mysql_options()
”.
Pode-se especificar os seguintes parâmetros para
MyODBC
na seção
[Servername]
de um arquivo
ODBC.INI
ou através do argumento
InConnectionString
na chamada
SQLDriverConnect()
.
Parâmetro | Valor padrão | Comentário |
user | ODBC (on Windows) | O nome do usuário usado para se conectar ao MySQL. |
server | localhost | O nme de máquina do servidor MySQL. |
database | O banco de dados padrão. | |
option | 0 | Um inteiro com o qual você pode especificar como o
MyODBC deve tarbalhar. Veja abaixo. |
port | 3306 | A porta TCP/IP usada se o servidor (server ) não for
localhost . |
stmt | Uma instrução que será executada ao conectar ao
MySQL . | |
password | A senha para a combinação
servidor(server )-usuário(user ). | |
socket | O socket ou pipe Windows para se conectar. |
O argumento option é usado para dizer ao
MyODBC
que o cliente não é 100% compatível
com ODBC. No Windows, o parâmetro option normalmente é
definido mudando as diferentes opções na tela de conexão mas
também podem ser definidas no argumento option. As seguintes
opções estão listadas na mesma ordem em que aparecem na tela
de conexão do MyODBC
:
Bit | Descrição |
1 | O cliente não pode aceitar que MyODBC retorne a
largura real de uma coluna. |
2 | O clinete nã pode aceitr que MySQL retorne o valor real de colunas afetadas. Se este parâmetro for definido o MySQL retornará 'registros encontrados'. É necessáriop o MySQL 3.21.14 ou posterior para funcionar. |
4 | Faz um log de depuração em c:\myodbc.log. É o mesmo que colocar
MYSQL_DEBUG=d:t:O,c::\myodbc.log no
AUTOEXEC.BAT |
8 | Não define nenhum limite de pacote para resultados e parâmetros. |
16 | Não faz perguntas mesmo se o driver quisesse. |
32 | Simula um driver ODBC 1.0 em alguns contextos. |
64 | Ignora o uso do nome de banco de dados 'bancodedados.tabela.coluna' |
128 | Força o usa de cursores de gerenciadores ODBC (experimental). |
256 | Disabilita o uso de busca estendida (experimental). |
512 | Completa campos CHAR para tamanho de coluna cheias. |
1024 | SQLDescribeCol() retrnará nome de colunas totalmente qualificados. |
2048 | Usa o protocolo cliente/servidor comprimido. |
4096 | Diz ao seridor para ignorar espaços após nome de funções e antes de
'(' (necessário para PowerBuilder).
Torna todos os nomes de funções palavras-chaves! |
8192 | Conecta com named pipes ao servidor mysqld executando
no NT. |
16384 | Altera colunas LONGLONG para colunas INT (algumas aplicações não podem tratar LONGLONG). |
32768 | Retorna 'user' como Table_qualifier e Table_owner para SQLTables (experimental) |
65536 | Lê paraâmetros dos grupos client e
odbc no my.cnf |
131072 | Adiciona algumas verificações extras de segurança (não deve ser necessário, mas...) |
Se você quiser ter muitas opções, você deve somar os parâmetros acima! Por exemplo, definir a opção como 12 (4+8) lhe permite debugar sem limite de pacotes.
O MYODBC.DLL
padrão é compilado para um
rendimento otimizado. Se você quiser depurar o
MyODBC
(por exemplo, habiliatr o trace),
você deve utilizar MYODBCD.DLL
. Para
instalar este arquivo copie MYODBCD.DLL
sobre o arquivo MYODBC.DLL
instalado.
MyODBC
tem sido testado com Access,
Admndemo.exe, C++-Builder, Borland Builder 4, Equipe de
Desenvovimento Centura (formalmente Gupta SQL/Windows),
ColdFusion (em Solaris e NT com svc pack 5), Crystal Reports,
DataJunction, Delphi, ERwin, Excel, iHTML, FileMaker Pro,
FoxPro, Notes 4.5/4.6, SBSS, Perl DBD-ODBC, Paradox,
Powerbuilder, Powerdesigner 32 bit, VC++, e Visual Basic.
Se você souber de qualquer outra aplicação que funcione com
MyODBC
, envie-nos email para lista de email
odbc
do MySQL sobre isto! See
Secção 1.7.1.1, “As Listas de Discussão do MySQL”.
Com alguns programas você pode obter um erro como este:
Another user has modifies the record that you have
modified
. Na maioria dos casos ele pode ser resolvido
fazendo o especificado abaixo:
Adicione um chave primária para a tabela se já não houver uma.
Adicione uma coluan timestamp se já não existir uma.
Só utilize campos double float. Alguns programa podem falhar quando comparam floats simples.
Se o exposto acima não ajudar, você deve fazer um arquivo de
rastreamento do MyODBC
e tentar encontrar o
que está dando errado.
A maioria dos programas devem funcionar com
MyODBC
, mas para cada um dos listados aqui,
nós mesmos testamos e recebemos confirmação de alguns
usuários que eles funcionam:
Programa
Access
Para fazer o Access funcionar:
Se você estiver usando Access 2000, você deve obter
e instalar o Microsoft MDAC (Microsoft Data
Access Components
) mais recente (versão 2.6
ou acima) em
http://www.microsoft.com/data/.
Ele irá consertar o o seguinte bug no Access: quando
você exporta dados para o MySQL, os nomes de tabelas
e colunas não são especificados. Outro modo de
contornar este bug é atualizar para MyODBC Versão
2.50.33 e MySQL Versão 3.23.x, que juntos fornecem um
modo de contornar este erro!
Você também deve obter e instalar Microsoft Jet 4.0
Service Pack 5 (SP5) que pode ser encontrado em
http://support.microsoft.com/support/kb/articles/Q
239/1/14.ASP. Isto irá corrigir alguns casos
onde colunas são marcadas como
#deletadas#
no Access.
Note que se você estiver usando o MySQL Versão 3.22, você deve aplicar o patch MDAC e utilizar MyODBC 2.50.32 ou 2.50.34 e acima para contornar este problema.
Para todas as versões do Access, você deve habilitar
a opção do MyODBC Return matching
rows
. Para Access 2.0, você também deve
habilitar Simulate ODBC 1.0
.
Você deve ter um timestamp em todas as tabelas que
você deseja atualizar. Para maior portabilidade
TIMESTAMP(14)
ou apenas
TIMESTAMP
é recomendado no lugar
de outras variações de
TIMESTAMP(X)
.
Você deve ter uma chave primáia na tabela. Se não,
registros novos ou atualizados podem aparecer como
#DELETED#
.
Só use campos DOUBLE
float. O
Access falaha ao comparar com campos single floats. Os
sintomas normais são que registros novos ou
atualizados podem aparecer como
#DELETED#
ou que você não possa
encontarar ou atualizar registros.
Se você estiver ligando uma tabela com MyODBC, que
tem BIGINT
como uma de suas
colunas, o resultado será mostrado como
#DELETED
. A solução para
contornar este problema é:
Tenha um ou mais colunas modelos com
TIMESTAMP
como o tipo de dados,
de preferência TIMESTAMP(14)
.
Verifique 'Change BIGINT columns to
INT'
na ciaxa diálogo de opções de
conexão no Admiistrador DSN ODBC
Delete o link a tabela e o recrie.
Ele ainda mostra o registro anterior como
#DELETADO#
, mas novos registros
adicionados/atualizados serão mostrados
apropriadamente.
Se você ainda obter o erro Another user has
changed your data
depois de adicionar uma
coluna TIMESTAMP
, o seguinte truque
pode lhe ajudar:
Nào utilize visualizar planilha de dados da
tabela
. Crie um formulario com os
campos que você quer, e use visulizar planilha de
dados de formulário
. Você deve
definir a propriedade DefaultValue
para a coluna TIMESTAMP
com
NOW()
. Esta pode ser uma boa idéia
para oculta a coluna TIMESTAMP
da
visualização para que seus usuários não fiquem
confusos.
Em alguns casos, o Access pode gerar consultas SQL
inválidas que o MySQL não entende. Você pode
arrumar isto selecionando
"Query|SQLSpecific|Pass-Through"
no
menu do Access.
No NT o Access irá mostrar colunas
BLOB
como OLE
OBJECTS
. Se você quiser colunas
MEMO
, você deve alterar a coluna
para TEXT
com ALTER
TABLE
.
O Access não pode sempre tratar colunas
DATE
apropriadamente. Se você
tiver um problema com isto, mude as colunas para
DATETIME
.
Se você tiver no Acces um coluna definida como
BYTE
, o Access tentará exportá-la
como TINYINT
em vez de
TINYINT UNSIGNED
. Isto lhe tará
problemas se você tiver valores > 127 na coluna!
ADO
Quando você está codificando com a API ADO e
MyODBC
você precisa ter atenção com
algumas propriedades padrões que não são suportadas pelo
servidor MySQL. Por exemplo, usando CursorLocation
Property
como adUseServer
retornará de RecordCount Property
um
resultado de -1. Para ter o valor correto, você precisa
definir esta propriedade a adUseClient
,
como mostrado no código VB abaixo:
Dim myconn As New ADODB.Connection Dim myrs As New Recordset Dim mySQL As String Dim myrows As Long myconn.Open "DSN=MyODBCsample" mySQL = "SELECT * from user" myrs.Source = mySQL Set myrs.ActiveConnection = myconn myrs.CursorLocation = adUseClient myrs.Open myrows = myrs.RecordCount myrs.Close myconn.Close
Outro modo de contornar o problea é utilizar uma
instrução SELECT COUNT(*)
para uma
consulta parecida para obter a contagem de registros
correta.
Active server pages (ASP)
Você deve usar a opção Return matching
rows
.
Aplicações BDE
Para faze-las funcionar, você deve definir os seguintes
parâmetros: Don't optimize column widths
e Return matching rows
.
Borland Builder 4
Qaundo você inicia uma consulta, você pode utilizar a
propriedade Active
ou utilizar o método
Open
. Note que Active
irá iniciar automaticamente executando uma consulta
SELECT * FROM ...
que pode não ser algo
bom se suas tabelas forem grandes.
ColdFusion (No Unix)
A seguinte informações é tirada da documentação do ColdFusion:
Utilize a seguinte informação para configurar o ColdFusion
Server para Linux para utilizar o driver unixODBC driver com
MyODBC
para fonte de dados MySQL. Allaire
verificou que o MyODBC
Versão 2.50.26
funciona com MySQL Versão 3.22.27 e ColdFusion para Linux.
(Quqlquer versão mais nova também deve funcionar.) Você
pode fazer o download do MyODBC
em
http://www.mysql.com/downloads/api-myodbc.html
ColdFusion Versão 4.5.1 lhe permite utilizar o
Administrador ColdFusion para adicionar a fonte de dados
MySQL. No entanto o driver não está incluído com o
ColdFusion Versão 4.5.1. Antes que o driver MySQL aparecer
na lista drop-down de fonte de dados ODBC, você deve
construir e copiar o driver MyODBC
para
/opt/coldfusion/lib/libmyodbc.so
.
O diretório Contrib contém o programa
mydsn-xxx.zip
que lhe permite construir
e remover o arquivo de registro DSN para o driver MyODBC em
aplicações Coldfusion.
DataJunction
Você tem que alterá-lo para uma saída
VARCHAR
em vez de
ENUM
, ja que ele exporta o último de uma
maneira que cause um grief no MySQL.
Excel
Funciona. Algumas dicas:
Se você tiver problema com datas, tente
selecioná-las como strings utilizando a função
CONCAT()
. Por exemplo:
select CONCAT(rise_time), CONCAT(set_time) from sunrise_sunset;
Valores retornados deste modo como strings devem ser reconhecidos corretamente como valores time pelo Excel97.
O propósito de CONCAT()
neste
exemplo é enganar o ODBC fazendo-o pensar que a
coluna é do ``tipo string''. Sem o
CONCAT()
, ODBC sabe que a coluna é
do tipo time e o Excel não entende isto.
Note que este é um bug do Excel, pois ele converte automaticamente uma string para um time. Isto seria ótimo se a fonte fosse um arquivo texto, mas se torna um erro quando a fonte e uma conexão ODBC que relata tipos exatos para cada coluna.
Word
Para recuperar os dados do MySQL para documentos Word/Excel,
você precisa utilizar o driver MyODBC
e
a ajuda do Add-in Microsoft Query.
Por exemplo, crie um bd com uma tabela contendo 2 colunas de texto:
Insira registros utilizando a ferramente cliente de
linha de comando mysql
.
Crie um arquivo DSN usando o gerenciador ODBC,
my
, por exemplo, para o bd acima.
Abra o aplicativo Word.
Crie um novo documento vazio.
Utilizando a barra de ferramentas chamada Banco de Dados, pressione o botão insira banco de dados.
Pressione o botão Obter Dados.
No moemnto certo, pressione o botão Ms Query na tela Obter Dados.
No Ms Query crie uma Nova Fonte de Dados utilizando o arquivo DSN my.
Selecione a nova consulta.
Selecione as colunas que você deseja.
Crie um filtro de desejar.
Faça um Ordenação se quiser.
Selecione Enviar Dados para o Microsoft Word.
Clique em Finalizar.
Clique em Inserir dados e selecione os registros.
Clique OK e você verá os registros no seu documento Word.
odbcadmin
Delphi
Você deve utilizar o BDE Versão 3.2 ou mais atual. Veja a
opção i Don't optimize column width
ao
conectar no MySQL.
Aqui está um código de Delphi potencialmente útil que
configura uma entrada ODBC e uma entrada BDE para para
MyODBC
(a entrada BDE exige de um Editor
de Alias BDE que é gratuito em um site Delphi Super Page.
(Obrigado a Bryan Brunton
<bryan@flesherfab.com>
por isto):
fReg:= TRegistry.Create; fReg.OpenKey('\Software\ODBC\ODBC.INI\DocumentsFab', True); fReg.WriteString('Database', 'Documents'); fReg.WriteString('Description', ' '); fReg.WriteString('Driver', 'C:\WINNT\System32\myodbc.dll'); fReg.WriteString('Flag', '1'); fReg.WriteString('Password', ''); fReg.WriteString('Port', ' '); fReg.WriteString('Server', 'xmark'); fReg.WriteString('User', 'winuser'); fReg.OpenKey('\Software\ODBC\ODBC.INI\ODBC Data Sources', True); fReg.WriteString('DocumentsFab', 'MySQL'); fReg.CloseKey; fReg.Free; Memo1.Lines.Add('DATABASE NAME='); Memo1.Lines.Add('USER NAME='); Memo1.Lines.Add('ODBC DSN=DocumentsFab'); Memo1.Lines.Add('OPEN MODE=READ/WRITE'); Memo1.Lines.Add('BATCH COUNT=200'); Memo1.Lines.Add('LANGDRIVER='); Memo1.Lines.Add('MAX ROWS=-1'); Memo1.Lines.Add('SCHEMA CACHE DIR='); Memo1.Lines.Add('SCHEMA CACHE SIZE=8'); Memo1.Lines.Add('SCHEMA CACHE TIME=-1'); Memo1.Lines.Add('SQLPASSTHRU MODE=SHARED AUTOCOMMIT'); Memo1.Lines.Add('SQLQRYMODE='); Memo1.Lines.Add('ENABLE SCHEMA CACHE=FALSE'); Memo1.Lines.Add('ENABLE BCD=FALSE'); Memo1.Lines.Add('ROWSET SIZE=20'); Memo1.Lines.Add('BLOBS TO CACHE=64'); Memo1.Lines.Add('BLOB SIZE=32'); AliasEditor.Add('DocumentsFab','MySQL',Memo1.Lines);
C++ Builder
Testado com BDE versão 3.0. O único problema conhecido é que quando o esquema de tabelas é alterado, os campos da consulta não são atualizados. O BDE, no entanto, parece não reconhecer chaves primárias, apenas o índice PRIMARY, mas isto será um problema.
Vision
Você deve utilizar a opcão Return matching
rows
.
Visual Basic
Para estar apto para habilitar uma tabela, você deve definir uma chave primária para a tabela.
Visual Basic com ADO não pode manipular inteiros grandes.
Isto significa que algumas consultas como SHOW
PROCESSLIST
não irão funcionar apropriadamente.
A correção é deifinir a opção
OPTION=16384
na string de conexão ODBC
ou configurar a opção Change BIGINT columns to
INT
na tela de conexão do MyODBC. Você pode
desejar definir a opção Return matching
rows
.
VisualInterDev
Se você obtem o erro [Microsoft][ODBC Driver
Manager] Driver does not support this parameter
a
razão pode ser que você tem um BIGINT
em seu resultado. Tente definir a opção Change
BIGINT columns to INT
na tela de conexão do
MyODBC.
Visual Objects
Você deve utilizar a opção Don't optimize column
widths
.
Um problema comum é como obter o valor de um ID gerado
automaticamente em um INSERT
. Com ODBC, você
pode fazer algo assim (considerando que auto
é um campo AUTO_INCREMENT
):
INSERT INTO foo (auto,text) VALUES(NULL,'text'); SELECT LAST_INSERT_ID();
Ou, se você estiver prestes a insrir o ID em outra tabela, você pode fazer assim:
INSERT INTO foo (auto,text) VALUES(NULL,'text'); INSERT INTO foo2 (id,text) VALUES(LAST_INSERT_ID(),'text');
See Secção 12.1.12.3, “Como Posso Obter a ID Única para a Última Linha Inserida?”.
Para o benefício de alguns aplicativos ODBC (pelo menos Delphi e Access), a seguinte consulta pode ser utilizada para encontrar um registro récem inserido:
SELECT * FROM nome_tabela WHERE auto IS NULL;
Se você encontrar dificuldades com MyODBC
,
você deve iniciar fazendo um arquivo log pelo gerenciador ODBC
(o log obtido ao requisitar logs do ODBCADMIN) e um log
MyODBC
.
Para obter um log MyODBC
, você precisa fazer
o seguinte:
Esteja certo de que você está utilizando
myodbcd.dll
e não
myodbc.dll
. O modo mais fácil de se
fazer isto é obter myodbcd.dll
da
distribuição MyODBC e copiá-la sobre o
myodbc.dll
, o qual estará,
provavelmente, em seu diretório
C:\Windows\system32
ou
C:\winnt\system32
.
Note que você provavelmente deseja restaurar o myodbc.dll
antigo ao finalizar o teste, já que ele é bem mais rpido
que myodbcd.dll
.
Marque a opção `Trace MyODBC' na tela de
conexão/configuração do MyODBC
. O logo
será escrito no arquivo C:\myodbc.log
.
Se a opção de ratreamento não for lembrada quando você
retornar a tela acima, significa que você não está
utilizando o driver myodbcd.dll
(veja o
item acima).
Inicie sua aplicação e tente fazê-la falhar.
Verifique o arquivo de rastreamento do
MyODBC
, para saber o que pode estar errado. Viocê
deve estar apto a encontrar as consultas executadas buscando
após a string >mysql_real_query
no
arquivo myodbc.log
.
Você também devev tentar duplicar as consultas no monitor
mysql
ou admndemo
para
descobrir se o erro é do MyODBC ou do MySQL.
Se você encontar algo errado, envie-nos somente os registros
relevantes (max 40 registros) para a lista de email
odbc
do MySQL. See
Secção 1.7.1.1, “As Listas de Discussão do MySQL”. Por favor, nunca envie todo o
arquivo log do MyODBC ou ODBC!
Se você não puder encontrar o que está errado, a última opção é fazer um arquivo (tar ou zip) que contenha um arquivo de rastreamento do MyODBC, o arquivo log do ODBC, e um arquivo README que explique o problema. Você pode enviá-lo para ftp://support.mysql.com/pub/mysql/secret/. Somente nós da MySQL AB teremos acesso ao arquivo que você enviar, a seremos bem discretos com os dados!
Se você pode criar um programa que também mostre este problema, nos envie ele também.
Se o programa funciona com algum outro servidor MySQL, você deve fazer um arquivo de log do MyODBC onde você faz exatamente a mesma coisa no ouuto servidor SQL.
Lembre-se que quanto mais informações você nos fornecer, mais satisfatória será a solução encontrada para o problema!
Existem 2 drivers JDBC suportados pelo MySQL:
MySQL Connector/J
do MySQL AB, implementado
100% em Java nativo. Este produto era formalmente conhecido
como o driver mm.mysql
. Você pode fazer o
doenload do MySQL Connector/J
em
http://www.mysql.com/products/connector-j/.
O driver Resin JDBC, que pode ser encontrado em http://www.caucho.com/projects/jdbc-mysql/index.xtp.
Para informação, consulte qualquer documentação JDBC, além das documentação dos proprietários de cada driver para recursos específicos do MySQL.
PHP é uma linguagem script do lado do servidor embutida em HTML que pode ser usada para criar páginas web dinâmicas. Ele contém suporte para acesso a diversos banco de dados, incluindo o MySQL. PHP pode ser executado como um programa separado ou compilado como um módulo para uso com o servidro web Apache.
A distribuição e documentação está disponível no web site PHP (http://www.php.net/).
Error: "Maximum Execution Time Exceeded" Este é um limite
do PHP; vá até o arquivo php3.ini
e
defina o tempo máximo de excução para algo maior que 30
segundos, de acordo com a necessidade. Também não é uma
má idéia dobrar a ram permitida por script para 16 MB em
vez de 8 MB.
Error: "Fatal error: Call to unsupported or undefined function mysql_connect() in .." Isto significa que sua versão do PHP não é compilada com suporte ao MySQL. Você também pode compilar um módulo MySQL dinâmico e carregá-lo no PHP ou recompilar o PHP com suporte ao MySQL. Isto é descrito em detalhes no manual PHP.
Error: "undefined reference to `uncompress'" Isto significa
que a biblioteca cliente é compilada com suporte a um
protocolo cliente/servidor compactado. A correção é
adicionar -lz
por último ao ligar com
-lmysqlclient
.
Esta seção documenta a interface Perl DBI
. A
interface anterior era chamada mysqlperl
.
DBI
/DBD
é a intrface Perl
recomendada atual;mente, assim mysqlperl
está
obsoleta e não será documentada aqui.
DBI
é uma interface genérica para muitos
bancos de dados. Isto significa que voccê pode escrever um
script que funciona com diferentes mecanismos de banco de dados
sem nenhuma mudança. Você precisa de um DataBase Driver -
Driver de Banco de Dados (DBD) definido para cada tipo de banco
de dados, para o MySQL este driver é chamado
DBD::mysql
.
Para mais informação sobre Perl5 DBI, visite a pagina web do
DBI
e leia a documentação:
http://dbi.perl.org/
Note que se você quiser usar transações com Perl, você
precisa ter o DBD-mysql
versão 1.2216 ou
posterior. Recomendamos usar a versão 2.1022 ou mais nova.
Installation instructions for MySQL Perl support are given in Secção 2.7, “Comentários de Instalação do Perl”.
Se você tiver o modulo MySQL instalado, você pode achar informação sobre as funcionalidades especificas do MySQL com um dos seguintes comandos:
shell>perldoc DBD/mysql
shell>perldoc mysql
Métodos e Atributos DBI Portáteis
Método/Atributo | Descrição |
connect | Estabelece uma conexão ao servidor de banco de dados. |
disconnect | Disconecta de um servidor de banco de dados. |
prepare | Prepara uma instrução SQL para ser executada. |
execute | Executa instruções preparadas. |
do | Prepara e executa uma instrução SQL. |
quote | Coloca valores string ou BLOB entre aspas para serem
inseridos. |
fetchrow_array | Busca a próxima linha como um vetor de campos. |
fetchrow_arrayref | Busca a próxima linha como um vetor referência de campos. |
fetchrow_hashref | Busca a prima linha como uma referência a uma tabela hash. |
fetchall_arrayref | Busca todos os dados como um vetor de vetor (matriz). |
finish | Finaliza uma instrução e deixa os recursos do sistema livres. |
rows | Retorna o número de linhas afetadas. |
data_sources | Retorna um vetor de banco de dados disponíves ne localhost. |
ChopBlanks | Controla de o método fetchrow_* elimina os espaços
em branco. |
NUM_OF_PARAMS | O número de colchetes em uma instrução preparada. |
NULLABLE | Quais colunas podem ser NULL . |
trace | Realiza rastreamento para depuração. |
Métodos e Atributos específicos do MySQL
Método/Atributos | Descrição |
mysql_insertid | O último valor AUTO_INCREMENT . |
is_blob | Quais colunas são valores BLOB . |
is_key | Quais colunas são chaves. |
is_num | Quais colunas são numéricas. |
is_pri_key | Quais colunas são chaves primárias. |
is_not_null | Quais colunas NÃO PODEM ser NULL . Veja
NULLABLE . |
length | O tamanho máximo das colunas. |
max_length | O tamanho máximo das colunas presentes no resultado. |
NAME | Nomes de colunas. |
NUM_OF_FIELDS | Número de campos retornados. |
table | Nome de tabelas no resultado. |
type | Todos os tipos de colunas |
Os métodos Perl são descritos em maiores detalhes nas seções seguintes. Variáveis usadas em métodos que retornam valor tem estes significados:
$dbh
Manipulador do Banco de Dados
$sth
Manipulador da Instrução
$rc
Código de Retorno (geralmente um status)
$rv
Valor de Retorno (geralmente um contador de linhas)
Métodos e Atributos DBI Portáteis
connect($data_source, $username,
$password)
Usa o método connect
para fazer uma
conexão do banco de dados a fonte de dados. O valor
$data_source
deve começar com
DBI:driver_name:
. Exemplo de uso de
connect
com o driver
DBD::mysql
:
$dbh = DBI->connect("DBI:mysql:$database", $user, $password); $dbh = DBI->connect("DBI:mysql:$database:$hostname", $user, $password); $dbh = DBI->connect("DBI:mysql:$database:$hostname:$port", $user, $password);
Se o nome do usuário e/ou senha não são definidos,
DBI
usa os valores das variáveis de
anbiente DBI_USER
e
DBI_PASS
, respctivamente. Se você não
especificar um nome de máquina, ele utiliza o padrão
'localhost'
. Se você não especificar um
número de porta, ele utiliza a porta padrão do
MySQL(3306).
Atá o Msql-Mysql-modules
Versão 1.2009,
o valor $data_source
permitia alguns
modificadores:
mysql_read_default_file=file_name
Lê file_name
como um arquivo de
opção. Para informação sobre arquivo de opções
veja Secção 4.1.2, “Arquivo de Opções my.cnf
”.
mysql_read_default_group=group_name
O grupo padrão ao se ler uma arquivo de opções é,
normalamente, o grupo [client]
.
Especificando a aopção
mysql_read_default_group
, o grupo
padrão se torna o grupo
[group_name]
.
mysql_compression=1
Utiliza comunicação compactada enter o cliente e o servidor (MySQL Versão 3.22.3 ou posterior).
mysql_socket=/path/to/socket
Especifica o caminho do socket Unix que é utilizado para se conectar ao servidor (MySQL Versão 3.21.15 ou posterior).
Múliplos modificadores podem ser dados. Cada um deve ser precedido de ponto e vírgula.
Por exemplo, se você quiser evitar colocar o nome de
usuário e senha em um script DBI
, você
pode buscá-los em um arquivo de opção
~/.my.cnf
do usuário ao invés de
escrever a sua chamada connect
desta
forma:
$dbh = DBI->connect("DBI:mysql:$database" . ";mysql_read_default_file=$ENV{HOME}/.my.cnf", $user, $password);
Esta chamado irá ler opções difinidas pelo grupo
[client]
no arquivo de opções. Se você
quiser fazer a mesma coisa mas utilizar opções
especificadas no grupo [perl]
, você pode
fazer:
$dbh = DBI->connect("DBI:mysql:$database" . ";mysql_read_default_file=$ENV{HOME}/.my.cnf" . ";mysql_read_default_group=perl", $user, $password);
disconnect
O método disconnect
disconecta o
manipulador de banco de dados do banco de dados. Ele é
normalmente chamado pouco antes de você sair do programa.
Exemplo:
$rc = $dbh->disconnect;
prepare($statement)
Prepara uma instrução SQL para execução pelo mecanismo
de banco de dados e retorna um manipulador de instrução
($sth)
, que você pode utilizar para
chamar o método execute
.
Normalmente você manipula a instrução
SELECT
(e instruções do tipo
SELECT
tais como SHOW
,
DESCRIBE
, e EXPLAIN
)
através de prepare
e
execute
. Exemplo:
$sth = $dbh->prepare($statement) or die "Can't prepare $statement: $dbh->errstr\n";
Se voê quiser ler grandes resultados em seu cliente, você
pode dizer ao Perl para utilizar
mysql_use_result()
com:
my $sth = $dbh->prepare($statement { "mysql_use_result" => 1});
execute
O método execute
executa um instrução
preparada. Para instrução não-SELECT
,
execute
retorna o número de linha
afetadas. Se nenhuma linha foi afetada,
execute
retorna "0E0"
,
que o Perl trata como zero mas considera com true. Se um
erro ocorrer, execute
retorna
undef
. Para instruções
SELECT
, execute
apenas
inicia a consulta SQL no banco de dados; você precisa
utilizar um dos métodos de fetch_*
descritos aqui para recuperar dados. Exemplo:
$rv = $sth->execute or die "can't execute the query: " . $sth->errstr;
do($statement)
O método do
prepara e executa uma
instrução SQL e retorna o número linhas afetadas. Se
nenhuma lina for afetada, do
retorna
"0E0"
, que o Perl trata como zero mas
considera como true (verdadeiro). Este método é geralmente
usado por instruções não-SELECT
que
não podem ser preparadas previamente (devida a limitações
do driver) ou que não precisa ser esecutada mais que uma
vez (inserts, deletes, etc.). Exemplo:
$rv = $dbh->do($statement) or die "Can't execute $statement: $dbh- >errstr\n";
Geralamente a instrução 'do' é mais rápida (e preferível) que prepare/execute para instruções que não contém parâmetros.
quote($string)
O método quote
é usada para "escapar"
qualquer caracter especial contido na string e para adcionar
as aspas necessárias na saída. Exemplo:
$sql = $dbh->quote($string)
fetchrow_array
Este mátodo busca a próxima linha de dados e a retorna como um vetor de valores de campo. Exemplo:
while(@row = $sth->fetchrow_array) { print qw($row[0]\t$row[1]\t$row[2]\n); }
fetchrow_arrayref
Este método busca a próxima linha de dados e a retorna como uma referência a um vetor de valores de campos. Exemplo:
while($row_ref = $sth->fetchrow_arrayref) { print qw($row_ref->[0]\t$row_ref->[1]\t$row_ref->[2]\n); }
fetchrow_hashref
Este método busca uma linha de dados e retorna uma referência a uma tabela hash contendo pares nome de campos/valores. Este método não é tão eficiente quanto utilizar referências a vetor como demostrado acima. Exemplo:
while($hash_ref = $sth->fetchrow_hashref) { print qw($hash_ref->{firstname}\t$hash_ref->{lastname}\t\ $hash_ref->{title}\n); }
fetchall_arrayref
Este método é usado para obter todos os dados (linhas) a serem retornados de uma instrução SQL. Ele retorna uma referência a um vetor de referências a vetores para cada linha. Você acessa ou imprime dados utilizando um loop aninhado. Exemplo:
my $table = $sth->fetchall_arrayref or die "$sth->errstr\n"; my($i, $j); for $i ( 0 .. $#{$table} ) { for $j ( 0 .. $#{$table->[$i]} ) { print "$table->[$i][$j]\t"; } print "\n"; }
finish
Indica que mais nenhum dado será buscado para este manipulador de instrução. Você chama este método para liberar o manipulador de instrução e qualquer recuros de sistema associado a ele. Exemplo:
$rc = $sth->finish;
rows
Retorna o número de linhas alteradas (atualiadas,
deletadas, etc.) pelo último comando. Ele é normalmente
utilizado após uma instrução execute
não-SELECT
. Exemplo:
$rv = $sth->rows;
NULLABLE
Retorna uma referência a um vetor de valores que indicam se
colunas podem conter valores NULL
. Os
valores possíveis para cada element do vetor é 0 ou uma
string vazia se a coluna não puder ser
NULL
, 1 se puder e 2 se a o estado
NULL
da coluna é desconhecido. Exemplo:
$null_possible = $sth->{NULLABLE};
NUM_OF_FIELDS
este atributi indica o número de campos retornados pela
instrução SELECT
ou SHOW
FIELDS
. Você pode usá-la para verificar se uma
instrução retornou um resultado: Um valor zero indica uma
intrução não-SELECT
como
INSERT
, DELETE
, ou
UPDATE
. Exemplo:
$nr_of_fields = $sth->{NUM_OF_FIELDS};
data_sources($driver_name)
Este método retorna um vetor contendo o nome dos bancos de
dados disponíveis no servidor MySQL na máquina
'localhost'
. Exemplo:
@dbs = DBI->data_sources("mysql");
ChopBlanks
Este atributo determina se o método
fetchrow_*
irá apagar espaços em branco
no inicio ou no fim dos valores retornados. Exemplo:
$sth->{'ChopBlanks'} =1;
trace($trace_level)
,
trace($trace_level, $trace_filename)
O método trace
habilita ou disabilita o
rastreamento. Quando chamado como um método da classe
DBI
, ele afeta o rastreamento em todos os
manipuladores. Quando chamado como um método do manipulador
de banco de dados ou de instrução, ele afeta o
rastreamento para o manipulador dado (e qualquer filho
futuro do manipulador). Definir
$trace_level
com 2 fornece detalhes da
informação do rastreamento. Definir
$trace_level
com 0 desabilita o
rastreamento. A saída do rastreamento vai para a saída
padrão de erros por padrão. Se
$trace_filename
for esecificado, o
arquivo é aberto no modo append e a saída para
todos manipuladores
rastreados traced handles é escrita neste arquivo. Exemplo:
DBI->trace(2); # rastreia tudo DBI->trace(2,"/tmp/dbi.out"); # rastreia tudo para # /tmp/dbi.out $dth->trace(2); # rastreia este manipulador de banco de dados $sth->trace(2); # rastreia este manipulador de instruções
Você também pode habilitar o rastreamento
DBI
configurando a variável de ambiente
DBI_TRACE
. Configurá-la com um valor
numérico é o mesmo que chamar
DBI->(value)
. Configurá-la com um
caminhao é o mesmo que chamar
DBI->(2,value)
.
Métodos e Atributos Especificos do MySQL
Os métodos mostrados aqui são específicso do MySQL e não
são parte do padrão DBI
. Diversos métodos
já estão obsoletos: is_blob
,
is_key
, is_num
,
is_pri_key
, is_not_null
,
length
, max_length
, e
table
. Quando existir uma alternativa no
padrão DBI
, ela será listada aqui:
mysql_insertid
Se você utilizar o recurso
AUTO_INCREMENT
do MySQL, os novos valores
auto-increment serão armazenados aqui. Exemplo:
$new_id = $sth->{mysql_insertid};
Com versões antigas da interface DBI, você pode usar
$sth->{'insertid'}
.
is_blob
Retorna uma referência a um vetor de valores booleanos;
para cada elemento do vetor, um valor TRUE indica que a
respectiva coluna é um BLOB
. Exemplo:
$keys = $sth->{is_blob};
is_key
Retorna um referência a um vetor de valores booleanos; para cada elemento do vetor, um valor de TRUE indica que a coluna respectiva é uma chave. Exemplo:
$keys = $sth->{is_key};
is_num
Retorna uma referência a um vetor de valores booleanos; para cada elemento do vetor, um valor de TRUE indica que a coluna respectiva contém valores numéricos. Exemplo:
$nums = $sth->{is_num};
is_pri_key
Retorna uma referência a um vetor de valores booleanos; para cada elemento do vetor, um valor de TRUE indica que a respectiva coluna é uma chave primária. Exemplo:
$pri_keys = $sth->{is_pri_key};
is_not_null
Retorna uma referência para um vetor de valores booleanos;
para cada elemento do vetor, um valor de FALSE indica que
esta coluna pode conter valores NULL
Exemplo:
$not_nulls = $sth->{is_not_null};
is_not_null
está obsoleto; é
preferível utilizar o atributo NULLABLE
(descrito acima), porque ele é um padrão DBI.
length
, max_length
Cada um destes métodos retornam uma referêcia a um vetor
com tamanho de colunas. O vetor length
indica a tamanho máximo que cada coluna pode ter (como
declarado na descrição da tabela). O vetor
max_length
indica o tamanho máximo
presente atualmente no resultado. Exemplo:
$lengths = $sth->{length}; $max_lengths = $sth->{max_length};
NAME
Retorna um referência a um vetor de nomes de colunas. Exemplo:
$names = $sth->{NAME};
table
Retorna um referência a um vetor de nomes de tabelas. Exemplo:
$tables = $sth->{table};
type
Retorna uma referência a um vetor com tipos de colunas. Exemplo:
$types = $sth->{type};
Você pode utilizar o comando perldoc
para
conseguir mais informação sobre DBI
.
perldoc DBI perldoc DBI::FAQ perldoc DBD::mysql
Voê também pode utilizar as ferramentas
pod2man
, pod2html
, etc.,
para traduzir para outro formato.
Você pode encontrar as últimas informações sobre
DBI
na pagina web DBI
:
http://dbi.perl.org/.
MySQL Connector/C++ (ou MySQL++
) é a API
oficiaL do MySQL para C++. Mais informações podem ser
encontradas em
http://www.mysql.com/products/mysql++/.
Você pode compilar o fonte do MySQL Windows com Borland C++ 5.02. (O fonte Windows só incluem projetos para Microsoft VC++, para Borland C++ você mesmo tem que fazer os arquivos de projetos.)
Um problema conhecido copm o Borland C++ é que ele usa uam
estrutura de alinhamento diferente do VC++. Isto significa que
você terá problema se você tentar utilizar as bibliotecas
libmysql.dll
padrões (que foi compilado com
VC++) com Borland C++. Você pode fazer o seguinte para ebitar
este problema.
Você pode utilizar bibliotecas MySQL estáticas para Borland C++ que você pode encontar em http://www.mysql.com/downloads/os-win32.html.
Só chame mysql_init()
com
NULL
como um argumento, não uma struct
MySQL pre-alocada.
MySQLdb
fornece suporte MySQL para Python,
compatível com a API Python DB version 2.0. Ela pode ser
encontrada em
http://sourceforge.net/projects/mysql-python/.
MySQLtcl é uma API simples para aceeso ao servidor de banco de dados MySQL a partir da linguagem de programação Tcl. Ela pode ser encontrada em http://www.xdobry.de/mysqltcl/.
Eiffel MySQL é uma interface para o servidor de banco de dados MySQL, utilizando a linguagem de programação Eiffel, escrita por Michael Ravits. Ela pode ser encontrada em http://efsa.sourceforge.net/archive/ravits/mysql.htm.
This is a translation of the MySQL Reference Manual that can be found at dev.mysql.com. The original Reference Manual is in English, and this translation is not necessarily as up to date as the English version.