...

After setting up the paths, filter, and file suffix, click the "List Configurations" button. This will generate a list of configuration names based on the above criteria. The configuration names appear on the Configurations sheet.

Configurations Sheet

The Configurations sheet lists the names and descriptions of XML configuration files that will be queried or modified by this utility. Only ACE XML configurations (with a TemplateProperties/Description XML field) will be included automatically in the list. You can click on the tab for the Configurations sheet at any time, or click the "Go to Configurations" button.

After clicking the "List Configurations" button on the Main Menu page, you will automatically be taken Click the “Go to Configurations“ button to switch to the Configurations sheet.

...

On the Configurations sheet, there are three columns:

Include

The configurations are automatically marked with "1".
The Query, Modify, or L5X actions will only act on the configurations with a “1” in this column.
You can exclude configurations by just changing the "1" to something else, or deleting unneeded rows, or by clearing cell contents. Any row with a blank Configuration Name will be treated as the end of the list for all actions.

Configuration Name

The configuration names listed are obtained from the Configuration Path and FileName Filter on the Main Menu dialog. If there are many configurations listed that you don't want to query, you can change the filter and re-run the list.
You can also manually enter configuration names in this column – it is not required to use the "List Configurations" button.

Description

The Description column is obtained from the <TemplateProperties> property in the ACE XML configuration file. This column has no purpose in the ACM utility, other than for information.

The Configurations sheet includes buttons that will take you to the Query, Modify, or L5X Tags sheet in order to set up queries or other actions.

Query Sheet

The Query sheet is used to request information from each XML configuration included on the Configurations sheet.

• Query rows must begin on the visible row immediately below the "Column Header" (row 15).

• After defining the Select Query (one or more rows), click the "Run Query" button. This will request information using each Select Query from each configuration on the Configurations sheet that has a "1" in the Include column.

• The results of all queries for all configurations will be stored on the Query Results sheet.

...

Query definitions consist of 4 columns, with one Query definition per row:

Column Header

The Column Header defines one or more columns of data to be stored on the Query Results sheet. The Column Header is just descriptive, but does need to be non-blank.

...

Program Option: Select either “Query Configurations,” Modify Configurations,” or “L5X Tool” for a list of corresponding options.

• The “Go To Query Setup” switches to the Query sheet (same for Modify sheet).

• The “Go To Query Results” switches to the Query Results sheet (same for Modify Results sheet).

• The “Run Query” or “Run Modify Query” perform the same function as the same-named buttons on each of those sheets - run the set of queries defined for either Query or Modify.

• The “Select L5X Tags List” switches to the L5X Tags sheet.

• The “L5X Import” and “Save to XML” button performs the same function as the same-named buttons on the L5X Tags sheet.

...

Configurations Sheet

The Configurations sheet lists the names and descriptions of XML configuration files that will be queried or modified by this utility. Only ACE XML configurations (with a TemplateProperties/Description XML field) will be included automatically in the list. You can click on the tab for the Configurations sheet at any time, or click the "Go to Configurations" button.

After clicking the "List Configurations" button on the Main Menu page, you will automatically be taken to the Configurations sheet.

...

On the Configurations sheet, there are three columns:

Include

The configurations are automatically marked with "1".
The Query, Modify, or L5X actions will only act on the configurations with a “1” in this column.
You can exclude configurations by just changing the "1" to something else, or deleting unneeded rows, or by clearing cell contents. Any row with a blank Configuration Name will be treated as the end of the list , and Run Query definitions following a Column Header will not be run. This can be used (by inserting a blank row) to limit the list Query definitions for testing, then delete the blank row to run subsequent queries.

If the Column Header ends with square brackets enclosing a positive integer number (e.g., “[2]”), it will create multiple columns in the Query Results sheet based on the number in brackets. The columns will contain XML data matching the Select Query (XPath) criteria.

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 Query Results.

Example:

If Column Header is "Ethernet IP[2]", it will create two columns on the Query Results page. 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.

Be aware that if using a fixed number of columns and the Query that you are using returns more XML nodes than are allowed to be displayed by the Column Header, it may give the false impression that there aren't as many nodes as there actually are.

