Registros e campos de diagnóstico
Os registros de diagnóstico são associados com ambiente, conexão, instrução ou identificadores de descritor ODBC. Quando uma função ODBC gera um código de retorno diferente de SQL_SUCCESS ou SQL_INVALID_HANDLE, o identificador chamado pela função possui registros de diagnóstico associados que contêm mensagens de erro ou mensagens informativas. Esses registros são retidos até que outra função seja chamada com aquele identificador. Depois disso, são descartados. Não há limite para o número de registros de diagnóstico que podem ser associados a um identificador de uma só vez.
Há dois tipos de registros de diagnóstico: cabeçalho e status. O registro de cabeçalho é registro 0; quando há registros de status, eles são registros 1 e posteriores. Os registros de diagnóstico contêm campos diferentes para o registro de cabeçalho e os registros de status. Os componentes ODBC também podem definir seus próprios campos de registro de diagnóstico.
Os campos no registro de cabeçalho contêm informações gerais sobre a execução de uma função, incluindo o código de retorno, a contagem de linhas, o número de registros de status e o tipo de instruções executadas. O registro de cabeçalho sempre é criado, a menos que uma função ODBC retorne SQL_INVALID_HANDLE. Para obter uma lista completa dos campos do registro de cabeçalho, consulte SQLGetDiagField.
Os campos dos registros de status contêm informações sobre erros ou avisos específicos retornados pelo Gerenciador de Driver ODBC, driver ou fonte de dados, incluindo o SQLSTATE, número do erro nativo, mensagem de diagnóstico, número da coluna e número da linha. Os registros de status só são criados se a função retornar SQL_ERROR, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_NEED_DATA ou SQL_STILL_EXECUTING. Para obter uma lista completa dos campos do registro de status, consulte SQLGetDiagField.
SQLGetDiagRec recupera um único registro de diagnóstico junto com seu ODBC SQLSTATE, número de erro nativo e campos da mensagem de diagnóstico. Essa funcionalidade é semelhante à função SQLError do ODBC 2.x. A função mais simples de tratamento de erros no ODBC 3.x é chamar repetidamente SQLGetDiagRec começando com o parâmetro RecNumber definido como 1 e aumentando RecNumber de 1 em 1 até que SQLGetDiagRec retorne SQL_NO_DATA. Esse procedimento é equivalente a um aplicativo ODBC 2.x que chama SQLError até ele retornar SQL_NO_DATA_FOUND.
O ODBC 3.x dá suporte a muito mais informações de diagnóstico do que o ODBC 2.x. Essas informações são armazenadas em campos adicionais de registros de diagnóstico recuperados com SQLGetDiagField.
O driver ODBC do SQL Server Native Client tem campos de diagnóstico específicos de driver que podem ser recuperados com SQLGetDiagField. Os rótulos para esses campos específicos de driver são definidos em sqlncli.h. Use esses rótulos para recuperar o estado SQL Server, nível de severidade, nome do servidor, nome do procedimento e número de linha associado a cada registro de diagnóstico. Além disso, sqlncli.h conterá definições dos códigos que o driver usa para identificar instruções Transact-SQL se um aplicativo chamar SQLGetDiagField com DiagIdentifier definido como SQL_DIAG_DYNAMIC_FUNCTION_CODE.
SQLGetDiagField é processado pelo Gerenciador de Driver ODBC usando as informações de erro do driver subjacente que ele armazena em cache. O Gerenciador de Driver ODBC não armazena em cache os campos de diagnóstico específicos de driver até que seja estabelecida uma conexão bem-sucedida. SQLGetDiagField retornará SQL_ERROR se for chamado para obter campos de diagnóstico específicos de driver antes que uma conexão bem-sucedida seja estabelecida. Se uma função de conexão ODBC retornar SQL_SUCCESS_WITH_INFO, os campos de diagnóstico específicos de driver para a função de conexão ainda não estarão disponíveis. Você só pode iniciar uma chamada a SQLGetDiagField para campos de diagnóstico específicos de driver depois que tiver feito outra chamada a uma função ODBC após a função de conexão.
A maioria dos erros relatados pelo driver ODBC doSQL Server Native Client podem ser diagnosticados com base apenas nas informações retornadas por SQLGetDiagRec. Em alguns casos, porém, as informações retornadas pelos campos de diagnóstico específicos de driver são importantes no diagnóstico de um erro. Ao codificar um identificador de erro ODBC para aplicativos que usam o driver ODBC do SQL Server Native Client, é recomendável usar também SQLGetDiagField para recuperar pelo menos os campos específicos de driver SQL_DIAG_SS_MSGSTATE e SQL_DIAG_SS_SEVERITY. Se um erro em particular for gerado em vários locais no código SQL Server, SQL_DIAG_SS_MSGSTATE indicará a um engenheiro de suporte da Microsoft onde especificamente o erro foi gerado, o que muitas vezes ajuda no diagnóstico de um problema.