Función SQLGetDescField

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

Resumen
SQLGetDescField devuelve el valor o valor actual de un único campo de un registro descriptor.

Sintaxis

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);  

Argumentos

DescriptorHandle
[Entrada] Identificador de descriptor.

RecNumber
[Entrada] Indica el registro descriptor desde el que la aplicación busca información. Los registros descriptores se numeran a partir de 0, y el número de registro 0 es el registro del marcador. Si el argumento FieldIdentifier indica un campo de encabezado, se omite RecNumber . Si RecNumber es menor o igual que SQL_DESC_COUNT pero la fila no contiene datos para una columna o parámetro, una llamada a SQLGetDescField devolverá los valores predeterminados de los campos. (Para obtener más información, vea "Inicialización de campos descriptores" en SQLSetDescField).

FieldIdentifier
[Entrada] Indica el campo del descriptor cuyo valor se va a devolver. Para obtener más información, vea la sección "FieldIdentifier Argument" en SQLSetDescField.

ValuePtr
[Salida] Puntero a un búfer en el que se va a devolver la información del descriptor. El tipo de datos depende del valor de FieldIdentifier.

Si ValuePtr es de 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 los 32 o 16 bits inferiores de un búfer y dejar el bit de orden superior sin cambios.

Si ValuePtr 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 ValuePtr.

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

Si FieldIdentifier 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 *ValuePtr es un puntero a una cadena de caracteres, BufferLength es la longitud de la cadena o SQL_NTS.

• Si *ValuePtr 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 *ValuePtr 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 *ValuePtr contiene un tipo de datos de longitud fija, BufferLength es SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT o SQL_IS_USMALLINT, según corresponda.

StringLengthPtr
[Salida] Puntero al búfer en el que se devuelve 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 *ValuePtr.

Devoluciones

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA o SQL_INVALID_HANDLE.

SQL_NO_DATA se devuelve si RecNumber es mayor que el número actual de registros descriptores.

SQL_NO_DATA se devuelve si DescriptorHandle es un identificador IRD y la instrucción está en estado preparado o ejecutado, pero no había ningún cursor abierto asociado.

Diagnóstico

Cuando SQLGetDescField devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado llamando a SQLGetDiagRec con un HandleType de SQL_HANDLE_STMT y un identificador de StatementHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLGetDescField y se explica cada uno en el contexto de esta función; la notación "(DM)" precede a las descripciones de SQLSTATEs devueltas por el Administrador de controladores. El código de retorno asociado a cada valor SQLSTATE es SQL_ERROR, a menos que se indique lo contrario.

