SQLColumns - Obtener información de columna para una tabla

Finalidad

SQLColumns() devuelve una lista de columnas en las tablas especificadas. La información se devuelve en un conjunto de resultados de SQL, que se puede recuperar utilizando las mismas funciones que se utilizan para buscar un conjunto de resultados generado por una consulta.

Sintaxis

SQLRETURN  SQLColumns       (
               SQLHSTMT          StatementHandle,   /* hstmt */
               SQLCHAR      FAR  *CatalogName,      /* szCatalogName */
               SQLSMALLINT       NameLength1,       /* cbCatalogName */
               SQLCHAR      FAR  *SchemaName,       /* szSchemaName */
               SQLSMALLINT       NameLength2,       /* cbSchemaName */
               SQLCHAR      FAR  *TableName,        /* szTableName */
               SQLSMALLINT       NameLength3,       /* cbTableName */
               SQLCHAR      FAR  *ColumnName,       /* szColumnName */
               SQLSMALLINT       NameLength4);      /* cbColumnName */

Argumentos de la función

Tabla 92. Argumentos de SQLColumns

Uso

Esta función se llama para recuperar información sobre las columnas de una tabla o de un conjunto de tablas. Es posible que una aplicación habitual desee llamar a esta función después de una llamada a SQLTables() para determinar las columnas de una tabla. La aplicación debería utilizar las series de caracteres devueltas en la TABLE_NAME del conjunto de resultados de SQLTables() como entrada para esta función.

SQLColumns() devuelve un conjunto de resultados estándar, ordenado mediante TABLE_NAME y ORDINAL_POSITION. *** lista las columnas en el conjunto de resultados.

Los argumentos TableName y ColumnName aceptan patrones de búsqueda.

Esta función no devuelve información sobre las columnas de un conjunto de resultados.En su lugar debería utilizarse SQLDescribeCol() o SQLColAttribute().

Las llamadas a SQLColumns() deben utilizarse con moderación, ya que en muchos casos se asignan a una consulta compleja y por tanto cara en el catálogo del sistema. Los resultados deben guardarse en vez de repetir las llamadas.

Las columnas VARCHAR del conjunto resultante de las funciones de catálogo se han declarado con un atributo de longitud máxima 128 para que sea coherente los límites de SQL92. Dado que los nombres de DB2 son inferiores a 128, la aplicación puede optar por poner siempre a un lado 128 caracteres (más el terminador nulo) para el almacenamiento intermedio de salida o, alternativamente llamar a SQLGetInfo() con SQL_MAX_TABLE_NAME_LEN y SQL_MAX_COLUMN_NAME_LEN para determinar respectivamente las longitudes reales de las columnas TABLE_NAME y COLUMN_NAME a las que da soporte el DBMS conectado.

Aunque en futuros releases se pueden añadir nuevas columnas y modificarse los nombres de las columnas existentes, la posición de las columnas actuales no cambiará.

Columnas devueltas por SQLColumns

Columna 1 TABLE_CAT (VARCHAR(128))

Siempre es nula (NULL).

Columna 2 TABLE_SCHEM (VARCHAR(128))

Siempre es nula (NULL).

Columna 3 TABLE_NAME (VARCHAR(128) no nulo)

Nombre de la tabla.

Columna 4 COLUMN_NAME (VARCHAR(128) no nulo)

Identificador de columna. Nombre de la columna de la tabla especificada, vista, alias o sinónimo.

Columna 5 DATA_TYPE (SMALLINT no NULL)

Tipo de datos SQL de la columna que se identifica por medio de COLUMN_NAME. Este es uno de los valores de la columna Tipo de datos de SQL simbólico de la sección Tipos de datos por omisión y simbólicos de SQL.

Columna 6 TYPE_NAME (VARCHAR(128) no NULL)

Serie de caracteres que representa el nombre del tipo de datos que corresponde a DATA_TYPE.

Columna 7 COLUMN_SIZE (INTEGER)

Si el valor de la columna DATA_TYPE denota un carácter o serie binaria, esta columna contendrá la longitud máxima de caracteres para la columna.

