Buffers
Um buffer é qualquer pedaço de memória do aplicativo usado para passar dados entre o aplicativo e o driver. Por exemplo, os buffers de aplicativos podem ser associados ou vinculados 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 diz respeito principalmente aos 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 vêm em pares. Os buffers de dados são usados para passar os próprios dados, enquanto os buffers de comprimento/indicadores são usados para passar o comprimento dos dados no buffer de dados ou um valor especial, como SQL_NULL_DATA, 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 de caracteres ou binários. 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 oposição a caracteres. Essa distinção não é importante para programas que usam cadeias de caracteres ANSI porque as durações em bytes e caracteres são as mesmas.
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 length em qualquer chamada de função que define o campo ou atributo para um dos seguintes valores. (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 length 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 length. Isso coloca um valor negativo no argumentolength.
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 length 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 length será SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_ISI_USMALLINT, conforme apropriado.
Esta seção contém os tópicos a seguir.