About Regions, Targets, and Markers
Each token (statistic) that you want to retrieve from a command output has to be marked as a target. Targets are not standalone entities, but live in the comprising free from or table output region.
- Free-form region: When working inside a free-format region, the data is assumed to consist of lines and words, separated by white space. Upon selecting a word as a target, the target is marked in the original response based on the word number and the line number.
However, there are cases when the device response may contain a variable number of lines, as shown below:
<table header>
<table data with variable number of rows>
Expression = 23
Supposing that you want to retrieve the number that is generated after the `=' string, you cannot use targets the common way, because targets use fixed line/word counting. Instead, the Response Template Editor provides a way to mark a variable position within the response that the target can use as a reference point. At runtime, these reference points called markers are looked for in the command response and help reference the target.
For the purpose of our example, defining the Expression string as a marker would allow the parser to determine which output line you are interested in.
The following general rules apply to markers:
There can be only one marker per response template. Multiple targets can be defined, not necessarily on the same line as the marker.
Since some devices may give spurious output at any time, the best practice is to place the marker and target on the same line, as close as possible to each other.
The target's word count in the response output can not change; instead, only the line number in the response can.
Targets can appear before or after the line with the marker; the only restriction is that the number of lines between the marker and all the targets cannot vary in the real response.
For information on defining targets within free format regions refer to Free-Form Response Templates.
- RepeatingBlock region: For this region type, the command output data is assumed to contain a portion that repeats several times.
When marking a target in a defined RepeatingBlock region, all occurrences of the repeating portion are analyzed and a vector of values is retrieved, with one value for every occurrence. The result of such an evaluation can then be used within other variables and Tcl commands.
A sample RepeatingBlock region (highlighted red) with a target defined within it is shown in Figure: Repeating Block Region with Timestamp Target:
Figure: Repeating Block Region with Timestamp Target
For information on defining targets within free RepeatingBlock regions refer to RepeatingBlock Response Templates.
- Table-format region: When working inside a table region, the data is assumed to be organized as rows and columns. A table starts at the first line in the marked area and ends at an empty line or the end of the response.
Normally, you must select a table region that includes one or more header lines and the first line(s) as a header.
The following types of table blocks exist:
- Regular table: A regular table is one that has columns and rows, with the data occurring right after the header line(s). For such tables that comprise multiple header lines, a mechanism is provided enabling you to specify the offset from the header of the first row that actually contains data.
- Line table: A line table is similar to the form below, comprising a literal line separator between the header and the data. For this type of table, data exists only on one line.
<header column1> <header column2> <etc.>
---------------- ---------------- ------
<value for col1> <value for col2> <etc.>For such tables, you do not have to define the header, since it is already in a well-defined format, nor do you have to specify the row index because there is only one data value.
Line table type outputs can be found, for example, in Cisco routers' command responses.
Table targets can be referenced in either of the following ways:
- Row-indexed tables: When referencing a row-indexed table, you must specify the row index for a particular column.
- Column-indexed targets: When referencing a column-index table, the value of a specific column is retrieved by specifying the value (reference value) in another column (reference column). The row index corresponding to the reference column entry that has a matching value is used to access a value in the specific column.
For example, given the table in Figure:Sample Column-Indexed Table, and considering that we are searching for the value of the actual column corresponding to a reference value of 50 in the reference column, then the resulting value is 78.
Figure:Sample Column-Indexed Table
Column-indexed table targets are created anywhere in the column where the data should be.
For information on defining targets within free RepeatingBlock regions refer to Table-Form Response Templates.
See Also