Função SQLFetchScroll

Conformidade
Versão Introduzida: Normas ODBC 3.0 Conformidade: ISO 92

Summary
O SQLFetchScroll recolhe o conjunto de linhas especificado de dados do conjunto de resultados e devolve dados para todas as colunas limitadas. Os conjuntos de linhas podem ser especificados numa posição absoluta ou relativa ou por marcador de página.

Ao trabalhar com um driver ODBC 2.x, o Gestor de Drivers mapeia esta função para SQLExtendedFetch. Para mais informações, consulte Mapear Funções de Substituição para Compatibilidade Retroativa de Aplicações.

Syntax

  
SQLRETURN SQLFetchScroll(  
      SQLHSTMT      StatementHandle,  
      SQLSMALLINT   FetchOrientation,  
      SQLLEN        FetchOffset);

Arguments

HandleStatement
[Entrada] Identificador do extrato.

FetchOrientation
[Entrada]

Tipo de busca:

SQL_FETCH_NEXT

SQL_FETCH_PRIOR

SQL_FETCH_FIRST

SQL_FETCH_LAST

SQL_FETCH_ABSOLUTE

SQL_FETCH_RELATIVE

SQL_FETCH_BOOKMARK

Para mais informações, consulte "Posicionamento do Cursor" na secção "Comentários".

FetchOffset
[Entrada]

Número da fila a buscar. A interpretação deste argumento depende do valor do argumento FetchOrientation . Para mais informações, consulte "Posicionamento do Cursor" na secção "Comentários".

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLFetchScroll devolve SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela seguinte lista os valores SQLSTATE comumente devolvidos pelo SQLFetchScroll e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário. Se ocorrer um erro numa única coluna, o SQLGetDiagField pode ser chamado com um DiagIdentifier de SQL_DIAG_COLUMN_NUMBER para determinar a coluna onde o erro ocorreu; e SQLGetDiagField pode ser chamado com um DiagIdentifier de SQL_DIAG_ROW_NUMBER para determinar a linha que contém essa coluna.

