DESCRIBE TABLE sentencia

Invocación para DESCRIBE TABLE

Esta sentencia sólo puede incorporarse en un programa de aplicación. Es una sentencia ejecutable que no puede prepararse dinámicamente. No debe especificarse en Java™.

Autorización para DESCRIBE TABLE

Los privilegios que posee el ID de autorización que es titular del plan o paquete deben incluir al menos uno de los siguientes (si existe un plan, la comprobación de la autorización se realiza únicamente con respecto al titular del plan):

• Propiedad de la tabla o vista
• El privilegio SELECCIONAR, INSERTAR, ACTUALIZAR, ELIMINAR o REFERENCIAS en el objeto
• El privilegio ALTER o INDEX en el objeto (solo tablas)
• Autoridad DBADM sobre la base de datos que contiene el objeto (solo tablas)
• Autorización SYSADM
• Autorización SYSCTRL (sólo tablas de catálogo)
• Autorización ACCESSCTRL (sólo tablas de catálogo)
• DBADM del sistema
• Autorización DATAACCESS
• Autorización EXPLAIN
• Autorización SQLADM

Si la base de datos se crea de forma implícita, los privilegios de la base de datos deben estar en la base de datos implícita o en DSNDB04.

Para una aplicación RRSAF que no tiene un plan y en la que el solicitante y el servidor son sistemas d Db2 for z/OS® , la autorización para ejecutar el paquete se realiza contra el ID de autorización principal o secundario del proceso.

descripción para DESCRIBE TABLE

TABLA variable de host

Identifica la tabla o vista. El nombre no debe identificar una tabla auxiliar. Cuando se ejecuta la sentencia DESCRIBE, la variable host debe contener un nombre que identifique una tabla o vista que exista en el servidor actual. Esta variable debe ser una cadena de caracteres de longitud fija o variable con un atributo de longitud inferior a 256. El nombre debe ir seguido de uno o más espacios en blanco si la longitud del nombre es menor que la longitud de la variable. No puede contener un punto como primer carácter ni espacios en blanco incrustados. Además, las comillas son el carácter de escape, independientemente del valor de la opción de delimitador de cadena. No se debe especificar una variable indicadora para la variable anfitriona.

INTO nombre-descriptor

Identifica un área de descriptor SQL (SQLDA), que se describe en Área de descriptor SQL (SQLDA ). Consulte Identificación de un SQLDA en C o C++ para saber cómo representar el nombre del descriptor en C.

Para idiomas distintos de REXX : Antes de ejecutar la instrucción DESCRIBE, el usuario debe establecer la siguiente variable en el SQLDA y el SQLDA debe estar asignado.

SQLN

Indica el número de apariciones de SQLVAR proporcionadas en el SQLDA. Db2 no cambia este valor. Para conocer las técnicas para determinar el número de ocurrencias necesarias, consulte Asignación de SQLDA.

Para REXX : El SQLDA no se asigna antes de su uso. Un SQLDA consiste en un conjunto de variables raíz. Hay una aparición de la variable stem.SQLD, seguida de cero o más apariciones de un conjunto de variables que es equivalente a una estructura SQLVAR. Esas variables comienzan con stem.n.

Después de que se ejecute la instrucción DESCRIBE TABLE, todos los campos de SQLDA excepto SQLN se establecen mediante Db2 o se ignoran. Para obtener información sobre el contenido de los campos, consulte Contenidos de SQLDA devueltos para la tabla DESCRIBE.

USING

Indica qué valor asignar a cada variable SQLNAME en el SQLDA. Si el valor solicitado no existe, SQLNAME se establece con una longitud de 0.

NAMES

Asigna el nombre de la columna. Este es el valor predeterminado.

Labels

Asigna la etiqueta de la columna. (Las etiquetas de columna se definen mediante la instrucción LABEL)

ANY

Asigna la etiqueta de la columna. Si la columna no tiene etiqueta o la etiqueta es una cadena de longitud 0, se utiliza el nombre de la columna en su lugar.

BOTH

