Función escalar REC2XML

La función REC2XML devuelve una serie formateada codificada en XML que contiene nombres de columna y datos de columna.

El esquema es SYSIBM.

En una base de datos Unicode, si un argumento proporcionado es una serie gráfica, se convertirá a una serie de caracteres antes de que se ejecute la función.

constante-decimal

Factor de expansión para sustituir caracteres de datos de columna. El valor decimal debe ser mayor que 0.0 y menor que o igual a 6.0. (SQLSTATE 42820).

El valor constante-decimal se utiliza para calcular la longitud de resultado de la función. Para cada columna con un tipo de datos de tipo carácter, el atributo de longitud de la columna se multiplica por este factor de expansión antes de que se sume a la longitud de resultado.

Para especificar que no haya expansión, utilice un valor de 1.0. Si se especifica un valor menor que 1.0, se reducirá la longitud de resultado calculada. Si la longitud real de la serie de resultado es mayor que la longitud de resultado calculada de la función, se producirá un error (SQLSTATE 22001).

serie-formato

Constante de serie que especifica qué formato debe utilizar la función durante la ejecución.

La serie-formato es sensible a las mayúsculas y minúsculas, de modo que los valores siguientes deben especificarse en mayúsculas para que se reconozcan.

COLATTVAL o COLATTVAL_XML: Estos formatos devuelven una serie con columnas como valores de atributo.

Los nombres de columna pueden ser valores de atributo XML válidos o pueden no serlo. Para los nombres de columna que no son valores de atributo XML válidos, se realiza la sustitución de caracteres en el nombre de columna antes de incluirlo en la serie de resultado.

Los valores de columna pueden ser nombres de elemento XML válidos o pueden no serlo. Si se especifica la serie-formato COLATTVAL, para los nombres de columna que no son valores de elemento XML válidos, se realiza la sustitución de caracteres en el valor de columna antes de incluirlo en la serie de resultado. Si se especifica la serie-formato COLATTVAL_XML, no se realiza la sustitución de caracteres en los valores de columna (aunque la sustitución de caracteres se realiza de todas formas en los nombres de columna).

serie-código-fila

Constante de serie que especifica el código utilizado para cada fila. Si se especifica una serie vacía, se supone el valor de fila.

Si se especifica una serie de uno o más caracteres en blanco, no aparecerá ninguna serie-código-fila inicial o serie-código-fila final (incluidos los delimitadores de signo mayor que y menor que) en la serie de resultado.

nombre-columna

Nombre calificado o no calificado de una columna de tabla. La columna debe tener uno de los tipos de datos siguientes (SQLSTATE 42815):

numérico (SMALLINT, INTEGER, BIGINT, DECIMAL, REAL, DOUBLE)
serie de caracteres (CHAR, VARCHAR; no se permite una serie de caracteres con un subtipo de BIT DATA)
fecha y hora (DATE, TIME, TIMESTAMP)
un tipo definido por el usuario basado en uno de los tipos de datos listados anteriormente

No se puede especificar más de una vez el mismo nombre de columna (SQLSTATE 42734).

El resultado de la función es VARCHAR en OCTETS, sin importar cuáles sean las unidades de serie del entorno o las columnas especificadas. La longitud máxima es 32 672 bytes (SQLSTATE 54006).

Examine la invocación siguiente:

   REC2XML (dc, fs, rt, c₁, c₂, ..., c_n)

Si el valor de fs es COLATTVAL o COLATTVAL_XML, el resultado será igual que esta expresión:

'<' CONCAT rt CONCAT '>' CONCAT y₁ CONCAT y₂
CONCAT ... CONCAT y_n CONCAT '</' CONCAT rt CONCAT '>'

donde y_n es equivalente a:

'<column name="' CONCAT xvc_n CONCAT vn

y vn es equivalente a:

'">' CONCAT r_n CONCAT '</columna>'

si la columna no es nula y

'" null="true"/>'

si el valor de columna es nulo.

xvc_n es equivalente a una representación de serie del nombre de columna de c_n, donde cualquier carácter que aparezca en la Tabla 2 se sustituye por la representación correspondiente. Esto asegura que la serie resultante sea un token de valor de elemento o atributo XML válido.

r_n es equivalente a una representación de serie como se indican en la Tabla 1

Tabla 1. Resultado de serie de valores de columna
Tipo de datos de c_n	r_n
CHAR, VARCHAR	El valor es una serie. Si la serie-formato no termina con los caracteres _XML, cada carácter de c_n se sustituye por la representación de sustitución correspondiente de la Tabla 2, como se indica. El atributo de longitud es: dc * el atributo de longitud de c_n.
SMALLINT, INTEGER, BIGINT, DECIMAL, NUMERIC, REAL, DOUBLE	El valor es LTRIM(RTRIM(CHAR(c_n))). El atributo de longitud es la longitud de resultado de CHAR(c_n). El carácter de decimal es siempre el carácter de punto (.).
DATE	El valor es CHAR(c_n,ISO). El atributo de longitud es la longitud de resultado de CHAR(c_n,ISO).
TIME	El valor es CHAR(c_n,JIS). El atributo de longitud es la longitud de resultado de CHAR(c_n,JIS)
TIMESTAMP	El valor es CHAR(c_n). El atributo de longitud es la longitud de resultado de CHAR(c_n).

