Função SQLMoreResults

  • Artigo

Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: ODBC

Resumo
SQLMoreResults determina se mais resultados estão disponíveis em uma instrução que contém instruções SELECT, UPDATE, INSERT ou DELETE e, nesse caso, inicializa o processamento para esses resultados.

Sintaxe

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);

Argumentos

StatementHandle
[Entrada] Identificador de instrução.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_PARAM_DATA_AVAILABLE.

Diagnósticos

Quando SQLMoreResults retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLMoreResults 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 o contrário.

SQLSTATE Erro Descrição
01000 Aviso geral Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.)
01S02 O valor da opção foi alterado O valor de um atributo de instrução foi alterado à medida que o lote estava sendo processado. (A função retorna SQL_SUCCESS_WITH_INFO.)
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 função concluir o processamento.
40001 Falha na serialização A transação foi revertida devido a um deadlock de recursos com outra transação.
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 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 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 StatementHandle. A função SQLMoreResults foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle. Em seguida, a função SQLMoreResults foi chamada novamente no StatementHandle.

A função SQLMoreResults 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 em 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 SQLMoreResults foi chamada.

(DM) Uma função de execução assíncrona (não esta) foi chamada para StatementHandle e ainda estava em execução quando essa função foi chamada.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para StatementHandle e retornados 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.
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.
HY117 A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar e somente leitura são permitidas. (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran.
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

As instruções SELECT retornam conjuntos de resultados. As instruções UPDATE, INSERT e DELETE retornam uma contagem de linhas afetadas. Se qualquer uma dessas instruções for enviada em lote, enviada com matrizes de parâmetros (numeradas em ordem de parâmetro crescente, na ordem em que aparecem no lote) ou em procedimentos, elas poderão retornar vários conjuntos de resultados ou contagens de linhas. Para obter informações sobre lotes de instruções e matrizes de parâmetros, consulte Lotes de instruções SQL e matrizes de valores de parâmetro.

Depois de executar o lote, o aplicativo é posicionado no primeiro conjunto de resultados. O aplicativo pode chamar SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos e todas as funções de metadados, no primeiro ou em quaisquer conjuntos de resultados subsequentes, assim como faria se houvesse apenas um único conjunto de resultados. Depois de terminar com o primeiro conjunto de resultados, o aplicativo chama SQLMoreResults para passar para o próximo conjunto de resultados. Se outro conjunto de resultados ou contagem estiver disponível, SQLMoreResults retornará SQL_SUCCESS e inicializará o conjunto de resultados ou a contagem para processamento adicional. Se qualquer instrução de geração de contagem de linhas aparecer entre instruções de geração de conjunto de resultados, elas poderão ser substituídas chamando SQLMoreResults. Depois de chamar SQLMoreResults para instruções UPDATE, INSERT ou DELETE , um aplicativo pode chamar SQLRowCount.

Se houver um conjunto de resultados atual com linhas não buscadas, SQLMoreResults descartará esse conjunto de resultados e disponibilizará o próximo conjunto de resultados ou contagem. Se todos os resultados tiverem sido processados, SQLMoreResults retornará SQL_NO_DATA. Para alguns drivers, os parâmetros de saída e os valores retornados não estão disponíveis até que todos os conjuntos de resultados e contagens de linhas tenham sido processados. Para esses drivers, os parâmetros de saída e os valores retornados ficam disponíveis quando SQLMoreResults retorna SQL_NO_DATA.

Todas as associações estabelecidas para o conjunto de resultados anterior ainda permanecem válidas. Se as estruturas de coluna forem diferentes para esse conjunto de resultados, chamar SQLFetch ou SQLFetchScroll poderá resultar em um erro ou truncamento. Para evitar isso, o aplicativo precisa chamar SQLBindCol para reassociar explicitamente conforme apropriado (ou fazer isso definindo campos de descritor). Como alternativa, o aplicativo pode chamar SQLFreeStmt com uma Opção de SQL_UNBIND para desassociar todos os buffers de coluna.

Os valores de atributos de instrução, como tipo de cursor, simultaneidade do cursor, tamanho do conjunto de chaves ou comprimento máximo, podem ser alterados à medida que o aplicativo navega pelo lote por chamadas para SQLMoreResults. Se isso acontecer, SQLMoreResults retornará SQL_SUCCESS_WITH_INFO e SQLSTATE 01S02 (o valor da opção foi alterado).

Chamar SQLCloseCursor ou SQLFreeStmt com uma Opção de SQL_CLOSE descarta todos os conjuntos de resultados e contagens de linhas que estavam disponíveis como resultado da execução do lote. O identificador de instrução retorna ao estado alocado ou preparado. Chamar SQLCancel para cancelar uma função em execução assíncrona quando um lote for executado e o identificador de instrução estiver no estado executado, posicionado por cursor ou assíncrono resultará em todos os conjuntos de resultados e contagens de linhas gerados pelo lote sendo descartado se a chamada de cancelamento tiver sido bem-sucedida. Em seguida, a instrução retorna ao estado preparado ou alocado.

Se um lote de instruções ou um procedimento combinar outras instruções SQL com instruções SELECT, UPDATE, INSERT e DELETE , essas outras instruções não afetarão SQLMoreResults.

Para obter mais informações, consulte Vários resultados.

Se uma instrução de atualização, inserção ou exclusão pesquisada em um lote de instruções não afetar nenhuma linha na fonte de dados, SQLMoreResults retornará SQL_SUCCESS. Isso é diferente do caso de uma instrução pesquisada de atualização, inserção ou exclusão executada por meio de SQLExecDirect, SQLExecute ou SQLParamData, que retorna SQL_NO_DATA se não afetar nenhuma linha na fonte de dados. Se um aplicativo chamar SQLRowCount para recuperar a contagem de linhas após uma chamada para SQLMoreResults não afetar nenhuma linha, SQLRowCount retornará SQL_NO_DATA.

Para obter informações adicionais sobre o sequenciamento válido de funções de processamento de resultados, consulte Apêndice B: Tabelas de Transição de Estado ODBC.

Para obter mais informações sobre SQL_PARAM_DATA_AVAILABLE e parâmetros de saída transmitidos, consulte Recuperando parâmetros de saída usando SQLGetData.

Disponibilidade de contagens de linhas

Quando um lote contém várias instruções de geração de contagem de linhas consecutivas, é possível que essas contagens de linhas sejam acumuladas em apenas uma contagem de linhas. Por exemplo, se um lote tiver cinco instruções de inserção, determinadas fontes de dados serão capazes de retornar cinco contagens de linhas individuais. Determinadas outras fontes de dados retornam apenas uma contagem de linhas que representa a soma das cinco contagens de linhas individuais.

Quando um lote contém uma combinação de instruções de geração de conjunto de resultados e geração de contagem de linhas, as contagens de linhas podem ou não estar disponíveis. O comportamento do driver em relação à disponibilidade de contagens de linhas é enumerado no tipo de informações SQL_BATCH_ROW_COUNT disponível por meio de uma chamada para SQLGetInfo. Por exemplo, suponha que o lote contenha um SELECT, seguido por dois INSERTs e outro SELECT. Em seguida, os seguintes casos são possíveis:

  • As contagens de linhas correspondentes às duas instruções INSERT não estão disponíveis. A primeira chamada para SQLMoreResults posicionará você no conjunto de resultados da segunda instrução SELECT .

  • As contagens de linhas correspondentes às duas instruções INSERT estão disponíveis individualmente. (Uma chamada para SQLGetInfo não retorna o bit SQL_BRC_ROLLED_UP para o tipo de informações SQL_BATCH_ROW_COUNT.) A primeira chamada para SQLMoreResults posicionará você na contagem de linhas da primeira INSERT e a segunda chamada posicionará você na contagem de linhas do segundo INSERT. A terceira chamada para SQLMoreResults posicionará você no conjunto de resultados da segunda instrução SELECT .

  • As contagens de linhas correspondentes aos dois INSERTs são acumuladas em uma única contagem de linhas disponível. (Uma chamada para SQLGetInfo retorna o bit SQL_BRC_ROLLED_UP para o tipo de informações SQL_BATCH_ROW_COUNT.) A primeira chamada para SQLMoreResults posicionará você na contagem de linhas acumuladas e a segunda chamada para SQLMoreResults posicionará você no conjunto de resultados do segundo SELECT.

Determinados drivers disponibilizam contagens de linhas apenas para lotes explícitos e não para procedimentos armazenados.

Para obter informações sobre Consulte
Cancelando o processamento de instruções Função SQLCancel
Buscar um bloco de dados ou rolar por um conjunto de resultados Função SQLFetchScroll
Buscar uma única linha ou um bloco de dados em uma direção somente para frente Função SQLFetch
Buscar parte ou todas as colunas de dados Função SQLGetData

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC
Recuperar parâmetros de saída usando SQLGetData