SQLSTATE	Error	Descripción
01000	Advertencia general	Mensaje informativo específico del controlador. (Function devuelve SQL_SUCCESS_WITH_INFO).
01004	Datos de cadena, truncados a la derecha	El búfer *ValuePtr no era lo suficientemente grande como para devolver todo el campo descriptor, por lo que el campo se truncó. La longitud del campo descriptor notruncado se devuelve en *StringLengthPtr. (Function devuelve SQL_SUCCESS_WITH_INFO).
07009	Índice de descriptor no válido	(DM) El argumento RecNumber era igual a 0, el atributo de instrucción SQL_ATTR_USE_BOOKMARK estaba SQL_UB_OFF y el argumento DescriptorHandle era un identificador IRD. (Este error se puede devolver para un descriptor asignado explícitamente solo si el descriptor está asociado a un identificador de instrucción). El argumento FieldIdentifier era un campo de registro, el argumento RecNumber era 0 y el argumento DescriptorHandle era un identificador IPD. El argumento RecNumber era menor que 0.
08S01	Error de vínculo de comunicación	Se produjo un error en el vínculo de comunicación entre el controlador y el origen de datos al que se conectó el controlador antes de que la función completara el procesamiento.
HY000	Error general	Se produjo un error para el que no había ningún SQLSTATE específico y para el que no se definió SQLSTATE específico de la implementación. El mensaje de error devuelto por SQLGetDiagRec en el búfer *MessageText describe el error y su causa.
HY001	Error de asignación de memoria	El controlador no pudo asignar la memoria necesaria para admitir la ejecución o finalización de la función.
HY007	La instrucción asociada no está preparada	DescriptorHandle estaba asociado a un StatementHandle como IRD y el identificador de instrucción asociado no se había preparado ni ejecutado.
HY010	Error de secuencia de función	(DM) DescriptorHandle estaba asociado a un StatementHandle para el que se llamó a una función de ejecución asincrónica (no a esta) y todavía se estaba ejecutando cuando se llamó a esta función. (DM) DescriptorHandle se asoció con un StatementHandle para el que se llamó a SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos y devolvió SQL_NEED_DATA. Se llamó a esta función antes de enviar datos para todos los parámetros o columnas de datos en ejecución. (DM) Se ha llamado a una función de ejecución asincrónica para el identificador de conexión asociado a DescriptorHandle. Esta función asincrónica todavía se estaba ejecutando cuando se llamó a la función SQLGetDescField .
HY013	Error de administración de memoria	No se pudo procesar la llamada de función porque no se pudo tener acceso a los objetos de memoria subyacentes, posiblemente debido a condiciones de memoria baja.
HY021	Información de descriptor incoherente	Los campos SQL_DESC_TYPE y SQL_DESC_DATETIME_INTERVAL_CODE no forman un tipo SQL ODBC válido, un tipo SQL específico del controlador válido (para IPD) o un tipo de C ODBC válido (para APD o ARD).
HY090	Longitud de búfer o cadena no válida	(DM) *ValuePtr era una cadena de caracteres y BufferLength era menor que cero.
HY091	Identificador de campo de descriptor no válido	FieldIdentifier no era un campo definido por ODBC y no era un valor definido por la implementación. FieldIdentifier no estaba definido para DescriptorHandle.
HY117	La conexión se suspende debido al estado de transacción desconocido. Solo se permiten funciones de desconexión y de solo lectura.	(DM) Para obtener más información sobre el estado suspendido, vea Función SQLEndTran.
HYT01	Se ha agotado el tiempo de espera de la conexión.	El período de tiempo de espera de conexión expiró antes de que el origen de datos responda a la solicitud. El período de tiempo de espera de conexión se establece a través de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	El controlador no admite esta función	(DM) El controlador asociado a DescriptorHandle no admite la función .

Comentarios

Una aplicación puede llamar a SQLGetDescField para devolver el valor de un único campo de un registro descriptor. Una llamada a SQLGetDescField puede devolver la configuración de cualquier campo de cualquier tipo descriptor, incluidos los campos de encabezado, los campos de registro y los campos de marcador. Una aplicación puede obtener la configuración de varios campos en los mismos descriptores o diferentes, en orden arbitrario, realizando llamadas repetidas a SQLGetDescField. También se puede llamar a SQLGetDescField para devolver campos descriptores definidos por el controlador.

Por motivos de rendimiento, una aplicación no debe llamar a SQLGetDescField para un IRD antes de ejecutar una instrucción .

La configuración de varios campos que describen el nombre, el tipo de datos y el almacenamiento de datos de columnas o parámetros también se pueden recuperar en una sola llamada a SQLGetDescRec. Se puede llamar a SQLGetStmtAttr para devolver el valor de un único campo en el encabezado descriptor que también es un atributo de instrucción. SQLColAttribute, SQLDescribeCol y SQLDescribeParam devuelven campos de registro o marcador.

Cuando una aplicación llama a SQLGetDescField para recuperar el valor de un campo que no está definido para un tipo de descriptor determinado, la función devuelve SQL_SUCCESS pero el valor devuelto para el campo no está definido. Por ejemplo, al llamar a SQLGetDescField para el campo SQL_DESC_NAME o SQL_DESC_NULLABLE de un APD o ARD, se devolverán SQL_SUCCESS pero un valor no definido para el campo.

Cuando una aplicación llama a SQLGetDescField para recuperar el valor de un campo definido para un tipo de descriptor determinado, pero que no tiene ningún valor predeterminado y aún no se ha establecido, la función devuelve SQL_SUCCESS pero el valor devuelto para el campo no está definido. Para obtener más información sobre la inicialización de campos descriptores y descripciones de los campos, vea "Inicialización de campos descriptores" en SQLSetDescField. Para obtener más información sobre los descriptores, vea Descriptores.

Funciones relacionadas

Para información acerca de	Vea
Obtención de varios campos descriptores	Función SQLGetDescRec
Establecimiento de un único campo descriptor	Función SQLSetDescField
Establecimiento de varios campos descriptores	Función SQLSetDescRec

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC