Función SQLGetDiagField

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

Resumen
SQLGetDiagField devuelve el valor actual de un campo de un registro de la estructura de datos de diagnóstico (asociada a un identificador especificado) que contiene información de error, advertencia y estado.

Sintaxis

SQLRETURN SQLGetDiagField(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     DiagIdentifier,  
     SQLPOINTER      DiagInfoPtr,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLengthPtr);  

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. Si el argumento DiagIdentifier indica cualquier campo del encabezado de diagnóstico, se omite RecNumber . Si no es así, debe ser superior a 0.

DiagIdentifier
[Entrada] Indica el campo del diagnóstico cuyo valor se va a devolver. Para obtener más información, vea la sección "Argumento DiagIdentifier " en "Comments".

DiagInfoPtr
[Salida] Puntero a un búfer en el que se va a devolver la información de diagnóstico. El tipo de datos depende del valor de DiagIdentifier. Si DiagInfoPtr es un tipo entero, las aplicaciones deben usar un búfer de SQLULEN e inicializar el valor en 0 antes de llamar a esta función, ya que algunos controladores solo pueden escribir el 32 o 16 bits inferior de un búfer y dejar el bit de orden superior sin cambios.

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

BufferLength
[Entrada] Si DiagIdentifier es un diagnóstico definido por ODBC y DiagInfoPtr apunta a una cadena de caracteres o a un búfer binario, este argumento debe ser la longitud de *DiagInfoPtr. Si DiagIdentifier es un campo definido por ODBC y *DiagInfoPtr es un entero, bufferLength se omite. Si el valor de *DiagInfoPtr es una cadena Unicode (al llamar a SQLGetDiagFieldW), el argumento BufferLength debe ser un número par.

Si DiagIdentifier es un campo definido por el controlador, la aplicación indica la naturaleza del campo en el Administrador de controladores estableciendo el argumento BufferLength . BufferLength puede tener los siguientes valores:

• Si DiagInfoPtr es un puntero a una cadena de caracteres, BufferLength es la longitud de la cadena o SQL_NTS.

• Si DiagInfoPtr es un puntero a un búfer binario, la aplicación coloca el resultado de la macro SQL_LEN_BINARY_ATTR(length) en BufferLength. Esto coloca un valor negativo en BufferLength.

• Si DiagInfoPtr es un puntero a un valor distinto de una cadena de caracteres o una cadena binaria, BufferLength debe tener el valor SQL_IS_POINTER.

• Si *DiagInfoPtr contiene un tipo de datos de longitud fija, BufferLength se SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT o SQL_IS_USMALLINT, según corresponda.

StringLengthPtr
[Salida] Puntero a un búfer en el que devolver el número total de bytes (excepto el número de bytes necesarios para el carácter de terminación NULL) disponible para devolver en *DiagInfoPtr, para los datos de caracteres. Si el número de bytes disponibles para devolver es mayor o igual que BufferLength, el texto de *DiagInfoPtr 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_INVALID_HANDLE o SQL_NO_DATA.

Diagnóstico

SQLGetDiagField 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: *DiagInfoPtr era demasiado pequeño para contener el campo de diagnóstico solicitado. Por lo tanto, los datos del campo de diagnóstico se truncaron. Para determinar que se ha producido un truncamiento, la aplicación debe comparar BufferLength con el número real de bytes disponibles, que se escribe en *StringLengthPtr.

• 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:

  • El argumento DiagIdentifier no era uno de los valores válidos.

  • El argumento DiagIdentifier se SQL_DIAG_CURSOR_ROW_COUNT, SQL_DIAG_DYNAMIC_FUNCTION, SQL_DIAG_DYNAMIC_FUNCTION_CODE o SQL_DIAG_ROW_COUNT, pero Handle no era un identificador de instrucción. (El Administrador de controladores devuelve este diagnóstico).

  • El argumento RecNumber fue negativo o 0 cuando DiagIdentifier indicó un campo de un registro de diagnóstico. RecNumber se omite para los campos de encabezado.

  • El valor solicitado era una cadena de caracteres y 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 SQLGetDiagField para lograr uno de los tres objetivos:

