Função SQLFetchScroll
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 3.0: 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
StatementHandle
[Entrada] Identificador de instrução.
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 obter mais informações, confira "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, confira "Posicionando o cursor" na seção "Comentários".
Retornos
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 Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLFetchScroll e explica cada um deles 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 o contrário. 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 podem ser chamados 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 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO será retornado se ocorrer um erro em uma ou mais linhas de uma operação de várias linhas, e SQL_ERROR será retornada 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 | A cadeia de caracteres ou os dados 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 cadeia de caracteres, ele estava truncado à direita. |
| 01S01 | Erro na linha | Erro ao buscar uma ou mais linhas. (Se esse SQLSTATE for retornado quando um aplicativo ODBC 3*.x* estiver trabalhando com um driver ODBC 2*.x*, ele poderá ser ignorado.) |
| 01S06 | Tentativa de busca antes que o conjunto de resultados retornasse o primeiro conjunto de linhas | O conjunto de linhas solicitado sobrepôs o 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 sobrepôs o 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 sobrepôs o início do conjunto de resultados quando FetchOrientation foi SQL_FETCH_RELATIVE, FetchOffset foi negativo e o valor absoluto de FetchOffset era menor ou igual ao tamanho do conjunto de linhas. O conjunto de linhas solicitado sobrepôs o início do conjunto de resultados quando FetchOrientation foi SQL_FETCH_ABSOLUTE, FetchOffset foi negativo e o valor absoluto de FetchOffset foi 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 time, timestamp e interval que contêm 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 no 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 associada 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 foi conectado falhou antes da função concluir 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 de indicador 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 teria feito com que toda a parte (em vez de fracionária) do número fosse truncada. Para obter mais informações, consulte Convertendo dados de tipos de dados SQL para C no apêndice D: tipos de dados. |
| 22007 | Formato de datetime 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 em divisão por zero. |
| 22015 | Estouro de campo de intervalo | Atribuir de um tipo SQL numérico ou intervalo exato a um tipo C de intervalo causou uma perda de dígitos significativos no campo à esquerda. Ao buscar dados para um tipo C de intervalo, não houve representação do valor do tipo SQL no tipo C do intervalo. |
| 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 C de caracteres 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 numérico exato ou aproximado, um datetime 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. |
| 24.000 | Estado de cursor inválido | StatementHandle estava em um estado executado, mas nenhum conjunto de resultados foi associado ao StatementHandle. |
| 40001 | Falha na 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 nenhum 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 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ções | (DM) Uma função em 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 StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem 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 StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para StatementHandle e retornados SQL_NEED_DATA. Essa função foi chamada antes de os dados serem 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 foi 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 | Comprimento de buffer ou cadeia de caracteres 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 de linha fora do intervalo | O valor especificado com o atributo de instrução SQL_ATTR_CURSOR_TYPE foi 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 de transação desconhecido. Somente funções desconectar 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 em SQLBindCol e o tipo de dados SQL da coluna correspondente. |
| HYT00 | Tempo limite esgotado | O período de tempo limite da consulta expirou antes da fonte de dados retornar 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 da fonte de dados responder à 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 dá suporte a essa 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 só pode ser chamado enquanto um conjunto de resultados existe, 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 de 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.
| FetchOrientation | Significado |
|---|---|
| SQL_FETCH_NEXT | Retornar o próximo conjunto de linhas. Isso é equivalente a chamar SQLFetch. SQLFetchScroll ignora o valor de FetchOffset. |
| SQL_FETCH_PRIOR | Retornar 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 | Retornar o conjunto de linhas começando na linha FetchOffset. |
| SQL_FETCH_FIRST | Retornar o primeiro conjunto de linhas no conjunto de resultados. SQLFetchScroll ignora o valor de FetchOffset. |
| SQL_FETCH_LAST | Retornar 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 bitmasks WQL_CA1_BOOKMARK nesses tipos de informações. Além disso, se o cursor for somente encaminhamento e FetchOrientation não for SQL_FETCH_NEXT, SQLFetchScroll retornará SQLSTATE HY106 (tipo fetch 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 sobrepor ao final do conjunto de resultados, SQLFetchScroll retornará um conjunto de linhas parcial. Ou seja, se S + R - 1 for maior que L, em que 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 somente 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 notação a seguir.
| Notation | Significado |
|---|---|
| Antes de começar | O cursor de bloco é posicionado antes do início do conjunto de resultados. Se a primeira linha do novo conjunto de linhas for antes do início do conjunto de resultados, SQLFetchScroll retornará SQL_NO_DATA. |
| Após o término | O cursor de bloco é posicionado após o final do conjunto de resultados. Se a primeira linha do novo conjunto de linhas estiver 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 . |
| BookmarkRow | 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 | Após o término |
| Após o término | Após o término |
[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 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 término de AND LastResultRow < RowsetSize[2] | 1[1] |
| Após o término de AND LastResultRow >= RowsetSize[2] | LastResultRow - RowsetSize + 1[2] |
[1] SQLFetchScroll retorna SQLSTATE 01S06 (Tentativa de busca 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 tiver sido alterado desde a chamada anterior para buscar linhas, esse será 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) OR (Após o término e FetchOffset < 0) | --[1] |
| BeforeStart AND FetchOffset <= 0 | Antes de começar |
| CurrRowsetStart = 1 AND FetchOffset < 0 | Antes de começar |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | > RowsetSize[3] | Antes de começar |
| CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | <= RowsetSize[3] | 1[2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRow | Após o término |
| Após o término de AND FetchOffset >= 0 | Após o término |
[1] SQLFetchScroll retorna o mesmo conjunto de linhas como se fosse 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 busca 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 tiver sido alterado desde a chamada anterior para buscar linhas, esse será 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 AND | FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize[2] | Antes de começar |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize[2] | 1[1] |
| FetchOffset = 0 | Antes de começar |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | Após o término |
[1] SQLFetchScroll retorna SQLSTATE 01S06 (tentativa de busca 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 tiver sido alterado desde a chamada anterior para buscar linhas, esse será 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 relativo de busca; não é uma operação atômica, assim 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 tiver sido alterado desde a chamada anterior para buscar linhas, esse será 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 | Após o término |
Para obter informações sobre indicadores, consulte Indicadores (ODBC).
Efeito de linhas excluídas, adicionadas e de erro no movimento do cursor
Às vezes, cursores estáticos e controlados por conjunto de chaves detectam linhas adicionadas ao conjunto de resultados e removem linhas excluídas do conjunto de resultados. Ao chamar SQLGetInfo com as opções SQL_STATIC_CURSOR_ATTRIBUTES2 e SQL_KEYSET_CURSOR_ATTRIBUTES2 e examinar 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 têm efeito sobre 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 aparecerá como se detecte essas alterações somente quando busca dados. Isso inclui o caso quando 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 quando SQLSetPos é chamado com fOption definido como SQL_REFRESH. No último caso, os dados nos buffers de conjunto de linhas são atualizados, mas não são refetchados e as linhas excluídas não são removidas do conjunto de resultados. Portanto, quando uma linha é excluída ou inserida no conjunto de linhas atual, o cursor não modifica os buffers de conjunto de linhas. Em vez disso, ele detecta a alteração quando busca qualquer conjunto de linhas que anteriormente incluía 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, um conjunto de linhas parcial é considerado para terminar 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 é um conjunto de linhas parcial, o aplicativo adiciona novas linhas e o cursor adiciona 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 seja composto pelas 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 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] |
|---|---|---|---|
| Excluir linha 21 | NEXT | 0 | 31 a 40 |
| Excluir 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 |
| Excluir linha 21 | PRIOR | 0 | 11 a 20 |
| Excluir linha 20 | PRIOR | 0 | 10 a 19 |
| Inserir linha entre as linhas 21 e 22 | PRIOR | 0 | 11 a 20 |
| Inserir linha entre as linhas 20 e 21 | PRIOR | 0 | 12 a 20, linha inserida |
| Excluir linha 21 | RELATIVE | 0 | 22 a 31[2] |
| Excluir 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 |
| Excluir linha 21 | ABSOLUTE | 21 | 22 a 31[2] |
| Excluir 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 começando com a linha 21. Como a linha 21 foi excluída, a primeira linha retorna é 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 associadas
SQLFetchScroll retorna dados em colunas associadas 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 de 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. Essa funcionalidade terá suporte se uma chamada para SQLGetInfo retornar o bit SQL_GD_BLOCK para o tipo de informações 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 como 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 buscado de linhas
SQLFetchScroll retorna o número de linhas buscadas no buffer buscado de linhas da mesma maneira que SQLFetch. Para obter mais informações, confira "Buffer buscado de linhas" na função SQLFetch.
Tratamento de erros
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 manipulam erros de maneira um pouco 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 usa simultaneidade otimista – ou seja, o atributo de instrução SQL_ATTR_CONCURRENCY tem um valor de SQL_CONCUR_VALUES ou SQL_CONCUR_ROWVER – SQLFetchScroll atualiza os valores de simultaneidade otimistas 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 refeta o conjunto de linhas atual. (É 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 valores a seguir para os argumentos de SQLExtendedFetch.
| Argumento SQLExtendedFetch | Valor |
|---|---|
| StatementHandle | StatementHandle em SQLFetchScroll. |
| FetchOrientation | FetchOrientation no 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 Bloquear cursores, 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" na Função SQLFetch.
Exemplo de código
Consulte Associação em termos de coluna, associação em linha, instruções de atualização e exclusão posicionadas e Atualizando linhas no conjunto de linhas com SQLSetPos.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associar 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 |
| Buscar 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 |
| Posicionando o cursor, atualizando dados no conjunto de linhas ou atualizando ou excluindo dados no conjunto de resultados | Função SQLSetPos |
| Definindo um atributo de instrução | Função SQLSetStmtAttr |
Consulte Também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de