Função SQLFetch
Compatibilidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92
Resumo
O SQLFetch busca o próximo conjunto de linhas de dados do conjunto de resultados e retorna dados para todas as colunas associadas.
Sintaxe
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
Argumentos
Identificador de declaração
[Entrada] Identificador de instrução.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLFetch retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec Function com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados pelo SQLFetch 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.
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.) |
| 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 os tipos de dados de tempo, carimbo de data/hora e intervalo 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 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 vez de 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. |
| 24.000 | 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 SQLFetch foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle. Em seguida, a função SQLFetch foi chamada novamente no StatementHandle. Ou a função SQLFetch 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 SQLFetch 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.) |
| 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. |
| 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
SQLFetch retorna o próximo conjunto de linhas no conjunto de resultados. Ele pode ser chamado somente enquanto um conjunto de resultados existir: 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, o SQLFetch também retornará essas informações. As chamadas para SQLFetch podem ser misturadas com chamadas para SQLFetchScroll , mas não podem ser misturadas com chamadas para SQLExtendedFetch. Para obter mais informações, consulte Buscando uma linha de dados.
Se um aplicativo ODBC 3*.x* funcionar com um driver ODBC 2*.x*, o Gerenciador de Driver mapeará chamadas SQLFetch para SQLExtendedFetch para um driver ODBC 2*.x* que dá suporte a SQLExtendedFetch. Se o driver ODBC 2*.x* não der suporte a SQLExtendedFetch, o Gerenciador de Driver mapeará chamadas SQLFetch para SQLFetch no driver ODBC 2*.x*, que pode buscar apenas uma única linha.
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.
Posicionando o cursor
Quando o conjunto de resultados é criado, o cursor é posicionado antes do início do conjunto de resultados. SQLFetch busca o próximo conjunto de linhas. É equivalente a chamar SQLFetchScroll com FetchOrientation definido como SQL_FETCH_NEXT. Para obter mais informações sobre cursores, consulte Cursores e Bloqueando Cursores.
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 pelo SQLFetch se sobrepõe ao final do conjunto de resultados, o SQLFetch 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 o SQLFetch retorna, a linha atual é a primeira linha do conjunto de linhas.
As regras listadas na tabela a seguir descrevem o posicionamento do cursor após uma chamada para SQLFetch, com base nas condições listadas na segunda tabela desta seção.
| Condição | Primeira linha do novo conjunto de linhas |
|---|---|
| Antes de começar | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | Depois de terminar |
| Depois de terminar | Depois de terminar |
[1] Se o tamanho do conjunto de linhas for alterado entre as buscas, este é o tamanho do conjunto de linhas que foi usado com a busca anterior.
[2] Se o tamanho do conjunto de linhas for alterado entre as buscas, este é o tamanho do conjunto de linhas que foi usado com a nova busca.
| 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, SQLFetch 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 estiver após o final do conjunto de resultados, SQLFetch 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. |
Por exemplo, suponha que um conjunto de resultados tenha 100 linhas e o tamanho do conjunto de linhas seja 5. A tabela a seguir mostra o conjunto de linhas e o código de retorno retornado pelo SQLFetch para diferentes posições iniciais.
| Conjunto de linhas atual | Código de retorno | Novo conjunto de linhas | # de linhas buscadas |
|---|---|---|---|
| Antes de começar | SQL_SUCCESS | 1 a 5 | 5 |
| 1 a 5 | SQL_SUCCESS | 6 a 10 | 5 |
| 52 a 56 | SQL_SUCCESS | 57 até 61 | 5 |
| 91 até 95 | SQL_SUCCESS | 96 até 100 | 5 |
| 93 até 97 | SQL_SUCCESS | 98 a 100. As linhas 4 e 5 da matriz de status da linha são definidas como SQL_ROW_NOROW. | 3 |
| 96 até 100 | SQL_NO_DATA | Nenhum. | 0 |
| 99 até 100 | SQL_NO_DATA | Nenhum. | 0 |
| Depois de terminar | SQL_NO_DATA | Nenhum. | 0 |
Retornando dados em colunas acopladas
À medida que o SQLFetch retorna cada linha, ele coloca os dados de cada coluna associada no buffer associado a essa coluna. Se nenhuma coluna estiver associada, o SQLFetch não retornará nenhum dado, mas moverá o cursor do bloco para frente. Os dados ainda podem ser recuperados usando SQLGetData. Se o cursor for um cursor de várias linhas (ou seja, o SQL_ATTR_ROW_ARRAY_SIZE for maior que 1), SQLGetData só poderá ser chamado se SQL_GD_BLOCK for retornado quando SQLGetInfo for chamado com um InfoType de SQL_GETDATA_EXTENSIONS. (Para obter mais informações, consulte SQLGetData.)
Para cada coluna acoplada em uma linha, o SQLFetch faz o seguinte:
Define o buffer de comprimento/indicador como SQL_NULL_DATA e prossegue para a próxima coluna se os dados forem NULL. Se os dados forem NULL e nenhum buffer de comprimento/indicador tiver sido associado, o SQLFetch retornará SQLSTATE 22002 (variável indicadora necessária, mas não fornecida) para a linha e prosseguirá para a próxima linha. Para obter informações sobre como determinar o endereço do buffer de comprimento/indicador, consulte "Endereços de buffer" em SQLBindCol.
Se os dados da coluna não forem NULL, o SQLFetch prosseguirá para a etapa 2.
Se o atributo de instrução SQL_ATTR_MAX_LENGTH for definido como um valor diferente de zero e a coluna contiver dados binários ou de caracteres, os dados serão truncados para SQL_ATTR_MAX_LENGTH bytes.
Observação
O atributo de instrução SQL_ATTR_MAX_LENGTH destina-se a reduzir o tráfego de rede. Geralmente é implementado pela fonte de dados, que trunca os dados antes de retorná-los pela rede. Drivers e fontes de dados não são necessários para dar suporte a ele. Portanto, para garantir que os dados sejam truncados para um tamanho específico, um aplicativo deve alocar um buffer desse tamanho e especificar o tamanho no argumento cbValueMax em SQLBindCol.
Converte os dados para o tipo especificado por TargetType em SQLBindCol.
Se os dados foram convertidos em um tipo de dados de comprimento variável, como caractere ou binário, o SQLFetch verifica se o comprimento dos dados excede o comprimento do buffer de dados. Se o comprimento dos dados de caractere (incluindo o caractere de terminação nula) exceder o comprimento do buffer de dados, o SQLFetch truncará os dados para o comprimento do buffer de dados menos o comprimento de um caractere de terminação nula. Em seguida, ele encerra os dados em nulo. Se o comprimento dos dados binários exceder o comprimento do buffer de dados, o SQLFetch os truncará para o comprimento do buffer de dados. O comprimento do buffer de dados é especificado com BufferLength em SQLBindCol.
O SQLFetch nunca trunca dados convertidos em tipos de dados de comprimento fixo; ele sempre pressupõe que o comprimento do buffer de dados é o tamanho do tipo de dados.
Coloca os dados convertidos (e possivelmente truncados) no buffer de dados. Para obter informações sobre como determinar o endereço do buffer de dados, consulte "Endereços de buffer" em SQLBindCol.
Coloca o comprimento dos dados no buffer de comprimento/indicador. Se o ponteiro do indicador e o ponteiro de comprimento foram definidos para o mesmo buffer (como uma chamada para SQLBindCol faz), o comprimento é gravado no buffer para dados válidos e SQL_NULL_DATA é gravado no buffer para dados NULL. Se nenhum buffer de comprimento/indicador foi associado, o SQLFetch não retornará o comprimento.
Para dados binários ou de caracteres, esse é o comprimento dos dados após a conversão e antes do truncamento porque o buffer de dados é muito pequeno. Se o driver não puder determinar o comprimento dos dados após a conversão, como às vezes é o caso com dados longos, ele definirá o comprimento como SQL_NO_TOTAL. Se os dados foram truncados por causa do atributo de instrução SQL_ATTR_MAX_LENGTH, o valor desse atributo é colocado no buffer de comprimento/indicador em vez do comprimento real. Isso ocorre porque esse atributo foi projetado para truncar dados no servidor antes da conversão, para que o driver não tenha como descobrir qual é o comprimento real.
Para todos os outros tipos de dados, esse é o comprimento dos dados após a conversão; ou seja, é o tamanho do tipo para o qual os dados foram convertidos.
Para obter informações sobre como determinar o endereço do buffer de comprimento/indicador, consulte "Endereços de buffer" em SQLBindCol.
Se os dados forem truncados durante a conversão sem perda de dígitos significativos (por exemplo, o número real 1,234 é truncado para o inteiro 1 quando convertido), SQLFetch retornará SQLSTATE 01S07 (truncamento fracionário) e SQL_SUCCESS_WITH_INFO. Se os dados forem truncados porque o comprimento do buffer de dados é muito pequeno (por exemplo, a cadeia de caracteres "abcdef" é colocada em um buffer de 4 bytes), SQLFetch retornará SQLSTATE 01004 (Dados truncados) e SQL_SUCCESS_WITH_INFO. Se os dados forem truncados devido ao atributo de instrução SQL_ATTR_MAX_LENGTH, o SQLFetch retornará SQL_SUCCESS e não retornará SQLSTATE 01S07 (truncamento fracionário) ou SQLSTATE 01004 (dados truncados). Se os dados forem truncados durante a conversão com uma perda de dígitos significativos (por exemplo, se um valor de SQL_INTEGER maior que 100.000 for convertido em um SQL_C_TINYINT), SQLFetch retornará SQLSTATE 22003 (valor numérico fora do intervalo) e SQL_ERROR (se o tamanho do conjunto de linhas for 1) ou SQL_SUCCESS_WITH_INFO (se o tamanho do conjunto de linhas for maior que 1).
O conteúdo do buffer de dados associado e do buffer de comprimento/indicador será indefinido se SQLFetch ou SQLFetchScroll não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO.
Matriz de status da linha
A matriz de status da linha é usada para retornar o status de cada linha no conjunto de linhas. O endereço dessa matriz é especificado com o atributo de instrução SQL_ATTR_ROW_STATUS_PTR. A matriz é alocada pelo aplicativo e deve ter tantos elementos quanto especificados pelo atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE. Seus valores são definidos por SQLFetch, SQLFetchScroll e SQLBulkOperations ou SQLSetPos (exceto quando eles foram chamados depois que o cursor foi posicionado por SQLExtendedFetch). Se o valor do atributo de instrução SQL_ATTR_ROW_STATUS_PTR for um ponteiro nulo, essas funções não retornarão o status da linha.
O conteúdo do buffer da matriz de status de linha será indefinido se SQLFetch ou SQLFetchScroll não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO.
Os valores a seguir são retornados na matriz de status da linha.
| Valor da matriz de status da linha | Descrição |
|---|---|
| SQL_ROW_SUCCESS | A linha foi buscada com êxito e não foi alterada desde a última busca desse conjunto de resultados. |
| SQL_ROW_SUCCESS_WITH_INFO | A linha foi buscada com êxito e não foi alterada desde a última busca desse conjunto de resultados. Porém, foi retornado um aviso sobre a fila. |
| SQL_ROW_ERROR | Ocorreu um erro ao efetuar fetch da linha. |
| SQL_ROW_UPDATED[1],[2] e [3] | A linha foi buscada com êxito e foi alterada desde a última vez que foi buscada desse conjunto de resultados. Se a linha for buscada novamente desse conjunto de resultados ou for atualizada pelo SQLSetPos, o status será alterado para o novo status da linha. |
| SQL_ROW_DELETED[3] | A linha foi excluída desde a última vez que foi buscada desse conjunto de resultados. |
| SQL_ROW_ADDED[4] | SQLBulkOperations inseriu a linha. Se a linha for buscada novamente desse conjunto de resultados ou for atualizada pelo SQLSetPos, seu status será SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | O conjunto de linhas se sobrepôs ao final do conjunto de resultados e não foi retornada nenhuma linha correspondente a esse elemento da matriz de status da linha. |
[1] Para cursores de conjunto de chaves, mistos e dinâmicos, se um valor de chave for atualizado, a linha de dados será considerada excluída e uma nova linha adicionada.
[2] Alguns drivers não podem detectar atualizações nos dados e, portanto, não podem retornar esse valor. Para determinar se um driver pode detectar atualizações para linhas para as quais foi efetuado um novo fetch, um aplicativo chama SQLGetInfo com a opção SQL_ROW_UPDATES.
[3] SQLFetch pode retornar esse valor somente quando ele é misturado com chamadas para SQLFetchScroll. Isso ocorre porque o SQLFetch avança pelo conjunto de resultados e, quando é usado exclusivamente, não busca novamente nenhuma linha. Como nenhuma linha é buscada novamente, o SQLFetch não detecta alterações feitas em linhas buscadas anteriormente. No entanto, se SQLFetchScroll posicionar o cursor antes de qualquer linha buscada anteriormente e SQLFetch for usado para buscar essas linhas, o SQLFetch poderá detectar quaisquer alterações nessas linhas.
[4] Retornado apenas por SQLBulkOperations. Não definido por SQLFetch ou SQLFetchScroll.
Buffer de linhas buscadas
O buffer de linhas buscadas é usado para retornar o número de linhas buscadas, incluindo aquelas linhas para as quais nenhum dado foi retornado porque ocorreu um erro enquanto elas estavam sendo buscadas. Em outras palavras, é o número de linhas para as quais o valor na matriz de status da linha não é SQL_ROW_NOROW. O endereço desse buffer é especificado com o atributo de instrução SQL_ATTR_ROWS_FETCHED_PTR. O buffer é alocado pelo aplicativo. Ele é definido por SQLFetch e SQLFetchScroll. Se o valor do atributo de instrução SQL_ATTR_ROWS_FETCHED_PTR for um ponteiro nulo, essas funções não retornarão o número de linhas buscadas. Para determinar o número da linha atual no conjunto de resultados, um aplicativo pode chamar SQLGetStmtAttr com o atributo SQL_ATTR_ROW_NUMBER.
O conteúdo do buffer de linhas buscadas será indefinido se SQLFetch ou SQLFetchScroll não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, exceto quando SQL_NO_DATA for retornado, caso em que o valor no buffer de linhas buscadas será definido como 0.
Manipulação de Erro
Erros e avisos podem ser aplicados a linhas individuais ou a toda a função. Para obter mais informações sobre registros de diagnóstico, consulte Diagnóstico e SQLGetDiagField.
Erros e avisos em toda a função
Se um erro se aplicar a toda a função, como SQLSTATE HYT00 (tempo limite expirado) ou SQLSTATE 24000 (estado de cursor inválido), SQLFetch retornará SQL_ERROR e o SQLSTATE aplicável. O conteúdo dos buffers do conjunto de linhas é indefinido e a posição do cursor permanece inalterada.
Se um aviso se aplicar a toda a função, o SQLFetch retornará SQL_SUCCESS_WITH_INFO e o SQLSTATE aplicável. Os registros de status para avisos que se aplicam a toda a função são retornados antes dos registros de status que se aplicam a linhas individuais.
Erros e avisos em linhas individuais
Se um erro (como SQLSTATE 22012 (Divisão por zero)) ou um aviso (como SQLSTATE 01004 (Dados truncados)) se aplicar a uma única linha, o SQLFetchfará o seguinte:
Define o elemento correspondente da matriz de status da linha como SQL_ROW_ERROR para erros ou SQL_ROW_SUCCESS_WITH_INFO para avisos.
Adiciona zero ou mais registros de status que contêm SQLSTATEs para o erro ou aviso.
Define os campos de número de linha e coluna nos registros de status. Se o SQLFetch não puder determinar um número de linha ou coluna, ele definirá esse número como SQL_ROW_NUMBER_UNKNOWN ou SQL_COLUMN_NUMBER_UNKNOWN, respectivamente. Se o registro de status não se aplicar a uma coluna específica, o SQLFetch definirá o número da coluna como SQL_NO_COLUMN_NUMBER.
O SQLFetch continua buscando linhas até que tenha buscado todas as linhas no conjunto de linhas. Ele retorna SQL_SUCCESS_WITH_INFO a menos que ocorra um erro em todas as linhas do conjunto de linhas (não incluindo linhas com status SQL_ROW_NOROW), caso em que retorna SQL_ERROR. Em particular, se o tamanho do conjunto de linhas for 1 e ocorrer um erro nessa linha, o SQLFetch retornará SQL_ERROR.
SQLFetch retorna os registros de status na ordem do número da linha. Ou seja, ele retorna todos os registros de status para linhas desconhecidas (se houver); Em seguida, ele retorna todos os registros de status da primeira linha (se houver) e, em seguida, retorna todos os registros de status da segunda linha (se houver) e assim por diante. Os registros de status para cada linha são ordenados de acordo com as regras normais para ordenar registros de status; para obter mais informações, consulte "Sequência de registros de status" em SQLGetDiagField.
Descritores e SQLFetch
As seções a seguir descrevem como o SQLFetch interage com os descritores.
Mapeamentos de argumento
O driver não define nenhum campo de descritor com base nos argumentos do SQLFetch.
Outros campos de descritor
Os campos de descritor a seguir são usados pelo SQLFetch.
| Campo do descritor | Desc. | Campo em | Definir através |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | header | SQL_ATTR_ROW_ARRAY_SIZE atributo de instrução |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | header | SQL_ATTR_ROW_STATUS_PTR atributo de instrução |
| SQL_DESC_BIND_OFFSET_PTR | ARD | header | SQL_ATTR_ROW_BIND_OFFSET_PTR atributo de instrução |
| SQL_DESC_BIND_TYPE | ARD | header | SQL_ATTR_ROW_BIND_TYPE atributo de instrução |
| SQL_DESC_COUNT | ARD | header | ColumnNumber de SQLBindCol |
| SQL_DESC_DATA_PTR | ARD | registros | Argumento TargetValuePtr de SQLBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | registros | StrLen_or_IndPtr argumento em SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | registros | Argumento BufferLength em SQLBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | registros | StrLen_or_IndPtr argumento em SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | header | SQL_ATTR_ROWS_FETCHED_PTR atributo de instrução |
| SQL_DESC_TYPE | ARD | registros | Argumento TargetType em SQLBindCol |
Todos os campos do descritor também podem ser definidos por meio de SQLSetDescField.
Buffers de comprimento e indicador separados
Os aplicativos podem vincular um único buffer ou dois buffers separados que podem ser usados para manter valores de comprimento e indicador. Quando um aplicativo chama SQLBindCol, o driver define os campos SQL_DESC_OCTET_LENGTH_PTR e SQL_DESC_INDICATOR_PTR do ARD para o mesmo endereço, que é passado no argumento StrLen_or_IndPtr . Quando um aplicativo chama SQLSetDescField ou SQLSetDescRec, ele pode definir esses dois campos como endereços diferentes.
SQLFetch determina se o aplicativo especificou buffers de comprimento e indicador separados. Nesse caso, quando os dados não são NULL, o SQLFetch define o buffer do indicador como 0 e retorna o comprimento no buffer de comprimento. Quando os dados são NULL, o SQLFetch define o buffer do indicador como SQL_NULL_DATA e não modifica o buffer de comprimento.
Exemplo de código
Consulte SQLBindCol, SQLColumns, SQLGetData e SQLProcedures.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| 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 um bloco de dados ou rolando por um conjunto de resultados | Função SQLFetchScroll |
| Fechando o cursor na instrução | Função SQLFreeStmt |
| Buscando parte ou toda uma coluna de dados | Função SQLGetData |
| Retornando o número de colunas do conjunto de resultados | Função SQLNumResultCols |
| Preparando uma instrução para execução | Função SQLPrepare |