Función SQLColumns (CLI)-Obtener información de columna para una tabla

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

Especificación:

CLI 2.1
ODBC 1.0

Unicode Equivalente: También puede utilizar esta función con el juego de caracteres Unicode. La función Unicode correspondiente es SQLColumnsW(). Para obtener detalles sobre las correlaciones de funciones ANSI a Unicode, consulte Funciones Unicode (CLI).

Sintaxis

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

Argumentos de la función

Tabla 1. Argumentos SQLColumns
Tipo de datos	Argumento	Uso	Descripción
SQLHSTMT	StatementHandle	Entrada	El indicador de la sentencia.
SQLCHAR *	CatalogName	Entrada	Un calificador de catálogo de un nombre de tabla de un tercero. Si el DBMS de destino no admite la denominación de 3 partes y CatalogName no es un puntero nulo ni apunta a una serie de longitud cero, se devuelve un conjunto de resultados vacío y SQL_SUCCESS. De lo contrario, este es un filtro válido para los DBMS que admiten nombres de 3 partes.
SQLSMALLINT	NameLength1	Entrada	Número de elementos SQLCHAR (o elementos SQLWCHAR para la variante Unicode de esta función) que se requieren para almacenar CatalogName o SQL_NTS si CatalogName termina en nulo.
SQLCHAR *	SchemaName	Entrada	Un almacenamiento intermedio que puede contener un valor de patrón para calificar el conjunto de resultados por nombre de esquema.
SQLSMALLINT	NameLength2	Entrada	El número de elementos SQLCHAR (o elementos SQLWCHAR para la variante Unicode de esta función) que se requieren para almacenar SchemaName o SQL_NTS si SchemaName tiene terminación nula.
SQLCHAR *	TableName	Entrada	Almacenamiento intermedio que puede contener un valor de patrón para calificar el conjunto de resultados por nombre de tabla.
SQLSMALLINT	NameLength3	Entrada	El número de elementos SQLCHAR (o elementos SQLWCHAR para la variante Unicode de esta función) que se requieren para almacenar TableName, o SQL_NTS si TableName tiene terminación nula.
SQLCHAR *	ColumnName	Entrada	Un almacenamiento intermedio que puede contener un valor de patrón para calificar el conjunto de resultados por nombre de columna.
SQLSMALLINT	NameLength4	Entrada	El número de elementos SQLCHAR (o elementos SQLWCHAR para la variante Unicode de esta función) que se requieren para almacenar ColumnName, o SQL_NTS si ColumnName tiene terminación nula.

Uso

Utilice esta función para recuperar información sobre las columnas de una tabla o un conjunto de tablas. Una aplicación puede llamar a esta función después de una llamada a SQLTables() para determinar las columnas de una tabla. La aplicación debe utilizar las series de caracteres que se devuelven en las columnas TABLE_SCHEMA y TABLE_NAME del conjunto de resultados SQLTables() como entrada para esta función.

La función SQLColumns() devuelve un conjunto de resultados estándar ordenado por TABLE_CAT, TABLE_SCHEM, TABLE_NAME y ORDINAL_POSITION. Columnas devueltas por SQLColumns lista las columnas que están en el conjunto de resultados.

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

A veces, una aplicación llama a la función y no se intenta restringir el conjunto de resultados que se devuelve. Para algunos orígenes de datos que contienen una gran cantidad de tablas, vistas y alias, por ejemplo, este escenario se asigna a un conjunto de resultados extremadamente grande y tiempos de recuperación muy largos. Para ayudar a reducir los tiempos de recuperación largos, puede especificar la palabra clave de configuración SchemaList en el archivo de inicialización CLI para ayudar a restringir el conjunto de resultados cuando la aplicación ha proporcionado un puntero nulo para SchemaName. Si la aplicación especifica una cadena SchemaName, la palabra clave SchemaList se sigue utilizando para restringir la salida. Por lo tanto, si el nombre de esquema que se proporciona no está en la cadena SchemaList, el resultado es un conjunto de resultados vacío.

Esta función no devuelve información sobre las columnas de un conjunto de resultados. En su lugar, debe utilizar la función SQLDescribeCol() o SQLColAttribute() .

Si el atributo SQL_ATTR_LONGDATA_COMPAT se establece en SQL_LD_COMPAT_YES mediante una llamada a SQLSetConnectAttr() o estableciendo la palabra clave LONGDATACOMPAT en el archivo de inicialización CLI , los tipos de datos LOB se notifican como SQL_LONGVARCHAR, SQL_LONGVARBINARY o SQL_LONGVARGRAPHIC.

En muchos casos, las llamadas a la función SQLColumns() se correlacionan con una consulta compleja y, por lo tanto, costosa en el catálogo del sistema, por lo que debe usar las llamadas con moderación y guardar los resultados, en lugar de repetir las llamadas.

Llame a SQLGetInfo() con SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_OWNER_SCHEMA_LEN, SQL_MAX_TABLE_NAME_LEN y SQL_MAX_COLUMN_NAME_LEN para determinar las longitudes reales de las columnas TABLE_CAT, TABLE_SCHEM, TABLE_NAME y COLUMN_NAME soportadas por el DBMS conectado.

