• Artigo

Tratando erros e mensagens em aplicativos

Erros gerados pelo Mecanismo de banco de dados do SQL Server ou pela instrução RAISERROR não fazem parte de um conjunto de resultados. Os erros são retornados aos aplicativos por meio de um mecanismo de tratamento de erro que é separado do processamento de conjuntos de resultados.

Cada API (interface de programação de aplicativo) do banco de dados tem um conjunto de funções, interfaces, métodos, objetos ou estruturas por meio dos quais mensagens e erros são retornados. Tipicamente, cada método ou função de API retorna um código de status que indica o sucesso da operação. Se o status for qualquer coisa diferente de êxito, o aplicativo poderá chamar os métodos, objetos ou funções de erro para recuperar as informações de erro.

O Mecanismo de Banco de Dados pode retornar informações ao chamador de uma das seguintes maneiras:

  1. Erros

    • Os erros do sys.messages com uma severidade de 11 ou maior.

    • Qualquer instrução RAISERROR com uma severidade de 11 ou superior.

  2. Mensagens

    • A saída da instrução PRINT.

    • A saída de várias instruções DBCC.

    • Os erros do sys.messages com uma severidade de 10 ou inferior.

    • Qualquer instrução RAISERROR com uma severidade de 10 ou inferior.

Aplicativos que usam APIs, como ActiveX Dados Objeto (ADO) e OLE DB geralmente não podem distinguir entre erros e mensagens. Em aplicativos ODBC (Open Database Connectivity), as mensagens geram um código de retorno de função SQL_SUCCESS_WITH_INFO e os erros normalmente geram um código de retorno SQL_ERROR. A diferença é mais pronunciada na DB-Library na qual os erros são retornados à função do manipulador de erros do aplicativo e as mensagens são retornadas à função do manipulador de mensagens do aplicativo. De maneira semelhante, ao usar o provedor SqlClient, os erros fazem com que a exceção do SqlException seja gerada. As mensagens não alteram o fluxo de controle e podem ser interceptadas pelo código do aplicativo registrando um retorno de chamada para o manipulador de eventos do InfoMessage.

Outros componentes também podem gerar erros:

  • O provedor OLE DB para SQL Server e o driver ODBC do SQL Server geram erros próprios. O formato desses erros é consistente com os formatos definidos nas especificações da API.

  • As Net-Libraries geram erros próprios.

  • A API de Procedimento Armazenado Estendido gera erros em seu próprio formato.

  • Os assistentes, aplicativos e utilitários do SQL Server, como o SQL Server Management Studio e o utilitário sqlcmd podem gerar seus próprios erros.

Os erros desses componentes são retornados ao aplicativo de chamada usando o mesmo mecanismo básico que erros do Mecanismo de Banco de Dados. Um aplicativo pode processar esses erros usando a mesma lógica de tratamento de erros que a usada para erros do Mecanismo de Banco de Dados. Como esses erros são gerados fora do Mecanismo de Banco de Dados, eles não podem ser processados em construções Transact-SQL TRY…CATCH. Para obter mais informações, consulte TRY...CATCH (Transact-SQL).

Tratamento de erros de ODBC

