The ACE Configuration Management (ACM) Utility is a tool for managing XML configurations for the Elecsys RediGate or Director products that are created in the ACE Editor software.
This utility provides the following features:
Retrieve a list of ACE XML configuration names and descriptions.
Select a subset of configurations to be used for subsequent Query or Modify actions.
Run an information query on all included configurations using XPath query definition.
Run a modification query on all included configurations using XPath.
Modification queries might change a value, substitute XML content, remove/add an XML child object, etc.
Select and import tags from an Allen Bradley L5X file to poll PLC data using ACE configuration.
Because the tool is designed to perform a set of actions on a group of configurations, it is ideal for batch queries or batch modification of configurations to update ACE properties, add new features, etc. The Elecsys ACE Editor is still needed to view and upload configurations, and will still be used for individually setting properties or adding objects to a single configuration.
The master copy of this ACM utility spreadsheet can be opened, configured for individual combinations and varieties of queries, and saved under different names for future reference. It is not required that the ACM spreadsheet retain its originally distributed filename. This will allow a user to keep multiple logs of information obtained from devices or results of a modification action.
The ACE Configuration Management (ACM) Utility is a Microsoft Excel workbook, which includes Visual Basic macros. This platform was chosen for its wide support on Windows operating system, which is also required for the Elecsys ACE Editor; and because Excel Visual Basic for Applications (VBA) supports XPath and XML methods.
Because the utility uses VBA macros, the default security settings in Microsoft Excel may prevent a user from being able to run the macros.
To set up macro security in Excel, select the menu:
File | Options | Trust Center | Trust Center Settings | Trusted Locations.
Click the Add New Location button, and add the file location where the utility (Excel file) will be stored.
Also, you may wish to disable the "/" key as an Excel menu option. In Options | Advanced | Lotus Compatibility, clear the "Microsoft Excel menu key" property. This will allow you to type XPath queries starting with "/" in a worksheet cell.
Test the ability to run macros by clicking the "Main Menu" button on the About sheet.
In addition to the ACM Utility and the ACE Configuration Editor software, the following utilities are also recommended for help in designing the XPath queries used in the utility:
A good text editor, such as Notepad++, to view XML files. (This will help by showing the XML structure of the configuration.)
A good text diff program, such as WinMerge, to view differences between the original and modified XML files. (This is useful when designing the XPath queries, to ensure that XML changes are made as intended.)
On the About page, click the "Main Menu" button. This will open a menu to select the location of ACE XML configurations, the output of modified files, and provides a menu of actions to perform.
Configuration Path: Click the Configuration Path button and browse to the folder containing ACE XML configurations.
For instance, C:\Users\username\Documents\Elecsys\ACE\CFG
FileName Filter: (optional) Enter a filename criteria to select a subset of the XML files.
Examples: *.xml (this is the default filter)
abc*.xml
or the FileName Filter could include a subfolder such as “myfiles\*.xml”
Output XML Path: Click the Output XML Path button and browse to the folder where the (modified) output XML files will be stored. This is only used with Modify actions.
If the Output XML Path is blank, output files will be stored in the same as the Configuration Path.
Output File Suffix: (optional) Enter a suffix to add to the modified output files.
For instance, a suffix of "_MOD" will create files with the output name
OriginalConfigurationName_MOD.XML
NOTE: If you use the same Output XML Path as the source Configuration Path and do not use an Output File Suffix then the output file will overwrite the original configuration! This is not recommended.
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. Click the “Go to Configurations“ button to switch to the Configurations sheet.
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.
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 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.
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:
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}".
This column has no purpose and is only descriptive to help document what the Query definition is used for.
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.
The Condition Query column is currently unused.
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.
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.
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.
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' or 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.)
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:
Column Header | Description | Select Query | Condition Query |
|---|---|---|---|
IP Address[3] | Get up to three IP addresses | //Node[@Type='EtherPort' and Properties[Instance='0' or Instance='1']] /Fields/Field[@Name='Network Card IP']/Value/text() | (blank) |
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:
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 |
configuration3.xml | n/a | n/a | n/a |
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.
Configuration Name | IP Address |
|---|---|
configuration1.xml | {10.63.191.26}{192.168.1.1} |
configuration2.xml | 10.1.2.3 |
configuration3.xml | n/a |
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.
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/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 | 2 |
configuration2.xml | 1 |
configuration3.xml | 0 |
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.
Column Header | Description | Select Query | Condition Query |
|---|---|---|---|
ChanNames[0] | Return array of Master Channel names | //Node[(@Type='Master Channel' or @Type='MastChan') and Properties/Instance <4 ] /@Name | (blank) |
ChanNumbers[0] | Return array of Master Channel numbers | //Node[(@Type='Master Channel' or @Type='MastChan') and Properties/Instance <4 ] /Properties/Instance/text() | (blank) |
UnitNumbers[0] | Return array of Modbus Field Unit addresses | //Node[(@Type='Master Channel' or @Type='MastChan') and Properties/Instance <4 ] /Node/Node [(@Type='FieldUnitModbus32' and count(Fields/Field[@Name='Poll Table'] /TABLE/TR) >0 )] /Properties/Instance/text() | |
CountPollTable[0] | Return array of number of Poll Table records in each Modbus unit under the selected Master Channels | //Node[(@Type='Master Channel' or @Type='MastChan') and Properties/Instance <4 ] /Node /Node[(@Type='FieldUnitModbus32' and count(Fields/Field[@Name='Poll Table'] /TABLE/TR) >0 )] ~~~ ./Fields/Field [@Name='Poll Table']/TABLE/TR/count[] | (blank) |
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:
Configuration Name | ChanNames | ChanNumbers | UnitNumbers | CountPollTable |
|---|---|---|---|---|
configuration1.xml | {Master Channel 0}{Master Channel 1}{Master Channel 2} | {0}{1}{2} | {1}{1}{2}{20} | {4}{2}{1}{2} |
configuration2.xml | MyChannel2 | 2 | {1}{2}{3} | {5}{5}{3} |
configuration3.xml | MyChannel2 | 2 | n/a | 0 |
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.
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>
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]
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 and can do a lot of damage if you don’t know what you are doing with it.
To be more specific, 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, which could corrupt a perfectly good ACE configuration. Be warned.
Some rules on ACE objects which are required by ACE Editor but not enforced by the management utility:
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 the XML template definition.
On the Modify sheet only (not the Query sheet), you can use variables to store data for reuse in later query definitions. The 'SaveToVAR' and 'ConstToVAR' actions will store data to a numbered variable. Any of the functional columns on the Modify sheet (Select Query, Mod Type, Source Data/File, or Source Query) can use the variables that have been previously saved in an earlier row in the table.
Variables that are used in these columns must have the form:
${VARxx}
where "xx" is a non-negative integer. The form is important - they must start with "${VAR", end with "}", and contain a number in between.
Leading zeros are not required (i.e., "${VAR00}" is identical to "${VAR0}"). More than one variable may be included in a query 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
The Modify sheet is used to both request and modify information in 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 Modify 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 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. 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, removing a node, etc.
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 Column Header will not be run. This can be used (by inserting a blank row) to limit the list Modify 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 Modify Results sheet based on the number in brackets. 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.
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.
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 selected, the contents of each node is displayed, separated by braces { }.) If the Select Query returns only a single node with no Modify action, it will be shown without braces.
This column has no purpose and is only descriptive to help remember what the Query definition is used for.
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 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 an empty column under its column header on the Modify Results sheet.
The Condition Query column is currently unused.
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.
Leave the Mod Type column blank to just run an informational query. The result is exactly the same as obtained with the Query and Query Results sheets, described above, but the output is stored on the Modify Results sheet. Source Data/File and Source Query are UNUSED.
Add contents of a file, typically containing a chunk of XML text, as child node(s) underneath each XML element selected by the Select Query.
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 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 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.
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 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 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 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.
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 selected elements to which the XML data was added; or it may be “n/a” if the Select Query returns no XML elements.
Same as ‘Add’, but 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. The ENTIRE contents of the Source Data 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 “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.
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 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.
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 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.
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" 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 “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.
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.
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[##]', 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 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, Source Data is an 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.
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).
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[ @Enabled='Yes' and Node/Node[ (@Type='FieldUnitModbus32' or @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): {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') 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”
Source Data/File: “No”
All ACE objects have an "Enabled" attribute that contains text, either "Yes" or "No".
Modify Results (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.
This example will add the entire contents of a file, which has been copied out of an existing configuration and includes only the Automated Processing section of XML text.
Column Header: ADD_AutoProc
Select Query: //Node[@Type='Clients']
Select the Networks parent where Automated Processing will be added.
Mod Type: AddFromFile
Source Data/File: autoProcSource.XML
autoProcSource.XML contains the entire XML of just the <Automated_Processing> node (not a full ACE configuration), with all its child objects needed in a configuration.
Source Query: (blank)
Modify Results (one column): added 1x
Note that in this example, we could obtain the source data from an existing configuration using a Source Query, such as:
Source Data/File: GoldenACEConfiguration.XML
GoldenACEConfiguration.XML contains a fully configured Automated Processing, to be copied into one or more other configurations.
Source Query: //Node [@Type="Automated_Processing"]
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: REM_Omni[0]
Select Query: //Node[ @Type='Omni-Modbus-Archives'] /Fields//TR
This removes all TR grandchildren (table rows) of the Omni-Modbus-Archives table, because the Column Header uses [0].
Mod Type: Remove
Source Data/File and Source Query: (blank in this example)
Modify Results: removed 4x
5. Count number of Modbus Field Units in the current configuration.
(For purpose of this example, these are assumed to be Omni flow computers.) This example illustrates the use of the SaveToVAR action. The saved value will be used in the next two examples.
Column Header: VAR00 (#Mod)
Select Query: //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. The "count()" at the end yields the number of such nodes with the above characteristics.
Mod Type: SaveToVAR
Source Data/File: 0
This setting will store the count of nodes into variable ${VAR00}.
Modify Results: The results page will display the value that was stored in the variable, such as "2".
6. Add two table rows to a table for every Modbus 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.
Column Header: ADD_OmniTimeSync
Select Query: //Node[ @Type='Time-Syncs'] /Fields/Field[@Name='Data Process Table']/TABLE
Select the intended object type, then select the <TABLE> grandchild which is the *parent* where new XML will be inserted.
Mod Type: AddFromFile[${VAR0}]
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}" in the Mod Type to substitute for the number of iterations that we wish to insert the file contents. The Mod Type is thus converted (for example) to "AddFromFile[2]" before being acted upon.
Source Data/File: TimeSyncTable-ModbusRow.XML
Source Query: blank
(But note that we could have pointed to an XML configuration file with the <TR> table rows we needed, and used a Source Query to request those rows as the items to be inserted.)
Modify Results: added 2x
7. Modify channel number in table, in the previous example, based on Master Channel of every Modbus Field Unit.
This example queries all the Modbus units (assumed for this example to be Omni flow computers), gets the Master Channel number, and modifies the first column of the table rows inserted in the previous example.
Column Header: OmniTSChan[0]
Select Query: //Node[ @Type='Omni-Modbus-Archives'] /Fields/Field[@Name='Data Process Table'] /TABLE/TR [TD[5] = '8'] /TD[1]
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
This option queries this configuration for data to use for modification.
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 Circuit, and enabled child Modbus unit), and gets the Instance number (Master Channel number).
Modify Results: modified 2x
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 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).
The TestXPath sheet can be used for testing XPath query definitions (either Select Query, or any document used in a Source Query).
The first seven columns in this sheet are the same as in the Modify (or Query) sheets, except the second column is a filename of an XML document (full path, or relative to the Configuration Path).
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 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.
The L5X Tags sheet is used to query tags from an Allen Bradley PLC program file, to aid in more quickly configuring the 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 of the ACE Configuration Management Utility. The user can then select which tags to poll, and the ACM Utility will automatically add the following information into an ACE configuration:
Scan Table entries for Master Channel
Poll Table entries for Field Unit
RTDB Table entries
TagNames Table entries
The ACE Configuration Management Utility doesn’t automatically create all the ACE Editor objects necessary to configuring an EtherNet/IP. It only fills in the existing tables of an already-configured EtherNet/IP Field Unit.
Thus, the first step is to create an ACE configuration file that will serve as the basic configuration for a RediGate or Director. All the required elements, such as AsyncPorts, Ethernet ports, Firewall, SerialMMI, etc., must be configured within the ACE Editor. The configuration must also include at least one (or more) set of the 5 required components for polling an Allen Bradley EtherNet/IP device:
Master Channel - Scan Table may begin with a blank table and will be filled in by the ACM Utility, but all other settings should be configured in the ACE Editor.
NetCircuit - Circuit should use Master Network Port of 44818, and the IP address of the PLC in the Connect Table.
FieldUnitEthernetIP - the Field Unit definition requires a unique Unit Address under each Master Channel. This Unit Address doesn’t correspond to an actual address of the PLC, but it is needed by the Master Channel to uniquely identify each PLC for scanning purposes. The Poll Table can begin blank and will be filled in by the ACM Utility. Other settings (Controller Type, etc.), should be set up based on Elecsys documentation for EtherNet/IP devices (see https://elecsysdocs.atlassian.net/wiki/spaces/IDG/pages/296343/Protocol+EtherNetIP-Master ).
RTDB - Database Definition may begin with a blank table and will be filled in by the ACM Utility.
TagNames - may begin with a blank table and will be filled in by the ACM Utility.
The L5X Import sheet is used to manage the selection of Allen Bradley tags to be polled, and to configure one of the XML configurations included on the Configurations sheet.
NOTE: When using the Modify feature of the ACM Utility, it is normally recommended in the Main Menu to use either a different Output XML Path and/or Output File Suffix from the source configurations, so the modified XML configurations will not overwrite the original files. The same thing can be done for the L5X Import utility as well. However, it is permissible to use the same Output XML Path and a blank Output File Suffix, so the changes to an EtherNet/IP field unit will be made in place in the same configuration.
Be aware that if you make changes to the L5X configuration and save them into a different XML file, then subsequently make further changes in the ACE Editor, you will need to select the latest (modified) ACE XML file to begin with, so that all changes are retained.
Use the List Configurations button to create a list of configurations on the Configurations sheet. Then click on the L5X Import button in the Main Menu or the L5X Tags sheet to set up the PLC tag information.
The L5X Import Setup dialog will configure the following items:
Choose the ACE XML Configuration from the list of included configurations on the Configurations sheet.
Choose the Master Channel and Field Unit of the Allen Bradley EtherNet/IP PLC to be set up for polling. Select the Master Channel first (the dropdown list only shows channels that have FieldUnitEthernetIP objects). Then select the Ethernet/IP Field Unit from the list of Field Units under that channel.
Choose the L5X Program File of the PLC. This must be a file in L5X format (Logix Designer XML File) that has been saved using the Rockwell Studio 5000 application.
Select or create an L5X Tag Setup File. This will be a unique file used by the ACM Utility to help manage details of tags selected for polling on every Field Unit – thus, the .L5Xtags files should have a name that is unique for each Field Unit.
Clearing the L5X Tag Setup File field will cause the ACM Utility to default to the same name as the L5X Program File (with an extension of “.L5Xtags”).
This file is not used by the RediGate or Director, but it is used by ACM in case the L5X Import details are modified in the future. Thus, it should be stored along with either the ACE XML configuration file or the L5X program file for future reference.
Set the Default Scan Period (in seconds). This can be modified for individual polls later. The Scan Period can be set to a negative number, which will disable all scans.
Select whether to include Program Tags from the PLC file. Leaving the box unchecked will use only global tags. Including Program Tags will increase the time to read data from the L5X file somewhat, depending on how large the program is.
After setting up all the L5X Import settings, click the OK (List L5X Tags) button to create a list of all the L5X tags for the PLC, and then switch to the L5X Tags sheet.
Clicking the Close button after making changes in the L5X Input Setup dialog will prompt to keep the changes, but will not refresh the list of tags.
Clicking the Go to L5X Tags List or Main Menu button will close the dialog (any changes will be lost), and open the L5X Tags sheet or return to the Main Menu dialog.
After clicking the OK button, a dialog will summarize what is being done before listing the L5X tags. Click the Cancel button to return to the L5X Import Setup dialog or OK to continue.
After the L5X program file has been read, the tags will be listed on the L5X Tags sheet. An example is shown below. All known AOI and UDT nested structures will be automatically expanded to show their inner tags.
Most of the information in the L5X Tags sheet is informational only and does not need to be modified. The first column (Include=1) is typically the only one that needs to be modified, and perhaps the Scan Period. Occasionally, the Data Type and Bit Position columns may need to be modified to read an integer and store individual bits, instead of storing the whole value into an integer register.
Include=1 – Enter a “1” in this column to include the PLC tag(s) in the Poll Table of the ACE configuration.
When the Include column is set to “1”, the entire row changes to a green color.
If the tag is unable to be polled by the RediGate/Director, it will have an “x” in the Include column, and the entire row changes to a red color.
Arrays are initially shown with just a single row (see “Array Size” below). Arrays can be expanded by selecting any cell on the first row of an array and clicking the Expand Array button. An array with a non-blank Include column will be automatically expanded when saving to XML.
If any other character is entered in the Include column other than “1”, that cell will change to a yellow color, but it will not be included as a polled tag. This might be used to disable polling of a tag for testing, but still indicate it as important (with the yellow color), as opposed to just clearing the cell to disable polling.
You can disable the polling of individual tags within an expanded array or AOI/UDT structure by clearing the Include column or changing them to something other than “1”. This can be important especially for large structures or PLC programs, to avoid polling unneeded data.
If a “1” is entered in the Include column for the first element of an expanded array or the first element of a AOI/UDT data type definition (top-level or inner structure), the ACM Utility will automatically change the Include column to “1” for all blank cells in the array or AOI/UDT structure. Any cells that are not blank will not be changed.
Entering a “1” on the row for a non-expanded array automatically implies that the entire array will be polled (and it will be expanded later when saving to XML).
If the Include column is cleared (set to blank) for the first element of an expanded array or the first element of a AOI/UDT data type definition (top-level or inner structure), the ACM Utility will automatically clear all the Include=1 cells for the array or AOI/UDT structure. Any cells that are not “1” within the array or structure will not be cleared.
Enter a value or clearing the cell in the Include column for any element in an array or AOI/UDT besides the first element or structure data type only affects that single row, not any others in the structure.
Scan Period – This column contains the default scan rate from the L5X Import dialog (in seconds) and will be saved into the Master Channel’s Scan Table. The Scan Period may be changed manually for individual tags. A negative Scan Period can be used, which will disable
# - This column shows the numerical order of the tags as read from the L5X program file. This column should not be modified. If the table is sorted by another column for some reason, this “#” column can be used to re-sort the table back into its original order.
Tag Name – This column contains the top-level tag (or array or AOI or UDT) name used in the L5X program file. Cells are blank except for the top-level tag name.
Element Name – This is the expansion of the top-level tag plus additional array or AOI/UDT structures defining each individual tag. These are the tag names that will be polled by the RediGate or Director.
Array elements are named using square brackets, such as “DINTARY[0]” or “Ary2D[0,0]”.
AOI/UDT nested structures are noted with “.” separating the levels, such as: “myUDT_tag.myUDT_inStrc.innerINT”.
Program tags are prefixed with “Program:” and the program name, such as: “Program:MainProgram.COUNTER1.ACC”.
Data Type – This is the PLC Data Type for the tag or AOI/UDT. Primitive data types (such as BOOL/BIT, SINT, DINT, REAL), some standard AOI/UDT types (such as TIMER, PID, STRING, COUNTER), and some custom structures may be supported if they are defined in the L5X file.
If you desire to read an integer type (INT, SINT, DINT) and store individual bits to Boolean registers, you will need to modify the Data Type column to be: SINT_BIT, INT_BIT, or DINT_BIT (respectively, all uppercase) for each data tag to be handled in this way. (Also modify the Bit Position column to identify individual bits.)
Array Size – This is the array size for array variables. The ACM Utility and the RediGate/Director only currently support up to 2-dimensional arrays.
Bit Position – This is the bit position of a BOOL/BIT within an analog word. For individual bits that are part of AOI/UDT structures, this value is simply included in the ACM Utility as information.
If you wish to read an integer type (INT, SINT, DINT) and store individual bits to Boolean registers, you will need to modify the Data Type column, as described above. Also, modify the Bit Position column to be a comma-separated list of bit numbers to read, where bits are numbered from 0 (least significant).
Example – you wish to read a DINT tag named “DINTARY[0]” (first element in a DINT array) and store only the 1st, 2nd, and last bits as Booleans: DINTARY[0].0, DINTARY[0].1, DINTARY[0].31. Modify the Data Type column to be “DINT_BIT” and the Bit Position column to be “0,1,31”.
Read/Write – This is the Read/Write type for the tag, if it’s declared in the L5X file or known structure.
Tag Depth – This is an indication in the ACM Utility of the level of the tag within an array or AOI/UDT structure, where 1 is a top-level tag, and numbers increase with increasing depth.
Alias – For any tags configured in the L5X file with an alias name, this column displays that information.
Hidden – For tags that are hidden, they are shown here with “TRUE”.
Usage – For tags that include a “Usage” property, they are shown here.
TimeInterval – The TimeInterval column is used in the ACM to indicate how much time elapsed from the beginning of reading the L5X tags. This is diagnostic information only.
Below is shown an example of the L5X Tags sheet with the following tags selected:
two inner tags of customTimer, DINTARY[1], DINTARY[3], and four bits of DINTARY[5] (0,1,16, and 31) stored into Boolean registers. The default Scan Period is 5 seconds, but has been changed to 1 second for DINTARY[3] and DINTARY[5].
Note that because the top-level “customTimer” structure (newTimerUDT data type) is polled, as well as the individual elements of the structure, it leads to a difference in the Poll Table, as will be explained in the next section.
In summary, the process of configuration is to 1) view the L5X Import Setup dialog and enter information specifying configuration, channel, unit, and L5X program file; 2) click the OK button to read tags from the L5X file; 3) select tags to include in the polling by entering data under the Include column. Optionally, enter comma-separated list of bits under Bit Position to identify bits within integers. 4) Then click the Save to XML button to set up the PLC tag polling in the RediGate or Director configuration (see below).
After setting up the L5X Tags sheet to select tags for polling, click the Save to XML button. Make sure the configuration is not open in the ACE Editor. After changes are made, the configuration will need to be re-opened in the ACE Editor to view the changes or to load to a RediGate or Director.
Click the OK button to confirm saving to XML. The output file will be saved according to the settings in the Main Menu (Output XML Path and Output File Suffix).
After saving the data to the XML configuration file, it will need to be re-opened in the ACE Editor to see the changes. Below is shown an example of several tags imported into an ACE configuration.
Poll Table: DINT values are polled into registers 47001-47003, Booleans are polled into registers 1-33.
Because the top-level customTimer structure was selected for polling in addition to the inner elements, the Poll Table lists “customTimer” as a “Struct” data type. Only this poll is scanned in the Scan Table (below). The following 6 lines in the Poll Table are “continuation polls” which define how the RediGate or Director will parse the integer or Boolean data elements from the single polled structure.
If the top-level customTimer row had not been polled, it would have appeared as two separate (scanned) polls for only the customTimer.ACC and customTimer.DN.
Scan Table: Only rows 1, 8, 9, and 10 in the Poll Table need to be scanned. Note the Scan Period column matches the Scan Period column for each scanned poll, as defined in the ACM Utility.
RTDB Table: Registers defined at 1-33 and 47001-47003.
TagName Table: Only the names for the polled tags appear in the TagNames object. Note that the Poll Table reads the DINTARY[5] and extracts all 32 bits into RTDB registers 2-33. But only registers 2, 3, 18, and 33 have tag names associated with them. If this data is sent via Report By Exception to a protocol (such as Sparkplug-B) that can report only registers with tag names, then only the named tags will be sent, even though there may be data stored in the non-tagged Boolean registers.
The L5X Import Setup dialog (above) set up a configuration for the L5X Tag Setup File (.L5Xtags extension). When the ACM Utility saves data into the XML configuration file, it also records a list of the included tags into the .L5Xtags file, to be used later when re-reading the L5X program file and modifying the tag list for ACE. The name of the .L5Xtags file (including full path) is stored within the ACE configuration as the Description of the TagNames object:
Note: the ACE configuration (any of the 5 tables) can be changed manually in the ACE Editor after saving data using the “Save to XML” option of the ACM Utility. However, any changes made to these tables manually within the ACE Editor will be overwritten the next time the ACM Utility is used to import data from the L5X file.
The above process of selecting the Master Channel, Field Unit, L5X program, and .L5Xtags file should be repeated for every PLC (Field Unit) polled within a given ACE configuration. It is not necessary to save the ACM Utility Excel spreadsheet file for each L5X Tags import action, because the .L5Xtags file (for every Channel/Unit) retains the information needed to repeat or modify the L5X Import in the future.
After the XML configuration file has been fully set up, use the ACE Editor to load the configuration into a RediGate or Director for testing.