Sustitución de caracteres:

En función del valor especificado para la serie-formato, se sustituirán determinados caracteres en los nombres de columna y en los valores de columna para asegurar que los nombres de columna formen valores de atributo XML válidos y que los valores de columna formen valores de elemento XML válidos.

Tabla 2. Sustituciones de caracteres para valores de atributo y valores de elemento XML
Carácter	Sustitución
<	<
>	>
"	"
&	&
'	'

Ejemplos

Nota: REC2XML no inserta espacios en blanco ni caracteres de nueva línea en la salida. Todas las salidas de los ejemplos se han formateado para mejorar la legibilidad.

Ejemplo 1: formatear, utilizando la tabla DEPARTMENT de la base de datos de ejemplo, la fila de tabla del departamento, excepto las columnas DEPTNAME y LOCATION, para el departamento 'D01' en una serie XML. Dado que los datos no contienen ninguno de los caracteres que necesitan sustituirse, el factor de expansión será 1.0 (sin expansión). Observe también que el valor MGRNO es nulo para esta fila.
```
   SELECT REC2XML (1.0, 'COLATTVAL', '', DEPTNO, MGRNO, ADMRDEPT)
     FROM DEPARTMENT
     WHERE DEPTNO = 'D01'
```
Este ejemplo devuelve la serie VARCHAR(117) siguiente:
```
   <row>
   <column name="DEPTNO">D01</column>
   <column name="MGRNO" null="true"/>
   <column name="ADMRDEPT">A00</column>
   </row>
```
Ejemplo 2: una planificación universitaria de 5 días incorpora una clase llamada '&43<FIE' en una tabla llamada CL_SCHED, con un formato nuevo para la columna CLASS_CODE. Utilizando la función REC2XML, este ejemplo formatea una serie XML con estos datos de clase nuevos, exceptuando la hora final de clase.
El atributo de longitud para la llamada REC2XML con un factor de expansión 1,0 sería 128 (11 para la actividad general de '<row>' y '</row>' 21 para los nombres de columna, 75 para <column name=, >, </column> y las comillas dobles, 7 para los datos CLASS_CODE, 6 para los datos DAY y 8 para los datos STARTING). Dado que los caracteres & y < se sustituirán, no será suficiente un factor de expansión de 1.0. El atributo de longitud de la función necesitará soportar un incremento de 7 a 14 bytes para los datos CLASS_CODE de formato nuevo.
Sin embargo, puesto que se sabe que el valor DAY no tendrá nunca más de 1 dígito de longitud, se añaden al total 5 unidades adicionales no utilizadas de longitud. Por lo tanto, la expansión sólo necesita gestionar un incremento de 2. Dado que CLASS_CODE es la única columna de serie de caracteres de la lista de argumentos, éstos son los únicos datos de columna a los que se aplica el factor de expansión. Para obtener un incremento de 2 para la longitud, sería necesario un factor de expansión de 9/7 (1,2857 aproximadamente). Se utilizará un factor de expansión de 1.3.
```
   SELECT REC2XML (1.3, 'COLATTVAL', 'record', CLASS_CODE, DAY, STARTING)
     FROM CL_SCHED
     WHERE CLASS_CODE = '&43<FIE'
```
Este ejemplo devuelve la serie VARCHAR(167) siguiente:
```
   <record>
   <column name="CLASS_CODE">&amp;43&lt;FIE</column>
   <column name="DAY">5</column>
   <column name="STARTING">06:45:00</column>
   </record>
```
Ejemplo 3: supongamos que se han añadido filas nuevas a la tabla EMP_RESUME de la base de datos de ejemplo. Las nuevas filas almacenan los resúmenes como series de XML válido. Se utiliza la serie-formato COLATTVAL_XML para que no se lleve a cabo la sustitución de caracteres. Ninguno de los resúmenes tiene más de 3500 bytes de longitud. Se utiliza la consulta siguiente para seleccionar la versión XML de los resúmenes de la tabla EMP_RESUME y formatearla en un fragmento de documento XML.
```
   SELECT REC2XML (1.0, 'COLATTVAL_XML', 'row', EMPNO, RESUME_XML)
     FROM (SELECT EMPNO, CAST(RESUME AS VARCHAR(3500)) AS RESUME_XML
       FROM EMP_RESUME
       WHERE RESUME_FORMAT = 'XML')
     AS EMP_RESUME_XML
```
Este ejemplo devuelve una fila para cada empleado que tiene un resumen en formato XML. Cada fila devuelta será una serie con el formato siguiente:
```
   <row>
   <column name="EMPNO">{número de empleado}</column>
   <column name="RESUME_XML">{resumen en XML}</column>
   </row>
```
Donde {employee number} es el valor EMPNO real para la columna y {resume in XML} es el valor de serie de fragmento XML real que constituye el resumen.