Asigna tanto la etiqueta como el nombre de la columna. En este caso, se necesitan dos o tres apariciones de SQLVAR por columna, dependiendo de si el conjunto de resultados contiene tipos distintos, para acomodar la información adicional. Para especificar esta expansión de la matriz SQLVAR, establezca SQLN en 2xn o 3xn, donde n es el número de columnas en el objeto que se describe. Para cada una de las columnas, las primeras n apariciones de SQLVAR, que son las entradas SQLVAR base, contienen los nombres de las columnas. La segunda o tercera n ocurrencias de SQLVAR, que son las entradas SQLVAR extendidas, contienen las etiquetas de columna. Si no hay tipos distintos, las etiquetas se devuelven en el segundo conjunto de entradas SQLVAR. De lo contrario, las etiquetas se devuelven en el tercer conjunto de entradas SQLVAR.

Para una tabla temporal declarada, el nombre de la columna se asigna independientemente del valor especificado en la cláusula USING porque las tablas temporales declaradas no pueden tener etiquetas.

Notas para DESCRIBE TABLE

Asignación de la SQLDA:

Antes de ejecutar la instrucción DESCRIBE o PREPARE INTO, el valor de SQLN debe establecerse en un valor mayor o igual a cero para indicar cuántas ocurrencias de SQLVAR se proporcionan en el SQLDA. Además, debe asignarse suficiente almacenamiento para contener el número de ocurrencias que especifica SQLN. Para obtener la descripción de las columnas de la tabla de resultados de una instrucción SELECT preparada, el número de apariciones de SQLVAR debe ser al menos igual al número de columnas. Además, si se especifica USAR AMBOS, o si las columnas incluyen LOB o tipos distintos, el número de apariciones de SQLVAR debe ser dos o tres veces el número de columnas. Consulte Determinar cuántas apariciones de SQLVAR se necesitan para obtener más información.

Primera técnica

Asigne un SQLDA con suficientes ocurrencias de SQLVAR para acomodar cualquier lista de selección que la aplicación tenga que procesar. En el extremo, el número de SQLVAR podría equivaler al triple del número máximo de columnas permitidas en una tabla de resultados. Una vez asignado el SQLDA, la aplicación puede utilizarlo repetidamente.

Esta técnica utiliza una gran cantidad de almacenamiento que nunca se desasigna, incluso cuando la mayor parte de su almacenamiento no se utilice para una lista de selección en particular.

Segunda técnica

Repita los dos pasos siguientes para cada lista de selección procesada:

1. Ejecutar una sentencia DESCRIBE con un SQLDA que no tenga ocurrencias de SQLVAR; es decir, un SQLDA para el que SQLN sea cero.
2. Asigne un nuevo SQLDA con suficientes ocurrencias de SQLVAR. Utilice los valores que se devuelven en SQLD y SQLCODE para determinar el número de entradas SQLVAR que se necesitan. El valor de SQLD es el número de columnas de la tabla de resultados, que es el número requerido de apariciones de SQLVAR o una fracción del número requerido (véase Determinar cuántas apariciones de SQLVAR se necesitan para más detalles). Si el SQLCODE es +236, +237, +238 o +239, el número de entradas SQLVAR necesarias es dos o tres veces el valor de SQLD, dependiendo de si se ha especificado USING BOTH. Establezca SQLN para reflejar el número de entradas SQLVAR que se han asignado.
3. Ejecute la instrucción DESCRIBE de nuevo, u

   Esta técnica permite una mejor gestión del almacenamiento que la primera técnica, pero duplica el número de sentencias DESCRIBE.

   usando el nuevo SQLDA.

Tercera técnica

Asigne un SQLDA que sea lo suficientemente grande como para manejar la mayoría (con suerte, todas) las listas de selección, pero que también sea razonablemente pequeño. Si una ejecución de DESCRIBE falla porque SQLDA es demasiado pequeño, asigne un SQLDA más grande y ejecute la instrucción DESCRIBE de nuevo.

Para el nuevo SQLDA más grande, utilice los valores que se devuelven en SQLD y SQLCODE de la sentencia DESCRIBE fallida para calcular el número de apariciones de SQLVAR que se necesitan, como se describe en la técnica dos. Recuerde comprobar los códigos SQLCODE +236, +237, +238 y +239, que indican si se necesitan entradas SQLVAR ampliadas porque los datos incluyen LOB o tipos distintos.

Esta tercera técnica es un compromiso entre las dos primeras técnicas. Su eficacia depende de una buena elección del tamaño de la SQLDA original.

Contenidos SQLDA devueltos para la tabla DESCRIBE

Después de que se ejecute una instrucción DESCRIBE TABLE, la siguiente lista describe el contenido de los campos SQLDA tal y como los establece o ignora Db2 .

