Registros y campos de diagnóstico
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 los campos del 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 campos de los registros de estado, vea SQLGetDiagField.
SQLGetDiagRec recupera un único registro de diagnóstico junto con el ODBC SQLSTATE, el número de error nativo y los campos de mensaje de diagnóstico. Esta funcionalidad es similar a la función SQLError de ODBC 2.x. La función de control de errores más simple de ODBC 3.x consiste en llamar repetidamente a SQLGetDiagRec empezando con el parámetro RecNumber establecido en 1 e incrementando RecNumber en 1 hasta que SQLGetDiagRec devuelve SQL_NO_DATA. Esto equivale a una aplicación de ODBC 2.x que llama a SQLError hasta que devuelve SQL_NO_DATA_FOUND.
ODBC 3.x admite mucha más información de diagnóstico que ODBC 2.x. Esta información se almacena en campos adicionales de registros de diagnóstico que se recuperan con SQLGetDiagField.
El controlador ODBC de SQL Server Native Client incluye 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. Utilice estas etiquetas para recuperar el estado de SQL Server, el nivel de gravedad, el nombre de servidor, el nombre de 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 el controlador utiliza para identificar instrucciones Transact-SQL si una aplicación llama a SQLGetDiagField con DiagIdentifier establecido en SQL_DIAG_DYNAMIC_FUNCTION_CODE.
El Administrador de controladores ODBC procesa SQLGetDiagField utilizando información de error del controlador subyacente que almacena en caché. 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 para obtener los 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. Solo se puede comenzar a llamar a SQLGetDiagField para obtener campos de diagnóstico específicos del proveedor después de efectuar una llamada a otra función de ODBC tras la función de conexión.
La mayoría de los errores que notifica el controlador ODBC de SQL Server Native Client se pueden diagnosticar eficazmente solo con la información que devuelve 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 de ODBC para las aplicaciones con el controlador ODBC de SQL Server Native Client, se recomienda utilizar también SQLGetDiagField para recuperar al menos los campos específicos del controlador SQL_DIAG_SS_SEVERITY y SQL_DIAG_SS_MSGSTATE. Si un error determinado se puede producir en varias ubicaciones del código de SQL Server, SQL_DIAG_SS_MSGSTATE indica a un ingeniero de soporte técnico de Microsoft de forma específica dónde se ha producido el error, lo que en ocasiones ayuda a diagnosticar un problema.