Para los tipos de datos DATE, TIME o TIMESTAMP, es el número total de caracteres necesarios para visualizar el valor cuando se convierte en carácter.

Para los tipos de datos numéricos, es el número total de dígitos que se permite en la columna.

Consulte también, Atributos de tipos de datos.

Columna 8 BUFFER_LENGTH (INTEGER)

El número máximo de bytes para que el almacenamiento intermedio C asociado almacene datos de esta columna en el caso de que SQL_C_DEFAULT se haya especificado en las llamadas SQLBindCol(), SQLGetData() y SQLBindParameter(). Esta longitud no incluye ningún terminador nulo. Para los tipos de datos numéricos exactos, incluye el decimal y el signo. Consulte también, Atributos de tipos de datos

Columna 9 DECIMAL_DIGITS (SMALLINT)

La escala de la columna. NULL se devuelve para los tipos de datos en los que la escala no resulta aplicable. Consulte también, Atributos de tipos de datos

Columna 10 NUM_PREC_RADIX (SMALLINT)

10 o NULL.

Si DATA_TYPE es un tipo de datos numérico exacto, esta columna contiene el valor 10 y COLUMN_SIZE contiene el número de dígitos decimales que se permiten para la columna.

Para los tipos de datos numéricos, el DBMS devuelve un NUM_PREC_RADIX de 10.

NULL se devuelve para los tipos de datos en los que el radix no resulta aplicable.

Columna 11 NULLABLE (SMALLINT no NULL)

SQL_NO_NULLS si la columna no acepta valores nulos (NULL).

SQL_NULLABLE si la columna acepta valores nulos (NULL).

Columna 12 REMARKS (VARCHAR(254))

Siempre es nula (NULL).

Columna 13 COLUMN_DEF (VARCHAR(254))

El valor por omisión de la columna. Si el valor por omisión es un literal numérico, esta columna contendrá la representación de caracteres del literal numérico que no tengan comillas simples encerrándolos. Si el valor por omisión es una serie de caracteres, esta columna es dicha serie encerrada entre comillas simples. Si el valor por omisión es una seudo-literal, como por ejemplo para las columnas DATE, TIME y TIMESTAMP, esta columna contendrá la palabra clave de la seudo-literal (por ejemplo CURRENT DATE) sin comillas.

Si NULL se ha especificado como valor por omisión, esta columna devuelve la palabra NULL, sin comillas. Si no se ha especificado ningún valor por omisión, esta columna es NULL.

Columna 14 SQL_DATA_TYPE (SMALLINT no NULL)

Esta columna es igual que la columna DATA_TYPE.

Columna 15 SQL_DATETIME_SUB (SMALLINT)

Esta columna siempre es nula (NULL).

Columna 16 CHAR_OCTET_LENGTH (INTEGER)

Contiene la longitud máxima en octetos para una columna de tipo de datos de carácter. Para conjuntos de caracteres de un único byte, es igual que COLUMN_SIZE. Para todos los demás tipos de datos es NULL.

Columna 17 ORDINAL_POSITION (INTEGER no NULL)

La posición ordinal de la columna de la tabla. La primera columna de la tabla es el número 1.

Columna 18 IS_NULLABLE (VARCHAR(254))

Contiene la serie 'NO' si se sable que la columna no sea anulable; y 'YES' en caso contrario.

Este conjunto de resultados resulta idéntico a la especificación de conjunto de resultados Columns() de X/Open CLI, el cual es una versión ampliada del conjunto de resultados SQLColumns() especificado en ODBC V2. El conjunto de resultados SQLColumns() de ODBC incluye cada una de las columnas en la misma posición.

Nota: Este conjunto de resultados resulta idéntico a la especificación de conjunto de resultados Columns() de X/Open CLI, el cual es una versión ampliada del conjunto de resultados SQLColumns() especificado en ODBC V2. El conjunto de resultados SQLColumns() de ODBC incluye cada una de las columnas en la misma posición.

Códigos de retorno

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

Diagnósticos

Tabla 93. SQLColumns SQLSTATEs

Restricciones

Ninguna.

Consulta relacionada

• SQLTables - Obtener información de tabla