Estas descripciones no se aplican necesariamente a los usos de un SQLDA en otras sentencias SQL (EXECUTE, OPEN, FETCH). Para más información sobre los otros usos, consulte el área de descriptores SQL (SQLDA ).

SQLDAID

Db2 establece los primeros 6 bytes en 'SQLDA' (cinco letras seguidas del carácter de espacio), el séptimo byte en un carácter de espacio o un número que indica el número de entradas SQLVAR necesarias, y el octavo byte en un carácter de espacio. El séptimo byte de SQLDAID puede establecerse en los siguientes valores para indicar cuántas entradas SQLVAR se necesitan para describir cada columna de la tabla de resultados:

espacio

El séptimo byte de SQLDAID es un carácter de espacio en las siguientes situaciones:

• NO SE ESPECIFICÓ USAR AMBOS y las columnas que se describen no incluyen LOB ni tipos distintos. Cada columna solo necesita una entrada SQLVAR. Si la opción estándar SQL es sí, Db2 establece SQLCODE en el código de advertencia +236. De lo contrario, SQLCODE es cero.
• SE ESPECIFICÓ USAR AMBOS y las columnas que se describen no incluyen LOB ni tipos distintos. Cada columna necesita dos entradas SQLVAR. Db2 establece SQLD en dos veces el número de columnas de la tabla de resultados. El segundo conjunto de SQLVAR se utiliza para las etiquetas.

2

Cada columna necesita dos entradas SQLVAR. Se requieren dos entradas por columna en las siguientes situaciones:

• NO SE ESPECIFICÓ USAR AMBOS y las columnas que se describen incluyen LOB o tipos distintos o ambos. Db2 establece el segundo conjunto de entradas SQLVAR con información para los LOB o tipos distintos que se describen.
• SE ESPECIFICÓ USAR AMBOS y las columnas incluyen LOB, pero no tipos distintos. Db2 establece el segundo conjunto de entradas SQLVAR con información para los LOB y etiquetas para las columnas que se describen.

3

Cada columna necesita tres entradas SQLVAR. Solo se requieren tres entradas cuando se especifica USO AMBOS y las columnas que se describen incluyen tipos distintos. La presencia de datos LOB no importa. Son los tipos distintos y no los LOB los que hacen que se necesiten tres entradas SQLVAR por columna cuando también se solicitan etiquetas. Db2 establece el segundo conjunto de entradas SQLVAR con información para los distintos tipos (y LOB, si los hay) y el tercer conjunto de entradas SQLVAR con las etiquetas de las columnas que se describen.

Para obtener más información sobre cómo se utiliza el séptimo byte de SQLDAID, consulte Determinar cuántas apariciones de SQLVAR se necesitan.

Un REXX SQLDA no contiene este campo.

SQLDABC

La longitud del SQLDA en bytes. Db2 establece el valor en SQLN×44+16.

Un REXX SQLDA no contiene este campo.

SQLD

Si la declaración preparada es una consulta, Db2 establece el valor en el número de columnas del objeto que se describe. (Para idiomas distintos del REXX, en el caso de que se haya especificado USAR AMBOS y la tabla de resultados no incluya LOB o tipos distintos, el valor es en realidad el doble del número de columnas. Para REXX, si se especifica USAR AMBOS, el valor es el doble del número de columnas, independientemente de si la tabla de resultados incluye LOB o tipos distintos) De lo contrario, si la declaración no es una consulta, Db2 establece el valor en 0.

SQLVAR

Una serie de información de descripción de campo para la columna que se describe. Hay dos tipos de entradas SQLVAR: la SQLVAR básica y la SQLVAR extendida.

Si el valor de SQLD es 0, o es mayor que el valor de SQLN, no se asigna ningún valor a ninguna ocurrencia de SQLVAR. Si el valor de SQLN se estableció de modo que haya suficientes ocurrencias de SQLVAR para describir las columnas especificadas (las columnas con LOB o tipos distintos y una solicitud de etiquetas aumentan el número de entradas SQLVAR necesarias), los valores se asignan a las primeras n ocurrencias de SQLVAR de modo que la primera ocurrencia de SQLVAR contenga una descripción de la primera columna, la segunda ocurrencia de SQLVAR contenga una descripción de la segunda columna, y así sucesivamente. Este primer conjunto de entradas SQLVAR se denomina entradas SQLVAR base. Cada columna siempre tiene una entrada SQLVAR base.

