SQLFetchScroll (Biblioteca de cursores)

Importante

Esse recurso será removido em uma versão futura do Windows. Evite usar esse recurso em um novo trabalho de desenvolvimento e planeje modificar aplicativos que atualmente usam esse recurso. A Microsoft recomenda usar a funcionalidade de cursor do driver.

Este tópico discute o uso da função SQLFetchScroll na biblioteca de cursores. Para obter informações gerais sobre SQLFetchScroll, consulte Função SQLFetchScroll.

A biblioteca de cursores implementa SQLFetchScroll chamando repetidamente SQLFetch no driver. Ele transfere os dados recuperados do driver para os buffers de conjunto de linhas fornecidos pelo aplicativo. Ele também armazena em cache os dados em arquivos de memória e disco. Quando um aplicativo solicita um novo conjunto de linhas, a biblioteca de cursores a recupera conforme necessário do driver (se não tiver sido buscado anteriormente) ou do cache (se ele tiver sido buscado anteriormente). Por fim, a biblioteca de cursores mantém o status dos dados armazenados em cache e retorna essas informações ao aplicativo na matriz de status da linha.

Quando a biblioteca de cursores é usada, as chamadas para SQLFetchScroll não podem ser misturadas com chamadas para SQLFetch ou SQLExtendedFetch.

Quando a biblioteca de cursores é usada, há suporte para chamadas para SQLFetchScroll para ODBC 2. x e para ODBC 3. x drivers.

Buffers de conjunto de linhas

A biblioteca de cursores otimiza a transferência de dados do driver para o buffer de conjunto de linhas fornecido pelo aplicativo se:

• O aplicativo usa a associação em linha.

• Não há bytes não utilizados entre campos na estrutura que o aplicativo declara para manter uma linha de dados.

• Os campos nos quais SQLFetch ou SQLFetchScroll retorna o comprimento/indicador de uma coluna seguem o buffer dessa coluna e precedem o buffer para a próxima coluna. Esses campos são opcionais.

Quando o aplicativo solicita um novo conjunto de linhas, a biblioteca de cursores recupera dados de seu cache e do driver, conforme necessário. Se os conjuntos de linhas novos e antigos se sobrepõem, a biblioteca de cursores poderá otimizar seu desempenho reutilizando os dados das seções sobrepostas dos buffers de conjunto de linhas. Portanto, as alterações não salvas nos buffers de conjunto de linhas são perdidas, a menos que os conjuntos de linhas novos e antigos se sobreponham e as alterações estejam nas seções sobrepostas dos buffers de conjunto de linhas. Para salvar as alterações, um aplicativo envia uma instrução de atualização posicionada.

Observe que a biblioteca de cursores sempre atualiza os buffers de conjunto de linhas com dados do cache quando um aplicativo chama SQLFetchScroll com o argumento FetchOrientation definido como SQL_FETCH_RELATIVE e o argumento FetchOffset definido como 0.

A biblioteca de cursores dá suporte à chamada de SQLSetStmtAttr com um atributo de SQL_ATTR_ROW_ARRAY_SIZE para alterar o tamanho do conjunto de linhas enquanto um cursor está aberto. O novo tamanho do conjunto de linhas entrará em vigor na próxima vez que SQLFetchScroll for chamado.

Associação do Conjunto de Resultados

A biblioteca de cursores recupera dados do driver somente conforme o aplicativo os solicita. Dependendo da fonte de dados e da configuração do atributo de instrução SQL_CONCURRENCY, isso tem as seguintes consequências:

• Os dados recuperados pela biblioteca de cursores podem ser diferentes dos dados que estavam disponíveis no momento em que a instrução foi executada. Por exemplo, depois que o cursor foi aberto, as linhas inseridas em um ponto além da posição atual do cursor podem ser recuperadas por alguns drivers.

• Os dados no conjunto de resultados podem ser bloqueados pela fonte de dados da biblioteca de cursores e, portanto, não estar disponíveis para outros usuários.

Depois que a biblioteca de cursores tiver armazenado em cache uma linha de dados, ela não poderá detectar alterações nessa linha na fonte de dados subjacente (exceto para atualizações posicionadas e exclusões que operam no cache do mesmo cursor). Isso ocorre porque, para chamadas para SQLFetchScroll, a biblioteca de cursores nunca refeta dados da fonte de dados. Em vez disso, ele refeta dados de seu cache.

Rolagem

A biblioteca de cursores dá suporte aos seguintes tipos de busca no SQLFetchScroll.

Tipo de cursor	Tipos de busca
Somente avanço	SQL_FETCH_NEXT
Estático	SQL_FETCH_NEXT SQL_FETCH_PRIOR SQL_FETCH_FIRST SQL_FETCH_LAST SQL_FETCH_RELATIVE SQL_FETCH_ABSOLUTE SQL_FETCH_BOOKMARK

Errors

Quando SQLFetchScroll é chamado e uma das chamadas para SQLFetch retorna SQL_ERROR, a biblioteca de cursores prossegue da seguinte maneira. Depois de concluir essas etapas, a biblioteca de cursores continuará sendo processada.

1. Chama SQLGetDiagRec para obter informações de erro do driver e posta isso como um registro de diagnóstico no Gerenciador de Driver.

2. Define o campo SQL_DIAG_ROW_NUMBER no registro de diagnóstico como o valor apropriado.

3. Define o campo SQL_DIAG_COLUMN_NUMBER no registro de diagnóstico como o valor apropriado, se aplicável; caso contrário, ele o define como 0.

4. Define o valor da linha em erro na matriz de status da linha como SQL_ROW_ERROR.

Depois que a biblioteca de cursores tiver chamado SQLFetch várias vezes em sua implementação de SQLFetchScroll, qualquer erro ou aviso retornado por uma das chamadas para SQLFetch estará em um registro de diagnóstico e poderá ser recuperado por uma chamada para SQLGetDiagRec. Se os dados foram truncados quando foram buscados, os dados truncados agora residirão no cache da biblioteca de cursores. Chamadas subsequentes para SQLFetchScroll para rolar até uma linha com dados truncados retornarão os dados truncados e nenhum aviso será gerado porque os dados são buscados do cache da biblioteca de cursores. Para acompanhar o comprimento dos dados retornados para que ele possa determinar se os dados retornados em um buffer foram truncados, um aplicativo deve associar o buffer de comprimento/indicador.

Operações de indicador

A biblioteca de cursores dá suporte à chamada de SQLFetchScroll com uma FetchOrientation de SQL_FETCH_BOOKMARK. Ele também dá suporte à especificação de um deslocamento no argumento FetchOffset que pode ser usado na operação de indicador. Essa é a única operação de indicador compatível com a biblioteca de cursores. A biblioteca de cursores não dá suporte à chamada de SQLBulkOperations.

Se o aplicativo tiver definido o atributo de instrução SQL_ATTR_USE_BOOKMARKS e tiver associado à coluna de indicador, a biblioteca de cursores gerará um indicador de comprimento fixo e o retornará ao aplicativo. A biblioteca de cursores cria e mantém os indicadores que ela usa; ele não usa indicadores mantidos na fonte de dados. Quando SQLFetchScroll é chamado para recuperar um bloco de dados que já foi buscado da fonte de dados, ele recupera os dados do cache da biblioteca de cursores. Como resultado, o indicador usado em uma chamada para SQLFetchScroll com uma FetchOrientation de SQL_FETCH_BOOKMARK deve ser criado e mantido pela biblioteca de cursores.

Interação com outras funções

Um aplicativo deve chamar SQLFetch ou SQLFetchScroll antes de preparar ou executar instruções de atualização ou exclusão posicionadas.