Puede especificar *ALL o *USRLIBL como valores en SchemaName para resolver las llamadas a procedimientos almacenados no calificados o para buscar bibliotecas en las llamadas de API de catálogo. Si especifica *ALL, CLI busca en todos los esquemas existentes de la base de datos conectada. No tiene que especificar *ALL, ya que este comportamiento es el predeterminado en CLI. Para IBM® Db2® para servidores IBM i , si especifica *USRLIBL, la CLI busca en las bibliotecas actuales del trabajo de servidor. Para otros servidores Db2 , *USRLIBL no tiene un significado especial y la CLI busca utilizando *USRLIBL como patrón. Como alternativa, puede establecer la palabra clave de configuración SchemaFilter IBM Data Server Driver o la palabra clave de configuraciónODBC de la lista de esquemas en *ALL o *USRLIBL.

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

Columnas devueltas por SQLColumns

Columna 1 TABLE_CAT (VARCHAR(128))

El nombre del catálogo. El valor es NULL si esta tabla no tiene catálogos.

Columna 2 TABLE_SCHEM (VARCHAR(128))

Nombre del esquema que contiene TABLE_NAME.

Columna 3 TABLE_NAME (VARCHAR(128) not NULL)

El nombre de la tabla, vista, alias o sinónimo.

Columna 4 COLUMN_NAME (VARCHAR(128) not NULL)

Identificador de columna. Nombre de la columna del sinónimo, el alias, la vista o la tabla especificados.

Columna 5 DATA_TYPE (SMALLINT no NULL)

Tipo de datos de SQL de la columna identificada por COLUMN_NAME. DATA_TYPE es uno de los valores de la columna Tipo de datos SQL simbólico de la tabla de tipos de datos simbólicos y predeterminados para CLI.

Columna 6 TYPE_NAME (VARCHAR(128) no NULL)

Una 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 indica una serie de caracteres o binaria, esta columna contiene la longitud máxima en elementos SQLCHAR o SQLWCHAR para la columna.

Para los tipos de datos de fecha, hora e indicación de fecha y hora, COLUMN_SIZE es el número total de elementos SQLCHAR o SQLWCHAR necesarios para mostrar el valor cuando se convierte al tipo de datos de caracteres.

Para los tipos de datos numéricos, COLUMN_SIZE es el número total de dígitos o el número total de bits permitidos en la columna, según el valor de la columna NUM_PREC_RADIX del conjunto de resultados.

Para la columnas definidas con la unidad CODEUNITS32, se devuelve el número de unidades de código para la columna.

Para el tipo de datos XML, se devuelve una longitud de cero.

Consulte la tabla de precisión del tipo de datos.

Columna 8 BUFFER_LENGTH (INTEGER)

El número máximo de bytes para el almacenamiento intermedio C asociado para almacenar datos de esta columna si se especifica SQL_C_DEFAULT en las llamadas SQLBindCol(), SQLGetData() y SQLBindParameter() . La longitud no incluye los terminadores nulos. Para tipos de datos numéricos exactos, la longitud contabiliza el decimal y el signo.

Consulte la tabla que recoge las longitudes de tipos de datos.

Columna 9 DECIMAL_DIGITS (SMALLINT)

La escala de la columna. Se devuelve NULL para los tipos de datos en los que la escala no es aplicable.

Consulte la tabla de escala del tipo de datos.

Columna 10 NUM_PREC_RADIX (SMALLINT)

10, 2 o NULL. Si DATA_TYPE es un tipo de datos numérico aproximado, esta columna contiene el valor 2 y la columna COLUMN_SIZE contiene el número de bits que se permiten en la columna.

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

Para tipos de datos numéricos, el DBMS puede devolver un NUM_PREC_RADIX de 10 o 2.

Se devuelve NULL para los tipos de datos en los que no es aplicable la raíz.

Columna 11 NULLABLE (SMALLINT no NULL)

SQL_NO_NULLS si la columna no acepta valores NULL.

SQL_NULLABLE si la columna acepta valores NULL.

Columna 12 REMARKS (VARCHAR(254))

Podría contener información descriptiva sobre la columna. Es posible que no se devuelva información en esta columna. Para obtener más detalles, consulte Optimizar palabra clave y atributo de columnas SQL.

Columna 13 COLUMN_DEF (VARCHAR(254))

El valor predeterminado de la columna. Si el valor predeterminado es un literal numérico, esta columna contiene la representación de caracteres del literal numérico sin comillas simples. Si el valor predeterminado es una serie de caracteres, esta columna es dicha serie entrecomillada con comillas simples. Si el valor predeterminado es un pseudoliteral, como en las columnas DATE, TIME y TIMESTAMP, esta columna contiene la palabra clave del pseudoliteral (por ejemplo, CURRENT DATE) sin comillas simples.

Si se especifica NULL como valor predeterminado, esta columna devuelve la palabra NULL, sin comillas. Si el valor predeterminado no se puede representar sin recorte, esta columna contiene TRUNCATED, sin comillas simples. Si no se especifica ningún valor predeterminado, esta columna es NULL.