Si la sentencia DESCRIBE incluye la cláusula USING BOTH, o las columnas que se describen incluyen LOB o tipos distintos, se necesitan entradas SQLVAR adicionales. Estas entradas SQLVAR adicionales se denominan entradas SQLVAR extendidas. Puede haber hasta dos conjuntos de entradas SQLVAR extendidas para cada columna.

Para REXX, SQLVAR es un conjunto de variables raíz que comienzan con stem. n, en lugar de una estructura. El REXX SQLDA utiliza únicamente un SQLVAR base. Sin embargo, REXX utiliza La forma en que Db2 asigna valores a las variables SQLVAR es la misma que para otros lenguajes. Es decir, las variables stem.1 describen la primera columna de la tabla de resultados, las variables stem.2 describen la segunda columna de la tabla de resultados, y así sucesivamente. Si se especifica USING BOTH, las variables de raíz +1 también describen la primera columna de la tabla de resultados, las variables de raíz. n +2 también describen la segunda columna de la tabla de resultados, y así sucesivamente.

La base SQLVAR:

SQLTYPE

Un código que indica el tipo de datos de la columna y si la columna puede contener valores nulos. Para los posibles valores de SQLTYPE, consulte los campos SQLTYPE y SQLLEN del SQLDA.

SQLLEN

Un valor de longitud que depende del tipo de datos de las columnas de resultados. SQLLEN es 0 para los tipos de datos LOB y XML. Para los otros valores posibles de SQLLEN, consulte los campos SQLTYPE y SQLLEN de SQLDA.

En un REXX SQLDA, para columnas DECIMAL o NUMERIC, Db2 establece los campos SQLPRECISION y SQLSCALE en lugar del campo SQLLEN.

SQLDATA

El CCSID de una columna de cadena. Para ver los posibles valores, consulte el campo SQLDATA del SQLDA.

En un REXX SQLDA, Db2 establece el campo SQLCCSID en lugar del campo SQLDATA.

SQLIND

Reservado.

SQLNAME

El nombre o etiqueta no cualificado de la columna, dependiendo del valor de USING (NAMES, LABELS, ANY o BOTH). El campo es una cadena de longitud 0 si la columna no tiene nombre o etiqueta. Para más detalles sobre columnas sin nombre, consulte la discusión de los nombres de las columnas de resultados en cláusula select. Este valor se devuelve en el esquema de codificación especificado por la opción de enlace ENCODING para el plan o paquete que contiene la declaración.

SQLLONGL

Solo para REXX, el atributo de longitud de una columna LOB. Otros idiomas utilizan SQLLONGLEN en el SQLVAR extendido.

SQLCCSID

Solo para REXX, el atributo de longitud de una columna LOB.

SQLTNAME

Solo para REXX, el nombre de tipo distinto totalmente calificado de la enésima columna en la tabla de resultados. Otros idiomas utilizan SQLDATATYPE-NAME en el SQLVAR extendido.

La extensión SQLVAR:

SQLLONGLEN

El atributo de longitud de una columna BLOB, CLOB o DBCLOB.

*

Reservado.

sqldatalen

No se utiliza.

SQLDATYPE-NAME

Para un tipo distinto, el nombre de tipo distinto totalmente calificado. De lo contrario, el valor es el nombre completo del tipo de datos incorporado.

Para una etiqueta, la etiqueta de la columna.

Este valor se devuelve en el esquema de codificación especificado por la opción de enlace ENCODING para el plan o paquete que contiene esta declaración.

Consideraciones de rendimiento:

Aunque Db2 no cambia el valor de SQLN, es posible que desee restablecer este valor después de que se ejecute la instrucción DESCRIBE. Si el contenido de SQLDA de la sentencia DESCRIBE se utiliza en una sentencia FETCH posterior, establezca SQLN en n (donde n es el número de columnas de la tabla de resultados) antes de ejecutar la sentencia FETCH. Para más detalles, consulte Preparación de SQLDA para la recuperación de datos

Uso de variables de host:

Si la sentencia DESCRIBE contiene variables de host, se asume que el contenido de las variables de host está en el esquema de codificación que se especificó en el parámetro ENCODING cuando se vinculó el paquete o plan que contiene la sentencia.

Consideraciones para las columnas ocultas implícitamente:

Una sentencia DESCRIBE TABLE devuelve información sobre columnas implícitamente ocultas en tablas.