Função SQLFetch

Conformidade
Versão introduzida: Conformidade com as normas ODBC 1.0: ISO 92

Resumo
SQLFetch busca o próximo conjunto de linhas de dados do conjunto de resultados e retorna dados para todas as colunas acopladas.

Sintaxe

  
SQLRETURN SQLFetch(  
     SQLHSTMT     StatementHandle);  

Argumentos

StatementHandle
[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óstico

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 retornados pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário. Se ocorrer um erro em uma única coluna, SQLGetDiagField pode ser chamado com um DiagIdentifier de SQL_DIAG_COLUMN_NUMBER para determinar a coluna em que o erro ocorreu; e SQLGetDiagField pode 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 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO é retornado se ocorrer um erro em uma ou mais, mas não todas, linhas de uma operação de várias linhas, e SQL_ERROR é retornado se ocorrer um erro em uma operação de linha única.

SQLSTATE	Erro	Descrição
01000	Advertência geral	Mensagem informativa específica do motorista. (A função retorna SQL_SUCCESS_WITH_INFO.)
01004	Dados da cadeia de caracteres, truncados à direita	Dados binários ou de cadeia de caracteres retornados para uma coluna resultaram no truncamento de caracteres não vazios ou dados binários não NULL. Se fosse um valor de cadeia de caracteres, ele estava 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 trabalhando com um driver ODBC 2*.x*, ele poderá ser ignorado.)
01S07	Truncamento fracionado	Os dados retornados para uma coluna foram truncados. Para os tipos de dados numéricos, a parte fracionária do número foi truncada. Para os tipos de dados de data/hora, 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 no SQLBindCol. A coluna 0 foi associada a um tipo de dados de SQL_C_BOOKMARK e o atributo SQL_ATTR_USE_BOOKMARKS statement 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 suporta 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 da cadeia de caracteres, truncados à direita	Um marcador de comprimento variável retornado para uma coluna foi truncado.
22002	Variável indicadora necessária, mas não fornecida	Os dados NULL foram obtidos 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 acopladas teria feito com que a parte inteira (em oposição à 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 datetime inválido	Uma coluna de caracteres no conjunto de resultados estava vinculada 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 de intervalo C 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 elenco	Uma coluna de caracteres no conjunto de resultados estava vinculada 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, um datetime ou um tipo de dados intervalar; o tipo SQL da coluna era um tipo de dados de caracteres; e o valor na coluna não era um literal válido do tipo C vinculado.
24000	Estado do 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 em que a busca foi executada foi encerrada para evitar o impasse.
40003	Conclusão da declaraçã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 de implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer de *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 suportar a 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 chamada 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. Esta função assíncrona ainda estava em execução quando a função SQLFetch foi chamada. (DM) SQLExecute, SQLExecDirectou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Esta função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. (DM) O especificado StatementHandle 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, SQLBulkOperationsou SQLSetPos foi chamado para o StatementHandle e retornou SQL_NEED_DATA. Esta 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 chamado.
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 pouca memória.
HY090	String inválida ou comprimento do buffer	O atributo SQL_ATTR_USE_BOOKMARK statement foi definido como SQL_UB_VARIABLE e a coluna 0 foi vinculada 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 SQL_ATTR_CURSOR_TYPE statement foi SQL_CURSOR_KEYSET_DRIVEN, mas o valor especificado com o atributo SQL_ATTR_KEYSET_SIZE statement foi maior que 0 e menor que o valor especificado com o atributo SQL_ATTR_ROW_ARRAY_SIZE statement.
HY117	A conexão é suspensa devido ao estado desconhecido da transação. Apenas as 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 fonte de dados não suporta a conversão especificada pela combinação do TargetType no SQLBindCol e o tipo de dados SQL da coluna correspondente.
HYT00	Tempo limite expirado	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	Expirou o tempo limite de ligação	O período de tempo limite de conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Driver não suporta esta função	(DM) O driver associado ao StatementHandle não suporta a função.
IM017	A sondagem está desativada no modo de notificação assíncrona	Sempre que o modelo de notificação é usado, a sondagem é desativada.
IM018	SQLCompleteAsync não foi chamado para concluir a operação assíncrona anterior neste 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.

Observações

SQLFetch retorna o próximo conjunto de linhas no conjunto de resultados. Ele pode ser chamado apenas enquanto existir um conjunto de resultados: 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 vinculada, 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 retorna 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 Obtendo uma linha de dados.

Se um aplicativo ODBC 3*.x* funciona com um driver ODBC 2*.x*, o Gerenciador de Driver mapeia chamadas SQLFetch para SQLExtendedFetch para um driver ODBC 2*.x* que suporta SQLExtendedFetch. Se o driver ODBC 2*.x* não suportar SQLExtendedFetch, o Gerenciador de Driver mapeia chamadas SQLFetch para SQLFetch no driver ODBC 2*.x*, que pode buscar apenas uma única linha.

Para obter mais informações, consulte os cursores de bloqueio , cursores roláveis e compatibilidade com versões anteriores no Apêndice G: Diretrizes de motorista para compatibilidade com versões anteriores.

Posicionar 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 SQL_ATTR_ROW_ARRAY_SIZE statement 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, 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 do 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 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 - Tamanho do conjunto de linhas[1]	CurrRowsetStart + Tamanho do conjunto de linhas[2]
CurrRowsetStart>LastResultRow - Tamanho do conjunto de linhas[1]	Após o fim
Após o fim	Após o fim

[1] Se o tamanho do conjunto de linhas for alterado entre 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 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 for anterior ao início do conjunto de resultados, SQLFetch retornará SQL_NO_DATA.
Após o fim	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 do 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 anos	5
1 a 5 anos	SQL_SUCCESS	6 a 10 anos	5
52 a 56 anos	SQL_SUCCESS	57 a 61 anos	5
91 a 95 anos	SQL_SUCCESS	96 a 100 anos	5
93 a 97 anos	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 a 100 anos	SQL_NO_DATA	Nenhum.	0
99 a 100	SQL_NO_DATA	Nenhum.	0
Após o fim	SQL_NO_DATA	Nenhum.	0

Retornando dados em colunas acopladas

Como SQLFetch retorna cada linha, ele coloca os dados para cada coluna acoplada no buffer vinculado a essa coluna. Se nenhuma coluna estiver vinculada, o SQLFetch não retornará dados, 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 pode ser chamado somente 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, SQLFetch faz o seguinte:

1. 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 vinculado, 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" em SQLBindCol.

   Se os dados da coluna não forem NULL, o SQLFetch prosseguirá para a etapa 2.

2. Se o atributo de instrução SQL_ATTR_MAX_LENGTH for definido como um valor diferente de zero e a coluna contiver caracteres ou dados binários, 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 suportá-lo. 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 no SQLBindCol.

3. Converte os dados para o tipo especificado por TargetType em SQLBindCol.

4. 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 caracteres (incluindo o caractere de terminação nula) exceder o comprimento do buffer de dados, SQLFetch truncará os dados para o comprimento do buffer de dados menos o comprimento de um caractere de terminação nulo. Em seguida, ele termina nulo os dados. Se o comprimento dos dados binários exceder o comprimento do buffer de dados, o SQLFetch o truncará para o comprimento do buffer de dados. O comprimento do buffer de dados é especificado com BufferLength no SQLBindCol.

   SQLFetch nunca trunca dados convertidos em tipos de dados de comprimento fixo; ele sempre assume que o comprimento do buffer de dados é o tamanho do tipo de dados.

5. 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.

6. Coloca o comprimento dos dados no buffer de comprimento/indicador. Se o ponteiro indicador e o ponteiro de comprimento foram definidos para o mesmo buffer (como faz uma chamada para SQLBindCol ), 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 vinculado, SQLFetch não retorna o comprimento.

   • Para dados binários ou de 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 pode determinar o comprimento dos dados após a conversão, como às vezes é o caso com dados longos, ele define o comprimento para SQL_NO_TOTAL. Se os dados foram truncados devido ao atributo de instrução SQL_ATTR_MAX_LENGTH, o valor desse atributo é colocado no buffer length/indicator em vez do comprimento real. Isso ocorre porque esse atributo é projetado para truncar dados no servidor antes da conversão, de modo que o driver não tem como descobrir qual é o comprimento real.

   • Para todos os outros tipos de dados, este é 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.

7. 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 retorna SQLSTATE 01S07 (truncamento fracionário) e SQL_SUCCESS_WITH_INFO. Se os dados forem truncados porque o comprimento do buffer de dados for 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, 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 acoplado e do buffer length/indicator será indefinido se SQLFetch ou SQLFetchScroll não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO.

Matriz de estado 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 quantos forem 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 obtida com sucesso e não foi alterada desde a última vez que foi obtida a partir deste conjunto de resultados.
SQL_ROW_SUCCESS_WITH_INFO	A linha foi obtida com sucesso e não foi alterada desde a última vez que foi obtida a partir deste conjunto de resultados. No entanto, um aviso foi retornado sobre a fila.
SQL_ROW_ERROR	Ocorreu um erro ao buscar a linha.
SQL_ROW_UPDATED[1],[2] e [3]	A linha foi obtida com sucesso e mudou desde a última vez que foi obtida a partir deste conjunto de resultados. Se a linha for buscada novamente a partir 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 a partir deste conjunto de resultados.
SQL_ROW_ADDED[4]	A linha foi inserida por SQLBulkOperations. Se a linha for buscada novamente a partir desse conjunto de resultados ou for atualizada pelo SQLSetPos, seu status será SQL_ROW_SUCCESS.
SQL_ROW_NOROW	O conjunto de linhas sobrepôs-se ao final do conjunto de resultados e nenhuma linha foi retornada que correspondesse 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 é considerada excluída e uma nova linha adicionada.

[2] Alguns drivers não podem detetar atualizações de dados e, portanto, não podem retornar esse valor. Para determinar se um driver pode detetar atualizações para linhas refetadas, 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 rebusca nenhuma linha. Como nenhuma linha é refetched, SQLFetch não deteta alterações que foram feitas em linhas buscadas anteriormente. No entanto, se SQLFetchScroll posicionar o cursor antes de quaisquer linhas buscadas anteriormente e SQLFetch for usado para buscar essas linhas, SQLFetch poderá detetar quaisquer alterações nessas linhas.

[4] Retornado apenas por SQLBulkOperations. Não definido por SQLFetch ou SQLFetchScroll.

Linhas buscadas Buffer

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. É 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 buscado de linhas será 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 Diagnostics 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 do 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, 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 SQLFetch fará 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, SQLFetch definirá o número da coluna como SQL_NO_COLUMN_NUMBER.

SQLFetch continua buscando linhas até ter 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, SQLFetch retornará SQL_ERROR.

SQLFetch retorna os registros de status em ordem numérica de linha. Ou seja, ele retorna todos os registros de status para linhas desconhecidas (se houver); Em seguida, ele retorna todos os registros de status para a 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 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 argumentos

O driver não define nenhum campo descritor com base nos argumentos de SQLFetch.

Outros campos descritores

Os seguintes campos descritores são usados pelo SQLFetch.

Campo descritor	Desc.	Campo em	Definir através de
SQL_DESC_ARRAY_SIZE	DAR	cabeçalho	SQL_ATTR_ROW_ARRAY_SIZE atributo da instrução
SQL_DESC_ARRAY_STATUS_PTR	IRD	cabeçalho	SQL_ATTR_ROW_STATUS_PTR atributo da instrução
SQL_DESC_BIND_OFFSET_PTR	DAR	cabeçalho	SQL_ATTR_ROW_BIND_OFFSET_PTR atributo de instrução
SQL_DESC_BIND_TYPE	DAR	cabeçalho	SQL_ATTR_ROW_BIND_TYPE atributo de instrução
SQL_DESC_COUNT	DAR	cabeçalho	Argumento ColumnNumber do SQLBindCol
SQL_DESC_DATA_PTR	DAR	registos	Argumento TargetValuePtr do SQLBindCol
SQL_DESC_INDICATOR_PTR	DAR	registos	StrLen_or_IndPtr argumento em SQLBindCol
SQL_DESC_OCTET_LENGTH	DAR	registos	Argumento BufferLength no SQLBindCol
SQL_DESC_OCTET_LENGTH_PTR	DAR	registos	StrLen_or_IndPtr argumento em SQLBindCol
SQL_DESC_ROWS_PROCESSED_PTR	IRD	cabeçalho	SQL_ATTR_ROWS_FETCHED_PTR atributo da instrução
SQL_DESC_TYPE	DAR	registos	Argumento TargetType no SQLBindCol

Todos os campos descritores também podem ser definidos através 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 para 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, SQLFetch define o buffer indicador como 0 e retorna o comprimento no buffer de comprimento. Quando os dados são NULL, SQLFetch define o buffer indicador para 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	Veja
Vinculando um buffer a uma coluna em um conjunto de resultados	da função SQLBindCol
Cancelamento do processamento de instruções	da 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	da função SQLExecute
Buscar um bloco de dados ou rolar por um conjunto de resultados	Função SQLFetchScroll
Fechar o cursor sobre a instrução	Função SQLFreeStmt
Obtenção de parte ou da totalidade de uma coluna de dados	Função SQLGetData
Retornando o número de colunas do conjunto de resultados	Função SQLNumResultCols
Preparação de uma declaração para execução	Função SQLPrepare

Ver também

de referência da API ODBC
Arquivos de cabeçalho ODBC