Função SQLFetch
Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ISO 92
Resumo
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
StatementHandle
[Entrada] Identificador de instrução.
Retornos
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 a função SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por 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 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ãoblank ou dados binários não NULL. Se fosse um valor de cadeia de caracteres, ele estava truncado com o botão direito. |
| 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.) |
| 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 conclusão do processamento da função. |
| 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 a parte inteira (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 caractere 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 | Falha na conexão associada 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 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çõ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 SQLFetch 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) 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álida | 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 este 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 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 foi maior que 0 e menor que o valor especificado com o atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE. |
| 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 à 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
SQLFetch retorna o próximo conjunto de linhas no conjunto de resultados. Ele 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, 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, confira Buscar 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* compatível com 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 Bloquear cursores, 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 Cursores de Bloco.
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 SQLFetch se sobrepor ao final do conjunto de resultados, SQLFetch 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 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 nesta 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] | Após o término |
| Após o término | Após o término |
[1] Se o tamanho do conjunto de linhas for alterado entre fetches, esse será o tamanho do conjunto de linhas usado com a busca anterior.
[2] Se o tamanho do conjunto de linhas for alterado entre fetches, esse será o tamanho do conjunto de linhas usado com a nova busca.
| 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, SQLFetch 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, 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 retornados 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 a 61 | 5 |
| 91 a 95 | SQL_SUCCESS | 96 a 100 | 5 |
| 93 a 97 | SQL_SUCCESS | 98 a 100. As linhas 4 e 5 da matriz de status de linha são definidas como SQL_ROW_NOROW. | 3 |
| 96 a 100 | SQL_NO_DATA | Nenhum. | 0 |
| 99 a 100 | SQL_NO_DATA | Nenhum. | 0 |
| Após o término | SQL_NO_DATA | Nenhum. | 0 |
Retornando dados em colunas associadas
À medida que SQLFetch retorna cada linha, ele coloca os dados de cada coluna associada no buffer associado a essa coluna. Se nenhuma coluna estiver associada, SQLFetch não retornará dados, mas moverá o cursor de 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 associada em uma linha, 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, SQLFetch retornará SQLSTATE 22002 (variável de indicador 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" no SQLBindCol.
Se os dados da coluna não forem NULL, 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 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, ele é implementado pela fonte de dados, que trunca os dados antes de devolvê-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 no 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, SQLFetch truncará os dados até o comprimento do buffer de dados menos o comprimento de um caractere de terminação nula. Em seguida, ele termina os dados em nulo. Se o comprimento dos dados binários exceder o comprimento do buffer de dados, SQLFetch o truncará até o comprimento do buffer de dados. O comprimento do buffer de dados é especificado com BufferLength em SQLBindCol.
O SQLFetch nunca trunca os dados convertidos em tipos de dados de comprimento fixo; ele sempre pressupõe que o comprimento do buffer de dados seja do 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" no SQLBindCol.
Coloca o comprimento dos dados no buffer de comprimento/indicador. Se o ponteiro indicador e o ponteiro de comprimento foram definidos como o mesmo buffer (como uma chamada para SQLBindCol ), o comprimento será gravado no buffer para dados válidos e SQL_NULL_DATA será gravado no buffer para dados NULL. Se nenhum buffer de comprimento/indicador tiver sido associado, SQLFetch não retornará o comprimento.
Para dados binários ou caracteres, esse é o comprimento dos dados após a conversão e antes do truncamento devido ao buffer de dados ser 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 define o comprimento como SQL_NO_TOTAL. Se os dados tiverem sido truncados devido ao atributo de instrução SQL_ATTR_MAX_LENGTH, o valor desse atributo será 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, de modo 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 no 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" no SQLBindCol.
Se os dados forem truncados durante a conversão sem perda de dígitos significativos (por exemplo, o número real 1.234 será 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 retorna SQLSTATE 01004 (Dados truncados) e SQL_SUCCESS_WITH_INFO. Se os dados forem truncados devido ao atributo de instrução SQL_ATTR_MAX_LENGTH, 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 tiver sido 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ão indefinidos se SQLFetch ou SQLFetchScroll não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO.
Matriz de status da linha
A matriz de status de 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 após o cursor ter sido 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 da 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. No entanto, um aviso foi retornado sobre a linha. |
| SQL_ROW_ERROR | Ocorreu um erro ao buscar a linha. |
| SQL_ROW_UPDATED[1],[2], e [3] | A linha foi buscada com êxito e foi alterada desde a última busca desse conjunto de resultados. Se a linha for buscada novamente desse conjunto de resultados ou for atualizada por SQLSetPos, o status será alterado para o novo status da linha. |
| SQL_ROW_DELETED[3] | A linha foi excluída desde a última busca desse conjunto de resultados. |
| SQL_ROW_ADDED[4] | A linha foi inserida por SQLBulkOperations. Se a linha for buscada novamente desse conjunto de resultados ou for atualizada por SQLSetPos, seu status será SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | O conjunto de linhas sobrepôs o final do conjunto de resultados e nenhuma linha foi retornada que correspondia 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 será adicionada.
[2] Alguns drivers não podem detectar atualizações de dados e, portanto, não podem retornar esse valor. Para determinar se um driver pode detectar atualizações de linhas refetchadas, um aplicativo chama SQLGetInfo com a opção SQL_ROW_UPDATES.
[3] SQLFetch só pode retornar esse valor quando ele é intermixado 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 é refetchada, 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 alterações nessas linhas.
[4] Retornado apenas por SQLBulkOperations. Não definido por SQLFetch ou SQLFetchScroll.
Buffer buscado de linhas
O buffer buscado de linhas é usado para retornar o número de linhas buscadas, incluindo as linhas para as quais nenhum dado foi retornado porque ocorreu um erro durante a busca. 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 buscado de linhas será indefinido se SQLFetch ou SQLFetchScroll não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, exceto quando SQL_NO_DATA for retornado, nesse caso, o valor no buffer buscado de linhas é definido como 0.
Tratamento de erros
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 na função inteira
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 de conjunto de linhas é indefinido e a posição do cursor é inalterada.
Se um aviso se aplicar a toda a funçã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, SQLFetchfará o seguinte:
Define o elemento correspondente da matriz de status de 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 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, SQLFetch definirá o número da coluna como SQL_NO_COLUMN_NUMBER.
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 (sem incluir linhas com status SQL_ROW_NOROW), nesse caso, retorna SQL_ERROR. Em particular, se o tamanho do conjunto de linhas for 1 e ocorrer um erro nessa linha, SQLFetch retornará SQL_ERROR.
SQLFetch retorna os registros de status na ordem de número de linha. Ou seja, retorna todos os registros de status para linhas desconhecidas (se houver); em seguida, retorna todos os registros de status da primeira linha (se houver) e, em seguida, retorna todos os registros de status para a segunda linha (se houver) e assim por diante. Os registros de status de 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" no SQLGetDiagField.
Descritores e SQLFetch
As seções a seguir descrevem como o SQLFetch interage com descritores.
Mapeamentos de argumentos
O driver não define nenhum campo de descritor com base nos argumentos de 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 | atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | header | atributo de instrução SQL_ATTR_ROW_STATUS_PTR |
| SQL_DESC_BIND_OFFSET_PTR | ARD | header | atributo de instrução SQL_ATTR_ROW_BIND_OFFSET_PTR |
| SQL_DESC_BIND_TYPE | ARD | header | atributo de instrução SQL_ATTR_ROW_BIND_TYPE |
| SQL_DESC_COUNT | ARD | header | Argumento ColumnNumber de SQLBindCol |
| SQL_DESC_DATA_PTR | ARD | records | Argumento TargetValuePtr de SQLBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | records | argumento StrLen_or_IndPtr no SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | records | Argumento BufferLength no SQLBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | records | argumento StrLen_or_IndPtr no SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | header | atributo de instrução SQL_ATTR_ROWS_FETCHED_PTR |
| SQL_DESC_TYPE | ARD | records | Argumento TargetType no SQLBindCol |
Todos os campos de descritor também podem ser definidos por meio de SQLSetDescField.
Separar buffers de tamanho e indicador
Os aplicativos podem associar 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 para endereços diferentes.
SQLFetch determina se o aplicativo especificou buffers de tamanho e indicador separados. Nesse caso, quando os dados não são NULL, SQLFetch define o buffer de indicador como 0 e retorna o comprimento no buffer de comprimento. Quando os dados são NULL, SQLFetch define o buffer de 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 |
|---|---|
| Associar um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| 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 |
| 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 |
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