Page History
...
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.
...
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 (unless *RELOAD is specified in the XMLOPTIONS parameter).
XMLOPTIONS: Optional (Advanced)
This parameter allows you to specify options that affect the way the XML document is loaded and queried.
...
Note that specifying this option will affect the form of XPath expressions necessary to successfully perform a given query. For more information, refer to:
3. *RELOAD
By default, 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. If, however, your solution re-uses the same XML document path and name but rewrites the file contents, then you may need to force the XML_QUERY activity to reload the XML document. You may do so by specifying the *RELOAD option on the first use of XML_QUERY after re-writing the XML document content.
...
| 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 used even if they changed from the earlier use (unless the *RELOAD option is included). |
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.
...
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.
...
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).
...
For more information about XPath expressions used with the XML_QUERY activity, refer to:
Alternatively, you may specify one of the following special values:
...
*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.
...
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.