Función SQLGetDescRec

  • Artículo

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

Resumen
SQLGetDescRec devuelve la configuración actual o los valores de varios campos de un registro descriptor. Los campos devueltos describen el nombre, el tipo de datos y el almacenamiento de datos de columnas o parámetros.

Sintaxis

  
SQLRETURN SQLGetDescRec(  
      SQLHDESC        DescriptorHandle,  
      SQLSMALLINT     RecNumber,  
      SQLCHAR *       Name,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLSMALLINT *   TypePtr,  
      SQLSMALLINT *   SubTypePtr,  
      SQLLEN *        LengthPtr,  
      SQLSMALLINT *   PrecisionPtr,  
      SQLSMALLINT *   ScalePtr,  
      SQLSMALLINT *   NullablePtr);

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 1, y el número de registro 0 es el registro del marcador. El argumento RecNumber debe ser menor o igual que el valor de SQL_DESC_COUNT. 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 SQLGetDescRec devolverá los valores predeterminados de los campos. (Para obtener más información, vea "Inicialización de campos descriptores" en SQLSetDescField).

Nombre
[Salida] Puntero a un búfer en el que se va a devolver el campo SQL_DESC_NAME para el registro descriptor.

Si Name es NULL, StringLengthPtr 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 Name.

BufferLength
[Entrada] Longitud del búfer *Name , en caracteres.

StringLengthPtr
[Salida] Puntero a un búfer en el que se va a devolver el número de caracteres de datos disponibles para devolver en el búfer *Name , excepto el carácter de terminación NULL. Si el número de caracteres era mayor o igual que BufferLength, los datos de *Name se truncan a BufferLength menos la longitud de un carácter de terminación null y el controlador termina en null.

TypePtr
[Salida] Puntero a un búfer en el que se va a devolver el valor del campo SQL_DESC_TYPE para el registro descriptor.

SubTypePtr
[Salida] Para los registros cuyo tipo es SQL_DATETIME o SQL_INTERVAL, se trata de un puntero a un búfer en el que se devuelve el valor del campo SQL_DESC_DATETIME_INTERVAL_CODE.

LengthPtr
[Salida] Puntero a un búfer en el que se va a devolver el valor del campo SQL_DESC_OCTET_LENGTH para el registro descriptor.

PrecisionPtr
[Salida] Puntero a un búfer en el que se va a devolver el valor del campo SQL_DESC_PRECISION para el registro descriptor.

ScalePtr
[Salida] Puntero a un búfer en el que se va a devolver el valor del campo SQL_DESC_SCALE para el registro descriptor.

NullablePtr
[Salida] Puntero a un búfer en el que se va a devolver el valor del campo SQL_DESC_NULLABLE para el registro descriptor.

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 SQLGetDescRec devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener un valor SQLSTATE asociado mediante una llamada a SQLGetDiagRec con un HandleType de SQL_HANDLE_DESC y un identificador de DescriptorHandle. En la tabla siguiente se enumeran los valores SQLSTATE devueltos normalmente por SQLGetDescRec 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 *Name no era lo suficientemente grande como para devolver el campo descriptor completo. Por lo tanto, el campo se ha truncado. La longitud del campo descriptor notruncado se devuelve en *StringLengthPtr. (Function devuelve SQL_SUCCESS_WITH_INFO).
07009 Índice de descriptor no válido El argumento FieldIdentifier era un campo de registro, el argumento RecNumber se estableció en 0 y el argumento DescriptorHandle era un identificador IPD.

(DM) El argumento RecNumber se estableció en 0 y el atributo de instrucción SQL_ATTR_USE_BOOKMARKS se estableció en SQL_UB_OFF, y el argumento DescriptorHandle era un identificador IRD.

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 IRD y el identificador de instrucción asociado no estaba en el estado preparado o 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 SQLGetDescRec .
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.
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 SQLGetDescRec para recuperar los valores de los siguientes campos descriptores para una sola columna o parámetro:

  • SQL_DESC_NAME

  • SQL_DESC_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE (para los registros cuyo tipo es SQL_DATETIME o SQL_INTERVAL)

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PRECISION

  • SQL_DESC_SCALE

  • SQL_DESC_NULLABLE

SQLGetDescRec no recupera los valores de los campos de encabezado.

Una aplicación puede impedir la devolución de la configuración de un campo estableciendo el argumento que corresponde al campo en un puntero nulo.

Cuando una aplicación llama a SQLGetDescRec 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, llamar a SQLGetDescRec para el campo SQL_DESC_NAME o SQL_DESC_NULLABLE de un APD o ARD devolverá SQL_SUCCESS pero un valor no definido para el campo.

Cuando una aplicación llama a SQLGetDescRec 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, vea "Inicialización de campos de descriptor" en SQLSetDescField.

Los valores de los campos también se pueden recuperar individualmente mediante una llamada a SQLGetDescField. Para obtener una descripción de los campos de un encabezado o registro de descriptor, vea SQLSetDescField. Para obtener más información sobre los descriptores, vea Descriptores.

Para información acerca de Vea
Enlace de una columna SQLBindCol (función)
Enlace de un parámetro Función SQLBindParameter
Obtención de un campo descriptor Función SQLGetDescField
Establecimiento de varios campos descriptores Función SQLSetDescRec

Consulte también

Referencia de API ODBC
Archivos de encabezado de ODBC