Função SQLExtendedFetch
Compatibilidade
Versão introduzida: Conformidade com os padrões ODBC 1.0: Preterido
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 Cursores de bloco, 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
Identificador de declaração
[Entrada] Identificador de instrução.
Orientação de busca
[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 é 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 de busca ser chamada. Em outras palavras, ele é usado apenas no estado de instrução S7. Não é usado nos estados de declaraçã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 das chamadas para SQLBulkOperations ou SQLSetPos depois que um cursor foi posicionado por SQLExtendedFetch são indefinidos.
Devoluções
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 comumente 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 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.
| 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. Se fosse um valor numérico, a parte fracionária do número era truncada. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01S01 | Erro na linha | Ocorreu um erro ao buscar uma ou mais linhas. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 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 a posição atual estava além da primeira linha e FetchOrientation estava SQL_PRIOR ou FetchOrientation estava 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 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 | Um valor de dados não pôde ser convertido para o tipo de dados C especificado por TargetType em 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 estava conectado falhou antes que a função concluísse o processamento. |
| 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 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 faria com que toda a parte (em oposição à 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 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. (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 na divisão por zero. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 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. (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 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. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 24.000 | Estado de cursor inválido | O 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 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çã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 SQLExtendedFetch 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) 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 | Buscar tipo fora do intervalo | (DM) O valor especificado para o argumento FetchOrientation era inválido. (Veja "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 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 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 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 ao tipo de busca especificado. 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. 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 | Timeout expired | O período de tempo limite da consulta expirou antes que a fonte de dados retornasse 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 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. |
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 ou 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 tamanhos de conjunto de linhas diferentes. 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 erros ligeiramente diferente do SQLFetchScroll. Para obter mais informações, consulte "Tratamento de erros" na seção "Comentários" do SQLFetchScroll.
SQLExtendedFetch não oferece 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 de qualquer função de busca ser chamada, SQLExtendedFetch não poderá ser chamado até que o cursor seja fechado e reaberto. Ou seja, SQLExtendedFetch pode ser chamado somente 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 "Drivers SQLFetchScroll e ODBC 2*.x*" em 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, o SQLFetch pode ser chamado para buscar várias linhas.
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 |
| 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 |