1. Para obtener información específica sobre errores o advertencias cuando una llamada de función ha devuelto SQL_ERROR o SQL_SUCCESS_WITH_INFO (o SQL_NEED_DATA para la función SQLBrowseConnect ).

2. Para determinar el número de filas del origen de datos que se vieron afectadas cuando se realizaron operaciones de inserción, eliminación o actualización con una llamada a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos (desde el campo de encabezado SQL_DIAG_ROW_COUNT) o para determinar el número de filas que existen en el cursor abierto actual, si el controlador puede proporcionar esta información (desde el campo de encabezado SQL_DIAG_CURSOR_ROW_COUNT).

3. Para determinar qué función se ejecutó mediante una llamada a SQLExecDirect o SQLExecute (de los campos de encabezado SQL_DIAG_DYNAMIC_FUNCTION y SQL_DIAG_DYNAMIC_FUNCTION_CODE).

Cualquier función ODBC puede publicar cero o más registros de diagnóstico cada vez que se llama, por lo que una aplicación puede llamar a SQLGetDiagField después de cualquier llamada a función ODBC. No hay ningún límite en el número de registros de diagnóstico que se pueden almacenar en cualquier momento. SQLGetDiagField recupera solo la información de diagnóstico asociada más recientemente a la estructura de datos de diagnóstico especificada en el argumento Handle . Si la aplicación llama a una función ODBC distinta de SQLGetDiagField o SQLGetDiagRec, se pierde cualquier información de diagnóstico de una llamada anterior con el mismo identificador.

Una aplicación puede examinar todos los registros de diagnóstico incrementando RecNumber, siempre y cuando SQLGetDiagField devuelva SQL_SUCCESS. El número de registros de estado se indica en el campo de encabezado SQL_DIAG_NUMBER. Las llamadas a SQLGetDiagField no son destructivas para los campos de encabezado y registro. La aplicación puede llamar a SQLGetDiagField de nuevo más tarde para recuperar un campo de un registro, siempre y cuando no se haya llamado a una función distinta de las funciones de diagnóstico en el período intermedio, lo que publicaría registros en el mismo identificador.

Una aplicación puede llamar a SQLGetDiagField para devolver cualquier campo de diagnóstico en cualquier momento, excepto por SQL_DIAG_CURSOR_ROW_COUNT o SQL_DIAG_ROW_COUNT, que devolverá SQL_ERROR si Handle no es un identificador de instrucción. Si cualquier otro campo de diagnóstico no está definido, la llamada a SQLGetDiagField devolverá SQL_SUCCESS (siempre que no se encuentre ningún otro diagnóstico) y se devuelve un valor indefinido para el campo.

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 de Handle.

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

Si HandleType es SQL_HANDLE_ENV, Handle puede ser un identificador de entorno compartido o no compartido.

Ningún campo de diagnóstico de encabezado específico del controlador debe estar asociado a un identificador de entorno.

Los únicos campos de encabezado de diagnóstico definidos para un identificador de descriptor son SQL_DIAG_NUMBER y SQL_DIAG_RETURNCODE.

Argumento DiagIdentifier

Este argumento indica el identificador del campo necesario a partir de la estructura de datos de diagnóstico. Si RecNumber es mayor o igual que 1, los datos del campo describen la información de diagnóstico devuelta por una función. Si RecNumber es 0, el campo se encuentra en el encabezado de la estructura de datos de diagnóstico y, por tanto, contiene datos relativos a la llamada de función que devolvió la información de diagnóstico, no a la información específica.

Los controladores pueden definir campos de registro y encabezado específicos del controlador en la estructura de datos de diagnóstico.

