SQLDescribeCol--Devolver un conjunto de atributos de una columna

Finalidad

Especificación: CLI de DB2 1.1 ODBC 1.0 ISO CLI

SQLDescribeCol() devuelve un conjunto de información descriptiva de uso habitual (nombre, tipo, precisión, escala, posibilidad de contener nulos) referente a la columna indicada del conjunto resultante generado por una consulta.

Se debe invocar SQLPrepare() o SQLExecDirect() antes de invocar esta función.

Generalmente esta función se invoca antes de una función de enlace de columna (SQLBindCol()) para determinar los atributos de una columna antes de enlazarla a una variable de aplicación.

Sintaxis 

SQLRETURN   SQLDescribeCol   (
                SQLHSTMT          StatementHandle,  /* hstmt */
                SQLUSMALLINT      ColumnNumber,      /* icol */
                SQLCHAR      *FAR ColumnName,        /* szColName */
                SQLSMALLINT       BufferLength,      /* cbColNameMax */
                SQLSMALLINT  *FAR NameLengthPtr,     /* pcbColName */
                SQLSMALLINT  *FAR DataTypePtr,       /* pfSqlType */
                SQLUINTEGER  *FAR ColumnSizePtr,     /* pcbColDef */
                SQLSMALLINT  *FAR DecimalDigitsPtr,  /* pibScale */
                SQLSMALLINT  *FAR NullablePtr);      /* pfNullable */

Argumentos de la función

Tabla 38. Argumentos de SQLDescribeCol

Tipo de datos Argumento Uso Descripción
SQLHSTMT StatementHandle entrada Descriptor de contexto de sentencia.
SQLUSMALLINT ColumnNumber entrada Número de la columna que se debe describir. Las columnas están numeradas secuencialmente, de izquierda a derecha, comenzando en 1.
SQLCHAR * ColumnName salida Puntero que apunta a un almacenamiento intermedio de nombres de columna. Este puntero se establece en NULL si no se puede determinar el nombre de la columna.
SQLSMALLINT BufferLength entrada Tamaño del almacenamiento intermedio de ColumnName.
SQLSMALLINT * NameLengthPtr salida Bytes disponibles para devolver para el argumento ColumnName. El nombre de columna (ColumnName) se trunca a BufferLength - 1 bytes si NameLengthPtr es mayor o igual que BufferLength.
SQLSMALLINT * DataTypePtr salida Tipo básico de datos SQL de la columna.
SQLUINTEGER * ColumnSizePtr salida Precisión de la columna tal como está definida en la base de datos.
SQLSMALLINT * DecimalDigitsPtr salida Escala de la columna tal como está definida en la base de datos (sólo es aplicable a SQL_DECIMAL).
SQLSMALLINT * NullablePtr salida Indica si la columna puede contener nulos. Cualquiera:

SQL_NO_NULLS

SQL_NULLABLE

Uso

Las columnas se identifican mediante un número, que se asigna secuencialmente de izquierda a derecha, y se pueden describir en cualquier orden. Los números de columna comienzan en el 1.

Si se especifica un puntero nulo para cualquiera de los argumentos de puntero, CLI de DB2 considera que la información no es necesaria para la aplicación y no se devuelve nada.

Códigos de retorno

Diagnósticos

Si SQLDescribeCol() devuelve SQL_ERROR o SQL_SUCCESS_WITH_INFO, se puede obtener uno de los SQLSTATE siguientes al invocar la función SQLError().

Tabla 39. SQLSTATE de SQLDescribeCol

SQLSTATE Descripción Explicación
01004 Datos truncados. El nombre de columna devuelto en el argumento ColumnName es más largo que el valor especificado en el argumento BufferLength. El argumento NameLengthPtr contiene la longitud del nombre de columna completo. (La función devuelve SQL_SUCCESS_WITH_INFO.)
07005 La sentencia no devolvió un conjunto resultante. La sentencia asociada al descriptor de sentencia (StatementHandle) no devolvió un conjunto resultante. No había ninguna columna para describir. (Invoque primero SQLNumResultCols() para determinar si hay alguna fila en el conjunto resultante.)
07009 Índice descriptor no válido. El valor especificado para ColumnNumber es menor o igual que 0. El valor especificado para el argumento ColumnNumber es mayor que el número de columnas del conjunto resultante.
40003 08S01 Error en el enlace de comunicaciones. El enlace de comunicaciones entre la aplicación y la fuente de datos se interrumpió antes de finalizar la función.
58004 Error inesperado del sistema. Error no recuperable del sistema.
HY001 Error de asignación de memoria. CLI de DB2 no puede asignar la memoria necesaria para ejecutar o finalizar la función.
HY002 Número de columna no válido. El valor especificado para el argumento ColumnNumber es menor que 1 o el valor especificado para el argumento ColumnNumber es mayor que el número de columnas del conjunto resultante.
HY090 Longitud no válida de la serie de caracteres o del almacenamiento intermedio. La longitud especificada en el argumento BufferLength es menor que 1.
HY010 Error de secuencia de función. Se llama a la función antes de llamar a SQLPrepare() o SQLExecDirect() para el descriptor de sentencia (StatementHandle).
HY013 Error inesperado de gestión de la memoria. CLI de DB2 no puede acceder a la memoria necesaria para ejecutar o finalizar la función.
HYC00 Controlador no apropiado. CLI de DB2 no reconoce el tipo de datos SQL de la columna ColumnNumber.

Restricciones

DB2 Everyplace sólo da soporte a los siguientes tipos de datos definidos por ODBC:

Consulta relacionada