• Artigo

Processando resultados (ODBC)

Depois que um aplicativo envia uma instrução SQL, o SQL Server retorna qualquer dado resultante 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, como COMPUTE ou COMPUTE BY, 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 de 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, geralmente o código de retorno de SQLExecute ou SQLExecDirect é a única indicação de que a instrução teve êxito.

Cada instrução INSERT, UPDATE e DELETE retorna um conjunto de resultados que contém apenas o número de linhas afetado pela modificação. Essa contagem é disponibilizada quando o aplicativo chama SQLRowCount. Os aplicativos ODBC 3.x devem chamar SQLRowCount para recuperar o conjunto de resultados ou SQLMoreResults para cancelá-lo. Quando um aplicativo executa um lote ou um procedimento armazenado que contém várias instruções INSERT, UPDATE ou DELETE, 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 instrução SET NOCOUNT ON no lote ou no procedimento armazenado.

O Transact-SQL inclui a instrução SET NOCOUNT. Quando a opção NOCOUNT está ativada, o SQL Server não retorna as contagens das linhas afetadas por uma instrução e SQLRowCount retorna 0. A versão do driver ODBC do SQL Server Native Client apresenta uma opção SQLGetStmtAttr específica do driver, SQL_SOPT_SS_NOCOUNT_STATUS, para relatar se a opção NOCOUNT está ativada ou desativada. Sempre que SQLRowCount retornar 0, o aplicativo deverá testar SQL_SOPT_SS_NOCOUNT_STATUS. Se SQL_NC_ON for retornado, o valor 0 de SQLRowCount indicará apenas que o SQL Server não retornou uma contagem de linhas. Se SQL_NC_OFF for retornado, isso significa que NOCOUNT está desativado e que o valor 0 de SQLRowCount indicará que a instrução não afetou nenhuma linha. Os aplicativos não deverão exibir o valor de SQLRowCount quando SQL_SOPT_SS_NOCOUNT_STATUS for SQL_NC_OFF. Lotes ou procedimentos armazenados grandes podem conter várias instruções SET NOCOUNT, de forma que os programadores não podem supor que SQL_SOPT_SS_NOCOUNT_STATUS permaneça constante. A opção deverá 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 receber essas mensagens, ele retornará SQL_SUCCESS_WITH_INFO para informar o aplicativo que há mensagens informativas disponíveis. Então, o aplicativo pode chamar SQLGetDiagRec para recuperar essas mensagens. As instruções Transact-SQL que funcionam deste modo são as seguintes:

  • DBCC

  • SET SHOWPLAN (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 severidade 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 a partir 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 recuperação de linhas da fonte de dados e de seu retorno ao aplicativo é chamado de busca.

Recuperando conjuntos de resultados COMPUTE e COMPUTE BY

A cláusula COMPUTE BY gera subtotais dentro de um conjunto de resultados; a cláusula COMPUTE gera um total no final do conjunto de resultados. O driver ODBC do SQL Server Native Client apresenta esses totais e subtotais ao aplicativo que fez a chamada, gerando vários conjuntos de resultados para cada instrução SELECT.

O exemplo a seguir usa COMPUTE BY para gerar subtotais e COMPUTE para gerar um total:

SELECT Title = CONVERT(char(20), title), type, price, advance
FROM Titles
WHERE ytd_sales IS NOT NULL
  AND type LIKE '%cook%'
ORDER BY type DESC
COMPUTE AVG(price), SUM(advance) BY type
COMPUTE SUM(price), SUM(advance)

Essas instruções produzem um cálculo de subtotal do preço médio e da soma de adiantamentos para cada tipo de livro e, em seguida, produzem uma soma total final dos dados de preço e de adiantamento. O driver apresenta o primeiro conjunto de resultados das linhas de livros do primeiro tipo de livro. Em seguida, gera um segundo conjunto de resultados com as duas colunas COMPUTE BY referentes ao AVG(preço) e ao SUM(adiantamento) para esse primeiro conjunto de livros. Em seguida, gera um terceiro conjunto de resultados para o próximo grupo de livros e um quarto conjunto de resultados com os subtotais de COMPUTE BY referentes a esse grupo. O driver intercala esses conjuntos de resultados até gerar o conjunto de resultados final com o total da cláusula COMPUTE SUM(preço), SUM(adiantamento).