Tratando de erros e mensagens
Quando um aplicativo chama uma função ODBC, o driver executa a função e retorna informações de diagnóstico de duas formas: um código de retorno indica o êxito ou a falha geral de uma função ODBC, e registros de diagnóstico fornecem informações detalhadas sobre a função. Os registros de diagnóstico incluem um registro de cabeçalho e registros de status. Pelo menos um registro de diagnóstico, o registro de cabeçalho, será retornado, mesmo que a função tenha êxito.
As informações de diagnóstico são usadas em tempo de desenvolvimento para capturar erros de programação, como identificadores inválidos e erros de sintaxe em instruções SQL embutidas em código. Elas também são usadas em tempo de execução para capturar erros e avisos de tempo de execução, como truncamento de dados, violações de regras e erros de sintaxe em instruções SQL inseridas pelo usuário. Em geral, a lógica de programação se baseia em códigos de retorno.
Por exemplo, depois que um aplicativo chama SQLFetch para recuperar as linhas em um conjunto de resultados, o código de retorno indica se o final do conjunto de resultados foi atingido (SQL_NO_DATA), se alguma mensagem informativa foi retornada (SQL_SUCCESS_WITH_INFO) ou se ocorreu um erro (SQL_ERROR).
Se o driver ODBC SQL Server Native Client retornar algo diferente de SQL_SUCCESS, o aplicativo poderá chamar SQLGetDiagRec para recuperar mensagens informativas ou de erro. Use SQLGetDiagRec para rolar para cima e para baixo no conjunto de mensagens se houver mais de uma mensagem.
O código de retorno SQL_INVALID_HANDLE sempre indica um erro de programação e nunca deve ser encontrado em tempo de execução. Todos os outros códigos de retorno fornecem informações, embora SQL_ERROR possa indicar um erro de programação.
A API nativa do Microsoft SQL Server original, DB-Library para C, permite que um aplicativo instale funções de tratamento de erros e tratamento de mensagens de retorno de chamada que retornam erros ou mensagens. Algumas instruções Transact-SQL, como PRINT, RAISERROR, DBCC e SET, retornam seus resultados para a função do manipulador de mensagens DB-Library em vez de para um conjunto de resultados. Porém, a API ODBC não tem nenhum recurso de retorno de chamada. Quando o driver ODBC SQL Server Native Client detecta mensagens retornadas de SQL Server, ele define o código de retorno ODBC como SQL_SUCCESS_WITH_INFO ou SQL_ERROR e retorna a mensagem como um ou mais registros de diagnóstico. Portanto, um aplicativo ODBC deve testar cuidadosamente esses códigos de retorno e chamar SQLGetDiagRec para recuperar dados de mensagem.
Para obter informações sobre como rastrear erros, confira Rastreamento do acesso a dados. Para obter informações sobre aprimoramentos no rastreamento de erros adicionados no SQL Server 2012, consulte Acessando informações de diagnóstico no log de eventos estendidos.