Direct element constructors

Direct element constructors use an XML-like notation to create element nodes. The constructed node can be a simple element or a complex element that contains attributes, text content, and nested elements.

The result of a direct element constructor is a new element node that has its own node identity. All of the attribute and descendant nodes of the new element node are also new nodes that have their own identities.

Syntax

namespace-declaration-attribute

element-name: An XML qualified name (QName) that represents the name of the element to construct. The name that is used for element-name in the end tag must exactly match the name that is used in the corresponding start tag, including the prefix or absence of a prefix. If element-name includes a namespace prefix, the prefix is resolved to a namespace URI by using the statically known namespaces. If element-name has no namespace prefix, the name is implicitly qualified by the default element namespace. The expanded QName that results from evaluating element-name becomes the name of the constructed element node.

attribute-name: A QName that represents the name of the attribute to construct. If attribute-name includes a namespace prefix, the prefix is resolved to a namespace URI by using the statically known namespaces. If attribute-name has no namespace prefix, the attribute is in no namespace. The expanded QName that results from evaluating attribute-name becomes the name of the constructed attribute node. The expanded QName of each attribute must be unique, or the expression results in a error.
Each attribute in a direct element constructor creates a new attribute node, with its own node identity. The parent of the new attribute node is the constructed element node. The new attribute node has a type annotation of xs:untypedAtomic.

attribute-value

A string of characters that specify a value for the attribute. The attribute value can contain enclosed expressions (expressions that are enclosed in curly braces) that are evaluated and replaced by their value when the element constructor is processed. Predefined entity references and character references are also valid and are replaced by the characters that they represent. The following table lists special characters that are valid within attribute-value, but must be represented by double characters or an entity reference.

Table 1. Representation of special characters in attribute values
Character	Representation required in attribute values
{	two open curly braces ({{)
}	two closed curly braces (}})
<	<
&	&
"	" or two double quotation marks (""), if the delimiters of the attribute value are double quotation marks
'	' or two single quotation marks (''), if the delimiters of the attribute value are single quotation marks

xmlns

The word that begins a namespace declaration attribute. When specified as a prefix in a QName, xmlns indicates that the value of prefix-to-bind will be bound to the URI that is specified by URI-literal. This namespace binding is added to the statically known namespaces for the constructor expression, and for all of the expressions that are nested inside of the expression, unless the binding is overridden by a nested namespace declaration attribute. For example, the namespace declaration attribute

xmlns:metric
= "http://example.org/metric/units"

binds the prefix metric to the namespace http://example.org/metric/units.

When specified as the complete QName with no prefix, xmlns indicates that the default element namespace is set to the value of URI-literal. This default element namespace is in effect for this constructor expression and for all expressions that are nested inside of the constructor expression, unless the declaration is overridden by a nested namespace declaration attribute. For example, the namespace declaration attribute xmlns = "http://example.org/animals" sets the default element namespace to http://example.org/animals.

prefix-to-bind

The prefix that is to be bound to the URI that is specified for URI-literal. The value of prefix-to-bind cannot be xml or xmlns. Specification of either of these values results in an error.

URI-literal

A string literal (a sequence of zero or more characters that is enclosed in single quotation marks or double quotation marks) that represents a URI. The string literal value must be a valid URI. The value of URI-literal can be a zero-length string only when the namespace declaration attribute is used to set the default element namespace. Otherwise, specification of a zero-length string for URI-literal results in an error.

element-content

The content of the direct element constructor. The content consists of everything between the start tag and end tag of the constructor. The boundary-space declaration in the prolog controls the way in which boundary whitespace is handled in element constructors. The resulting content sequence is a concatenation of the content entities. Any resulting adjacent text characters, including text resulting from enclosed expressions, are merged into a single text node. Any resulting attribute nodes must come before any other content in the resulting content sequence.

element-content can consist of any of the following content:

Text characters

Text characters create text nodes. Adjacent text nodes are merged into a single text node. Line endings within sequences of characters are normalized according to the rules for end-of-line handling that are specified for XML 1.0. The following table lists special characters that are valid within element-content, but must be represented by double characters or an entity reference.

Table 2. Representation of special characters in element content
Character	Representation required in element content
{	two open curly braces ({{)
}	two closed curly braces (}})
<	<
&	&

Nested direct constructors

Any direct constructors can be nested within direct element constructors.

CDataSections

CDataSections are specified using the following syntax: <![CDATA[contents]]>. contents is a series of characters. The characters that are specified for contents, including special characters such as < and &, are treated as literal characters rather than as delimiters. The sequence ]]> terminates the CDataSection and is therefore not allowed within contents.

Character references and predefined entity references

During processing, predefined entity references and character references are expanded into their referenced strings.

Enclosed expressions

An enclosed expression is an XQuery expression that is enclosed in curly braces. For example, {5 + 7} is an enclosed expression. The value of an enclosed expression can be any sequence of nodes and atomic values. Enclosed expressions can be used within the content of a direct element constructor to compute the content and the attributes of the constructed node. For each node that is returned by an enclosed expression, a new copy is made of the node and all of its descendants, which retain their original type annotations. Any attribute nodes that are returned by element-content must be at the beginning of the resulting content sequence; these attribute nodes become attributes of the constructed element. Any element, content, or processing instruction nodes that are returned by element-content become children of the newly constructed node. Any atomic values that are returned by element-content are converted to strings and stored in text nodes, which become children of the constructed node. Adjacent text nodes are merged into a single text node.

Important: Because XMLQUERY, XMLEXISTS and XMLTABLE use single quotation marks to enclose an XQuery expression, single quotation marks (') within direct element constructors need to be replaced with two single quotation marks ('').

Examples

The following direct element constructor creates a book element. The book element contains complex content that includes an attribute node, some nested element nodes, and some text nodes:
```
<book isbn="isbn-0060229357">
    <title>Harold and the Purple Crayon</title>
    <author>
        <first>Crockett</first>
        <last>Johnson</last>
    </author>
</book>
```
The following example demonstrates the use of a CDATA section in a direct element constructor. CDATA sections are handled and stored as escaped text data. When the data is serialized, the contents of the CDATA sections display as escaped text. The CDATA sections are not preserved.
```
SELECT XMLQUERY('
   <TEST>
     {for $i in (1,2,3)
      return <a><![CDATA[<c>CDATA TEST!!!</c>]]></a> }
   </TEST>')
FROM SYSIBM.SYSDUMMY1;
```
The SELECT statement returns results similar to these:
```
<?xml version="1.0" encoding="UTF8"?>
<TEST>
  <a>&lt;c&gt;CDATA TEST!!!&lt;/c&gt;</a>
  <a>&lt;c&gt;CDATA TEST!!!&lt;/c&gt;</a>
  <a>&lt;c&gt;CDATA TEST!!!&lt;/c&gt;</a>
</TEST>
```
The following examples demonstrate how element content is processed in direct element constructors:
- The following expression constructs an element node that has one child, a text node that contains the value "1":
```
<a>{1}</a>
```
- The following expression constructs an element node that has one child, a text node that contains the value "1 2 3":
```
<a>{1, 2, 3}</a>
```
- The following expression constructs an element node that has one child, a text node that contains the value "123":
```
<c>{1}{2}{3}</c>
```
- The following expression constructs an element node that has one child, a text node that contains the value "1 2 3":
```
<b>{1, "2", "3"}</b>
```
- The following expression constructs an element node that has one child, a text node that contains the value "I saw 8 cats."
```
<fact>I saw {5 + 3} cats.</fact>
```