DB2 Version 9.7 for Linux, UNIX, and Windows

db2-xdb:expression decomposition annotation

The db2-xdb:expression annotation specifies a customized expression, the result of which is inserted into the table this element is mapped to.

db2-xdb:expression belongs to the set of decomposition annotations that can be added to an XML schema document to describe the mappings between elements and attributes of XML documents to DB2® base tables. The decomposition process uses the annotated XML schema to determine how elements and attributes of an XML document should be decomposed into DB2 tables.

Annotation type

Attribute of <xs:element> or <xs:attribute>, or optional child element of <db2-xdb:rowSetMapping>, effective only on annotations that include a column mapping

How to specify

db2-xdb:expression is specified in any of the following ways (where value represents a valid value for the annotation):

<xs:element db2-xdb:expression="value" db2-xdb:column="value" />
<xs:attribute db2-xdb:expression="value" db2-xdb:column="value" />

<db2-xdb:rowSetMapping>
  <db2-xdb:rowSet>value</db2-xdb:rowSet>
  <db2-xdb:column>value</db2-xdb:column>
  <db2-xdb:expression>value</db2-xdb:expression>
  …
</db2-xdb:rowSetMapping>

Namespace

http://www.ibm.com/xmlns/prod/db2/xdb1

Valid values

The value of db2-xdb:expression must have the following syntax, which constitutes a subset of SQL expressions:

expression := function (arglist) | constant | $DECOMP_CONTENT | $DECOMP_ELEMENTID |
   $DECOMP_DOCUMENTID | (scalar-fullselect) | expression operator expression |
   (expression) | special-register | CAST (expression AS data-type) |
   XMLCAST (expression AS data-type) | XML-function

operator := + | - | * | / | CONCAT

arglist := expression | arglist, expression

Details

The db2-xdb:expression annotation enables you to specify a customized expression, which is applied to the content of the XML element or attribute being annotated when $DECOMP_CONTENT is used. The result of evaluating this expression is then inserted into the column specified during decomposition.

This annotation is also useful in cases where you want to insert constant values (such as the name of an element), or generated values that do not appear in the document.

db2-xdb:expression must be specified using valid SQL expressions, and the type of the evaluated expression must be statically determinable and compatible with the type of the target column that the value is to be inserted into. The following subset of SQL expressions are supported; any other SQL expressions not described below are unsupported and have an undefined behavior in the context of this annotation.

function (arglist): A built-in or user-defined scalar SQL function. The arguments of a scalar function are individual scalar values. A scalar function returns a single value (possibly null). Refer to the documentation on functions for more information.
constant: A value, sometimes called a literal, that is a string constant or a numeric constant. Refer to the documentation on constants for more information.
$DECOMP_CONTENT: The value of the mapped XML element or attribute from the document, constructed according to the setting of the db2-xdb:contentHandling annotation. Refer to the decomposition keywords documentation for more information.
$DECOMP_ELEMENTID: A system-generated integer identifier that uniquely identifies within the XML document, the element or attribute this annotation describes. Refer to the decomposition keywords documentation for more information.
$DECOMP_DOCUMENTID: The string value specified in the documentid input parameter of the xdbDecompXML stored procedure, which identifies the XML document being decomposed. Refer to the decomposition keywords documentation for more information.
(scalar-fullselect): A fullselect, enclosed in parentheses, that returns a single row consisting of a single column value. If the fullselect does not return a row, the result of the expression is the NULL value.
expression operator expression: The result of two supported expression operands, as defined in the supported values listing above. Refer to the documentation on expressions for details on expression operations.
(expression): An expression enclosed in parentheses that conforms to the list of supported expressions defined above.
special-register: The name of a supported special register. This setting evaluates to the value of the special register for the current server. Refer to the documentation for special registers for a complete listing of supported special registers.
CAST (expression AS data-type): The expression cast to the specified SQL data type, if the expression is not NULL. If the expression is NULL, the result is a null value of the SQL data type specified. When inserting a NULL value into a column, the expression must cast NULL into a compatible column type (for example: CAST (NULL AS INTEGER), for an integer column).
XMLCAST (expression AS data-type): The expression cast to the specified data type, if the expression is not NULL. The expression or the target data type must be the XML type. If the expression is NULL, the target type must be XML, and the result is a null XML value.
XML-function: Any supported SQL/XML function.

Example

The following example shows how the db2-xdb:expression annotation can be used to apply a value from the XML document to a user-defined function. The result returned from the UDF is then inserted into the database, rather than the value from the document itself. A section of the annotated schema is presented first.

<xs:element name="author">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="firstname" type="xs:string" />
      <xs:element name="lastname" type="xs:string" />
      <xs:element name="activeStatus" type="xs:boolean" />
      <xs:attribute name="ID" type="xs:integer"
                    db2-xdb:rowSet="AUTHORS" db2-xdb:column="NUMBOOKS"
                    db2-xdb:expression="AuthNumBooks (INTEGER ($DECOMP_CONTENT))" />
    </xs:sequence>
  </xs:complexType>
</xs:element>

Assume that there is a user-defined function called AuthNumBooks that takes an integer parameter, which represents the author's ID, and returns the total number of books that author has in the system.

The <author> element that is being mapped is presented next.

<author ID="22">
  <firstname>Ann</firstname>
  <lastname>Brown</lastname>
  <activeStatus>1</activeStatus>
</author>

$DECOMP_CONTENT is replaced with the value "22" from the instance of the ID attribute. Because $DECOMP_CONTENT is always substituted with a character type, and because the AuthNumBooks UDF takes an integer parameter, the db2-xdb:expression annotation must cast $DECOMP_CONTENT to an integer. Assume that the UDF returns the integer 8 for this author whose ID is 22; 8 is then inserted into the NUMBOOKS column of the AUTHORS table, as shown next.

Table 1. AUTHORS
AUTHID	FIRSTNAME	SURNAME	ACTIVE	NUMBOOKS
NULL	NULL	NULL	NULL	8