Registros y campos de diagnóstico
Se aplica a:
SQL Server Azure SQL Database Azure SQL Instancia administrada Azure Synapse Analytics Analytics Platform System (PDW)
Los registros de diagnóstico se asocian a controladores de entorno, conexión, instrucción o descriptor de ODBC. Cuando una función de ODBC genera un código de retorno distinto de SQL_SUCCESS o SQL_INVALID_HANDLE, el identificador que llama la función incluye registros de diagnóstico asociados que contienen mensajes informativos o de error. Estos registros se conservan hasta que se llama a otra función con el mismo identificador, momento en el cual se descartan. No hay ningún límite al número de registros de diagnóstico que pueden estar asociados a un identificador en un momento determinado.
Existen dos tipos de registros de diagnóstico: encabezado y estado. El registro de encabezado es el registro 0; cuando hay registros de estado, son registros 1 y posteriores. Los registros de diagnóstico contienen diferentes campos para el registro de encabezado y los registros de estado. Los componentes ODBC también pueden definir sus propios campos de registro de diagnóstico.
Los campos del registro de encabezado contienen información general sobre la ejecución de una función, incluido el código de retorno, el recuento de filas, el número de registros de estado y tipo de instrucción ejecutada. El registro de encabezado se crea siempre, a menos que una función de ODBC devuelva SQL_INVALID_HANDLE. Para obtener una lista completa de campos en el registro de encabezado, vea SQLGetDiagField.
Los campos de los registros de estado contienen información sobre errores o advertencias concretos devueltos por el Administrador de controladores ODBC, el controlador o el origen de datos, incluidos SQLSTATE, el número de error nativo, el mensaje de diagnóstico, el número de columna y el número de fila. Los registros de estado solamente se crean si la función devuelve SQL_ERROR, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_NEED_DATA o SQL_STILL_EXECUTING. Para obtener una lista completa de los campos de los registros de estado, vea SQLGetDiagField.
SQLGetDiagRec recupera un único registro de diagnóstico junto con sus campos ODBC SQLSTATE, número de error nativo y mensaje de diagnóstico. Esta funcionalidad es similar a ODBC 2.xfunción SQLError . La función de control de errores más sencilla en ODBC 3.x es llamar repetidamente a SQLGetDiagRec a partir del parámetro RecNumber establecido en 1 e incrementar RecNumber en 1 hasta que SQLGetDiagRec devuelva SQL_NO_DATA. Esto equivale a un ODBC 2.x aplicación que llama a SQLError hasta que devuelve SQL_NO_DATA_FOUND.
ODBC 3.x admite mucho más información de diagnóstico que ODBC 2.x. Esta información se almacena en campos adicionales en los registros de diagnóstico recuperados mediante SQLGetDiagField.
El controlador ODBC de SQL Server Native Client tiene campos de diagnóstico específicos del controlador que se pueden recuperar con SQLGetDiagField. Las etiquetas de estos campos específicos de controlador se definen en sqlncli.h. Use estas etiquetas para recuperar el estado de SQL Server, el nivel de gravedad, el nombre del servidor, el nombre del procedimiento y el número de línea asociados a cada registro de diagnóstico. Además, sqlncli.h contiene definiciones de los códigos que usa el controlador para identificar instrucciones Transact-SQL si una aplicación llama a SQLGetDiagField con DiagIdentifier establecido en SQL_DIAG_DYNAMIC_FUNCTION_CODE.
SQLGetDiagField lo procesa el Administrador de controladores ODBC mediante la información de error que almacena en caché del controlador subyacente. El Administrador de controladores ODBC no almacena en caché los campos de diagnóstico específicos del controlador hasta que no se ha realizado una conexión correcta. SQLGetDiagField devuelve SQL_ERROR si se llama a para obtener campos de diagnóstico específicos del controlador antes de que se haya completado una conexión correcta. Si una función de conexión de ODBC devuelve SQL_SUCCESS_WITH_INFO, los campos de diagnóstico específicos del controlador todavía no están disponibles en la función de conexión. Puede empezar a llamar a SQLGetDiagField para campos de diagnóstico específicos del controlador solo después de haber realizado otra llamada de función ODBC después de la función connect.
La mayoría de los errores notificados por el controlador ODBC de SQL Server Native Client se pueden diagnosticar de forma eficaz mediante solo la información devuelta por SQLGetDiagRec. En algunos casos, sin embargo, la información que devuelven los campos de diagnóstico específicos del controlador es importante para diagnosticar un error. Al codificar un controlador de errores ODBC para aplicaciones que usan el controlador ODBC de SQL Server Native Client, también es recomendable usar SQLGetDiagField para recuperar al menos los campos SQL_DIAG_SS_MSGSTATE y SQL_DIAG_SS_SEVERITY específicos del controlador. Si se puede generar un error determinado en varias ubicaciones del código de SQL Server, SQL_DIAG_SS_MSGSTATE indica a un ingeniero de soporte técnico de Microsoft específicamente dónde se produjo un error, lo que a veces ayuda a diagnosticar un problema.