Tipos de Dados de Instruções Preparadas da API C

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

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

• MYSQL_STMT
  

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

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

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

• MYSQL_BIND
  

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

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

  • enum enum_field_types buffer_type
    

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

  • void *buffer
    

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

  • unsigned long buffer_length
    

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

  • unsigned long *length
    

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

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

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

  • bool *is_null
    

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

• MYSQL_TIME

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

  A estrutura MYSQL_TIME contém os seguintes membros:

  • unsigned int year
    

    O ano.

  • unsigned int month
    

    O mês do ano.

  • unsigned int day
    

    O dia do mês.

  • unsigned int hour
    

    A hora do dia.

  • unsigned int minute
    

    O minuto da hora.

  • unsigned int second
    

    Os segundos.

  • my_bool neg
    

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

  • unsigned long second_part
    

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

  Apenas aquelas partes de uma estrutura MYSQL_TIME que se aplica a um dado tipo de valor temporal são usados: Os elementos year, month e day são usados para valores DATE, DATETIME e TIMESTAMP. Os elementos hour, minute e second são usados para valores TIME, DATETIME e TIMESTAMP. Leia "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.

Retornar