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 foi retornada alguma mensagem informativa (SQL_SUCCESS_WITH_INFO) ou se ocorreu um erro (SQL_ERROR).

Se o driver ODBC do SQL Server Native Client retornar qualquer coisa diferente de SQL_SUCCESS, o aplicativo poderá chamar SQLGetDiagRec para recuperar mensagens informativas ou de erro. Se houver mais de uma mensagem, use SQLGetDiagRec para rolar para cima e para baixo no conjunto de mensagens.

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 original do Microsoft SQL Server, DB-Library para C, permite que um aplicativo instale funções de tratamento de mensagens e de tratamento de erros de retorno de chamada que retornam erros ou mensagem. Algumas instruções Transact-SQL, como PRINT, RAISERROR, DBCC e SET, retornam seus resultados para a função de manipulador de mensagens de DB-Library e não para um conjunto de resultados. Porém, a API ODBC não tem nenhum recurso de retorno de chamada. Quando o driver ODBC do SQL Server Native Client detecta mensagens voltando do SQL Server, ele define o código de retorno do 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 mensagens.

Para obter mais informações sobre o rastreamento de erros, consulte Rastreamento do acesso a dados.