...
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.
It is recommended to copy the intended XML content directly from an XML configuration file and include one blank line
The Modify Results sheet will return a value such as “added #x” if successful, where the # is the number of source selected elements to which the XML data was added; or it may be “n/a” if the Select Query returns no XML elements.
Modify
...
Add[##]
Same as ‘Add’, but add contents of the Source Data/File column, typically containing a chunk of XML text, as child node(s) to the text included under underneath each XML element selected by the Select Query. The ENTIRE contents of 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 one parent element, which may include multiple children elements. If the XML text includes multiple top-level parent nodes (siblings), only the first will be used.column 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 “modified “added #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.
...
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.
Modify
Change the selected XML node(s) to the contents of a file.The the text included under the Source Data/File column may contain the filename (using a partial pathname, relative to the Configuration Path configured in the Main 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 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. 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).
But if the source data contains "<Sibling1></Sibling1><Sibling2></Sibling2>", then a MAXIMUM of two Select Query nodes will be modified – the first selected node will be changed to <Sibling1>, and the second will be changed to <Sibling2>.
Remove
Remove the selected XML node(s) specified by Select Query.
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.
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]).
...
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 one parent element, which may include multiple children elements. If the XML text includes multiple top-level 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 may contain the filename (using a partial pathname, relative to the Configuration Path configured in the Main 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 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. 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).
But if the source data contains "<Sibling1></Sibling1><Sibling2></Sibling2>", then a MAXIMUM of two Select Query nodes will be modified – the first selected node will be changed to <Sibling1>, and the second will be changed to <Sibling2>.
Remove
Remove the selected XML node(s) specified by Select Query.
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.
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.
The Modify Results sheet will return a value such as “removed #x” if successful, where the # is the total number of selected elements that were removed; or it may be “n/a” if the Source or Select Query returns no XML elements.
Reorder
Move the selected XML node(s) specified by Select Query in relation to their sibling XML nodes.
The Source Data/File column should contains a number (or variable such as ${VAR02} containing a number) that specifies the new location of the selected node among its siblings.
If multiple siblings under each parent are selected, they will be moved together but retain their order among themselves.
Set the Source Data to 0 to make it the first sibling object under its parent.
Set the Source Data to a number between 1 and the maximum number of siblings to move the selected object after the numbered sibling. The Source Data value should be no greater than the number of siblings at each Select Query location. The Source Query column is UNUSED.
Examples:
Select Query selects one or more Field Unit <Node> elements. With
Select Query points to <TABLE> node, the parent of <TR>. A Remove action with "5
...
"
...
SaveToVAR
...
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.
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.
ConstToVAR
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 return a value such as “reordered #x” if successful, where the # is the number of elements that were moved under each parent node; or it may be “n/a” if the Select Query returns no XML elements; or it may be “NOT reordered” if there was a problem such as a wrong sibling number.
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:
The Select Query column contains a value of “10”retrieves a "/count()" of objects or a value (such as "10.63.191.26"). Source Data column is "2". The value of 10 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.
Source Data/File
...
ConstToVAR
Save the contents of the Select Data/File column depends on the Mod Type and query definition on each row.
For a blank action (query only), the Source Data/File column is unused.
For 'Modify' action, Source Data column is a fixed text value that will be substituted at each matching Select Query node.
For 'AddFromFile', 'AddFromFile##', or 'ModifyFromFile' actions, Source File column contains the file name of the data to be added or modified. This may be just a filename (for files located in Configuration Path) or a fully qualified Drive:\Path\Filename. The contents of an XML file may be limited to a subset of elements using the Source Query.
For 'Remove' action, Source Data is a optional positive integer, giving the maximum number of nodes that will be removed at each Select Query location.
For 'SaveToVAR' and 'ConstToVAR' actions, the Source Data column is a non-negative integer containing the variable number into which to store the node value or constant.
Source Query
The use of the Source Query column depends on the Mod Type and query definition on each row.
...
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.
Source Data/File
The use of the Select Data/File column depends on the Mod Type action and query definition used on each row.
For a blank Mod Type action (query only), the Source Data/File column is unused.
For the 'Modify' action, Source Data column is a fixed text value that will be substituted at each matching Select Query node.
For the 'AddFromFile', 'AddFromFile##AddFromFile[##]', and or 'ModifyFromFile' actions, Source File column contains the file name of the data to be added or modified. This may be just a filename or partial path (for files located relative to 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 Configuration Path) or a fully qualified Drive:\Path\Filename. The contents of an XML file may be limited to a subset of elements using the Source Query. This may also be “self” to refer to the configuration file being modified.
For 'Remove' action, the Source Query Data is an 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
...
This example queries for an object of a certain "Enabled=Yes" attribute and gets its grandchildren that have a certain "Name" attribute.
Column Header: ModChans[0]
This lists them all in one column. Use [##] for a set number, or omit [0] for only the first Master Channel.
Select Query: //Node[ @Enabled='Yes' && Node/Node[ (@Type='FieldUnitModbus32' || @Type='FieldUnitModbusTCP32')] ] /@Name
Select all enabled nodes whose grandchild has a Modbus FieldUnit type, and list the parent node's name(s).
Mod Type, Source Data/File, Source Query: (blank)
Modify Results (single column): {Omni Channel 01}{PLC Channel 05}
Output is in braces { } because the Column Header ends with [0] and more than one node was queried.
2. Disable all but the first two Modbus or Allen Bradley Field Units under channel 1
This can be done with two Modify queries – the first disables all units, and the second enables the first two.
...
positive integer, giving the maximum number of nodes that will be removed at each Select Query location.
For 'SaveToVAR' and 'ConstToVAR' actions, the Source Data column is a non-negative integer containing the variable number into which to store the node value or constant.
Source Query
The use of the Source Query column depends on the Mod Type action and query definition on each row.
For a blank Mod Type 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 used 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
Below are several examples describing how the various Mod Type actions work.
1. List all Master Channel names that have Modbus Field Units as children.
This example queries for an object of a certain "Enabled=Yes" attribute and gets its grandchildren that have a certain "Name" attribute. This is the same as used on the the Query sheet.
Column Header: ModChans[0]
This lists them all in one column. Use [##] for a set number, or omit [0] for only the first Master Channel.
Select Query: //Node[ Properties/Instance = 1] /@Enabled='Yes' and Node/Node[ (@Type='FieldUnitModbus32' || or @Type='FieldUnitModbusTCP32' || @Type='FieldUnitABDF1M')] ] /@Enabled
...
@Name
Select all enabled nodes whose grandchild has a Modbus FieldUnit type, and list the parent node's name(s).
Mod Type: Modify, Source Data/File: No
...
, Source Query: (blank)
Modify Results (one single column): modified 5x
This tells the number of source nodes that were modified.
(Note, Excel's XPath support doesn't seem to include "position()", which would make this simpler. This could also be done using a Select Query including instance numbers > 2, if the object instance numbers correspond to the correct objects to disable.)
Column Header: Enable[2{Channel 01}{PLC Channel 05}
Output is in braces { } because the Column Header ends with [0] and more than one node was queried.
2. Disable all but the first Modbus Field Unit under channel 1.
This uses the position() qualifier and assumes that all Field Units are under the same circuit.
Column Header: Disable[0]
Select Query: //Node[ Properties/Instance = 1] /Node/Node[ (@Type='FieldUnitModbus32' || or @Type='FieldUnitModbusTCP32' || @Type='FieldUnitABDF1M')] /@Enabled) and position() > 1] /@Enabled
This query selects the Enabled property of all Modbus grandchild nodes under the Master Channel with Instance=1, where the position() of the nodes under its parent (Circuit) is greater than 1.
Mod Type: Modify“Modify”
Source Data/File: Yes“No”
All ACE objects have an "Enabled" attribute that contains text, either "Yes" or "No".
Modify Results (two columns): Enable(1), Enable(2). Both say "modified 1x"
...
one column): “modified 5x”
This tells the number of source nodes that were modified.
3. Add Automated Processing section under Clients, using a dedicated XML text file.
...
autoProcSource.XML contains the entire XML of just the Automated Processing node<Automated_Processing> node (not a full ACE configuration), with all its child objects needed in a configuration.
...
4. Remove existing table rows in the Automated Processing table that was imported above.
This clears the table and allows it to be set up specifically for the ACE objects configured in each configuration.
...
Column Header: VAR00 (#Mod)
Select Query: //Node[ /Node[ @Enabled='Yes' and (@Type='MastChanFlexScan' or @Type='Master Channel' or @Type='MastChan') ] /Node[(@Type='AsyncCircuit' or @Type='NetCircuit') and @Enabled='Yes' && ] /Node[(@Type='FieldUnitModbus32' || or @Type='FieldUnitModbusTCP32') ] ~~~ ..and @Enabled='Yes'] /count()
or a simpler version:
//Node[@Enabled='Yes'] /Node[@Enabled='Yes'] /..[Node[(@Type='FieldUnitModbus32' or @Type='FieldUnitModbusTCP32') and @Enabled='Yes'] /count()
This selects nodes of Modbus type that are enabled, which must have both a parent Circuit and Master Channel that are also enabled. Note the use of the two XPath queries chained with "~~~", and the ". ." indicates backing up to the parent of the node(s) selected in the first query. The "count()" at the end yields the number of such nodes with the above characteristics.
...
6. Add two table rows to a table for every Modbus Field UnitModbus Field Unit, obtained in the previous example.
This example uses a separate file containing a single <TR> section with all its <TD> child rows rows which are the new Poll Table entries.
...
In the previous example, we used a SaveToVAR action to count the number of enabled Modbus field units. Now we are using the phrase "${VAR0}" to substitute in the Mod Type to substitute for the number of iterations that we wish to insert the file contents. The Mod Type is translated to thus converted (for instanceexample) to "AddFromFile[52]" before being acted upon.
...
7. Modify channel number in table, in the previous example, based on Master Channel of every Modbus Field Unit.
...
Select Query: //Node[ @Type='Omni-Modbus-Archives'] /Fields/Field[@Name='Data Process Table'] /TABLE/TR [TD[45] = '8'] /TD[01]
This selects the first <TD> column in the table (Channel number), where the 5th <TD> column is a value of "8" (Omni Batch report). (Note, this query only modifies half of the newly inserted rows in the table in this example. Another query row would be needed to modify the rows where the 5th column is "9", Omni Hourly report.)
In this example, there are two matching <TD> elements returned by the Select Query. Both will be modified with the Modify query.
Mod Type: ModifyFromFile
Source Data/File: self
...
Source Query: //Node[ @Enabled='Yes' && and Node[ @Enabled='Yes'] && and Node/Node[ @Enabled='Yes' && and (@Type='FieldUnitModbus32' || or @Type='FieldUnitModbusTCP32')] ] /Properties/Instance/text()
This query selects all enabled Master Channels (which also have an enabled channelCircuit, and enabled circuit, enabled child Modbus unit), and gets the Instance number (Master Channel number).
...
Note that the Select Query selects two rows in the table to be modified, and the Source Query selects potentially all of the Master Channel numbers, if they are different – if there had been more than one Channel, then the nodes would have been modified one for one. In reality, however, in this example all the Modbus field units are under the same channel, so the query actually on only returns one node: the Master Channel <Instance> that is the parent of all the Modbus units. Therefore, the Modify query has a single node that is the source, so ALL of the Select Query nodes are modified to match this single value (Channel instance number), no matter how many <TD> rows are matched (one to many).
...
Using TestXPath Sheet
...
Enter data for Column Header, Mod Type, Source Data/File, and/or Source Query, and click the "> Test XPATH <" button. The basic rules for these columns are followed, as described in the section Modify Sheet. The main differences are:
When clicking the "> Test XPATH <" button, the query and action are performed ONLY on the same row as the currently-selected cell.
The Number of Child Nodes column (H) gives the count of nodes requested by the Select Query, regardless of whether whether or not the query ends with "/count()".
The Select Query XML column (I) contains all queried nodes, separated by braces { }, as if the Column Header ended with [0].
The Modify Results column (J) contains the results of any Modify action, separated by braces { }, as they would appear in multiple columns of the Modify Results sheet.
...
Using L5X Tags Sheet
The L5X Tags sheet is used to query tags from an Allen Bradley PLC program in order to aid in configuring polling of an EtherNet/IP device in the ACE Configuration editor. The Allen Bradley tags are queried from its L5X (XML) configuration file and displayed in the L5X Tags sheet. The user can select which tags to poll, and the ACE Configuration Management Utility will automatically add the information into an ACE configuration:
Scan Table entries for Master Channel
Poll Table entries for Field Unit
RTDB Table entries
TagNames Table entries