Processando resultados (ODBC)

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsAnalytics Platform System (PDW)

Depois que um aplicativo envia uma instrução SQL, o SQL Server retorna todos os dados resultantes como um ou mais conjuntos de resultados. Um conjunto de resultados é um conjunto de linhas e colunas que correspondem aos critérios da consulta. As instruções SELECT, funções de catálogo e alguns procedimentos armazenados geram um conjunto de resultados disponibilizado para um aplicativo no formato tabular. Se a instrução SQL executada for um procedimento armazenado, um lote contendo vários comandos ou uma instrução SELECT contendo palavras-chave, haverá vários conjuntos de resultados a serem processados.

As funções de catálogo ODBC também podem recuperar dados. Por exemplo, SQLColumns recupera dados sobre colunas na fonte de dados. Esses conjuntos de resultados podem conter zero ou mais linhas.

Outras instruções SQL, como GRANT ou REVOKE, não retornam conjuntos de resultados. Para essas instruções, o código de retorno de SQLExecute ou SQLExecDirect geralmente é a única indicação de que a instrução foi bem-sucedida.

Cada INSERTinstrução , UPDATE, and DELETE retorna um conjunto de resultados contendo apenas o número de linhas afetadas pela modificação. Essa contagem é disponibilizada quando o aplicativo chama SQLRowCount. ODBC 3.x aplicativos devem chamar SQLRowCount para recuperar o conjunto de resultados ou SQLMoreResults para cancelá-lo. Quando uma aplicação executa um procedimento em lote ou armazenado contendo múltiplas INSERT, UPDATE, ou DELETE instruções, o conjunto de resultados de cada instrução de modificação deve ser processado usando SQLRowCount ou cancelado usando SQLMoreResults. Essas contagens podem ser canceladas incluindo uma SET NOCOUNT instrução ON no procedimento batch ou armazenado.

Transact-SQL inclui a SET NOCOUNT declaração. Quando a NOCOUNT opção é ativada, o SQL Server não retorna as contagens das linhas afetadas por uma instrução e o SQLRowCount retorna 0. A versão do driver ODBC do SQL Server Native Client introduz uma opção SQLGetStmtAttr específica para o driver, SQL_SOPT_SS_NOCOUNT_STATUS, para informar se a NOCOUNT opção está ligada ou desativada. Sempre que SQLRowCount retornar 0, o aplicativo deverá testar SQL_SOPT_SS_NOCOUNT_STATUS. Se SQL_NC_ON for retornado, o valor de 0 de SQLRowCount indicará apenas que o SQL Server não retornou uma contagem de linhas. Se SQL_NC_OFF for retornado, significa que NOCOUNT está desligado e o valor de 0 do SQLRowCount indica que a instrução não afetou nenhuma linha. Os aplicativos não devem exibir o valor de SQLRowCount quando SQL_SOPT_SS_NOCOUNT_STATUS é SQL_NC_OFF. Grandes lotes ou procedimentos armazenados podem conter múltiplas SET NOCOUNT instruções, então os programadores não podem assumir SQL_SOPT_SS_NOCOUNT_STATUS permanece constante. A opção deve ser testada sempre que SQLRowCount retornar 0.

Várias outras instruções Transact-SQL retornam seus dados em mensagens e não em conjuntos de resultados. Quando o driver ODBC do SQL Server Native Client recebe essas mensagens, ele retorna SQL_SUCCESS_WITH_INFO para que o aplicativo saiba que as mensagens informativas estão disponíveis. Em seguida, o aplicativo pode chamar SQLGetDiagRec para recuperar essas mensagens. As instruções Transact-SQL que funcionam dessa maneira são:

  • DBCC

  • SETSHOWPLAN (disponível com versões anteriores do SQL Server)

  • SET STATISTICS

  • PRINT

  • RAISERROR

O driver ODBC do SQL Server Native Client retorna SQL_ERROR em um RAISERROR com uma gravidade de 11 ou superior. Se a severidade do RAISERROR for 19 ou superior, a conexão também será descartada.

Para processar os conjuntos de resultados de uma instrução SQL, o aplicativo:

  • Determina as características do conjunto de resultados.

  • Associa as colunas às variáveis do programa.

  • Recupera um único valor, uma linha inteira de valores ou várias linhas de valores.

  • Testa se há mais conjuntos de resultados e, se houver, faz loops de volta para determinar as características do novo conjunto de resultados.

O processo de recuperar linhas da fonte de dados e retorná-las ao aplicativo é chamado de busca.

Nesta seção

Confira também

SQL Server Cliente Nativo (ODBC)
Tópicos de instrução sobre processamento de resultados (ODBC)

  • Last updated on