Buffers

Um buffer é qualquer parte da memória do aplicativo usada para passar dados entre o aplicativo e o driver. Por exemplo, os buffers de aplicativo podem ser associados ou ligados a colunas de conjunto de resultados com SQLBindCol. À medida que cada linha é buscada, os dados são retornados para cada coluna nesses buffers. Os buffers de entrada são usados para passar dados do aplicativo para o driver; os buffers de saída são usados para retornar dados do driver para o aplicativo.

Observação

Se uma função ODBC retornar SQL_ERROR, o conteúdo de quaisquer argumentos de saída para essa função será indefinido.

Essa discussão se preocupa principalmente com buffers de tipo indeterminado. Os endereços desses buffers aparecem como argumentos do tipo SQLPOINTER, como o argumento TargetValuePtr no SQLBindCol. No entanto, alguns dos itens discutidos aqui, como os argumentos usados com buffers, também se aplicam a argumentos usados para passar cadeias de caracteres para o driver, como o argumento TableName em SQLTables.

Esses buffers geralmente são fornecidos em pares. Os buffers de dados são usados para passar os dados em si, enquanto os buffers de comprimento/indicador são usados para passar o comprimento dos dados no buffer de dados ou um valor especial, como SQL_NULL_DATA, o que indica que os dados são NULL. O comprimento dos dados em um buffer de dados é diferente do comprimento do próprio buffer de dados. A ilustração a seguir mostra a relação entre o buffer de dados e o buffer de comprimento/indicador.

Um buffer de comprimento/indicador é necessário sempre que o buffer de dados contém dados de comprimento variável, como dados binários ou caracteres. Se o buffer de dados contiver dados de comprimento fixo, como um inteiro ou uma estrutura de data, um buffer de comprimento/indicador será necessário apenas para passar valores de indicador porque o comprimento dos dados já é conhecido. Se um aplicativo usa um buffer de comprimento/indicador com dados de comprimento fixo, o driver ignora todos os comprimentos passados nele.

O comprimento do buffer de dados e dos dados que ele contém é medido em bytes, em vez de caracteres. Essa distinção não é importante para programas que usam cadeias de caracteres ANSI porque os comprimentos em bytes e caracteres são os mesmos.

Quando o buffer de dados representa um campo de descritor definido pelo driver, um campo de diagnóstico ou um atributo, o aplicativo deve indicar ao Gerenciador de Driver a natureza do argumento de função que indica o valor do campo ou atributo. O aplicativo faz isso definindo o argumento de comprimento em qualquer chamada de função que define o campo ou atributo como um dos valores a seguir. (O mesmo é verdadeiro para funções que recuperam os valores do campo ou atributo, com a exceção de que o argumento aponta para os valores que para a função de configuração estão no próprio argumento.)

• Se o argumento de função que indica o valor do campo ou atributo for um ponteiro para uma cadeia de caracteres, o argumento de comprimento será o comprimento da cadeia de caracteres ou SQL_NTS.

• Se o argumento de função que indica o valor do campo ou atributo for um ponteiro para um buffer binário, o aplicativo colocará o resultado da macro SQL_LEN_BINARY_ATTR(comprimento) no argumento comprimento. Isso coloca um valor negativo no argumento length .

• Se o argumento de função que indica o valor do campo ou atributo for um ponteiro para um valor diferente de uma cadeia de caracteres ou uma cadeia de caracteres binária, o argumento de comprimento deverá ter o valor SQL_IS_POINTER.

• Se o argumento de função que indica o valor do campo ou atributo contiver um valor de comprimento fixo, o argumento de comprimento será SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_ISI_USMALLINT, conforme apropriado.

Esta seção contém os seguintes tópicos.

• Buffers diferidos

• Alocando e liberando buffers

• Usando buffers de dados