The REC2XML function returns a string formatted with XML tags, containing column names and column data.

The schema is SYSIBM.

In a Unicode database, if a supplied argument is a graphic string, it is first converted to a character string before the function is executed.

decimal-constant

The expansion factor for replacing column data characters.
The decimal value must be greater than 0.0 and less than or equal to 6.0. (SQLSTATE 42820).

The decimal-constant value is used to calculate the result length of the function.
For every column with a character data type, the length attribute of the column is multiplied by this expansion factor before it is added in to the result length.

To specify no expansion, use a value of 1.0.
Specifying a value less than 1.0 reduces the calculated result length.
If the actual length of the result string is greater than the calculated result length of the function, then an error is raised (SQLSTATE 22001).

format-string

The string constant that specifies which format the function is to use during execution.

The format-string is case-sensitive, so the following values must be specified in uppercase to be recognized.

COLATTVAL or COLATTVAL_XML

These formats return a string with columns as attribute values.

Column names may or may not be valid XML attribute values.
For column names which are not valid XML attribute values, character replacement is performed on the column name before it is included in the result string.

Column values may or may not be valid XML element names.
If the format-string COLATTVAL is specified, then for the column names which are not valid XML element values, character replacement is performed on the column value before it is included in the result string.
If the format-string COLATTVAL_XML is specified, then character replacement is not performed on column values (although character replacement is still performed on column names).

row-tag-string

A string constant that specifies the tag used for each row.
If an empty string is specified, then a value of row is assumed.

If a string of one or more blank characters is specified, then no beginning row-tag-string or ending row-tag-string (including the angle bracket delimiters) will appear in the result string.

column-name

A qualified or unqualified name of a table column.
The column must have one of the following data types (SQLSTATE 42815):

• numeric (SMALLINT, INTEGER, BIGINT, DECIMAL, REAL, DOUBLE)
• character string (CHAR, VARCHAR; a character string with a subtype of BIT DATA is not allowed)
• datetime (DATE, TIME, TIMESTAMP)
• a user-defined type based on one of the previously listed data types

The same column name cannot be specified more than once (SQLSTATE 42734).

The result of the function is VARCHAR in OCTETS, regardless of the string units of the environment or the specified columns.
The maximum length is 32 672 bytes (SQLSTATE 54006).

Consider the following invocation:

   REC2XML (dc, fs, rt, c1, c2, ..., cn)

If the value of fs is either COLATTVAL or COLATTVAL_XML, then the result is the same as this expression:

   '<' CONCAT rt CONCAT '>' CONCAT y1 CONCAT y2
          CONCAT ... CONCAT yn CONCAT '</' CONCAT rt CONCAT '>'

   '<column name="' CONCAT xvcn CONCAT vn

   '">' CONCAT rn CONCAT '</column>'

   '" null="true"/>'

xvc_n is equivalent to a string representation of the column name of c_n, where any characters appearing in Table 2 are replaced with the corresponding representation.
This ensures that the resulting string is a valid XML attribute or element value token.

The r_n is equivalent to a string representation as indicated in Table 1

Table 1. Column Values String Result

Character replacement:

Depending on the value specified for the format-string, certain characters in column names and column values will be replaced to ensure that the column names form valid XML attribute values and the column values form valid XML element values.

Table 2. Character Replacements for XML Attribute Values and Element Values

Examples

Note:

REC2XML does not insert blank spaces or new line characters in the output.
All example output has been formatted to enhance readability.

1. Using the DEPARTMENT table in the sample database, format the department table row, except the DEPTNAME and LOCATION columns, for department 'D01' into an XML string. Since the data does not contain any of the characters which require replacement, the expansion factor will be 1.0 (no expansion).
   Also note that the MGRNO value is null for this row.

      SELECT REC2XML (1.0
      ,      'COLATTVAL'
      ,      ''
      ,      DEPTNO
      ,      MGRNO
      ,      ADMRDEPT)
      FROM   DEPARTMENT
      WHERE  DEPTNO = 'D01'

   This example returns the following VARCHAR(117) string:

      <row>
      <column name="DEPTNO">D01</column>
      <column name="MGRNO" null="true"/>
      <column name="ADMRDEPT">A00</column>
      </row>

2. A 5-day university schedule introduces a class named &43<FIE to a table called CL_SCHED, with a new format for the CLASS_CODE column.
   Using the REC2XML function, this example formats an XML string with this new class data, except for the class end time.

   The length attribute for the REC2XML call with an expansion factor of 1.0 would be 128 (11 for the <row> and </row> overhead, 21 for the column names, 75 for the <column name=, >, </column> and double quotation marks, 7 for the CLASS_CODE data, 6 for the DAY data, and 8 for the STARTING data).
   Since the & and < characters will be replaced, an expansion factor of 1.0 will not be sufficient.
   The length attribute of the function will need to support an increase from 7 to 14 bytes for the new format CLASS_CODE data.

   However, since it is known that the DAY value will never be more than 1 digit long, an unused extra 5 units of length are added to the total.
   Therefore, the expansion only needs to handle an increase of 2. Since CLASS_CODE is the only character string column in the argument list, this is the only column data to which the expansion factor applies.
   To get an increase of 2 for the length, an expansion factor of 9/7 (approximately 1.2857) would be needed. An expansion factor of 1.3 will be used.

        SELECT REC2XML (1.3
        ,              'COLATTVAL'
        ,              'record'
        ,               CLASS_CODE
        ,               DAY
        ,               STARTING)
        FROM   CL_SCHED
        WHERE  CLASS_CODE = '&43<FIE'

   This example returns the following VARCHAR(167) string:

        <record>
        <column name="CLASS_CODE">&amp;43&lt;FIE</column>
        <column name="DAY">5</column>
        <column name="STARTING">06:45:00</column>
        </record>

3. Assume that new rows have been added to the EMP_RESUME table in the sample database.
   The new rows store the resumes as strings of valid XML.
   The COLATTVAL_XML format-string is used so character replacement will not be carried out.
   None of the resumes are more than 3500 bytes in length.
   The following query is used to select the XML version of the resumes from the EMP_RESUME table and format it into an XML document fragment.

      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

   This example returns a row for each employee who has a resume in XML format.
   Each returned row will be a string with the following format:

      <row>
      <column name="EMPNO">{employee number}</column>
      <column name="RESUME_XML">{resume in XML}</column>
      </row>

   Where {employee number} is the actual EMPNO value for the column and {resume in XML} is the actual XML fragment string value that is the resume.