...

Example:

If Column Header is "Ethernet IP[0]", it will create one column on the Query Results sheet. The column will be labeled "Ethernet IP" and may include contents such as: "{10.95.213.86}{192.168.100.1}".

Description

This column has no purpose and is only descriptive to help document what the Query definition is used for.

Select Query

The Select Query column uses XPath syntax to define selection criteria for one or more XML nodes in each configuration file. The selected node(s) will have their text stored in the Query Results page. See the section Understanding XPath Queries for help in understanding XPath query format used in the ACE Management Utility.

If there is a row with a non-blank Column Header but a blank Select Query, it will create an empty column under its column header on the Query Results page.

Condition Query

The Condition Query column is currently unused.

Understanding XPath Queries

XML is a structured document format that uses a nested hierarchy of parent/child elements. The Elecsys ACE Editor (version 3.0 and higher) uses XML for both the template and configuration definitions.
XPath is a very powerful query language that allows a complex set of criteria to search an XML document. See www.w3schools.org for more generic information and tutorials on XML and XPath.

XML Structure

When defining XPath queries, it is important to understand the XML structure of the ACE configurations.

Example:

An EtherPort object in the ACE Editor defines the Ethernet network interface. Below is a picture of the ACE properties for Ethernet object with Type=EtherPort and Instance=0 (DownFile=netethr0).

...

This object is represented in the XML configuration file using the following XML text (abbreviated here to include only a few properties):

<Node Type="EtherPort" Name="EtherPort0" Enabled="Yes">

<Properties>

<Instance>0</Instance>

<DownFile>netethr0</DownFile>

</Properties>

<Fields>

<Field Name="Network Card IP" Width="2147483647" Type="IPADDRESS">

<Value>10.63.191.26</Value>

</Field>

<Field Name="Subnet Mask" Width="2147483647" Type="IPADDRESS">

<Value>255.255.0.0</Value>

</Field>

<Field Name="Default Gateway" Width="2147483647" Type="IPADDRESS">

<Value>0.0.0.0</Value>

</Field>

</Fields>

...

• Elements, defined by a tag structure (such as <Node>, <Properties>, and <Field>)

• Attributes (such as Type, Name, and Enabled) with values (such as “EtherPort” and “Yes”)

• Text content within XML elements (such as "netethr0", "10.63.191.26", and "EtherPort0").

All XML elements must have an opening and closing tag (such as <Node> and </Node>) and be properly nested. Note that XML is case-sensitive, so you must ensure that all queries use the proper case.

XPath Example 1 – selection of XML nodes for Ethernet IP Address

On the Query or Modify sheet, you can define a Select Query such as:

//Node[@Type='EtherPort' and Properties/Instance='0' ] /Fields/Field[@Name='Network Card IP']/Value/text()

