Función SQLGetDiagRec

  • Artículo

Conformidad
Versión introducida: Cumplimiento de estándares odbc 3.0: ISO 92

Resumen
SQLGetDiagRec devuelve los valores actuales de varios campos de un registro de diagnóstico que contiene información de error, advertencia y estado. A diferencia de SQLGetDiagField, que devuelve un campo de diagnóstico por llamada, SQLGetDiagRec devuelve varios campos usados habitualmente de un registro de diagnóstico, incluido SQLSTATE, el código de error nativo y el texto del mensaje de diagnóstico.

Sintaxis

  
SQLRETURN SQLGetDiagRec(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLCHAR *       SQLState,  
     SQLINTEGER *    NativeErrorPtr,  
     SQLCHAR *       MessageText,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   TextLengthPtr);

Argumentos

HandleType
[Entrada] Identificador de tipo de identificador que describe el tipo de identificador para el que se requieren diagnósticos. Debe ser una de las siguientes:

  • SQL_HANDLE_DBC

  • SQL_HANDLE_DBC_INFO_TOKEN

  • SQL_HANDLE_DESC

  • SQL_HANDLE_ENV

  • SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN controlador solo lo usa el Administrador de controladores y el controlador. Las aplicaciones no deben usar este tipo de identificador. Para obtener más información sobre SQL_HANDLE_DBC_INFO_TOKEN, vea Developing Connection-Pool Awareness in an ODBC Driver.

Handle
[Entrada] Identificador de la estructura de datos de diagnóstico, del tipo indicado por HandleType. Si HandleType es SQL_HANDLE_ENV, Handle puede ser un identificador de entorno compartido o no compartido.

RecNumber
[Entrada] Indica el registro de estado desde el que la aplicación busca información. Los registros de estado se numeran de 1.

SQLState
[Salida] Puntero a un búfer en el que devolver un código SQLSTATE de cinco caracteres (y terminar NULL) para el registro de diagnóstico RecNumber. Los dos primeros caracteres indican la clase ; las tres siguientes indican la subclase. Esta información se incluye en el campo de diagnóstico de SQL_DIAG_SQLSTATE. Para obtener más información, vea SQLSTATEs.

NativeErrorPtr
[Salida] Puntero a un búfer en el que se va a devolver el código de error nativo, específico del origen de datos. Esta información se incluye en el campo de diagnóstico SQL_DIAG_NATIVE.

MessageText
[Salida] Puntero a un búfer en el que se va a devolver la cadena de texto del mensaje de diagnóstico. Esta información se incluye en el campo de diagnóstico de SQL_DIAG_MESSAGE_TEXT. Para obtener el formato de la cadena, consulte Mensajes de diagnóstico.

Si MessageText es NULL, TextLengthPtr seguirá devolviendo el número total de caracteres (excepto el carácter de terminación NULL para los datos de caracteres) disponible para devolver en el búfer al que apunta MessageText.

BufferLength
[Entrada] Longitud del búfer *MessageText en caracteres. No hay ninguna longitud máxima del texto del mensaje de diagnóstico.

TextLengthPtr
[Salida] Puntero a un búfer en el que devolver el número total de caracteres (excepto el número de caracteres necesarios para el carácter de terminación NULL) disponible para devolver en *MessageText. Si el número de caracteres disponibles para devolver es mayor que BufferLength, el texto del mensaje de diagnóstico de *MessageText se trunca en BufferLength menos la longitud de un carácter de terminación NULL.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA o SQL_INVALID_HANDLE.

Diagnóstico