Una aplicación ODBC 3*.x* que trabaje con un controlador ODBC 2*.x* podrá llamar a SQLGetDiagField solo con un argumento DiagIdentifier de SQL_DIAG_CLASS_ORIGIN, SQL_DIAG_CLASS_SUBCLASS_ORIGIN, SQL_DIAG_CONNECTION_NAME, SQL_DIAG_MESSAGE_TEXT, SQL_DIAG_NATIVE, SQL_DIAG_NUMBER, SQL_DIAG_RETURNCODE, SQL_DIAG_SERVER_NAME o SQL_DIAG_SQLSTATE. Todos los demás campos de diagnóstico devolverán SQL_ERROR.

Campos de encabezado

Los campos de encabezado enumerados en la tabla siguiente se pueden incluir en el argumento DiagIdentifier .

Campos de registro

Los campos de registro enumerados en la tabla siguiente se pueden incluir en el argumento DiagIdentifier .

Valores de los campos de función dinámica

En la tabla siguiente se describen los valores de SQL_DIAG_DYNAMIC_FUNCTION y SQL_DIAG_DYNAMIC_FUNCTION_CODE que se aplican a cada tipo de instrucción SQL ejecutada por una llamada a SQLExecute o SQLExecDirect. El controlador puede agregar valores definidos por el controlador a los enumerados.

Secuencia de registros de estado

Los registros de estado se colocan en una secuencia basada en el número de fila y el tipo del diagnóstico. El Administrador de controladores determina el orden final en el que se devuelven los registros de estado que genera. El controlador determina el orden final en el que se devuelven los registros de estado que genera.

Si tanto el Administrador de controladores como el controlador publican registros de diagnóstico, el Administrador de controladores es responsable de ordenarlos.

Si hay dos o más registros de estado, la secuencia de los registros se determina primero por número de fila. Las reglas siguientes se aplican para determinar la secuencia de registros de diagnóstico por fila:

• Los registros que no corresponden a ninguna fila aparecen delante de los registros que corresponden a una fila determinada, ya que SQL_NO_ROW_NUMBER se define como -1.

• Los registros para los que se desconoce el número de fila aparecen delante de todos los demás registros, ya que SQL_ROW_NUMBER_UNKNOWN se define como -2.

• Para todos los registros que pertenecen a filas específicas, los registros se ordenan por el valor del campo SQL_DIAG_ROW_NUMBER. Se muestran todos los errores y advertencias de la primera fila afectada y, a continuación, se muestran todos los errores y advertencias de la siguiente fila afectada, etc.

Dentro de cada fila, o para todos los registros que no corresponden a una fila o para la que se desconoce el número de fila, o para todos esos registros con un número de fila igual a SQL_NO_ROW_NUMBER, el primer registro enumerado se determina mediante un conjunto de reglas de ordenación. Después del primer registro, el orden de los demás registros que afectan a una fila no está definido. Una aplicación no puede suponer que los errores preceden a las advertencias después del primer registro. Las aplicaciones deben examinar la estructura de datos de diagnóstico completa para obtener información completa sobre una llamada incorrecta a una función.

Las reglas siguientes se usan para determinar el primer registro dentro de una fila. El registro con el rango más alto es el primer registro. El origen de un registro (Administrador de controladores, controlador, puerta de enlace, etc.) no se tiene en cuenta cuando se clasifican los registros.

• Errores Los registros de estado que describen los errores tienen la clasificación más alta. Las reglas siguientes se aplican a errores de ordenación:

  • Los registros que indican un error de transacción o un posible error de transacción han salido de todos los demás registros.

  • Si dos o más registros describen la misma condición de error, los SQLSTATEs definidos por la especificación de la CLI de Open Group (clases de 03 a HZ) e SQLSTATEs definidos por el controlador.

• Valores de datos no definidos por la implementación Los registros de estado que describen los valores sin datos definidos por el controlador (clase 02) tienen la segunda clasificación más alta.

• Advertencias Los registros de estado que describen advertencias (clase 01) tienen la clasificación más baja. Si dos o más registros describen la misma condición de advertencia, las SQLSTATEs de advertencia definidas por la especificación de la CLI de Open Group desactiven las SQLSTATEs definidas por ODBC y definidas por el controlador.

Funciones relacionadas

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC