Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Conformidade
Versão Introduzida: Conformidade com as Normas ODBC 1.0: Descontinuada
Summary
SQLExtendedFetch 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.
Note
No ODBC 3*.x*, SQLExtendedFetch foi substituído por SQLFetchScroll. Aplicações ODBC 3*.x* não devem chamar SQLExtendedFetch; em vez disso, deviam chamar SQLFetchScroll. O Gestor de Drivers mapeia SQLFetchScroll para SQLExtendedFetch ao trabalhar com um driver ODBC 2*.x*. Os drivers ODBC 3*.x* devem suportar SQLExtendedFetch se quiserem trabalhar com aplicações ODBC 2*.x* que o chamem. Para mais informações, consulte "Comentários" e Cursores de Bloco, Cursores Roláveis e Compatibilidade Retrocedente no Apêndice G: Diretrizes de Drivers para Compatibilidade Retroativa.
Syntax
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Arguments
HandleStatement
[Entrada] Identificador do extrato.
FetchOrientation
[Entrada] Tipo de buscar. Isto é o mesmo que o FetchOrientation no SQLFetchScroll.
FetchOffset
[Entrada] Número da fila a buscar. Isto é igual ao FetchOffset no SQLFetchScroll, com uma exceção. Quando o FetchOrientation está SQL_FETCH_BOOKMARK, o FetchOffset é um marcador de comprimento fixo, não um deslocamento de um favorito. Por outras palavras, SQLExtendedFetch recupera o marcador deste argumento, não o atributo da instrução SQL_ATTR_FETCH_BOOKMARK_PTR. Não suporta marcadores de comprimento variável nem suporta a obtenção de um conjunto de linhas num deslocamento (diferente de 0) a partir de um marcador de páginas.
RowCountPtr
[Saída] Apontador para um buffer onde se deve devolver o número de linhas realmente obtido. Este buffer é usado da mesma forma que o buffer especificado pelo atributo da instrução SQL_ATTR_ROWS_FETCHED_PTR. Este buffer é usado apenas pelo SQLExtendedFetch. Não é utilizado pelo SQLFetch nem pelo SQLFetchScroll.
RowStatusArray
[Saída] Apontar para um array onde devolver o estado de cada linha. Este array é usado da mesma forma que o array especificado pelo atributo da instrução SQL_ATTR_ROW_STATUS_PTR.
No entanto, o endereço deste array não é armazenado no campo SQL_DESC_STATUS_ARRAY_PTR no IRD. Além disso, este array é usado apenas pelo SQLExtendedFetch e pelo SQLBulkOperations com uma Operação de SQL_ADD ou SQLSetPos quando é chamado após SQLExtendedFetch. Não é usado pelo SQLFetch ou SQLFetchScroll, nem pelo SQLBulkOperations ou SQLSetPos quando são chamados depois de SQLFetch ou SQLFetchScroll. Também não é usado quando o SQLBulkOperations com uma Operação de SQL_ADD é chamado antes de qualquer função fetch ser chamada. Por outras palavras, é usado apenas no estado de instrução S7. Não é utilizado nos estados de instruções S5 ou S6. Para mais informações, consulte Transições de Declarações no Apêndice B: Tabelas de Transição de Estado ODBC.
As aplicações devem fornecer um ponteiro válido no argumento RowStatusArray ; se não, o comportamento de SQLExtendedFetch e o comportamento das chamadas para SQLBulkOperations ou SQLSetPos após um cursor ter sido posicionado por SQLExtendedFetch não estão definidos.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando o SQLExtendedFetch devolve SQL_ERROR ou SQL_SUCCESS_WITH_INFO, pode ser obtido um valor SQLSTATE associado ao chamar o SQLError. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLExtendedFetch 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 ocorreu o erro; e o SQLGetDiagField pode ser chamado com um DiagIdentifier de SQL_DIAG_ROW_NUMBER para determinar a linha que contém essa coluna.
| SQLSTATE | Erro | Description |
|---|---|---|
| 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. Se fosse um valor numérico, a parte fracionária do número era truncada. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 01S01 | Erro em linha | Ocorreu um erro ao buscar uma ou mais linhas. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 01S06 | Tentar buscar antes do conjunto de resultados devolver o primeiro conjunto de linhas | O conjunto de linhas solicitado sobrepunha-se ao início do conjunto de resultados quando a posição atual estava além da primeira linha, e ou FetchOrientation era SQL_PRIOR ou FetchOrientation era SQL_RELATIVE com um FetchOffset negativo cujo valor absoluto era menor ou igual ao SQL_ROWSET_SIZE atual. (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 | Um valor de dado não podia ser convertido para o tipo de dados C especificado pelo TargetType no SQLBindCol. |
| 07009 | Índice de descritores inválido | A coluna 0 foi atribuída com SQLBindCol, 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. |
| 22002 | Variável indicadora necessária, mas não fornecida | Os dados NULL eram recolhidos numa coluna cujo StrLen_or_IndPtr definido pelo SQLBindCol era um ponteiro nulo. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 22003 | Valor numérico fora do intervalo | Devolver o valor numérico (como numérico ou cadeia) de uma ou mais colunas teria feito com que toda a parte (em vez de fracionária) do número fosse truncada. (Função devolve SQL_SUCCESS_WITH_INFO.) Para mais informações, consulte Diretrizes para Tipos de Dados Intervalados e Numéricos 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. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 22012 | Divisão por zero | Um valor de uma expressão aritmética era devolvido, o que resultava numa divisão por zero. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 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. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 22018 | Valor de personagem inválido para especificação de elenco | 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. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 24000 | Estado do cursor inválido | O StatementHandle estava num estado executado, mas nenhum conjunto de resultados estava associado ao StatementHandle. |
| 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 retornada por SQLError no buffer de *MessageText descreve o erro e 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, e depois a função era novamente chamada 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 SQLExtendedFetch 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) SQLExtendedFetch era chamado para o StatementHandle depois de ser chamado SQLFetch ou SQLFetchScroll e antes de SQLFreeStmt ser chamado com a opção SQL_CLOSE. (DM) SQLBulkOperations era chamado para uma instrução antes de ser chamado SQLFetch, SQLFetchScroll ou SQLExtendedFetch , e depois SQLExtendedFetch era chamado antes de SQLFreeStmt ser chamado com a opção SQL_CLOSE. |
| 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. |
| HY106 | Tipo de busca fora do alcance | (DM) O valor especificado para o argumento FetchOrientation era inválido. (Ver "Comentários.") O argumento FetchOrientation foi SQL_FETCH_BOOKMARK, e o atributo da instrução SQL_ATTR_USE_BOOKMARKS foi definido para SQL_UB_OFF. O valor da opção de SQL_CURSOR_TYPE sentença era SQL_CURSOR_FORWARD_ONLY, e o valor do argumento FetchOrientation não era SQL_FETCH_NEXT. O argumento FetchOrientation foi SQL_FETCH_RESUME. |
| HY107 | Valor da linha fora do intervalo | O valor especificado com a opção de instrução SQL_CURSOR_TYPE era SQL_CURSOR_KEYSET_DRIVEN, mas o valor especificado com o atributo de instrução SQL_KEYSET_SIZE era maior que 0 e inferior ao valor especificado com o atributo de instrução SQL_ROWSET_SIZE. |
| HY111 | Valor de marcador inválido | O argumento FetchOrientation era SQL_FETCH_BOOKMARK, e o marcador especificado no argumento FetchOffset não era válido. |
| 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 a fonte de dados não suportam o tipo de fetch especificado. 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. Este erro aplica-se apenas quando o tipo de dado SQL da coluna foi mapeado para um tipo de dado SQL específico do driver. |
| 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. O período de tempo é definido através do SQLSetStmtOption, SQL_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. |
Comments
O comportamento do SQLExtendedFetch é idêntico ao do SQLFetchScroll, com as seguintes exceções:
SQLExtendedFetch e SQLFetchScroll usam métodos diferentes para devolver o número de linhas buscadas. SQLExtendedFetch devolve o número de linhas obtidas em *RowCountPtr; SQLFetchScroll devolve o número de linhas obtidas diretamente para o buffer apontado por SQL_ATTR_ROWS_FETCHED_PTR. Para mais informações, consulte o argumento RowCountPtr .
SQLExtendedFetch e SQLFetchScroll retornam o estado de cada linha em diferentes arrays. Para mais informações, consulte o argumento RowStatusArray .
SQLExtendedFetch e SQLFetchScroll usam métodos diferentes para recuperar o marcador quando o FetchOrientation está SQL_FETCH_BOOKMARK. O SQLExtendedFetch não suporta marcadores de livros de comprimento variável nem a obtenção de conjuntos de linhas a um deslocamento diferente de 0 a partir de um favorito. Para mais informações, veja o argumento FetchOffset .
SQLExtendedFetch e SQLFetchScroll usam tamanhos de linhas diferentes. O SQLExtendedFetch usa o valor do atributo da instrução SQL_ROWSET_SIZE, e o SQLFetchScroll usa o valor do atributo da instrução SQL_ATTR_ROW_ARRAY_SIZE.
O SQLExtendedFetch tem uma semântica de gestão de erros ligeiramente diferente do SQLFetchScroll. Para mais informações, consulte "Gestão de Erros" na secção "Comentários" do SQLFetchScroll.
O SQLExtendedFetch não suporta deslocamentos de ligação (o atributo SQL_ATTR_ROW_BIND_OFFSET_PTR da instrução).
Chamadas para SQLExtendedFetch não podem ser misturadas com chamadas para SQLFetch ou SQLFetchScroll, e se SQLBulkOperations for chamado antes de qualquer função fetch ser chamada, SQLExtendedFetch não pode ser chamado até que o cursor seja fechado e reaberto. Ou seja, SQLExtendedFetch só pode ser chamado no estado da instrução S7. Para mais informações, consulte Transições de Declarações no Apêndice B: Tabelas de Transição de Estado ODBC.
Quando uma aplicação chama SQLFetchScroll usando um driver ODBC 2*.x*, o Gestor de Drivers mapeia esta chamada para SQLExtendedFetch. Para mais informações, consulte "SQLFetchScroll and ODBC 2*.x* Drivers" em SQLFetchScroll.
No ODBC 2*.x*, o SQLExtendedFetch era chamado para buscar várias linhas e o SQLFetch era chamado para buscar uma única linha. No ODBC 3*.x*, por outro lado, o SQLFetch pode ser chamado para buscar várias linhas.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Ligar um buffer a uma coluna num conjunto de resultados | Função SQLBindCol |
| Realização de operações de inserção, atualização ou eliminação em massa | Função SQLBulkOperations |
| Cancelamento do processamento de extratos | Função SQLCancel |
| Devolver informação sobre uma coluna num conjunto de resultados | Função SQLDescribeCol |
| Execução de uma instrução SQL | Função SQLExecDirect |
| Execução de uma instrução SQL preparada | Função SQLExecute |
| Devolvendo o número de colunas do conjunto de resultados | Função SQLNumResultCols |
| Posicionamento do cursor, atualização dos dados no conjunto de linhas, ou atualização ou eliminação de dados no conjunto de resultados | Função SQLSetPos |
| Definir um atributo de instrução | Função SQLSetStmtAttr |