SQLGetDiagRec no publica registros de diagnóstico por sí mismos. Usa los siguientes valores devueltos para notificar el resultado de su propia ejecución:

  • SQL_SUCCESS: la función devolvió correctamente la información de diagnóstico.

  • SQL_SUCCESS_WITH_INFO: el búfer *MessageText era demasiado pequeño para contener el mensaje de diagnóstico solicitado. No se generaron registros de diagnóstico. Para determinar que se produjo un truncamiento, la aplicación debe comparar BufferLength con el número real de bytes disponibles, que se escribe en *TextLengthPtr.

  • SQL_INVALID_HANDLE: el identificador indicado por HandleType y Handle no era un identificador válido.

  • SQL_ERROR: se produjo una de las siguientes acciones:

    • RecNumber fue negativo o 0.

    • BufferLength era menor que cero.

    • Cuando se usa una notificación asincrónica, no se completó la operación asincrónica en el identificador.

  • SQL_NO_DATA: RecNumber era mayor que el número de registros de diagnóstico que existían para el identificador especificado en Handle. La función también devuelve SQL_NO_DATA para cualquier RecNumber positivo si no hay registros de diagnóstico para Handle.

Comentarios

Normalmente, una aplicación llama a SQLGetDiagRec cuando una llamada anterior a una función ODBC ha devuelto SQL_ERROR o SQL_SUCCESS_WITH_INFO. Sin embargo, dado que cualquier función ODBC puede publicar cero o más registros de diagnóstico cada vez que se llama, una aplicación puede llamar a SQLGetDiagRec después de cualquier llamada a función ODBC. Una aplicación puede llamar a SQLGetDiagRec varias veces para devolver algunos o todos los registros de la estructura de datos de diagnóstico. ODBC no impone ningún límite al número de registros de diagnóstico que se pueden almacenar en cualquier momento.

SQLGetDiagRec no se puede usar para devolver campos del encabezado de la estructura de datos de diagnóstico. (El argumento RecNumber debe ser mayor que 0). La aplicación debe llamar a SQLGetDiagField para este propósito.

SQLGetDiagRec recupera solo la información de diagnóstico asociada más recientemente con el identificador especificado en el argumento Handle . Si la aplicación llama a otra función ODBC, excepto SQLGetDiagRec, SQLGetDiagField o SQLError, se pierde cualquier información de diagnóstico de las llamadas anteriores en el mismo identificador.

Una aplicación puede examinar todos los registros de diagnóstico mediante bucles, incrementando RecNumber, siempre y cuando SQLGetDiagRec devuelva SQL_SUCCESS. Las llamadas a SQLGetDiagRec no son destructivas para los campos de encabezado y registro. La aplicación puede llamar de nuevo a SQLGetDiagRec más adelante para recuperar un campo de un registro siempre que no haya ninguna otra función, excepto SQLGetDiagRec, SQLGetDiagField o SQLError, se ha llamado provisionalmente. La aplicación también puede recuperar un recuento del número total de registros de diagnóstico disponibles llamando a SQLGetDiagField para recuperar el valor del campo SQL_DIAG_NUMBER y, a continuación, llamar a SQLGetDiagRec muchas veces.

Para obtener una descripción de los campos de la estructura de datos de diagnóstico, vea SQLGetDiagField. Para obtener más información, vea Uso de SQLGetDiagRec y SQLGetDiagField e Implementación de SQLGetDiagRec y SQLGetDiagField.

Al llamar a una API distinta de la que se ejecuta de forma asincrónica, se generará el error de secuencia de función HY010. Sin embargo, el registro de error no se puede recuperar antes de que se complete la operación asincrónica.

Argumento HandleType

Cada tipo de identificador puede tener información de diagnóstico asociada. El argumento HandleType indica el tipo de identificador del argumento Handle .

Algunos campos de encabezado y registro no se pueden devolver para los identificadores de entorno, conexión, instrucción y descriptor. Esos identificadores para los que un campo no es aplicable se indican en las secciones "Campos de encabezado" y "Campos de registro" de SQLGetDiagField.

Una llamada a SQLGetDiagRec devolverá SQL_INVALID_HANDLE si HandleType es SQL_HANDLE_SENV, lo que indica un identificador de entorno compartido. Sin embargo, si HandleType es SQL_HANDLE_ENV, Handle puede ser un identificador de entorno compartido o no compartido.

Para información acerca de Vea
Obtener un campo de un registro de diagnóstico o un campo del encabezado de diagnóstico Función SQLGetDiagField

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC
Programa de ejemplo de ODBC