Many people start developing code with an easy skeleton, then extending it and adding the more complex stuff. Why not do the same for an XQuery?
db2 => values xmlquery('$FOO' passing '<a><b>small test</b></a>' as "FOO")
------
<a><b>small test</b></a>
The above the scaled down version of the easy skeleton. It seems to work well. Now let's extend it:
db2 => values xmlquery('$FOO/a/b' passing '<a><b>small test</b></a>' as "FOO")
SQL16011N The result of an intermediate step expression in an XQuery path expression contains an atomic value. Error QName=err:XPTY0019. SQLSTATE=10507
Hm, that doesn't look expected, or does it? Looking into the XQuery and DB2 error description doesn't help either if you are dealing with such problems. The only thing that really helps here is experience. And it says: Remember to process well-formed documents!
In the above statements we pass a string in for XQuery processing. The simple skeleton works because we just return the string. However, the XQuery processor refuses to apply step expressions ("a" and "b" in our case) to the value "$FOO" because it is NOT an XML document, but a string. Hence the error message with the hint "contains an atomic value" (the string). What can we do? We can pass in a valid XML document:
db2 => values xmlquery('$FOO/a/b' passing xmlparse(document '<a><b>small test</b></a>') as "FOO")
------
<b>small test</b>
To produce an XML document out of a string we just use the XMLPARSE function as shown. And suddenly everything seems clear. Remember to process well-formed documents!