Função SQLExtendedFetch
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: preterida
Resumo
SQLExtendedFetch 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.
Observação
No ODBC 3*.x*, SQLExtendedFetch foi substituído por SQLFetchScroll. Os aplicativos ODBC 3*.x* não devem chamar SQLExtendedFetch; Em vez disso, eles devem chamar SQLFetchScroll. O Gerenciador de Driver mapeia SQLFetchScroll para SQLExtendedFetch ao trabalhar com um driver ODBC 2*.x*. Os drivers ODBC 3*.x* devem dar suporte a SQLExtendedFetch se quiserem trabalhar com aplicativos ODBC 2*.x* que o chamam. Para obter mais informações, consulte "Comentários" e Bloquear cursores, cursores roláveis e compatibilidade com versões anteriores no Apêndice G: Diretrizes de driver para compatibilidade com versões anteriores.
Sintaxe
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
FetchOrientation
[Entrada] Tipo de busca. Isso é o mesmo que FetchOrientation em SQLFetchScroll.
FetchOffset
[Entrada] Número da linha a ser buscada. Isso é o mesmo que FetchOffset em SQLFetchScroll, com uma exceção. Quando FetchOrientation é SQL_FETCH_BOOKMARK, FetchOffset é um indicador de comprimento fixo, não um deslocamento de um indicador. Em outras palavras, SQLExtendedFetch recupera o indicador desse argumento, não o atributo de instrução SQL_ATTR_FETCH_BOOKMARK_PTR. Ele não dá suporte a indicadores de comprimento variável e não dá suporte à busca de um conjunto de linhas em um deslocamento (diferente de 0) de um indicador.
RowCountPtr
[Saída] Ponteiro para um buffer no qual retornar o número de linhas realmente buscadas. Esse buffer é usado da mesma maneira que o buffer especificado pelo atributo de instrução SQL_ATTR_ROWS_FETCHED_PTR. Esse buffer é usado apenas por SQLExtendedFetch. Ele não é usado por SQLFetch ou SQLFetchScroll.
RowStatusArray
[Saída] Ponteiro para uma matriz na qual retornar o status de cada linha. Essa matriz é usada da mesma maneira que a matriz especificada pelo atributo de instrução SQL_ATTR_ROW_STATUS_PTR.
No entanto, o endereço dessa matriz não é armazenado no campo SQL_DESC_STATUS_ARRAY_PTR no IRD. Além disso, essa matriz é usada apenas por SQLExtendedFetch e por SQLBulkOperations com uma Operação de SQL_ADD ou SQLSetPos quando ela é chamada após SQLExtendedFetch. Ele não é usado por SQLFetch ou SQLFetchScroll e não é usado por SQLBulkOperations ou SQLSetPos quando eles são chamados após SQLFetch ou SQLFetchScroll. Ele também não é usado quando SQLBulkOperations com uma Operação de SQL_ADD é chamado antes de qualquer função fetch ser chamada. Em outras palavras, ele é usado somente no estado de instrução S7. Ele não é usado nos estados de instrução S5 ou S6. Para obter mais informações, consulte Transições de instrução no apêndice B: tabelas de transição de estado ODBC.
Os aplicativos devem fornecer um ponteiro válido no argumento RowStatusArray ; caso contrário, o comportamento de SQLExtendedFetch e o comportamento de chamadas para SQLBulkOperations ou SQLSetPos após um cursor ter sido posicionado por SQLExtendedFetch são indefinidos.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLExtendedFetch retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLError. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLExtendedFetch 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.
| 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. Se for um valor numérico, a parte fracionária do número foi truncada. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01S01 | Erro na linha | Erro ao buscar uma ou mais linhas. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 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 a posição atual estava além da primeira linha e FetchOrientation foi SQL_PRIOR ou FetchOrientation foi SQL_RELATIVE com um FetchOffset negativo cujo valor absoluto era menor ou igual ao SQL_ROWSET_SIZE atual. (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 | Não foi possível converter um valor de dados para o tipo de dados C especificado por TargetType no SQLBindCol. |
| 07009 | Índice de descritor inválido | A coluna 0 foi associada a SQLBindCol 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. |
| 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 era um ponteiro nulo. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 22003 | Valor numérico fora do intervalo | Retornar o valor numérico (como numérico ou cadeia de caracteres) para uma ou mais colunas teria feito com que toda a parte (em vez de fracionária) do número fosse truncada. (A função retorna SQL_SUCCESS_WITH_INFO.) Para obter mais informações, consulte Diretrizes para tipos de dados numéricos e de intervalo 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. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 22012 | Divisão por zero | Um valor de uma expressão aritmética foi retornado, o que resultou em divisão por zero. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 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. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 22018 | Valor de caractere inválido para especificação de conversão | 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. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 24.000 | Estado de cursor inválido | StatementHandle estava em um estado executado, mas nenhum conjunto de resultados foi associado ao StatementHandle. |
| 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 SQLError 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 e, 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 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 SQLExtendedFetch foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou 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 chamar primeiro 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 foram chamados para o StatementHandle e retornaram 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) SQLExtendedFetch foi chamado para o StatementHandle depois que SQLFetch ou SQLFetchScroll foi chamado e antes de SQLFreeStmt ser chamado com a opção SQL_CLOSE. (DM) SQLBulkOperations foi chamado para uma instrução antes de SQLFetch, SQLFetchScroll ou SQLExtendedFetch ser chamado e, em seguida, SQLExtendedFetch foi chamado antes de SQLFreeStmt ser chamado com a opção SQL_CLOSE. |
| 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. |
| HY106 | Tipo de busca fora do intervalo | (DM) O valor especificado para o argumento FetchOrientation era inválido. (Confira "Comentários".) 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 da opção de instrução SQL_CURSOR_TYPE foi SQL_CURSOR_FORWARD_ONLY e o valor do argumento FetchOrientation não foi SQL_FETCH_NEXT. O argumento FetchOrientation foi SQL_FETCH_RESUME. |
| HY107 | Valor de linha fora do intervalo | O valor especificado com a opção de instrução SQL_CURSOR_TYPE foi SQL_CURSOR_KEYSET_DRIVEN, mas o valor especificado com o atributo de instrução SQL_KEYSET_SIZE foi maior que 0 e menor que o valor especificado com o atributo de instrução SQL_ROWSET_SIZE. |
| HY111 | Valor de indicador inválido | O argumento FetchOrientation foi SQL_FETCH_BOOKMARK e o indicador especificado no argumento FetchOffset não era válido. |
| HY117 | A conexão é suspensa devido ao estado de transação desconhecido. 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 ao tipo de busca especificado. 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. Esse erro se aplica somente quando o tipo de dados SQL da coluna foi mapeado para um tipo de dados SQL específico do driver. |
| HYT00 | Tempo limite esgotado | O período de tempo limite da consulta expirou antes da fonte de dados retornar o conjunto de resultados. O período de tempo limite é definido por meio de SQLSetStmtOption, SQL_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. |
Comentários
O comportamento de SQLExtendedFetch é idêntico ao de SQLFetchScroll, com as seguintes exceções:
SQLExtendedFetch e SQLFetchScroll usam métodos diferentes para retornar o número de linhas buscadas. SQLExtendedFetch retorna o número de linhas buscadas em *RowCountPtr; SQLFetchScroll retorna o número de linhas buscadas diretamente para o buffer apontado por SQL_ATTR_ROWS_FETCHED_PTR. Para obter mais informações, consulte o argumento RowCountPtr .
SQLExtendedFetch e SQLFetchScroll retornam o status de cada linha em matrizes diferentes. Para obter mais informações, consulte o argumento RowStatusArray .
SQLExtendedFetch e SQLFetchScroll usam métodos diferentes para recuperar o indicador quando FetchOrientation é SQL_FETCH_BOOKMARK. SQLExtendedFetch não dá suporte a indicadores de comprimento variável nem busca de conjuntos de linhas em um deslocamento diferente de 0 de um indicador. Para obter mais informações, consulte o argumento FetchOffset .
SQLExtendedFetch e SQLFetchScroll usam diferentes tamanhos de conjunto de linhas. SQLExtendedFetch usa o valor do atributo de instrução SQL_ROWSET_SIZE e SQLFetchScroll usa o valor do atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE.
SQLExtendedFetch tem semântica de tratamento de erro ligeiramente diferente de SQLFetchScroll. Para obter mais informações, consulte "Tratamento de erros" na seção "Comentários" do SQLFetchScroll.
SQLExtendedFetch não dá suporte a deslocamentos de associação (o atributo de instrução SQL_ATTR_ROW_BIND_OFFSET_PTR).
As chamadas para SQLExtendedFetch não podem ser misturadas com chamadas para SQLFetch ou SQLFetchScroll e, se SQLBulkOperations for chamado antes que qualquer função fetch seja chamada, SQLExtendedFetch não poderá ser chamado até que o cursor seja fechado e reaberto. Ou seja, SQLExtendedFetch só pode ser chamado no estado de instrução S7. Para obter mais informações, consulte Transições de instrução no Apêndice B: Tabelas de Transição de Estado ODBC.
Quando um aplicativo chama SQLFetchScroll ao usar um driver ODBC 2*.x*, o Gerenciador de Driver mapeia essa chamada para SQLExtendedFetch. Para obter mais informações, consulte "SqLFetchScroll e Drivers ODBC 2*.x* no SQLFetchScroll.
No ODBC 2*.x*, SQLExtendedFetch foi chamado para buscar várias linhas e SQLFetch foi chamado para buscar uma única linha. No ODBC 3*.x*, por outro lado, SQLFetch pode ser chamado para buscar várias linhas.
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 da instrução | 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 |
| 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