Função SQLFetchScroll
Compatibilidade
Versão introduzida: ODBC 3.0 Conformidade com os padrões: ISO 92
Resumo
SQLFetchScroll busca o conjunto de linhas especificado de dados do conjunto de resultados e retorna dados para todas as colunas associadas. Os conjuntos de linhas podem ser especificados em uma posição absoluta ou relativa ou por indicador.
Ao trabalhar com um driver ODBC 2.x, o Gerenciador de Driver mapeia essa função para SQLExtendedFetch. Para obter mais informações, consulte Mapeando funções de substituição para compatibilidade com versões anteriores de aplicativos.
Sintaxe
SQLRETURN SQLFetchScroll(
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLLEN FetchOffset);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução.
Orientação de busca
[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 obter mais informações, consulte "Posicionando o cursor" na seção "Comentários".
FetchOffset
[Entrada]
Número da linha a ser buscada. A interpretação desse argumento depende do valor do argumento FetchOrientation . Para obter mais informações, consulte "Posicionando o cursor" na seçã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 retorna 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 a seguir lista os valores SQLSTATE normalmente retornados por SQLFetchScroll e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma. Se ocorrer um erro em uma única coluna, SQLGetDiagField poderá ser chamado com um DiagIdentifier de SQL_DIAG_COLUMN_NUMBER para determinar a coluna em que o erro ocorreu; e SQLGetDiagField poderá 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 retornar SQL_SUCCESS_WITH_INFO ou SQL_ERROR (exceto SQLSTATEs 01xxx), SQL_SUCCESS_WITH_INFO será retornado se ocorrer um erro em uma ou mais, mas não em todas, linhas de uma operação de várias linhas e SQL_ERROR será retornado se ocorrer um erro em uma operação de linha única.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia de caracteres, truncados à direita | Os dados de cadeia de caracteres ou binários retornados para uma coluna resultaram no truncamento de caracteres não em branco ou dados binários não NULL. Se fosse um valor de string, era truncado à direita. |
| 01S01 | Erro na linha | Ocorreu um erro ao buscar uma ou mais linhas. (Se esse SQLSTATE for retornado quando um aplicativo ODBC 3*.x* estiver funcionando com um driver ODBC 2*.x*, ele poderá ser ignorado.) |
| 01S06 | Tentativa de buscar antes que o conjunto de resultados retorne o primeiro conjunto de linhas | O conjunto de linhas solicitado se sobrepôs ao início do conjunto de resultados quando FetchOrientation foi SQL_FETCH_PRIOR, a posição atual estava além da primeira linha e o número da linha atual é menor ou igual ao tamanho do conjunto de linhas. O conjunto de linhas solicitado se sobrepôs ao início do conjunto de resultados quando FetchOrientation foi SQL_FETCH_PRIOR, a posição atual estava além do final do conjunto de resultados e o tamanho do conjunto de linhas era maior que o tamanho do conjunto de resultados. O conjunto de linhas solicitado se sobrepôs ao início do conjunto de resultados quando FetchOrientation era SQL_FETCH_RELATIVE, FetchOffset era negativo e o valor absoluto de FetchOffset era menor ou igual ao tamanho do conjunto de linhas. O conjunto de linhas solicitado se sobrepôs ao início do conjunto de resultados quando FetchOrientation era SQL_FETCH_ABSOLUTE, FetchOffset era negativo e o valor absoluto de FetchOffset era maior que o tamanho do conjunto de resultados, mas menor ou igual ao tamanho do conjunto de linhas. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01S07 | Truncamento fracionário | Os dados retornados para uma coluna foram truncados. Para tipos de dados numéricos, a parte fracionária do número foi truncada. Para tipos de dados de tempo, carimbo de data/hora e intervalo contendo um componente de tempo, a parte fracionária do tempo foi truncada. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 07006 | Violação de atributo de tipo de dados restrito | O valor de dados de uma coluna no conjunto de resultados não pôde ser convertido para o tipo de dados especificado por TargetType em SQLBindCol. A coluna 0 foi associada a um tipo de dados de SQL_C_BOOKMARK e o atributo de instrução SQL_ATTR_USE_BOOKMARKS foi definido como SQL_UB_VARIABLE. A coluna 0 foi associada a um tipo de dados de SQL_C_VARBOOKMARK e o atributo de instrução SQL_ATTR_USE_BOOKMARKS não foi definido como SQL_UB_VARIABLE. |
| 07009 | Índice de descritor inválido | O driver era um driver ODBC 2*.x* que não dá suporte a SQLExtendedFetch e um número de coluna especificado na associação para uma coluna era 0. A coluna 0 foi vinculada e o atributo de instrução SQL_ATTR_USE_BOOKMARKS foi definido como SQL_UB_OFF. |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver estava conectado falhou antes que a função concluísse o processamento. |
| 22001 | Dados de cadeia de caracteres, truncados à direita | Um indicador de comprimento variável retornado para uma coluna foi truncado. |
| 22002 | Variável indicadora necessária, mas não fornecida | Os dados NULL foram buscados em uma coluna cujo StrLen_or_IndPtr definido por SQLBindCol (ou SQL_DESC_INDICATOR_PTR definido por SQLSetDescField ou SQLSetDescRec) era um ponteiro nulo. |
| 22003 | Valor numérico fora do intervalo | Retornar o valor numérico (como numérico ou cadeia de caracteres) para uma ou mais colunas associadas faria com que toda a parte (em oposição à fracionária) do número fosse truncada. Para obter mais informações, consulte Convertendo dados de tipos de dados SQL em C no Apêndice D: Tipos de dados. |
| 22007 | Formato de data e hora inválido | Uma coluna de caracteres no conjunto de resultados foi associada a uma estrutura C de data, hora ou carimbo de data/hora, e um valor na coluna era, respectivamente, uma data, hora ou carimbo de data/hora inválido. |
| 22012 | Divisão por zero | Um valor de uma expressão aritmética foi retornado, o que resultou na divisão por zero. |
| 22015 | Estouro de campo de intervalo | A atribuição de um tipo SQL numérico ou de intervalo exato a um tipo C de intervalo causou uma perda de dígitos significativos 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 caractere inválido para especificação de conversão | Uma coluna de caracteres no conjunto de resultados foi associada a um buffer de caracteres C e a coluna continha um caractere para o qual não havia representação no conjunto de caracteres do buffer. O tipo C era um tipo de dados numérico exato ou aproximado, uma data/hora ou um tipo de dados de intervalo; o tipo SQL da coluna era um tipo de dados de caractere; e o valor na coluna não era um literal válido do tipo C associado. |
| 24000 | Estado de cursor inválido | O StatementHandle estava em um estado executado, mas nenhum conjunto de resultados foi associado ao StatementHandle. |
| 40001 | Falha de serialização | A transação na qual a busca foi executada foi encerrada para evitar deadlock. |
| 40003 | Conclusão da instrução desconhecida | A conexão associada falhou durante a execução dessa função e o estado da transação não pode ser determinado. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | O driver não pôde alocar a memória necessária para dar suporte à execução ou conclusão da função. |
| HY008 | Operação cancelada | O processamento assíncrono foi habilitado para o StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle. Em seguida, a função foi chamada novamente no StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle de um thread diferente em um aplicativo multithread. |
| HY010 | Erro de sequência de função | (DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função assíncrona ainda estava em execução quando a função SQLFetchScroll foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. (DM) O StatementHandle especificado não estava em um estado executado. A função foi chamada sem primeiro chamar SQLExecDirect, SQLExecute ou uma função de catálogo. (DM) Uma função de execução assíncrona (não esta) foi chamada para o StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para o StatementHandle e retornado SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução. (DM) SQLFetch foi chamado para o StatementHandle depois que SQLExtendedFetch foi chamado e antes de SQLFreeStmt com a opção SQL_CLOSE ser chamada. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa. |
| HY090 | Cadeia de caracteres ou comprimento de buffer inválido | O atributo de instrução SQL_ATTR_USE_BOOKMARK foi definido como SQL_UB_VARIABLE e a coluna 0 foi associada a um buffer cujo comprimento não era igual ao comprimento máximo do indicador para esse conjunto de resultados. (Esse comprimento está disponível no campo SQL_DESC_OCTET_LENGTH do IRD e pode ser obtido chamando SQLDescribeCol, SQLColAttribute ou SQLGetDescField.) |
| HY106 | Buscar tipo fora do intervalo | DM) O valor especificado para o argumento FetchOrientation era inválido. (DM) O argumento FetchOrientation foi SQL_FETCH_BOOKMARK e o atributo de instrução SQL_ATTR_USE_BOOKMARKS foi definido como SQL_UB_OFF. O valor do atributo de instrução SQL_ATTR_CURSOR_TYPE foi SQL_CURSOR_FORWARD_ONLY e o valor do argumento FetchOrientation não foi SQL_FETCH_NEXT. O valor do atributo de instrução SQL_ATTR_CURSOR_SCROLLABLE foi SQL_NONSCROLLABLE e o valor do argumento FetchOrientation não foi 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 menor que o valor especificado com o atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE. |
| HY111 | Valor de indicador inválido | O argumento FetchOrientation foi SQL_FETCH_BOOKMARK e o indicador apontado pelo valor no atributo de instrução SQL_ATTR_FETCH_BOOKMARK_PTR não era válido ou era um ponteiro nulo. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran. |
| HYC00 | Recurso opcional não implementado | O driver ou a fonte de dados não dá suporte à conversão especificada pela combinação do TargetType no SQLBindCol e do tipo de dados SQL da coluna correspondente. |
| HYT00 | Timeout expired | O período de tempo limite da consulta expirou antes que a fonte de dados retornasse o conjunto de resultados solicitado. O período de tempo limite é definido por meio de SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver associado ao StatementHandle não dá suporte à função. |
| IM017 | A sondagem está desabilitada no modo de notificação assíncrona | Sempre que o modelo de notificação é usado, a sondagem é desabilitada. |
| IM018 | SQLCompleteAsync não foi chamado para concluir a operação assíncrona anterior nesse identificador. | Se a chamada de função anterior no identificador retornar SQL_STILL_EXECUTING e se o modo de notificação estiver habilitado, SQLCompleteAsync deverá ser chamado no identificador para fazer o pós-processamento e concluir a operação. |
Comentários
SQLFetchScroll retorna um conjunto de linhas especificado do conjunto de resultados. Os conjuntos de linhas podem ser especificados por posição absoluta ou relativa ou por indicador. SQLFetchScroll pode ser chamado somente enquanto existe um conjunto de resultados, ou seja, após uma chamada que cria um conjunto de resultados e antes que o cursor sobre esse conjunto de resultados seja fechado. Se alguma coluna estiver associada, ela retornará os dados nessas colunas. Se o aplicativo tiver especificado um ponteiro para uma matriz de status de linha ou um buffer no qual retornar o número de linhas buscadas, SQLFetchScroll também retornará essas informações. As chamadas para SQLFetchScroll podem ser misturadas com chamadas para SQLFetch , mas não podem ser misturadas com chamadas para SQLExtendedFetch.
Para obter mais informações, consulte Usando cursores de bloco e Usando cursores roláveis.
Posicionando o cursor
Quando o conjunto de resultados é criado, o cursor é posicionado antes do início do conjunto de resultados. SQLFetchScroll posiciona o cursor do bloco com base nos valores dos argumentos FetchOrientation e FetchOffset , conforme mostrado na tabela a seguir. As regras exatas para determinar o início do novo conjunto de linhas são mostradas na próxima seção.
| Orientação de busca | Significado |
|---|---|
| SQL_FETCH_NEXT | Retorne o próximo conjunto de linhas. Isso é equivalente a chamar SQLFetch. SQLFetchScroll ignora o valor de FetchOffset. |
| SQL_FETCH_PRIOR | Retorne o conjunto de linhas anterior. SQLFetchScroll ignora o valor de FetchOffset. |
| SQL_FETCH_RELATIVE | Retorne o conjunto de linhas FetchOffset do início do conjunto de linhas atual. |
| SQL_FETCH_ABSOLUTE | Retorne o conjunto de linhas começando na linha FetchOffset. |
| SQL_FETCH_FIRST | Retorne o primeiro conjunto de linhas no conjunto de resultados. SQLFetchScroll ignora o valor de FetchOffset. |
| SQL_FETCH_LAST | Retorne o último conjunto de linhas completo no conjunto de resultados. SQLFetchScroll ignora o valor de FetchOffset. |
| SQL_FETCH_BOOKMARK | Retorne as linhas FetchOffset do conjunto de linhas do indicador especificado pelo atributo de instrução SQL_ATTR_FETCH_BOOKMARK_PTR. |
Os drivers não são necessários para dar suporte a todas as orientações de busca; um aplicativo chama SQLGetInfo com um tipo de informação de SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 ou SQL_STATIC_CURSOR_ATTRIBUTES1 (dependendo do tipo do cursor) para determinar quais orientações de busca têm suporte do driver. O aplicativo deve examinar as SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE e WQL_CA1_BOOKMARK bitmasks nesses tipos de informações. Além disso, se o cursor for somente para frente e FetchOrientation não for SQL_FETCH_NEXT, SQLFetchScroll retornará SQLSTATE HY106 (tipo de busca fora do intervalo).
O atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE especifica o número de linhas no conjunto de linhas. Se o conjunto de linhas que está sendo buscado por SQLFetchScroll se sobrepõe ao final do conjunto de resultados, SQLFetchScroll retorna um conjunto de linhas parcial. Ou seja, se S + R - 1 for maior que L, onde S é a linha inicial do conjunto de linhas que está sendo buscado, R é o tamanho do conjunto de linhas e L é a última linha no conjunto de resultados, então apenas as primeiras linhas L - S + 1 do conjunto de linhas são válidas. As linhas restantes estão vazias e têm um status de SQL_ROW_NOROW.
Depois que SQLFetchScroll retorna, a linha atual é a primeira linha do conjunto de linhas.
Regras de posicionamento do cursor
As seções a seguir descrevem as regras exatas para cada valor de FetchOrientation. Essas regras usam a seguinte notação.
| Notação | Significado |
|---|---|
| Antes de começar | O cursor do bloco é posicionado antes do início do conjunto de resultados. Se a primeira linha do novo conjunto de linhas estiver antes do início do conjunto de resultados, SQLFetchScroll retornará SQL_NO_DATA. |
| Depois de terminar | O cursor do bloco é posicionado após o final do conjunto de resultados. Se a primeira linha do novo conjunto de linhas for após o final do conjunto de resultados, SQLFetchScroll retornará SQL_NO_DATA. |
| CurrRowsetStart | O número da primeira linha no conjunto de linhas atual. |
| LastResultRow | O número da última linha no conjunto de resultados. |
| RowsetSize | O tamanho do conjunto de linhas. |
| FetchOffset | O valor do argumento FetchOffset . |
| Linha de favoritos | A linha correspondente ao indicador especificado pelo atributo de instrução SQL_ATTR_FETCH_BOOKMARK_PTR. |
SQL_FETCH_NEXT
As regras a seguir se aplicam.
| Condição | Primeira linha do novo conjunto de linhas |
|---|---|
| Antes de começar | 1 |
| CurrRowsetStart + RowsetSize[1] <= LastResultRow | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | Depois de terminar |
| Depois de terminar | Depois de terminar |
[1] Se o tamanho do conjunto de linhas tiver sido alterado desde a chamada anterior para buscar linhas, esse será o tamanho do conjunto de linhas que foi usado com a chamada anterior.
SQL_FETCH_PRIOR
As regras a seguir se aplicam.
| Condição | Primeira linha do novo conjunto de linhas |
|---|---|
| Antes de começar | Antes de começar |
| CurrRowsetStart = 1 | Antes de começar |
| < 1 CurrRowsetStart <= RowsetSize [2] | 1 [1] |
| CurrRowsetStart > RowsetSize [2] | CurrRowsetStart - RowsetSize [2] |
| Após o fim E LastResultRow < RowsetSize [2] | 1 [1] |
| Após o fim E LastResultRow >= RowsetSize [2] | LastResultRow - RowsetSize + 1 [2] |
[1] SQLFetchScroll retorna SQLSTATE 01S06 (Tentativa de buscar antes que o conjunto de resultados retorne o primeiro conjunto de linhas) e SQL_SUCCESS_WITH_INFO.
[2] Se o tamanho do conjunto de linhas foi alterado desde a chamada anterior para buscar linhas, este é o novo tamanho do conjunto de linhas.
SQL_FETCH_RELATIVE
As regras a seguir se aplicam.
| Condição | Primeira linha do novo conjunto de linhas |
|---|---|
| (Antes de iniciar AND FetchOffset > 0) OU (Após o final AND FetchOffset < 0) | --[1] |
| BeforeStart E FetchOffset <= 0 | Antes de começar |
| CurrRowsetStart = 1 E FetchOffset < 0 | Antes de começar |
| CurrRowsetStart > 1 E CurrRowsetStart + FetchOffset < 1 E | FetchOffset | > RowsetSize [3] | Antes de começar |
| CurrRowsetStart > 1 E CurrRowsetStart + FetchOffset < 1 E | FetchOffset | <= RowsetSize [3] | 1 [2] |
| <1 = CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | Depois de terminar |
| Após o fim AND FetchOffset >= 0 | Depois de terminar |
[1] SQLFetchScroll retorna o mesmo conjunto de linhas como se tivesse sido chamado com FetchOrientation definido como SQL_FETCH_ABSOLUTE. Para obter mais informações, consulte a seção "SQL_FETCH_ABSOLUTE".
[2] SQLFetchScroll retorna SQLSTATE 01S06 (Tentativa de buscar antes que o conjunto de resultados retorne o primeiro conjunto de linhas) e SQL_SUCCESS_WITH_INFO.
[3] Se o tamanho do conjunto de linhas foi alterado desde a chamada anterior para buscar linhas, este é o novo tamanho do conjunto de linhas.
SQL_FETCH_ABSOLUTE
As regras a seguir se aplicam.
| Condição | Primeira linha do novo conjunto de linhas |
|---|---|
| FetchOffset < 0 E | FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 E | FetchOffset | > LastResultRow E | FetchOffset | > RowsetSize [2] | Antes de começar |
| FetchOffset < 0 E | FetchOffset | > LastResultRow E | FetchOffset | <= RowsetSize [2] | 1 [1] |
| FetchOffset = 0 | Antes de começar |
| <1 = FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | Depois de terminar |
[1] SQLFetchScroll retorna SQLSTATE 01S06 (Tentativa de buscar antes que o conjunto de resultados retorne o primeiro conjunto de linhas) e SQL_SUCCESS_WITH_INFO.
[2] Se o tamanho do conjunto de linhas foi alterado desde a chamada anterior para buscar linhas, este é o novo tamanho do conjunto de linhas.
Uma busca absoluta executada em um cursor dinâmico não pode fornecer o resultado necessário porque as posições de linha em um cursor dinâmico são indeterminadas. Essa operação é equivalente a uma busca primeiro seguida por um parente de busca; não é uma operação atômica, como é uma busca absoluta em um cursor estático.
SQL_FETCH_FIRST
As regras a seguir se aplicam.
| Condição | Primeira linha do novo conjunto de linhas |
|---|---|
| Qualquer | 1 |
SQL_FETCH_LAST
As regras a seguir se aplicam.
| Condição | Primeira linha do novo conjunto de linhas |
|---|---|
| RowsetSize [1]<= LastResultRow | LastResultRow - RowsetSize + 1 [1] |
| RowsetSize [1]> LastResultRow | 1 |
[1] Se o tamanho do conjunto de linhas foi alterado desde a chamada anterior para buscar linhas, este é o novo tamanho do conjunto de linhas.
SQL_FETCH_BOOKMARK
As regras a seguir se aplicam.
| Condição | Primeira linha do novo conjunto de linhas |
|---|---|
| BookmarkRow + FetchOffset < 1 | Antes de começar |
| <1 = BookmarkRow + FetchOffset <= LastResultRow | BookmarkRow + FetchOffset |
| BookmarkRow + FetchOffset > LastResultRow | Depois de terminar |
Para obter informações sobre indicadores, consulte Indicadores (ODBC).
Efeito de linhas excluídas, adicionadas e de erro no movimento do cursor
Cursores estáticos e controlados por conjunto de chaves às vezes detectam linhas adicionadas ao conjunto de resultados e removem linhas excluídas do conjunto de resultados. Chamando SQLGetInfo com as opções SQL_STATIC_CURSOR_ATTRIBUTES2 e SQL_KEYSET_CURSOR_ATTRIBUTES2 e examinando as máscaras de bits SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS e SQL_CA2_SENSITIVITY_UPDATES, um aplicativo determina se os cursores implementados por um driver específico fazem isso. Para drivers que podem detectar linhas excluídas e removê-las, os parágrafos a seguir descrevem os efeitos desse comportamento. Para drivers que podem detectar linhas excluídas, mas não podem removê-las, as exclusões não afetam os movimentos do cursor e os parágrafos a seguir não se aplicam.
Se o cursor detectar linhas adicionadas ao conjunto de resultados ou remover linhas excluídas do conjunto de resultados, ele parecerá detectar essas alterações somente quando buscar dados. Isso inclui o caso em que SQLFetchScroll é chamado com FetchOrientation definido como SQL_FETCH_RELATIVE e FetchOffset definido como 0 para buscar novamente o mesmo conjunto de linhas, mas não inclui o caso em que SQLSetPos é chamado com fOption definido como SQL_REFRESH. No último caso, os dados nos buffers do conjunto de linhas são atualizados, mas não buscados novamente, e as linhas excluídas não são removidas do conjunto de resultados. Assim, quando uma linha é excluída ou inserida no conjunto de linhas atual, o cursor não modifica os buffers do conjunto de linhas. Em vez disso, ele detecta a alteração quando busca qualquer conjunto de linhas que incluía anteriormente a linha excluída ou agora inclui a linha inserida.
Por exemplo:
// Fetch the next rowset.
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);
// Delete third row of the rowset. Does not modify the rowset buffers.
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);
// The third row has a status of SQL_ROW_DELETED after this call.
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);
// Refetch the same rowset. The third row is removed, replaced by what
// was previously the fourth row.
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);
Quando SQLFetchScroll retorna um novo conjunto de linhas que tem uma posição relativa ao conjunto de linhas atual - ou seja, FetchOrientation é SQL_FETCH_NEXT, SQL_FETCH_PRIOR ou SQL_FETCH_RELATIVE - ele não inclui alterações no conjunto de linhas atual ao calcular a posição inicial do novo conjunto de linhas. No entanto, ele inclui alterações fora do conjunto de linhas atual se for capaz de detectá-las. Além disso, quando SQLFetchScroll retorna um novo conjunto de linhas que tem uma posição independente do conjunto de linhas atual - ou seja, FetchOrientation é SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE ou SQL_FETCH_BOOKMARK - ele inclui todas as alterações que é capaz de detectar, mesmo que estejam no conjunto de linhas atual.
Ao determinar se as linhas recém-adicionadas estão dentro ou fora do conjunto de linhas atual, considera-se que um conjunto de linhas parcial termina na última linha válida; ou seja, a última linha para a qual o status da linha não é SQL_ROW_NOROW. Por exemplo, suponha que o cursor seja capaz de detectar linhas recém-adicionadas, o conjunto de linhas atual seja um conjunto de linhas parcial, o aplicativo adicione novas linhas e o cursor adicione essas linhas ao final do conjunto de resultados. Se o aplicativo chamar SQLFetchScroll com FetchOrientation definido como SQL_FETCH_NEXT, SQLFetchScroll retornará o conjunto de linhas começando com a primeira linha recém-adicionada.
Por exemplo, suponha que o conjunto de linhas atual compreenda as linhas 21 a 30, o tamanho do conjunto de linhas seja 10, o cursor remova as linhas excluídas do conjunto de resultados e o cursor detecte as linhas adicionadas ao conjunto de resultados. A tabela a seguir mostra as linhas que SQLFetchScroll retorna em várias situações.
| Alterar | Tipo de busca | FetchOffset | Novo conjunto de linhas[1] |
|---|---|---|---|
| Suprimir a linha 21 | NEXT | 0 | 31 a 40 |
| Suprimir a linha 31 | NEXT | 0 | 32 a 41 |
| Inserir linha entre as linhas 21 e 22 | NEXT | 0 | 31 a 40 |
| Inserir linha entre as linhas 30 e 31 | NEXT | 0 | Linha inserida, 31 a 39 |
| Suprimir a linha 21 | ANTERIOR | 0 | 11 a 20 |
| Suprimir a linha 20 | ANTERIOR | 0 | 10 a 19 |
| Inserir linha entre as linhas 21 e 22 | ANTERIOR | 0 | 11 a 20 |
| Inserir linha entre as linhas 20 e 21 | ANTERIOR | 0 | 12 a 20, linha inserida |
| Suprimir a linha 21 | RELATIVE | 0 | 22 a 31[2] |
| Suprimir a linha 21 | RELATIVE | 1 | 22 a 31 |
| Inserir linha entre as linhas 21 e 22 | RELATIVE | 0 | 21, linha inserida, 22 a 29 |
| Inserir linha entre as linhas 21 e 22 | RELATIVE | 1 | 22 a 31 |
| Suprimir a linha 21 | ABSOLUTE | 21 | 22 a 31[2] |
| Suprimir a linha 22 | ABSOLUTE | 21 | 21, 23 a 31 |
| Inserir linha entre as linhas 21 e 22 | ABSOLUTE | 22 | Linha inserida, 22 a 29 |
[1] Esta coluna usa os números de linha antes de qualquer linha ser inserida ou excluída.
[2] Nesse caso, o cursor tenta retornar linhas que começam com a linha 21. Como a linha 21 foi excluída, a primeira linha retornada é a linha 22.
As linhas de erro (ou seja, linhas com um status de SQL_ROW_ERROR) não afetam o movimento do cursor. Por exemplo, se o conjunto de linhas atual começar com a linha 11 e o status da linha 11 for SQL_ROW_ERROR, chamar SQLFetchScroll com FetchOrientation definido como SQL_FETCH_RELATIVE e FetchOffset definido como 5 retornará o conjunto de linhas começando com a linha 16, assim como faria se o status da linha 11 fosse SQL_SUCCESS.
Retornando dados em colunas acopladas
SQLFetchScroll retorna dados em colunas acopladas da mesma forma que SQLFetch. Para obter mais informações, consulte "Retornando dados em colunas associadas" na função SQLFetch.
Se nenhuma coluna estiver associada, SQLFetchScroll não retornará dados, mas moverá o cursor do bloco para a posição especificada. Se os dados podem ser recuperados de colunas não associadas de um cursor de bloco com SQLGetData depende do driver. Esse recurso terá suporte se uma chamada para SQLGetInfo retornar o bit SQL_GD_BLOCK para o tipo de informação SQL_GETDATA_EXTENSIONS.
Endereços de buffer
SQLFetchScroll usa a mesma fórmula para determinar o endereço dos buffers de dados e comprimento/indicador que SQLFetch. Para obter mais informações, consulte "Endereços de buffer" na função SQLBindCol.
Matriz de status da linha
SQLFetchScroll define valores na matriz de status da linha da mesma maneira que SQLFetch. Para obter mais informações, consulte "Matriz de status de linha" na função SQLFetch.
Buffer de linhas buscadas
SQLFetchScroll retorna o número de linhas buscadas no buffer de linhas buscadas da mesma maneira que SQLFetch. Para obter mais informações, consulte "Buffer de linhas buscadas" na função SQLFetch.
Manipulação de Erro
Quando um aplicativo chama SQLFetchScroll em um driver ODBC 3.x, o Gerenciador de Driver chama SQLFetchScroll no driver. Quando um aplicativo chama SQLFetchScroll em um driver ODBC 2.x, o Gerenciador de Driver chama SQLExtendedFetch no driver. Como SQLFetchScroll e SQLExtendedFetch lidam com erros de uma maneira ligeiramente diferente, o aplicativo vê um comportamento de erro ligeiramente diferente quando chama SQLFetchScroll em drivers ODBC 2.x e ODBC 3.x.
SQLFetchScroll retorna erros e avisos da mesma maneira que SQLFetch; para obter mais informações, consulte "Tratamento de erros" no SQLFetch. SQLExtendedFetch retorna erros da mesma maneira que SQLFetch, com as seguintes exceções:
Quando ocorre um aviso que se aplica a uma linha específica no conjunto de linhas, SQLExtendedFetch define a entrada correspondente na matriz de status da linha como SQL_ROW_SUCCESS, não SQL_ROW_SUCCESS_WITH_INFO.
Se ocorrerem erros em todas as linhas do conjunto de linhas, SQLExtendedFetch retornará SQL_SUCCESS_WITH_INFO, não SQL_ERROR.
Em cada grupo de registros de status que se aplica a uma linha individual, o primeiro registro de status retornado por SQLExtendedFetch deve conter SQLSTATE 01S01 (Erro na linha); SQLFetchScroll não retorna esse SQLSTATE. Se SQLExtendedFetch não puder retornar SQLSTATEs adicionais, ele ainda deverá retornar esse SQLSTATE.
SQLFetchScroll e simultaneidade otimista
Se um cursor usar simultaneidade otimista, ou seja, o atributo de instrução SQL_ATTR_CONCURRENCY tiver um valor de SQL_CONCUR_VALUES ou SQL_CONCUR_ROWVER , SQLFetchScroll atualizará os valores de simultaneidade otimista usados pela fonte de dados para detectar se uma linha foi alterada. Isso acontece sempre que SQLFetchScroll busca um novo conjunto de linhas, inclusive quando ele busca novamente o conjunto de linhas atual. (Ele é chamado com FetchOrientation definido como SQL_FETCH_RELATIVE e FetchOffset definido como 0.)
Drivers SQLFetchScroll e ODBC 2.x
Quando um aplicativo chama SQLFetchScroll em um driver ODBC 2.x, o Gerenciador de Driver mapeia essa chamada para SQLExtendedFetch. Ele passa os seguintes valores para os argumentos de SQLExtendedFetch.
| Argumento SQLExtendedFetch | Valor |
|---|---|
| Identificador de declaração | StatementHandle em SQLFetchScroll. |
| Orientação de busca | FetchOrientation em SQLFetchScroll. |
| FetchOffset | Se FetchOrientation não for SQL_FETCH_BOOKMARK, o valor do argumento FetchOffset em SQLFetchScroll será usado. Se FetchOrientation for SQL_FETCH_BOOKMARK, o valor armazenado no endereço especificado pelo atributo de instrução SQL_ATTR_FETCH_BOOKMARK_PTR será usado. |
| RowCountPtr | O endereço especificado pelo atributo de instrução SQL_ATTR_ROWS_FETCHED_PTR. |
| RowStatusArray | O endereço especificado pelo atributo de instrução SQL_ATTR_ROW_STATUS_PTR. |
Para obter mais informações, consulte Cursores em bloco, cursores roláveis e compatibilidade com versões anteriores no Apêndice G: diretrizes de driver para compatibilidade com versões anteriores.
Descritores e SQLFetchScroll
SQLFetchScroll interage com descritores da mesma maneira que SQLFetch. Para obter mais informações, consulte a seção "Descritores e SQLFetchScroll" em Função SQLFetch.
Exemplo de código
Consulte Associação de coluna, Associação de linha, Instruções de atualização e exclusão posicionadas e Atualização de linhas no conjunto de linhas com SQLSetPos.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| Executando operações de inserção, atualização ou exclusão em massa | Função SQLBulkOperations |
| Cancelando o processamento de instruções | Função SQLCancel |
| Retornando informações sobre uma coluna em um conjunto de resultados | Função SQLDescribeCol |
| Executando uma instrução SQL | Função SQLExecDirect |
| Executando uma instrução SQL preparada | Função SQLExecute |
| Buscando uma única linha ou um bloco de dados em uma direção somente para frente | Função SQLFetch |
| Fechando o cursor na instrução | Função SQLFreeStmt |
| Retornando o número de colunas do conjunto de resultados | Função SQLNumResultCols |
| Posicionar o cursor, atualizar dados no conjunto de linhas ou atualizar ou excluir dados no conjunto de resultados | Função SQLSetPos |
| Configurando um atributo de instrução | Função SQLSetStmtAttr |