XML_QUERY
The XML_QUERY activity permits a LANSA Composer solution to selectively interrogate values contained in an XML document using XML Path Language (XPath) expressions.
XPath is an industry-standard syntax for constructing path expressions to select nodes in an XML document. It is beyond the scope of this document to provide a detailed description of XPath syntax. However, you can refer to the following heading for an introduction and examples:
The XML_QUERY activity is not suitable or intended for and usually would not be used to process the entire contents of an XML document. Rather it is intended for limited and selective interrogation of particular values from the XML document. In some applications, for example, it may be necessary for your LANSA Composer solution to determine certain key values from the XML document in order to decide how to proceed with further processing or for use in the course of further processing.
As an example, suppose you are building a solution that receives and processes sales orders in an agreed XML format.
One part of your solution might process the sales order XML document in its entirety, probably using a LANSA Composer Transformation Map to read the contents and update your application database.
However, in a separate step, your solution is required to email an acknowledgement of the order. In order to do so, the most convenient means to access the customer's return email address is directly from the corresponding element value in the original sales order XML document.
In such circumstances, your solution could use the XML_QUERY activity to selectively and efficiently address and retrieve just the value of the element (or attribute) in the sales order XML document that contains the customer's return email address and then pass that to the MAIL_SEND activity or whatever means your solution uses to generate and send the acknowledgement.
NOTE: The XML_QUERY activity loads the entire XML document into memory when processing your queries. Application performance can degrade when used with exceptionally large XML files.
The supplied processing sequence EXAMPLE_XML01 implements the XML_QUERY activity to interrogate the supplied tutorial orders XML file, TUTorder.xml. This is a working example that you may wish to use as a starting point for your exploration of the XML_QUERY activity.
INPUT Parameters:
XMLFILE : Required
This parameter specifies the path and name of the XML document file whose contents are to be queried.
Note that the XML_QUERY activity is optimised to avoid reloading the XML document if it is the same as the preceding usage in the same Processing Sequence.
XMLOPTIONS : Optional (Advanced)
This parameter allows you to specify options that affect the way the XML document is loaded and queried.
You may specify one or more of the values described below. Each value should be separated by at least one space, and you must specify quote marks around the complete string of value(s) to distinguish them from built-in variable names.
1. *VALIDATE
By default the XML document is parsed WITHOUT validating it against any DTD or schema it may reference. In this mode, the XML document is required to be well-formed, but conformance to the DTD or schema is NOT checked. For many typical applications of the XML_QUERY activity, validation is an unnecessary overhead. However, you can specify this option if you require validation to be performed.
2. *NAMESPACEAWARE
By default the XML document is parsed in a non-namespace-aware mode. For most cases, this simplifies the form of the XPath expressions necessary to perform a given query.
In some more complex documents (and especially for documents in which more than one namespace is referenced) it may be necessary to specify this option in order to load the document in namespace-aware mode.
Note that specifying this option will affect the form of XPath expressions necessary to successfully perform a given query. For more information, refer to:
NOTE: If the XML document specified by the XMLFILE parameter is already loaded by the preceding use of the XML_QUERY activity in the same processing sequence, the options specified in the XMLOPTIONS parameter will not be effective even if they changed from the earlier use.
CURRENTNODE : Optional (Advanced)
This parameter can be used to set the "current" node in the presently loaded XML document. The "current" node is the node to which the XPath expression in the QUERYNODES parameter will apply.
By default, the current node is the document node. The special value (and default) *DOCUMENT specifies the document node. Providing the XPath expression used in the QUERYNODES parameter is formulated appropriately, it can be executed against the document node, and in many cases this will be all that is needed.
However, in more complex applications of the XML_QUERY activity, particularly when used iteratively, you may specify an XPath expression that identifies a single node that is to be the current (context) node for the QUERYNODES expression. In particular, the XPath expressions generated when the special *XPATH or *XPATH_CONCISE values are used (in the QUERYNODESVALUE1 through QUERYNODESVALUE5 parameters) may be used in subsequent iterations as the current node for further queries.
If you use this parameter, you should specify an appropriately formulated XPath expression that identifies a single node in the document that is to be the "current" node. For more information about XPath expressions used with the XML_QUERY activity, refer to:
QUERYNODES : Required
The QUERYNODES parameter 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 using the CURRENTNODE parameter.
For more information about XPath expressions used with the XML_QUERY activity, refer to:
Note that if no nodes are selected when the XPath expression is evaluated, it is not treated as an error. Instead the RESULTCOUNT output parameter will be set to zero (0) and the RESULTVALUES1 through RESULTVALUES5 output parameters will not be filled.
QUERYNODESVALUE1 : Optional
The QUERYNODESVALUE1 parameter identifies the first of up to five values that are to be returned in the RESULTVALUES1 through RESULTVALUES5 output parameters for each "selected" node (that is, each node "selected" by evaluating the XPath expression specified in the QUERYNODES parameter).
This parameter is optional. If the XPath expression specified in the QUERYNODES parameter fully identifies a set of elements or attributes whose value(s) are to be returned, there is no need to specify the QUERYNODESVALUE1 parameter. The default value of *NODEVALUE 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 XML_QUERY activity, refer to:
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 held in a processing sequence variable.
QUERYNODESVALUE2
QUERYNODESVALUE3
QUERYNODESVALUE4
QUERYNODESVALUE5 : Optional
The parameters QUERYNODESVALUE2 through QUERYNODESVALUE5 are optional, but, if specified, they function similarly to the QUERYNODESVALUE1 parameter.
They allow you to specify further XPath expressions that (with the QUERYNODESVALUE1 parameter) identify up to five separate values relative to each "selected" node to be returned in the RESULTVALUES1 through RESULTVALUES5 output parameters for each "selected" node.
Unlike the QUERYNODESVALUE1 keyword, these keywords have no default. If you do not specify them, they will not be used and the corresponding output parameter is not filled.
If you do specify these parameters, you must do so contiguously. The activity will stop looking after the first parameter that is not used. For example, if you specify QUERYNODESVALUE1 and QUERYNODESVALUE3, then the latter will be ignored because QUERYNODESVALUE2 was not used.
OUTPUT Parameters:
RESULTCOUNT:
Upon successful completion this parameter will contain the count of nodes selected by the XPath expression specified in the QUERYNODES parameter.
RESULTVALUES1:
Upon successful completion this parameter will contain a list of the values, for each "selected" node, specified by QUERYNODESVALUE1 parameter.
RESULTVALUES2
RESULTVALUES2
RESULTVALUES4
RESULTVALUES5:
Upon successful completion these parameters will contain lists of the values, for each "selected" node, specified by the corresponding QUERYNODESVALUE2 through QUERYNODESVALUE5 parameter, if used.