Es posible que no se devuelva información en esta columna. Para obtener más detalles, consulte Optimizar palabra clave y atributo de columnas SQL.

Columna 14 SQL_DATA_TYPE (SMALLINT no NULL)

Tipo de datos de SQL, tal y como se visualiza en el campo de registro SQL_DESC_TYPE del IRD. Esta columna es la misma que la columna DATA_TYPE en Columnas devueltas por SQLColumns para los tipos de datos de fecha, hora e indicación de fecha y hora.

Columna 15 SQL_DATETIME_SUB (SMALLINT)

Código de subtipo para tipos de datos de indicación de fecha y hora:

SQL_CODE_DATE
SQL_CODE_TIME
SQL_CODE_TIMESTAMP

Para cualquier otro tipo de datos, esta columna devuelve NULL.

Columna 16 CHAR_OCTET_LENGTH (INTEGER)

En conjuntos de caracteres de un solo byte, es igual que COLUMN_SIZE. Para las columnas definidas con la unidad CODEUNITS32, se devuelve el número de unidades de código para la columna. Para el tipo XML, se devuelve cero. Para cualquier otro tipo de datos, se devuelve NULL.

Columna 17 ORDINAL_POSITION (INTEGER no NULL)

Posición ordinal de la columna en la tabla. La primera columna de la tabla es la número 1.

Columna 18 IS_NULLABLE (VARCHAR(254))

Contiene la serie 'NO' si se sabe que la columna no admite valores nulos y 'YES' si la columna admite valores nulos.

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

Optimizar el atributo y la palabra clave de las columnas SQL

Es posible configurar el controlador CLI/ODBC para optimizar las llamadas a la función SQLColumns() utilizando:

Palabra clave de configuración OPTIMIZESQLCOLUMNS CLI/ODBC
El atributo de conexión SQL_ATTR_OPTIMIZESQLCOLUMNS de SQLSetConnectAttr()

Si alguno de estos valores está definido, no se devuelve la información contenida en las columnas siguientes:

Columna 12 REMARKS
Columna 13 COLUMN_DEF

Códigos de retorno

SQL_ERROR
SQL_INVALID_HANDLE
SQL_STILL_EXECUTING
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO

Diagnósticos

Tabla 2. SQLSTATE SQLColumns
SQLSTATE	Descripción	Explicación
24000	Estado de cursor no válido.	Ya había un cursor abierto en el identificador de sentencia.
40003 08S01	Anomalía de enlace de comunicaciones.	El enlace de comunicaciones entre la aplicación y la fuente de datos ha fallado antes de que se completara la función.
HY001	Anomalía de asignación de memoria.	La CLI de Db2 no puede asignar la memoria necesaria para dar soporte a la ejecución o finalización de la función. Es probable que la memoria de nivel de proceso se haya agotado para el proceso de aplicaciones. Consulte la configuración del sistema operativo para obtener información sobre las limitaciones de memoria de nivel de proceso.
HY008	La operación se ha cancelado.	El procesamiento asincrónico se habilitó para StatementHandle. Se ha llamado a la función y, antes de que completara la ejecución, se ha llamado a `SQLCancel()` en StatementHandle desde una hebra diferente en una aplicación multihebra. Posteriormente, se ha llamado de nuevo a la función en StatementHandle.
HY010	Error de secuencia de función.	Se ha llamado a la función mientras se encontraba en una operación de datos en tiempo de ejecución (`SQLParamData()`, `SQLPutData()`). Se llamó a la función mientras se encontraba dentro de una operación SQL BEGIN COMPOUND y END COMPOUND. Se llamó a una función de ejecución asíncrona (no esta) para StatementHandle y todavía se estaba ejecutando cuando se llamó a esta función. Se ha llamado a la función antes de que se hubiera preparado una sentencia en el identificador de sentencia.
HY014	No hay más descriptores de contexto.	Db2 CLI no ha podido asignar un descriptor de contexto debido a limitaciones de recursos.
HY090	Longitud de almacenamiento intermedio o serie no válida.	El valor de uno de los argumentos de longitud de nombre era menor que 0, pero no igual a SQL_NTS.
HYT00	Tiempo de espera agotado.	El período de tiempo de espera venció antes de que el origen de datos devolviese el conjunto de resultados. Puede establecer el periodo de tiempo de espera utilizando el atributo SQL_ATTR_QUERY_TIMEOUT para `SQLSetStmtAttr()`. Nota: Este SQLSTATE sólo se aplica a aplicaciones .Net.

Restricción

La función SQLColumns() no admite la devolución de datos desde el alias de un alias. Si se efectúa la llamada en un alias de un alias, la función SQLColumns() devuelve un conjunto de resultados vacío.

Ejemplo

El siguiente ejemplo de código obtiene información de columna para una tabla.

  /* get column information for a table */
  cliRC = SQLColumns(hstmt,
                     NULL,
                     0,
                     tbSchemaPattern,
                     SQL_NTS,
                     tbNamePattern,
                     SQL_NTS,
                     colNamePattern,
                     SQL_NTS);