...
//Properties[DownFile='netethr0' || or DownFile='netethr1'] ~~~ ../Fields/Field[@Name='Network Card IP']/Value/text()
...
configuration1.xml has three channels. Channel 0 includes Modbus unit 1. Either Channel 1 includes units 1 and 2, or Channel 2 includes units 2 and 20. All four Modbus units have non-blank Poll Tables.
configuration2.xml has a single Master Channel 2, containing three Field Units.
configuration3.xml has a single Master Channel 2, but it doesn’t have any Modbus Field Units with non-blank Poll Tables.
Using last() and position()
Within qualifiers (predicates) of an XPath query, the “last()” identifier indicates the last item selected in the set of elements returned by an XPath statement. The “position()” identifier can be used to reference items within the returned set of elements.
Examples:
Select the first Ethernet node in a set://Node[@Type='Networks'] /Node [@Type='EtherPort'][1]
Select the last Ethernet node in a set://Node[@Type='Networks'] /Node [@Type='EtherPort'][last()]
Select the next to last Ethernet node in a set://Node[@Type='Networks'] /Node [@Type='EtherPort'][last()-1]
Select the first two Ethernet nodes in a set://Node[@Type='Networks'] /Node[@Type='EtherPort'] [position() <= 2]
Select the last two Ethernet nodes in a set://Node[@Type='Networks'] /Node[@Type='EtherPort'] [position() >= last()-1]
Querying a section of XML
If you wish the query to return a selection of XML text, rather than just an individual property value, just broaden the scope of the XPath query; that is, don't go as deep into the nested XML hierarchy of tags down to the last “/text()” element.
Selecting one or more XML text nodes will often be useful or necessary, such as:
When troubleshooting why an XPath query isn’t working as expected, you can remove parts from the end of a query until the ACM tool returns some intended XML content; then adjust the XPath query by adding on additional notation at the end, until the query selects the intended set of XML elements.
When using a Modify query to remove a section of XML (a whole ACE object or a table row), you must select the whole XML elements being removed.
When using a Modify query to replace a section of XML content, you must select the correct set of XML elements to be modified, so that the new XML text will replace it fully, so as to maintain the correct structure used by the ACE Editor.
When using a Modify query to add a section of XML content, you must use the Select Query to select the parent element (or set of parents) in order to add the new XML content underneath it (or them).
...
Querying a section of XML
If you wish the query to return a selection of XML text, rather than just an individual property value, just broaden the scope of the XPath query; that is, don't go as deep into the nested XML hierarchy of tags down to the last “/text()” element.
Selecting one or more XML text nodes will often be useful or necessary, such as:
When troubleshooting why an XPath query isn’t working as expected, you can remove parts from the end of a query until the ACM tool returns some intended XML content; then adjust the XPath query by adding on additional notation at the end, until the query selects the intended set of XML elements.
When using a Modify query to remove a section of XML (a whole ACE object or a table row), you must select the whole XML elements being removed.
When using a Modify query to replace a section of XML content, you must select the correct set of XML elements to be modified, so that the new XML text will replace it fully, so as to maintain the correct structure used by the ACE Editor.
When using a Modify query to add a section of XML content, you must use the Select Query to select the parent element (or set of parents) in order to add the new XML content underneath it (or them).
For instance, to return the XML text that represents the entire eth0 Ethernet configuration, you could use:
//Node[@Type='EtherPort' && Properties[Instance='0']]
or
//Node[DownFile='netethr0']
This would return all the XML text between <Node> and </Node>, such as:
<Node Type="EtherPort" Name="EtherPort0" Enabled="Yes">
(content omitted here for brevity)
</Node>
Using last() and position()
Within qualifiers (predicates) of an XPath query, the “last()” identifier indicates the last item selected in the set of elements returned by an XPath statement. The “position()” identifier can be used to reference items within the returned set of elements.
Examples:
Select the first Ethernet node in a set://Node[@Type='Networks'] /Node [@Type='EtherPort'][1]
Select the last Ethernet node in a set://Node[@Type='Networks'] /Node [@Type='EtherPort'][last()]
Select the next to last Ethernet node in a set://Node[@Type='Networks'] /Node [@Type='EtherPort'][last()-1]
Select the first two Ethernet nodes in a set://Node[@Type='EtherPort' && Properties[InstanceNetworks'] /Node[@Type='0EtherPort'] ]
...
[position() <= 2]
Select the last two Ethernet nodes in a set://Node[DownFile@Type='netethr0Networks']
This would return all the XML text between <Node> and </Node>, such as:
<Node Type="EtherPort" Name="EtherPort0" Enabled="Yes">
(content omitted here for brevity)
</Node>
/Node[@Type='EtherPort'] [position() >= last()-1]
Rules for dealing with ACE configurations
...
If the Column Header ends with square brackets enclosing a positive integer number (e.g. “[2]”), it will create multiple columns in Modify Results sheet based on the number in brackets. The columns will contain XML data matching the Select Query (XPath) criteria, and the maximum number of nodes that will be modified. If the Select Query returns fewer XML nodes than the defined columns, the rest of the columns will contain “n/a”. If the Select Query matches more XML nodes than the columns allow, the rest of the data will be omitted from Modify ResultsResults.
The Modify Results columns will contain XML data matching the Select Query (XPath) criteria (if using a simple query), or an indication of how many modifications have been done (such as “removed 12x” or “added 4x”). The number of results columns indicates the maximum number of nodes that will be modified.
Example:
If Column Header is "Ethernet IP[2]", it will create two columns on the Modify Results sheet.
The columns will be labeled "Ethernet IP(1)" and "Ethernet IP(2)". If the Select Query yields the IP address of Ethernet port objects, only the first two will be listed in these columns.
...
Add contents of a file, typically containing a chunk of XML text, as a child node(s) underneath each XML element selected by the Select Query.
...
The source XML file may contain a small section of XML text, or it may be a complete ACE XML configuration or template file (with an additional qualifying Source Query to select within the source XML for the content to be added).
self – The source XML data may also come from a different location within the same ACE configuration file being modified, using the word "self" for Source Data/File and a query defined under Source Query.
Note that the AddFromFile action will add the to be added).
self – The source XML data may also come from a different location within the same ACE configuration file being modified, using the word "self" for Source Data/File and a query defined under Source Query.
Note that the AddFromFile action will add the ENTIRE contents of the file (or elements specified by the Source Query) under ALL of the XML elements selected by the Select Query (up to the limit specified in the Column Header). Note, this is different from the behavior of the ModifyFromFile action.
The Modify Results sheet will return a value such as “added #x” if successful, where the # is the number of source elements to which the XML data was added; or it may be “n/a” if the Source or Select Query returns no XML elements.
AddFromFile[##]
Add contents of a file (same as AddFromFile) as a child node underneath each XML element selected by the Select Query. The ENTIRE contents of the file (or as part of the file specified by the Source Query) under ALL of the XML elements selected by the Select Query (up to the limit specified in the Column Header). This is different from the behavior of the ModifyFromFile action.
AddFromFile[##]
Add contents of a file (same as AddFromFile) as a child node underneath each XML element selected by the Select Query. The contents of the file (or part of the file specified by Source Query) is added ## number of times under each parent element in the Select Query. This is typically used to add multiple lines to a table, or multiple objects of the same kind at multiple Select Query insertion points.
Example:
Select Query: points to the <TABLE> property of an ACE table, which may select one or more ACE objects in each configuration.
Column Header: “AddRows[0]” - using “[0]” will modify all of the selected tables. Using “[2]” will only modify the first two selected tables. Omitting the square brackets will only modify the first selected <TABLE>
The “Mod Type” is defined as: AddFromFile[4]
Source Data/File identifies a source containing one or more <TR> elements to be added
Source Query: selects one or more <TR> rows in the source.
Running this Modify query will take data from the source file containing one or more <TR> elements and add all of those elements to every selected <TABLE>.
...
is added ## number of times under each parent element in the Select Query. This is typically used to add multiple lines to a table, or multiple objects of the same kind at one or more Select Query insertion points.
The Modify Results sheet will return a value such as “added #x” if successful, where the # is the number of source elements which were added (up to total number of Select Query elements * the number ## in the “AddFromFile[##]” Mod Type); or it may be “n/a” if the Source or Select Query returns no XML elements.
Example:
Select Query: points to the <TABLE> property of an ACE table, which may select one or more ACE objects in each configuration.
Column Header: “AddRows[0]” - using “[0]” will modify all of the tables in the Select Query. Using “[2]” will only modify the first two selected tables. Omitting the square brackets will only modify the first selected <TABLE>.
The “Mod Type” is defined as: AddFromFile[4]. The Source Data/File identifies a source containing one or more <TR> elements to be added (using optional Source Query to select one or more <TR> rows in the source).
Running this Modify query will take data from the source file containing one or more <TR> elements and add all of those selected <TR> elements to every selected <TABLE>.
In place of the number inside the [ ] brackets of “AddFromFile[]”, you can use a variable such as ${VAR02} that has previously been set to a certain value. See Using Variable Values for more explanation of the variable feature.
Add
Add contents of the Source Data/File column, typically containing a chunk of XML text, as child node(s) underneath each XML element selected by the Select Query (Source Query column is UNUSED).
This option differs from the AddFromFile options above, by allowing new text to be included directly in the ACM utility spreadsheet, thus not requiring an external file or Source Query to specify the data to be added. This is nice for relatively short sections of XML – however, Microsoft Excel is limited to 32767 characters in a cell.
The Modify Results sheet will return a value such as “added #x” if successful, where the # is the number of source elements to which the XML data was added; or it may be “n/a” if the Select Query returns no XML elements.
Modify
Change the selected XML node(s) to the text included under the Source Data/File column in the Modify sheet. The Source Data may be a simple text value, such as "10.63.191.26", or a section of XML text, such as "<Value>10.63.191.26</Value>". Source Query is UNUSED.
If the Source Data contains XML text, it should include only include one parent node element, which may include multiple children elements. If it the XML text includes multiple top-level sibling parent nodes (siblings), only the first will be used.
The Modify Results sheet will return a value such as “modified #x” if successful, where the # is the number of source elements which were modified; or it may be “n/a” if the Select Query returns no XML elements.
ModifyFromFile
Change the selected XML node(s) to the contents of a file.
The Source Data/File column contains may contain the filename (if located in using a partial pathname, relative to the Configuration Path configured on in the Setup sheetMain Menu), or a fully qualified directory and filename (such as C:\Data\mydata.XML). The Source Query is optional.
The source file may contain plain text, a small section of XML text, or another whole it may be a complete ACE XML configuration or template file (with an additional qualifying Source Query to select within the source XML for the content to be added).
self – The source XML data may also come from a different location within the same ACE configuration file being modified, using the word "self" for Source Data/File and a query defined under Source Query.
Note that if the source data used with the ModifyFromFile actions contains plain text or a single top-level XML node, then the entire source data will be used to modify ALL Select Query nodes.
But if the source data contains multiple top-level XML sibling nodes, EACH sibling node will be used to modify EACH Select Query node, one for one, until either the Select Query nodes or the Source nodes have been exhausted. After that, no more nodes will be modified. This Note, this is different behavior from the AddFromFile actions.
Examples:
If the source data contains "<Parent><Sibling1></Sibling1><Sibling2></Sibling2></Parent>", the data is considered a single XML element called "<Parent>". This single element will substitute for (modify) ALL Select Query nodes (up to the limit specified by the Column Header).
...
Or, it may remove children of those nodes, by adding an additional XPath query under the Source Query column. If the Source Query column is non-blank, it will be added to the Select Query to choose child elements of Select Query.
If the Source Data/File column contains a number (or variable such as ${VAR02} containing a number), up to that many nodes will be removed at EACH Select Query location.If the Source Query column is non-blank, it will be added to the Select Query to choose child elements of Select Query.
Examples:
1. Select Query points to a set of <TABLE><TR> nodes. A Remove action (with no Source Data or Source Query) will delete all selected <TR> nodes, up to the number of nodes included in the Column Header brackets [ ] (or all selected <TR> nodes, if Column Header ends with [0]).
2. Select Query points to <TABLE> node, the parent of <TR>. A Remove action with "5" in Source Data and "./TR" in Source Query will remove ONLY the first five <TABLE><TR> elements under each <TABLE> node selected by the Select Query.
SaveToVAR
Save a value or block of XML text retrieved by Select Query into a numbered variable. The value of the variable can be used in later query or modify actions as a substitutable parameter. Source Data/File column contains an integer number, specifying the variable to use. Source Query is UNUSED.
The Modify Results sheet will include the content of the variable that was saved.
Example:
Select Query retrieves a "/count()" of objects or a value (such as "10.63.191.26"). Source Data column is "2". The value returned by the Select Query is stored into variable #2, which can be retrieved later with "${VAR02}".
See Using Variable Values for more explanation of the variable feature.
...
Save the contents of the Select Query column into a numbered variable. The Select Query, in this unique case only, is NOT an XPath query, but a fixed value or text string. The value of the variable can be used in later query or modify actions as a substitutable parameter. Source Data/File column contains an integer number, specifying the variable to use. Source Query is UNUSED.
The Modify Results sheet will include the content of the variable that was saved.
Example:
The Select Query column contains a value of “10”. Source Data column is "2". The value of 10 is stored into variable #2, which can be retrieved later with "${VAR02}".
See Using Variable Values for more explanation of the variable feature.
...