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