QUERY

The QUERY command is used to selectively interrogate values contained in the presently loaded XML document using XPath expressions.

You must provide a working list with the QUERY command in which the result value(s) will be returned to your program.  The working list will be filled with zero, one or more entries – one entry for each selected node (resulting from the query in the NODES keyword).

The working list must contain at least one field in which the value for the node specified by the NODESVALUE1 keyword will be placed.

It must contain one additional field for each of the NODESVALUE2 through NODESVALUE5 keywords for which values are specified.  For example, if you specify all five keywords NODESVALUE1 through NODESVALUE5, then your working list must provide five fields in which to receive the resulting values for each selected node.

                                                         Required 

  

 QUERY ---------- NODES ------------ xpath expression ------------->

 

  ----------------------------------------------------------------- 

                                                         Optional 

 

             >--- NODESVALUE1 ------- . ---------------------------> 

                                     *LOCALNAME

                                     *NAMESPACEPREFIX

                                     *NAMESPACEURI

                                     *NODENAME

                                     *NODEVALUE

                                     *XPATH

                                     *XPATH_CONCISE

                                      xpath expression

 

             >--- NODESVALUE2 ------ *LOCALNAME -------------------> 

                  NODESVALUE3        *NAMESPACEPREFIX

                  NODESVALUE4        *NAMESPACEURI

                  NODESVALUE5        *NODENAME

                                     *NODEVALUE

                                     *XPATH

                                     *XPATH_CONCISE

                                      xpath expression

 

Keywords

NODES

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.

NODESVALUE1

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.

Examples

The following examples execute a QUERY command that will query each <SalesOrder> element in the presently loaded document and, for each, return

 

The two values are returned for each "selected" node in the entries of the ORDERS working list.

RDML Example:

DEFINE FIELD(#ORDERNUM) TYPE(*CHAR) LENGTH(10) COLHDG('Order' 'Number') INPUT_ATR(LC)
DEFINE FIELD(#CUSTNUM) TYPE(*CHAR) LENGTH(10) COLHDG('Customer' 'Number') INPUT_ATR(LC)
DEF_LIST NAME(#ORDERS) FIELDS(#ORDERNUM #CUSTNUM) TYPE(*WORKING) ENTRYS(100)
 
     …
 
CLR_LIST NAMED(#ORDERS)
CHANGE FIELD(#JSMCMD) TO('''query nodes(//SalesOrder) nodesvalue1(@SONumber) nodesvalue2(Customer/@CustNumber) service_list(ORDERNUM,CUSTNUM)''')
USE BUILTIN(JSM_COMMAND) WITH_ARGS(#JSMCMD) TO_GET(#JSMSTS #JSMMSG #ORDERS)
 

RDMLX Example:

define field(#ORDERNUM) type(*CHAR) length(10) colhdg('Order' 'Number') input_atr(LC)
define field(#CUSTNUM) type(*CHAR) length(10) colhdg('Customer' 'Number') input_atr(LC)
def_list name(#ORDERS) fields(#ORDERNUM #CUSTNUM) type(*WORKING) entrys(100)
     …
 

clr_list named(#ORDERS)
#jsmcmdx := 'query nodes(//SalesOrder) nodesvalue1(@SONumber) nodesvalue2(Customer/@CustNumber) '
use builtin(JSMX_COMMAND) with_args(#jsmcmdx) to_get(#jsmsts #jsmmsg #orders)