A especificação de ODBC introduziu um modelo de erros que funciona como a base dos modelos de erros das APIs genéricas de banco de dados, como ADO e OLE DB, e as APIs criadas sobre ODBC—RDO, DAO (Objeto de Acesso a Dados) e as Classes de Banco de Dados Microsoft Foundation Classes (MFC). Isso também se aplica ao driver de ODBC do SQL Server Native Client. No modelo de ODBC, os erros têm os seguintes atributos:

  • SQLSTATE

    O SQLSTATE é um código de erro de cinco caracteres definido originalmente na especificação de ODBC. Os códigos SQLSTATE são comuns entre todos os drivers ODBC e fornecem uma maneira para os aplicativos codificarem tratamento de erros básicos sem testar todos os diferentes códigos de erro retornados pelos vários bancos de dados. O SQLSTATE do ODBC não tem nada a fazer com o atributo de estado das mensagens de erro do Mecanismo de Banco de Dados.

    O ODBC 2.x retorna um conjunto de códigos SQLSTATE e o ODBC 3.x retorna um conjunto de códigos de SQLSTATE alinhados com o Open Group Data Management: Structured Query Language (SQL), versão 2 padrão. Como todos os drivers ODBC retornam os mesmos conjuntos de códigos SQLSTATE, os aplicativos que baseiam seu tratamento de erros nos códigos do SQLSTATE são mais portáteis.

  • Número de erro nativo

    O número de erro nativo é o número de erro do banco de dados subjacente. Os aplicativos de ODBC recebem os números de erros de Mecanismo de Banco de Dados como números de erros nativos.

  • Cadeia de caracteres da mensagem de erro

    A mensagem de erro é retornada no parâmetro da cadeia de caracteres da mensagem de erro.

Quando uma função ODBC retorna um status diferente de SQL_SUCCESS, o aplicativo pode chamar , SQLGetDiagRec para obter as informações do erro. Por exemplo, se um aplicativo ODBC obtiver um erro de sintaxe (número do erro do SQL Server 170), o SQLGetDiagRec retornará o seguinte.

szSqlState = 42000, pfNative = 170
szErrorMsg =
'[Microsoft][ODBC SQL Server Driver][SQL Server]
                                     Line 1: Incorrect syntax near *'

A função ODBC SQLGetDiagField permite que os drivers ODBC especifiquem campos de diagnóstico específicos ao driver nos registros do diagnóstico retornados pelo driver. O driver ODBC do SQL Server especifica campos específicos ao driver para manter informações de erros do Mecanismo de Banco de Dados, como os códigos de estado e de severidade do Mecanismo de Banco de Dados.

Para obter mais informações sobre como recuperar mensagens de erro em aplicativo s ODBC, consulte Tratando de erros e mensagens.

Tratamento de erros ADO

O ADO usa um objeto de erros e uma coleção de erros para retornar informações de erros padrão, como o SQLSTATE, o número do erro nativo e a cadeia de caracteres da mensagem de erro. Essas são as mesmas informações de suas contrapartes ODBC. O ADO não oferece suporte a nenhuma interface de erro específica ao provedor. As informações de erros específicas ao Mecanismo de Banco de Dados, como a severidade ou o estado, não estão disponíveis para aplicativos ADO.

Para obter mais informações sobre como recuperar mensagens de erro em aplicativos ADO, consulte Tratando de erros e mensagens.

Tratamento de erros OLE DB

O OLE DB usa a interface IErrorInfo para retornar informações de erros padrão, como o SQLSTATE, o número do erro nativo e a cadeia de caracteres do erro. Essas são as mesmas informações de suas contrapartes ODBC. O OLE DB Provider for SQL Server define uma interface ISQLServerErrorInfo para retornar informações específicas ao Mecanismo de Banco de Dados, como a severidade, o estado, o nome do procedimento e o número da linha.

Para obter mais informações sobre como recuperar mensagens de erro em aplicativos OLE DB, consulte Erros.

Tratamento de erros do SqlClient

O provedor gerenciado SqlClient gera uma exceção SQLEXCEPTION quando um erro não tratado é gerado pelo Mecanismo de banco de dados do SQL Server. Por meio da classe SqlException, os aplicativos podem recuperar informações sobre erros produzidos no lado do servidor, incluindo número de erros, mensagem do erro, severidade do erro e outras informações sobre o contexto da exceção.

Para avisos de processamento e mensagens informativas enviadas pelo Mecanismo de banco de dados do SQL Server, os aplicativos podem criar um representante do SqlInfoMessageEventHandler para escutar o evento do InfoMessage na classe SqlConnection. De maneira semelhante ao caso da exceção, as informações de contexto da mensagem, como severidade e estado, são passadas como argumentos ao retorno da chamada.