Para todos os SQLSTATEs que podem devolver SQL_SUCCESS_WITH_INFO ou SQL_ERROR (exceto 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO é devolvido se ocorrer um erro numa ou mais, mas não todas, linhas de uma operação de várias linhas, e SQL_ERROR é devolvido se ocorrer um erro numa operação de uma única linha.

SQLSTATE	Erro	Descrição
01000	Aviso geral	Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.)
01004	Dados de cadeia, truncados à direita	Dados de string ou binários devolvidos para uma coluna resultavam na truncação de caracteres não em branco ou de dados binários não NULL. Se fosse um valor de cadeia, era truncado à direita.
01S01	Erro em linha	Ocorreu um erro ao buscar uma ou mais linhas. (Se este SQLSTATE for devolvido quando uma aplicação ODBC 3.x estiver a trabalhar com um driver ODBC 2.x, pode ser ignorado.)
01S06	Tentar buscar antes do conjunto de resultados devolver o primeiro conjunto de linhas	O conjunto de linhas solicitado sobrepunha o início do conjunto de resultados quando o FetchOrientation estava SQL_FETCH_PRIOR, a posição atual estava para além da primeira linha e o número da linha atual era menor ou igual ao tamanho do conjunto de linhas. O conjunto de linhas solicitado sobrepunha-se ao início do conjunto de resultados quando o FetchOrientation estava SQL_FETCH_PRIOR, a posição atual estava para além do fim do conjunto de resultados, e o tamanho do conjunto de linhas era maior do que o tamanho do conjunto de resultados. O conjunto de linhas solicitado sobrepunha-se ao início do conjunto de resultados quando o FetchOrientation estava SQL_FETCH_RELATIVE, o FetchOffset era negativo e o valor absoluto do FetchOffset era menor ou igual ao tamanho do conjunto de linhas. O conjunto de linhas solicitado sobrepunha-se ao início do conjunto de resultados quando o FetchOrientation era SQL_FETCH_ABSOLUTE, o FetchOffset era negativo e o valor absoluto do FetchOffset era maior do que o tamanho do conjunto de resultados, mas inferior ou igual ao tamanho do conjunto de linhas. (Função devolve SQL_SUCCESS_WITH_INFO.)
01S07	Truncamento fracionado	Os dados devolvidos para uma coluna eram truncados. Para tipos de dados numéricos, a parte fracionária do número era truncada. Para tipos de dados de tempo, carimbo temporal e intervalo contendo um componente temporal, a parte fracionária do tempo foi truncada. (Função devolve SQL_SUCCESS_WITH_INFO.)
07006	Violação de atributo de tipo de dado restrito	O valor de dados de uma coluna no conjunto de resultados não podia ser convertido para o tipo de dados especificado pelo TargetType no SQLBindCol. A coluna 0 era atribuída a um tipo de dado SQL_C_BOOKMARK, e o atributo da instrução SQL_ATTR_USE_BOOKMARKS era definido como SQL_UB_VARIABLE. A coluna 0 foi atribuída a um tipo de dado SQL_C_VARBOOKMARK, e o atributo da instrução SQL_ATTR_USE_BOOKMARKS não foi definido como SQL_UB_VARIABLE.
07009	Índice de descritores inválido	O controlador era um ODBC 2.x que não suporta SQLExtendedFetch, e o número de coluna especificado na ligação para uma coluna era 0. A coluna 0 foi encadernada, e o atributo da instrução SQL_ATTR_USE_BOOKMARKS foi definido para SQL_UB_OFF.
08S01	Falha da ligação de comunicação	A ligação de comunicação entre o driver e a fonte de dados à qual o driver estava ligado falhou antes de a função concluir o processamento.
22001	Dados de cadeia, truncados à direita	Um marcador de página de comprimento variável devolvido para uma coluna era truncado.
22002	Variável indicadora necessária, mas não fornecida	Os dados NULL eram recolhidos numa coluna cujo StrLen_or_IndPtr definido pelo SQLBindCol (ou SQL_DESC_INDICATOR_PTR conjunto pelo SQLSetDescField ou SQLSetDescRec) era um ponteiro nulo.
22003	Valor numérico fora do intervalo	Devolver o valor numérico (como numérico ou string) para uma ou mais colunas encadernadas teria feito com que toda a parte (em vez de fracionária) do número fosse truncada. Para mais informações, consulte Conversão de Dados de SQL para Tipos de Dados C no Apêndice D: Tipos de Dados.
22007	Formato de data-hora inválido	Uma coluna de caracteres no conjunto de resultados era associada a uma estrutura C, data, hora ou carimbo temporal, e um valor na coluna era, respetivamente, uma data, hora ou carimbo temporal inválido.
22012	Divisão por zero	Um valor de uma expressão aritmética era devolvido, o que resultava numa divisão por zero.
22015	Excesso de campo de intervalo	Atribuir de um tipo SQL numérico ou de intervalo exato a um tipo C de intervalo causava uma perda significativa de dígitos no campo principal. Ao buscar dados para um tipo de intervalo C, não havia representação do valor do tipo SQL no tipo de intervalo C.
22018	Valor de personagem inválido para especificação de elenco	Uma coluna de caracteres no conjunto de resultados estava associada a um buffer de caracteres C, e a coluna continha um carácter para o qual não havia representação no conjunto de caracteres do buffer. O tipo C era um tipo numérico exato ou aproximado, uma data-hora ou um tipo de dado de intervalo; o tipo SQL da coluna era um tipo de dado de carácter; e o valor na coluna não era um literal válido do tipo C limitado.
24000	Estado do cursor inválido	O StatementHandle estava num estado executado, mas nenhum conjunto de resultados estava associado ao StatementHandle.
40001	Falha de serialização	A transação em que o fetch foi executado foi terminada para evitar um impasse.
40003	Conclusão da afirmação desconhecida	A ligação associada falhou durante a execução desta função, e o estado da transação não pode ser determinado.
HY000	Erro geral	Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer MessageText* descreve o erro e a sua causa.
HY001	Erro de alocação de memória	O driver não conseguia alocar a memória necessária para suportar a execução ou conclusão da função.
HY008	Operação cancelada	O processamento assíncrono foi ativado para o StatementHandle. A função era chamada e, antes de terminar a execução, o SQLCancel ou SQLCancelHandle era chamado no StatementHandle. Depois, a função era chamada novamente no StatementHandle. A função era chamada e, antes de terminar a execução, o SQLCancel ou SQLCancelHandle era chamado no StatementHandle a partir de um thread diferente numa aplicação multithread.
HY010	Erro de sequência de funções	(DM) Uma função de execução assíncrona era chamada para o handle de ligação associado ao StatementHandle. Esta função assíncrona ainda estava a ser executada quando a função SQLFetchScroll foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults era chamado para o StatementHandle e devolvido SQL_PARAM_DATA_AVAILABLE. Esta função era chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. (DM) O HandleStatement especificado não estava num estado executado. A função era chamada sem antes chamar SQLExecDirect, SQLExecute ou uma função de catálogo. (DM) Uma função de execução assíncrona (não esta) era chamada para o StatementHandle e continuava a ser executada quando esta função era chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos era chamado para o StatementHandle e devolvido SQL_NEED_DATA. Esta função era chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados na execução. (DM) SQLFetch foi chamado para o StatementHandle depois de ser chamado SQLExtendedFetch e antes de SQLFreeStmt com a opção SQL_CLOSE ser chamada.
HY013	Erro de gestão de memória	A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória.
HY090	Comprimento inválido da corda ou do buffer	O atributo da instrução SQL_ATTR_USE_BOOKMARK foi definido para SQL_UB_VARIABLE, e a coluna 0 foi atribuída a um buffer cujo comprimento não era igual ao comprimento máximo do marcador para este conjunto de resultados. (Este comprimento está disponível no campo SQL_DESC_OCTET_LENGTH do IRD e pode ser obtido chamando SQLDescribeCol, SQLColAttributes ou SQLGetDescField.)
HY106	Tipo de busca fora do alcance	DM) O valor especificado para o argumento FetchOrientation era inválido. (DM) O argumento FetchOrientation foi SQL_FETCH_BOOKMARK, e o atributo da SQL_ATTR_USE_BOOKMARKS foi definido para SQL_UB_OFF. O valor do atributo da SQL_ATTR_CURSOR_TYPE sentença era SQL_CURSOR_FORWARD_ONLY, e o valor do argumento FetchOrientation não era SQL_FETCH_NEXT. O valor do atributo da SQL_ATTR_CURSOR_SCROLLABLE instrução era SQL_NONSCROLLABLE, e o valor do argumento FetchOrientation não era SQL_FETCH_NEXT.
HY107	Valor da linha fora do intervalo	O valor especificado com o atributo de instrução SQL_ATTR_CURSOR_TYPE era SQL_CURSOR_KEYSET_DRIVEN, mas o valor especificado com o atributo de instrução SQL_ATTR_KEYSET_SIZE era maior que 0 e inferior ao valor especificado com o atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE.
HY111	Valor de marcador inválido	O argumento FetchOrientation era SQL_FETCH_BOOKMARK, e o marcador apontado pelo valor no atributo da instrução SQL_ATTR_FETCH_BOOKMARK_PTR não era válido ou era um ponteiro nulo.
HY117	A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas.	(DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran.
HYC00	Funcionalidade opcional não implementada	O driver ou fonte de dados não suporta a conversão especificada pela combinação do TargetType no SQLBindCol e do tipo de dados SQL da coluna correspondente.
HYT00	O tempo limite expirou	O período de tempo de espera da consulta expirava antes de a fonte de dados devolver o conjunto de resultados solicitado. O período de tempo é definido através do SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01	Expirou o tempo limite de ligação	O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	O driver não suporta esta função	(DM) O driver associado ao StatementHandle não suporta a função.
IM017	A sondagem está desativada no modo de notificação assíncrona	Sempre que o modelo de notificação é utilizado, o sonding é desativado.
IM018	O SQLCompleteAsync não foi chamado para completar a operação assíncrona anterior neste handle.	Se a chamada de função anterior no handle devolver SQL_STILL_EXECUTING e se o modo de notificação estiver ativado, o SQLCompleteAsync deve ser chamado no handle para fazer o pós-processamento e completar a operação.

Comments

SQLFetchScroll devolve um conjunto de linhas especificado do conjunto de resultados. Os conjuntos de linhas podem ser especificados por posição absoluta ou relativa ou por favorito. SQLFetchScroll só pode ser chamado enquanto existe um conjunto de resultados – ou seja, após uma chamada que cria um conjunto de resultados e antes de o cursor sobre esse conjunto ser fechado. Se alguma coluna estiver vinculada, devolve os dados nessas colunas. Se a aplicação especificou um ponteiro para um array de estado de linhas ou um buffer onde devolver o número de linhas buscadas, o SQLFetchScroll devolve também esta informação. Chamadas para SQLFetchScroll podem ser misturadas com chamadas para SQLFetch , mas não podem ser misturadas com chamadas para SQLExtendedFetch.

Para mais informações, consulte Uso de Cursores de Bloco e Utilização de Cursores Roláveis.

Posicionamento do Cursor

Quando o conjunto de resultados é criado, o cursor é posicionado antes do início do conjunto de resultados. SQLFetchScroll posiciona o cursor de bloco com base nos valores dos argumentos FetchOrientation e FetchOffset , conforme mostrado na tabela seguinte. As regras exatas para determinar o início do novo conjunto de linhas são apresentadas na secção seguinte.

FetchOrientation	Meaning
SQL_FETCH_NEXT	Devolve o próximo conjunto de linhas. Isto é equivalente a chamar SQLFetch. O SQLFetchScroll ignora o valor do FetchOffset.
SQL_FETCH_PRIOR	Devolve o conjunto de linhas anterior. O SQLFetchScroll ignora o valor do FetchOffset.
SQL_FETCH_RELATIVE	Devolva o conjunto de linhas FetchOffset do início do conjunto de linhas atual.
SQL_FETCH_ABSOLUTE	Devolva o conjunto de linhas começando na linha FetchOffset.
SQL_FETCH_FIRST	Devolva o primeiro conjunto de linhas no conjunto de resultados. O SQLFetchScroll ignora o valor do FetchOffset.
SQL_FETCH_LAST	Devolva o último conjunto completo de linhas no conjunto de resultados. O SQLFetchScroll ignora o valor do FetchOffset.
SQL_FETCH_BOOKMARK	Devolva as linhas FetchOffset do conjunto de linhas do marcador especificado pelo atributo da instrução SQL_ATTR_FETCH_BOOKMARK_PTR.

Os drivers não são obrigados a suportar todas as orientações de busca; uma aplicação chama SQLGetInfo com um tipo de informação SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 ou SQL_STATIC_CURSOR_ATTRIBUTES1 (dependendo do tipo de cursor) para determinar quais as orientações de busca suportadas pelo driver. A aplicação deve analisar as máscaras de bits SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE e WQL_CA1_BOOKMARK nestes tipos de informação. Além disso, se o cursor for apenas para frente e o FetchOrientation não estiver SQL_FETCH_NEXT, o SQLFetchScroll devolve SQLSTATE HY106 (tipo Fetch fora do alcance).

O atributo da instrução SQL_ATTR_ROW_ARRAY_SIZE especifica o número de linhas no conjunto de linhas. Se o conjunto de linhas que está a ser obtido pelo SQLFetchScroll se sobrepõe ao final do conjunto de resultados, o SQLFetchScroll devolve um conjunto parcial de linhas. Ou seja, se S + R - 1 for maior que L, onde S é a linha inicial do conjunto de linhas a ser buscado, R é o tamanho do conjunto de linhas, e L é a última linha do conjunto de resultados, então apenas as primeiras L - S + 1 linhas do conjunto são válidas. As restantes linhas estão vazias e têm o estado de SQL_ROW_NOROW.

Depois de o SQLFetchScroll regressar, a linha atual é a primeira linha do conjunto de linhas.

Regras de Posicionamento do Cursor

As secções seguintes descrevem as regras exatas para cada valor do FetchOrientation. Estas regras usam a seguinte notação.

Anotações	Meaning
Antes de começar	O cursor de bloco está posicionado antes do início do conjunto de resultados. Se a primeira linha do novo conjunto de linhas for anterior ao início do conjunto de resultados, SQLFetchScroll devolve SQL_NO_DATA.
Após o fim	O cursor de bloco é posicionado após o final do conjunto de resultados. Se a primeira linha do novo conjunto de linhas for posterior ao fim do conjunto de resultados, SQLFetchScroll devolve SQL_NO_DATA.
CurrRowsetStart	O número da primeira linha do conjunto atual.
LastResultRow	O número da última linha do conjunto de resultados.
RowsetSize	O tamanho do conjunto de linhas.
FetchOffset	O valor do argumento FetchOffset .
BookmarkRow	A linha correspondente ao marcador especificado pelo atributo SQL_ATTR_FETCH_BOOKMARK_PTR sentença.