Buscar uma linha de dados
Para buscar uma linha de dados, um aplicativo chama SQLFetch. SQLFetch pode ser chamado com qualquer tipo de cursor, mas ele só move o cursor do conjunto de linhas em uma direção somente para frente. SQLFetch avança o cursor para a próxima linha e retorna os dados de todas as colunas que foram associadas com chamadas para SQLBindCol. Quando o cursor atinge o final do conjunto de resultados, SQLFetch retorna SQL_NO_DATA. Para obter exemplos de chamada SQLFetch, confira Usar SQLBindCol.
Exatamente como o SQLFetch é implementado é específico do driver, mas o padrão geral é que o driver recupere os dados para colunas associadas da fonte de dados, converta-os de acordo com os tipos das variáveis associadas e coloque os dados convertidos nessas variáveis. Se o driver não puder converter nenhum dado, SQLFetch retornará um erro. O aplicativo pode continuar buscando linhas, mas os dados da linha atual são perdidos. O que acontece com os dados para colunas não associadas depende do driver, mas a maioria dos drivers os recupera e descarta ou nunca os recupera.
O driver também define os valores de qualquer buffer de comprimento/indicador que tenha sido associado. Se o valor de dados de uma coluna for NULL, o driver definirá o buffer de comprimento/indicador correspondente como SQL_NULL_DATA. Se o valor de dados não for NULL, o driver definirá o buffer de comprimento/indicador para o comprimento de byte dos dados após a conversão. Se esse comprimento não puder ser determinado, como às vezes é o caso com dados longos que são recuperados por mais de uma chamada de função, o driver define o buffer de comprimento/indicador como SQL_NO_TOTAL. Para tipos de dados de comprimento fixo, como inteiros e estruturas de data, o comprimento do byte é o tamanho do tipo de dados.
Para dados de comprimento variável, como dados de caracteres e binários, o driver verifica o comprimento do byte dos dados convertidos em relação ao comprimento do byte do buffer associado à coluna; o comprimento do buffer é especificado no argumento BufferLength no SQLBindCol. Se o comprimento do byte dos dados convertidos for maior que o comprimento do byte do buffer, o driver truncará os dados para caber no buffer, retornará o comprimento não truncado no buffer de comprimento/indicador, retornará SQL_SUCCESS_WITH_INFO e colocará SQLSTATE 01004 (dados truncados) no diagnóstico. A única exceção a isso é se um indicador de comprimento variável for truncado quando retornado por SQLFetch, que retorna SQLSTATE 22001 (dados de cadeia de caracteres, truncados à direita).
Os dados de comprimento fixo nunca são truncados, porque o driver assume que o tamanho do buffer associado é o tamanho do tipo de dados. O truncamento de dados tende a ser raro, porque o aplicativo geralmente associa um buffer grande o suficiente para armazenar todo o valor de dados; ele determina o tamanho necessário a partir dos metadados. No entanto, o aplicativo pode associar explicitamente um buffer que ele sabe ser muito pequeno. Por exemplo, ele pode recuperar e exibir os primeiros 20 caracteres de uma descrição de peça ou os primeiros 100 caracteres de uma coluna de texto longa.
Os dados de caracteres devem ser terminados em nulo pelo driver antes de serem retornados ao aplicativo, mesmo que tenham sido truncados. O caractere de terminação nula não está incluído no comprimento de byte retornado, mas requer espaço no buffer associado. Por exemplo, suponha que um aplicativo use cadeias de caracteres compostas de dados de caracteres no conjunto de caracteres ASCII, um driver tenha 50 caracteres de dados para retornar e o buffer do aplicativo tenha 25 bytes. No buffer do aplicativo, o driver retorna os primeiros 24 caracteres seguidos por um caractere de terminação nula. No buffer de comprimento/indicador, ele retorna um comprimento de byte de 50.
O aplicativo pode restringir o número de linhas no conjunto de resultados definindo o atributo de instrução SQL_ATTR_MAX_ROWS antes de executar a instrução que cria o conjunto de resultados. Por exemplo, o modo de visualização em um aplicativo usado para formatar relatórios precisa apenas de dados suficientes para exibir a primeira página do relatório. Ao restringir o tamanho do conjunto de resultados, esse recurso seria executado mais rapidamente. Esse atributo de instrução se destina a reduzir o tráfego de rede e pode não ser suportado por todos os drivers.