SQLGetDiagRec--Obtener varios valores de campos del registro de diagnósticos

Finalidad


Especificación: CLI de DB2 5.0 ODBC 3.0

SQLGetDiagRec() devuelve el valor actual del campo SQLSTATE de un registro de diagnóstico que contiene información sobre errores, avisos y estados.

Antes de invocar esta función se debe asignar un descriptor de conexión utilizando SQLAllocHandle().

Sintaxis 

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

Argumentos de la función


Tabla 68. Argumentos de SQLGetDiagRec

Tipo de datos Argumento Uso Descripción
SQLSMALLINT HandleType entrada Identificador del tipo de descriptor de contexto que describe el tipo de descriptor de contexto para el cual se desea información de diagnóstico. Puede ser SQL_HANDLE_STMT o SQL_HANDLE_DBC.
SQLHANDLE Handle entrada Descriptor de contexto correspondiente a la estructura de datos de diagnóstico; su tipo está indicado por HandleType.
SQLSMALLINT RecNumber entrada Indica el registro de estado en el que la aplicación busca información. Su valor debe ser 1.
SQLCHAR SQLState salida Puntero que apunta a un almacenamiento intermedio en el que devolver un código SQLSTATE, de cinco caracteres, perteneciente al registro de diagnóstico RecNumber. Los primeros dos caracteres indican la clase; los tres siguientes indican la subclase.
SQLINTEGER NativeErrorPtr salida Puntero que apunta a un almacenamiento intermedio en el que devolver el código de error nativo, que es específico de la fuente de datos.
SQLCHAR MessageText salida Puntero que apunta a un almacenamiento intermedio en el que devolver el texto del mensaje de error. Los campos devueltos por SQLGetDiagRec() están contenidos en una serie de texto.
SQLINTEGER BufferLength entrada Longitud (en bytes) del almacenamiento intermedio MessageText.
SQLSMALLINT TextLengthPtr salida Puntero que apunta a un almacenamiento intermedio que contendrá el número total de bytes (excepto los bytes necesarios para el carácter de terminación en nulo) para devolver en MessageText. Si el número de bytes para devolver es mayor que BufferLength, el texto del mensaje de error contenido en MessageText se trunca hasta que su longitud sea BufferLength menos la longitud del carácter de terminación en nulo.

Uso

Habitualmente una aplicación invoca SQLGetDiagRec() cuando una llamada anterior a una función de CLI de DB2 devuelve un código de retorno distinto de SQL_SUCCESS.

SQLGetDiagRec() devuelve una serie de caracteres que contiene varios campos del registro de la estructura de datos de diagnóstico.

El funcionamiento de SQLGetDiagRec() se ha ampliado en la Versión 8.1 de DB2 Everyplace. Ahora se pueden devolver los SQLSTATE siguientes: 57011, HY024, HY092, HY000, HY012. Para obtener más información sobre estos SQLSTATE, consulte el Listado de los SQLSTATE.

SQLGetDiagRec() recupera sólo la información de diagnóstico más reciente asociada al descriptor de contexto especificado en el argumento Handle. Si la aplicación invoca otra función, excepto SQLGetDiagRec(), se pierde la información de diagnóstico obtenida en llamadas anteriores para el mismo descriptor de contexto.

Argumento HandleType

Cada tipo de descriptor de contexto tiene información de diagnóstico asociada a él. El argumento HandleType indica el tipo del descriptor de contexto especificado en Handle. DB2 Everyplace soporta descriptores de contexto de sentencia y de conexión.

Códigos de retorno

Diagnósticos

SQLGetDiagRec() no notifica valores de error por sí mismo. Utiliza los valores de retorno siguientes para notificar el resultado de su propia ejecución:

SQL_SUCCESS
La función devolvió satisfactoriamente información de diagnóstico.

SQL_SUCCESS_WITH_INFO
El almacenamiento intermedio MessageText es demasiado pequeño para contener el mensaje de diagnóstico solicitado. No se genera ningún registro de diagnóstico. Para determinar que se ha producido un truncamiento, la aplicación debe comparar BufferLength con el número real de bytes disponibles, que está escrito en StringLengthPtr.

SQL_INVALID_HANDLE
El descriptor de contexto indicado por HandleType y Handle no es un descriptor de contexto válido.

SQL_ERROR
Se ha producido una de las situaciones siguientes:

SQL_NO_DATA
RecNumber es mayor que el número de registros de diagnóstico que existían para el descriptor de contexto especificado en Handle. La función también devuelve SQL_NO_DATA para cualquier valor positivo de RecNumber si no hay ningún registro de diagnóstico para Handle.

Restricciones

Ninguna.

Consulta relacionada