QUERY

The NODES keyword must specify an appropriately formulated XPath expression that identifies one or more nodes in the document for which values are to be returned.

The XPath expression is evaluated in the context of the "current" node.  By default the "current" node is the document node but it may be altered.  Refer to the SET command for information on setting the "current" node.

For more information about XPath expressions used with the XMLQueryService, refer to Quick Guide to XPath expressions for use with XMLQueryService.

If no nodes are selected when the XPath expression is evaluated, it is not treated as an error.  In this case, the command succeeds (with a returned status of 'OK') but the working list will be empty.

The NODESVALUE1 keyword identifies the value that is to be returned in the FIRST column of the provided working list for each "selected" node (that is, each node "selected" by evaluating the XPath expression specified in the NODES keyword).

The keyword is optional.  If the XPath expression specified in the NODES keyword fully identifies a set of elements or attributes whose value(s) are to be returned, there is no need to specify the NODESVALUE1 keyword.  The default value of '.' is, in fact, an XPath expression that specifies that the value of the context node (in this case, each "selected" node) is to be used.

If you specify this keyword, you should specify a further XPath expression that will be evaluated in the context of each "selected" node and that will identify a single element or attribute value relative to that node whose value is to be returned.

For more information about XPath expressions used with the XMLQueryService, refer to Quick Guide to XPath expressions for use with XMLQueryService.

Alternatively, you may specify one of the following special values:

*LOCALNAME: returns the node name (usually an element or attribute name) of the "selected" node, without any namespace prefix, if present;

*NAMESPACEPREFIX: returns the namespace prefix of the "selected" node;

*NAMESPACEURI: returns the namespace URI of the "selected" node;

*NODENAME: returns the node name (usually an element or attribute name) of the "selected" node;

*NODEVALUE: returns the value of the "selected" node, equivalent to using an XPath expression of '.';

*XPATH:
*XPATH_CONCISE: These values both return a generated XPath expression that uniquely identifies the "selected" node within the XML document.  The generated XPath expressions mostly use ordinal notation, and so are valid only for the specific node instance in the specific document instance.  Such generated expressions can be used, however, to iteratively process a document using further QUERY commands.  The second form generates an expression that is more concise (though less human-readable), particularly when the document is being processed in namespace-aware mode.  The concise form may be necessary for use with very complex XML documents that may otherwise generate XPath expressions that are longer than can be processed by the client application.

NODESVALUE2
NODESVALUE3
NODESVALUE4
NODESVALUE5

The keywords NODESVALUE2 through NODESVALUE5 are optional, but, if specified, they function similarly to the NODESVALUE1 keyword.

They allow you to specify further XPath expressions that (with the NODESVALUE1 keyword) identify up to five separate values relative to each "selected" node to be returned in the corresponding working list columns.

Unlike the NODESVALUE1 keyword, these keywords have no default.  If you do not specify them, they will not be used and the corresponding working list columns are not referenced or required.

If you do specify these keywords, you must do so contiguously.  The service will stop looking after the first keyword that is not used.  For example, if you specify NODESVALUE1 and NODESVALUE3, then the latter will be ignored because NODESVALUE2 was not used.