• This XPath query first locates all XML elements with a tag <Node>. Every visible object in the ACE Configuration Editor starts with <Node>. The initial double forward slashes (//) at the beginning of the XPath statement finds any element called <Node>, no matter how deeply it is nested in the XML document. Using a single forward slash (/) would only include elements beginning with the topmost (root) element of the XML file.

• The above XPath query is further limited using square brackets [ ] with an XPath qualifier (predicate). This example includes only <Node> elements which have an attribute (indicated with the leading “@”) of ‘Type=EtherPort', and a child element with a ‘<Properties><Instance>’ tag containing a value of 0. This defines the ACE Ethernet object with an instance number of 0.

• Note that either single-quotes or double-quotes may be used XPath queries, but they must be used consistently in matched sets.

• For any <Node> (one or more) matching the above criteria, the XPath query further limits the selection to <Node> elements that have direct child elements <Fields><Field> (with attribute 'Name=”Network Card IP’). This selects for the XML element containing the IP address of the Ethernet object.

• Note that the <Field> elements of an ACE object include all the first-level properties shown in the ACE Editor. In this example, this includes the IP address, Subnet Mask, and Default Gateway of an Ethernet object definition.

• After finding this matching <Field> (one or more), the XPath query ending with /Value/text() returns the text included between the <Value> and </Value> tags.

• Note that when selecting plain text between opening and closing tags, the query must end with “/text()”. It is not typically necessary to use “/text()” inside of square bracket qualifiers, as shown with Properties/Instance='0'.

XPath Example 2 – using chained XPath queries

A special notation used in the ACE Configuration Management Utility (not part of XPath syntax) is the "~~~" notation, which may be used to chain together two XPath queries, if necessary. The above example used a single XPath query to request the IP address of EtherPort object(s) with Instance=0. The same query could be done in the ACM using two separate XPath statements, joined together sequentially with "~~~". The ACM Utility only currently supports up to two joined statements.

//Properties[DownFile='netethr0' || DownFile='netethr1'] ~~~ ../Fields/Field[@Name='Network Card IP']/Value/text()

• In this example, the first XPath statement selects the <Properties> element from up to two different ACE "EtherPort" objects, containing a child <DownFile> tag with text of either ‘netethr0’ or ‘netethr1’. This is equivalent to selecting an <Instance> tag with text of either ‘0' or '1’.

• After the first XPath query has selected one or more <Properties> elements, the second XPath statement begins the set of selected elements and performs an additional qualifying selection. In this case, the second statement begins with "..", which moves up a single level to select the parent <Node> of each of the <Properties> elements. (Multiple sets of ../../../ can be used to move up more than one level.)

• Then the second XPath query descends through the children of those <Node> elements: <Fields><Field> (where the attribute is qualified to included only Name=”Network Card IP”), and the text within its <Value> element.

• After applying both XPath queries, the query will have selected two nodes: the IP address of both "netethr0" and "netethr1" (if they both exist in the ACE configuration).

• Note, again, that the “~~~” notation is part of ACM only and is not standard XPath.

XPath Example 3

As a second example, we can define a Select Query similar to the example above using only a single XPath statement, not requiring the chaining of two statements (i.e., avoiding the "~~~" notation that is unique to the ACE Management Utility).

(For the more technically minded, the reason the first example required the chaining of two queries is that Microsoft Excel/Visual Basic's XPath handling doesn't appear to support the "/../" notation in the middle of an XPath query. Thus, because we started the query at the <Properties> level and had to back up to its parent, it required a second query to ascend to the parents of the nodes selected in the first query.)

...

//Node[@Type='EtherPort' && Properties[Instance='0' || Instance='1']]for all actions.

Configuration Name

The configuration names listed are obtained from the Configuration Path and FileName Filter on the Main Menu dialog. If there are many configurations listed that you don't want to query, you can change the filter and re-run the list.
You can also manually enter configuration names in this column – it is not required to use the "List Configurations" button.

Description

The Description column is obtained from the <TemplateProperties> property in the ACE XML configuration file. This column has no purpose in the ACM utility, other than for information.

The Configurations sheet includes buttons that will take you to the Query, Modify, or L5X Tags sheet in order to set up queries or other actions.

...

Query Sheet

The Query sheet is used to request information from each XML configuration included on the Configurations sheet.

After setting up the list of configurations on the Configurations sheet, define one or more XML queries on the Query sheet.

• Query rows must begin on the visible row immediately below the "Column Header" (row 15).

• After defining the Select Query (one or more rows), click the "Run Query" button. This will request information using each Select Query from each configuration on the Configurations sheet that has a "1" in the Include column.

• The results of all queries for all configurations will be stored on the Query Results sheet.

...

Query definitions consist of 4 columns, with one Query definition per row:

Column Header

The Column Header defines one or more columns of data to be stored on the Query Results sheet. The Column Header is just descriptive, but does need to be non-blank.

Any row containing a blank Column Header will be treated as the end of the list, and Run Query definitions following a Column Header will not be run. This can be used (by inserting a blank row) to limit the list Query definitions for testing, then delete the blank row to run subsequent queries.

If the Column Header ends with square brackets enclosing a positive integer number (e.g., “[2]”), it will create multiple columns in the Query Results sheet based on the number in brackets. The columns will contain XML data matching the Select Query (XPath) criteria.

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 Query Results.

Example:

If Column Header is "Ethernet IP[2]", it will create two columns on the Query 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.

Be aware that if using a fixed number of columns and the Query that you are using returns more XML nodes than are allowed to be displayed by the Column Header, it may give the false impression that there aren't as many nodes as there actually are.

If the Column Header ends with [0], it will create only a single column in Query Results. If the Select Query returns multiple elements, the contents of each element will be included in the single column, separated by braces { }. If the Select Query returns only a single node, it will be shown without braces.

Example:

If Column Header is "Ethernet IP[0]", it will create one column on the Query Results sheet. The column will be labeled "Ethernet IP" and may include contents such as: "{10.95.213.86}{192.168.100.1}".

Description

This column has no purpose and is only descriptive to help document what the Query definition is used for.

Select Query

The Select Query column uses XPath syntax to define selection criteria for one or more XML nodes in each configuration file. The selected element(s) (one or more, depending on the Column Header) will have their text stored in the Query Results page. See the section Understanding XPath Queries for help in understanding XPath query format used in the ACE Configuration Management Utility.

If there is a row with a non-blank Column Header but a blank Select Query, it will create an empty column under its column header on the Query Results sheet.

Condition Query

The Condition Query column is currently unused.

...

Understanding XPath Queries

XML is a structured document format that uses a nested hierarchy of parent/child elements. The Elecsys ACE Editor (version 3.0 and higher) uses XML for both the template and configuration definitions.
XPath is a very powerful query language that allows a complex set of criteria to search an XML document. See www.w3schools.org for more generic information and tutorials on XML and XPath.

XML Structure

When defining XPath queries, it is important to understand the XML structure of the ACE configurations.

Example:

An EtherPort object in the ACE Editor defines the Ethernet network interface. Below is a picture of the ACE properties for Ethernet object with Type=EtherPort and Instance=0 (DownFile=netethr0).

...

This object is represented in the XML configuration file using the following XML text (abbreviated here to include only a few properties):

<Node Type="EtherPort" Name="EtherPort0" Enabled="Yes">

<Properties>

<Instance>0</Instance>

<DownFile>netethr0</DownFile>

</Properties>

<Fields>

<Field Name="Network Card IP" Width="2147483647" Type="IPADDRESS">

<Value>10.63.191.26</Value>

</Field>

<Field Name="Subnet Mask" Width="2147483647" Type="IPADDRESS">

<Value>255.255.0.0</Value>

</Field>

<Field Name="Default Gateway" Width="2147483647" Type="IPADDRESS">

<Value>0.0.0.0</Value>

</Field>

</Fields>

</Node>

XML syntax consists of:

• Elements, defined by a tag structure (such as <Node>, <Properties>, and <Field>)

• Attributes (such as Type, Name, and Enabled) with values (such as “EtherPort” and “Yes”)

• Text content within XML elements (such as "netethr0", "10.63.191.26", and "EtherPort0").

All XML elements must have an opening and closing tag (such as <Node> and </Node>) and be properly nested. Note that XML is case-sensitive, so you must ensure that all queries use the proper case.

XPath Example 1 – selection of XML nodes for Ethernet IP Address

On the Query or Modify sheet, you can define a Select Query such as:

//Node[@Type='EtherPort' and Properties[Instance='0' or Instance='1']] /Fields/Field[@Name='Network Card IP']/Value/text()

• This XPath query first locates all XML elements with a tag <Node>. Every visible object in the ACE Configuration Editor starts with <Node>. The initial double forward slashes (//) at the beginning of the XPath statement finds any element called <Node>, no matter how deeply it is nested in the XML document. Using a single forward slash (/) would only include elements beginning with the topmost (root) element of the XML file.

• The above XPath query is further limited using square brackets [ ] with an XPath qualifier (predicate). This example includes only <Node> elements which have an attribute of ‘Type=EtherPort'. Attributes are indicated in XPath with the leading “@”. The query is further qualified to include only child elements with a ‘<Properties>/<Instance>’ tag containing a value of either 0 or 1. This defines the ACE Ethernet objects that configure eth0 or eth1 in Linux.

• Note that either single-quotes or double-quotes may be used XPath queries, but they must be used consistently in matched sets.

• For any <Node> (one or more) matching the above criteria, the XPath query further limits the selection to <Node> elements that have direct child elements <Fields><Field> (with attribute 'Name=”Network Card IP’). This selects for the XML element containing the IP address of the Ethernet object.

• Note that the <Field> elements of an ACE object include all the first-level properties shown in the ACE Editor. In this example, this includes the IP address, Subnet Mask, and Default Gateway of an Ethernet object definition.

• After finding this matching <Field> (one or more), the XPath query ending with /Value/text() returns the text included between the <Value> and </Value> tags.

• Note that when selecting plain text between opening and closing tags, the query must end with “/text()”. It is not typically necessary to use “/text()” inside of square bracket qualifiers, as shown with Instance='0'. Using “/text()” is only allowed for plain text; it is not allowed and should be omitted when the selected element is XML text or an XML attribute.

XPath Example 2 – using chained XPath queries

A special notation used in the ACE Configuration Management Utility (not part of XPath syntax) is the "~~~" notation, which may be used to chain together two XPath queries, if necessary. The above example used a single XPath query to request the IP address of EtherPort object(s) with Instance=0. The same query could be done in the ACM using two separate XPath statements, joined together sequentially with "~~~". The ACM Utility only currently supports up to two joined statements.

//Properties[DownFile='netethr0' || DownFile='netethr1'] ~~~ ../Fields/Field[@Name='Network Card IP']/Value/text()

• In this example, the first XPath statement selects the <Properties> element from up to two different ACE "EtherPort" objects, containing a child <DownFile> tag with text of either ‘netethr0’ or ‘netethr1’. This is equivalent to selecting an <Instance> tag with text of either ‘0' or '1’.

• After the first XPath query has selected one or more <Properties> elements, the second XPath statement begins the set of selected elements and performs an additional qualifying selection. In this case, the second statement begins with "..", which moves up a single level to select the parent <Node> of each of the <Properties> elements. (Multiple sets of ../../../ can be used to move up more than one level.)

• Then the second XPath query descends through the children of those <Node> elements: <Fields><Field> (where the attribute is qualified to included only Name=”Network Card IP”), and the text within its <Value> element.

• After applying both XPath queries, the query will have selected two nodes: the IP address of both "netethr0" and "netethr1" (if they both exist in the ACE configuration).

• Note, again, that the “~~~” notation is part of ACM only and is not standard XPath.

(For the more technically minded, the “~~~” notation was implemented because an earlier version of Microsoft Excel/Visual Basic's XPath handling didn’t support using "/../" notation in the middle of an XPath query, to back up a level from a selected node. Now, this appears to be supported. There is still a use for the chained ~~~ queries, at least when getting an array of “counts.” See example further down.)

What is the result?

Let's put together all the above and see what data may be obtained in the Query Results sheet for Example 1 or Example 2.

Using a single row in the Query (or Modify) sheet with the XPath query in Example 1, we will have the following Query definition:

After running the query, assuming the configuration(s) listed on the Configurations sheet have zero or more Ethernet objects configured, the resulting data on the Query Results sheet might look something like this:

Note that in this example, we purposely defined the Column Header to include three columns, but the query will only return (at most) two Ethernet elements, and the second configuration only has one. The remaining columns will be included in Query Results, but will be populated with "n/a" to indicate there are no XML nodes matching the XPath criteria defined in Select Query.

If, instead, the Column Header had been set as "IP Address" (no square brackets), the data would have included only a single column of “IP Address,” containing the first Ethernet port’s IP address from each configuration, or “n/a”. The additional matching IP addresses (such as “192.168.1.1”) will not appear in the results.

If the Column Header had been set as “IP Address[0]” (with '0' in square brackets), the resulting data in Query Results would have included only a single column of “IP Address,” containing all matching Ethernet port IP addresses.

Retrieving an attribute

If you wish to return the value of an attribute, as opposed to the text content inside a set of an XML “<tag></tag>” structure, use the "@" symbol plus the attribute name. For instance, to select the visible name of the ACE object representing the eth0 Ethernet configuration, you might use a Select Query like:

//Node[@Type='EtherPort' and Properties[Instance=0]]/@Name

or

//Node[Properties/DownFile='netethr0']/@Name

or

//Properties[DownFile='netethr0'] /../@Name

Each of the above three XPath examples does the exact same thing. In the first two cases, the parent EtherPort <Node> is selected with qualifiers, then the “Name” attribute of <Node> is returned. In the third case, the EtherPort <Properties> element is selected, then the next part of the query moves up to the parent <Node> and selects its “Name” attribute.

The "/text()" suffix after the “@Name” attribute is NOT allowed for retrieving attribute values. It is only allowed (and required) when returning plain text content inside of XML tags.

Getting a count of nodes

If you wish to retrieve the number of matching nodes for an XPath query, rather than the text data for them, add "/count()" at the end of a Select Query (total of 8 characters, with no spaces). Note, this is a unique notation of the ACM Utility (not part of XPath syntax).

As an example, define a Column Header titled "# of IP addresses" and a Select Query listed below:

//Node[@Type='EtherPort'] /Fields/Field[ @Name='Network Card IP'] /Value/text()

In this case, we start by selecting all <Node> elements in the document (i.e., every object in ACE starts with <Node>), but with the qualifiers given in brackets [ ].

• The first qualifier is that the <Node> must have an attribute "Type" with a value of "EtherPort". This will select only EtherPort ACE objects. Note that the "@" symbol is required in "@Type='EtherPort'" because Type is an attribute as opposed to an element.

• The second qualifier is that the <Node> must have a child element <Properties>, which in turn must have a child element <Instance> with a text value of either "0" or "1". This is a different way of selecting both the eth0 and eth1 Ethernet object definitions (we could have used the <DownFile> element instead).

• So far, we have selected two <Node> XML elements. Everything else in the XPath query up to this point (between the nested sets of square brackets) consists of qualifiers to determine which <Nodes> to pick. Next, the XPath statement descends into the children and grandchildren of those two <Node> elements, by selecting the elements:
  <Fields>, <Field> (whose Name attribute is "Network Card IP"), <Value>, and finally the text() content of <Value> (the IP address of the Ethernet configuration).

What is the result?

Let's put together all the above and see what data may be obtained in the Query Results sheet.

Using a single row in the Query (or Modify) sheet with one of the above two examples, we will have the following Query definition:

...

Column Header

...

Description

...

Select Query

...

Condition Query

...

IP Address[3]

...

Get up to three IP addresses

...

//Node [@Type='EtherPort' && Properties[Instance='0' || Instance='1']] /Fields /Field [@Name='Network Card IP'] /Value/text()

...

(blank)

Assuming the configuration(s) listed on the Configurations sheet have one or more Ethernet objects configured, the resulting data on the Query Results sheet might look something like this:

...

Configuration Name

...

IP Address(1)

...

IP Address(2)

...

IP Address(3)

...

configuration1.xml

...

10.63.191.26

...

192.168.1.1

...

n/a

...

configuration2.xml

...

10.1.2.3

...

n/a

...

n/a

...

If, instead, the Column Header had been set as "IP Address" (no square brackets), the data would have included only a single column of “IP Address”, containing the first Ethernet port’s IP address from each configuration.

Getting a count of nodes

If you wish to retrieve the number of matching nodes for an XPath query, rather than the data content of them, add "/count()" at the end of a Select Query. This is a unique notation of the ACE Management Utility (not part of XPath syntax).

As an example, define a Column Header of "# of IP addresses" and a Select Query listed below:

//Node[@Type='EtherPort']] /Fields/Field[ @Name='Network Card IP'] /Value/text()/count()

or just

//Node[@Type='EtherPort']]/count()

Note that we haven't limited the <Instance> numbers to specific Ethernet objects, as in the previous examples. The Query Results might be:

...

Configuration Name

...

# of IP Addresses

...

configuration1.xml

...

4

...

configuration2.xml

...

1

Retrieving an attribute

If you wish to get the value of an attribute, as opposed to the text content inside a “<tag>...</tag>” structure, use the "@" symbol with the attribute name. For instance, to get the visible name of the ACE object representing the eth0 Ethernet configuration, you might use a Select Query like:

//Node[@Type='EtherPort' && Properties[Instance='0']]/@Name

or

//Node[DownFile='netethr0']/@Name

or

//Properties[DownFile='netethr0'] ~~~ ../@Name/text()

...

/count()

or just

//Node[@Type='EtherPort']/count()

Note that we haven't limited the <Instance> numbers to specific Ethernet objects, as in the previous examples. The Query Results might be:

Getting an array of node counts (and count in qualifier)

Using the “/count()” notation, above, will return a total of all the matching nodes for the entire XPath query.

If you wish to retrieve a collection of elements, and then get a count of a subset of matching nodes under each element from the first set, a different notation must be used. In this case, use a chained query (with “~~~”), and then add "/count[]" at the end of the second part of the Select Query (total of 8 characters, with no spaces, using square brackets instead of parentheses). Note, this is also a unique notation of the ACM Utility (not part of XPath syntax).

One example where this is useful would be to count how the number of TABLE rows that exist under each of a collection of parent objects. The example shown below returns an array of counts for the Poll Table rows in each of a set of Field Unit exist under one or more Master Channels.

There is another way to use “count” as a qualifier, where a certain set of matching XPath elements can be limited by how many are found in a query. This notation is standard XPath syntax and is explained below.

In the following example, three queries are defined.

Explanation:

• In each query, the “Type” attribute selects for “Master Channel” objects, but also including the older object name “MastChan”. The “Properties/Instance <4) is also used to limit the selection of Master Channel objects for only having instance number 0 through 3.

• In the last two queries, “Type” attribute selects for Field Unit objects with the attribute Type=FieldUnitModbus32. In addition, the “count(node-set)” notation is used to find only Poll Table fields containing non-empty tables (with “count(Fields/Field[@Name='Poll Table'] /TABLE/TR) >0”). As mentioned above, this notation is standard XPath notation, where the text inside the count(*) function uses XPath query notation to select a set of matching nodes. The Fields/Field with attribute “Poll Table” are the children of the parent “FieldUnitModbus32” <Node>.

• In the 4th query, a chained query is used. The first query selects a set of FieldUnitModbus32 <Node> elements. The second query ends with “/count[]” (with square brackets) and counts the number of Poll Table rows inside each of the Field Unit nodes obtained in the first query, excluding those Field Units with empty poll tables.

Possible results of these queries might be:

Explanation of the above results:

• 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.

Querying a section of XML

If you wish the query to return a section 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. This will often be necessary especially in cases where you are doing a Modify query and need to either remove a section (whole object or table row) or modify a section of XML with new XML from a file. It will also be necessary when adding a section of XML, because the Select Query must select the parent node where the new XML element is to be added)” 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 entire XML section text that represents the entire eth0 Ethernet configuration, you could use:

...

<Node Type="EtherPort" Name="EtherPort0" Enabled="Yes">

(content omitted here for brevity)

</Node>

...

(content omitted here for brevity)

</Node>

Rules for dealing with ACE configurations

Unlike the ACE Editor, which imposes a number of programmatic constraints on instance numbers, adding, deleting and naming of objects, the ACE Configuration Management Utility is kind of like holding a loaded gun – you have a lot of power , but you and can do a lot of damage if you don’t know what you are doing with it.

To be more explicitspecific, the XPath Modify queries currently allow you make many changes to the XML file which are not allowed in either XML or the ACE Editor, and which could break corrupt a perfectly good ACE configuration. Be warned.

...

• Unique instance numbers are required for all sibling <Node> elements under a parent node, within the instance number limitations defined in the XML template.

• Unique object names are required for all <Node> elements in a configuration.

• Object types, DownFile properties, and all property and table columns must agree with with the XML template definition.

...

Leading zeros are not required (i.e., "${VAR00}" is identical to "${VAR0}"). More than one variable may be included in a query (etc.). after defining its content. Variables may contain any text, whether a number (count of items) or a queried section of XML text that could be used in a later Modify action.

Values saved to variables are NOT saved between separate runs of the "> Modify Configurations <" macro. They only apply to the queries on the Modify sheet when

...

Modify Sheet

The Modify sheet is used to both request and modify information in each XML configuration included on the Configurations sheet.

...

• Query rows must begin on the visible row immediately below the "Column Header" (row 19).

• After defining the Select Query (one or more rows) and other columns, click the "> Run Modify Configurations <Query" button.
  This will run the listed Modify Query definitions for each configuration on the Configurations sheet that has a "1" in the Include column.

• The results of all actions for all configurations will be stored on the Modify Results sheet.

...

Modify Query definitions consist of 7 columns, with one Query definition per row.

The Column Header, Description, Select Query, and Condition Query columns serve the same purpose on the Modify sheet as they do on the Query sheet , when used as a simple query (no Modify action). When a “Mod Type” action is selected, the Select Query chooses one or more nodes (or parents of nodes) in the XML document, at which point the action will be performed (, such as modifying a value, adding a child node, or removing a node), etc.

...

Column Header

The Column Header defines one or more columns of data to be stored on the Modify Results sheet. The Column Header is just descriptive, but does need to be non-blank.

Any row containing a blank Column Header will be treated as the end of the list, and Run Modify Query definitions following a row with a blank Column Header will not be run. This can be used (by inserting a blank row) to run only a few of the Query limit the list Modify definitions for testing, then delete the blank row to run additional subsequent queries.

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 number defines the maximum number of columns in Modify Results that will contain XML data matching the Select Query (XPath) criteria, and /or 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 Results.

Example:

If Column Header is "Ethernet IP[2]", it will create two columns on the Modify Results page 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.

Be aware that if using a fixed number of columns and the query that you are using returns more XML nodes than are allowed to be displayed by the Column Header, it may give the false impression that there aren't as many nodes as there actually are. Only the nodes selected will be modified.

If the Column Header ends with [0], it will create only a single column in Modify Results, but if the Select Query returns multiple nodes, every node will be modified. (Or if no Modify action is selectselected, the contents of each node is displayed, separated by braces { }.) If the Select Query returns only a single nodenode with no Modify action, it will be shown without braces.)

Description

This column has no purpose and is only descriptive to help remember what the Select Query definition is used for.

Select Query

The Select Query column uses XPath notation to select syntax to define selection criteria for one or more XML nodes in each configuration file. The selected element(s) selected (one or more, depending on the Column Header) will be acted on by the Modify action. See the section Understanding XPath Queries for help in understanding XPath query format used in the ACE Configuration Management Utility.

If there is a row with a non-blank Column Header but a blank Select Query, it will create a spare column in results, with no dataan empty column under its column header on the Modify Results sheet.

Condition Query

The Condition Query column is currently unused. It may eventually support the ability to include an additional condition for whether or not to include XML nodes obtained in the XPath query.

Mod Type

The following Modify actions are supported. See below under Examples of Modify Query actions for additional description of the types of actions that can be performed.

...

Add contents of a file, typically containing a chunk of XML text, as a child node *UNDER* underneath each XML element selected by the Select Query.

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 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 ENTIRE contents of the file (or or as specified by the Source Query) at ALL nodes under ALL of the XML elements selected by the Select Query (up to the limit specified by in the Column Header). This is different from the behavior of the ModifyFromFile action.

...

Add contents of a file (same as AddFromFile) as a child node *UNDER* 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 at under each parent nodeelement 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 (for one or more ACE objects).
Define Mod Type to be: AddFromFile[4]

...

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>.

...

• For a blank action (query only), 'Modify', 'SaveToVAR', and 'ConstToVAR' actions, the Source Query column is unused.

• For the 'AddFromFile', 'AddFromFile##', and 'ModifyFromFile' actions, the Source Query is optional and may be used to select one or more nodes within the XML file containing data to add or modify nodes within the ACE configuration file.

• For the 'Remove' action, the Source Query is optional. If used, it would be an XPath query to further qualify children of the Select Query node(s) to be removed.

• A Source Query that starts with “./" or “../" is used relative to the Select Query location(s).

...

Examples of Modify Query actions

...