Função SQLMoreResults

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.

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.

Funções relacionadas

Consulte Também

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