Registros e campos de diagnóstico
Aplica-se a: 
SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics Analytics Platform System (PDW)
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 de campos no 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 de campos nos registros de status, consulte SQLGetDiagField.
SQLGetDiagRec recupera um único registro de diagnóstico junto com seu SQLSTATE ODBC, número de erro nativo e campos de mensagem de diagnóstico. Essa funcionalidade é semelhante ao ODBC 2.xSQLError . A função de tratamento de erros mais simples no ODBC 3.x é chamar repetidamente SQLGetDiagRec começando com o parâmetro RecNumber definido como 1 e incrementando RecNumber em 1 até que SQLGetDiagRec retorne SQL_NO_DATA. Isso é equivalente a um ODBC 2.x chamando SQLError até retornar SQL_NO_DATA_FOUND.
ODBC 3.x suporta muito mais informações de diagnóstico do que ODBC 2.x. Essas informações são armazenadas em campos adicionais em registros de diagnóstico recuperados usando SQLGetDiagField.
O driver ODBC do SQL Server Native Client tem campos de diagnóstico específicos do 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 do SQL Server, o nível de gravidade, o nome do servidor, o nome do procedimento e o número da linha associados a cada registro de diagnóstico. Além disso, sqlncli.h contém 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 informações de erro que ele armazena em cache do driver subjacente. 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 do driver antes que uma conexão bem-sucedida seja concluída. 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ê pode começar a chamar SQLGetDiagField para campos de diagnóstico específicos do driver somente depois de fazer outra chamada de função ODBC após a função connect.
A maioria dos erros relatados pelo driver ODBC do SQL Server Native Client pode ser diagnosticada com eficiência usando apenas as informações retornadas pelo 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 manipulador de erros ODBC para aplicativos que usam o driver ODBC do SQL Server Native Client, é uma boa ideia usar também SQLGetDiagField para recuperar pelo menos os campos específicos do driver SQL_DIAG_SS_MSGSTATE e SQL_DIAG_SS_SEVERITY. Se um erro específico puder ser gerado em vários locais no código do SQL Server, SQL_DIAG_SS_MSGSTATE indicará a um engenheiro de suporte da Microsoft especificamente onde um erro foi gerado, o que às vezes ajuda no diagnóstico de um problema.