Customize YANG RPC Output on Devices Running Junos OS

The blank-line statement inserts a line between each repetition of data when the RPC reply returns the same set of information for multiple entities. For example, if the RPC reply returns data for multiple interfaces, the formatted ASCII output inserts a blank line between each interface’s set of data.

To insert a blank line between each entity’s data set, include the blank-line statement directly under the format statement.

The capitalize statement capitalizes the first word of a node’s value in an output field. It does not affect the capitalization of a node’s formal name. For example, if the RPC output includes a state node with the value online, the capitalize statement causes the value to be capitalized in the output.

To capitalize the first word of the node’s value, include the capitalize statement within the format statement. The placement of the statement determines the statement’s scope and whether it affects a single field, all fields in a single line, or all lines.

When you execute an RPC on a device running Junos OS, it returns the RPC reply as an XML document. Container and leaf nodes under the RPC output statement translate into XML elements in the RPC reply. In YANG RPCs for devices running Junos OS, you can also define custom formatted ASCII output that is displayed when you execute the RPC on the Junos OS command-line interface (CLI) or request RPC output in text format.

In Junos OS Release 17.2 and earlier releases, to create custom command output for a specific RPC output container, create a child container that includes the cli-format statement. The cli-format statement indicates that the enclosing container defines the CLI formatting for the parent container, and that this container should not be included as a node in the XML data of the RPC reply. Within the formatting container, map the data for the parent container to output fields, and use statements from the Junos OS ODL extensions module to specify how to display the output for that parent container.

To create custom command output for a specific RPC output container in Junos OS Release 17.3 and later releases, see format.

A node’s formal name, or label, is the text that precedes a node’s contents in the output when the leading statement is included in the formatting instructions for that node’s output field. To create a label for a node, you must include the formal-name statement in the definition of the leaf node. In the following example, the version node has the formal name Version:

The colon statement inserts a colon after the node’s label in an output field. If the formatting instructions include both the colon and leading statements, the node’s label and a colon are inserted before the node’s value in the output. For example:

To insert the label and a colon in the output field, include the leading and colon statements within the format statement. The placement of the statements determines the scope and whether the statements affect a single field, all fields in a single line, or all lines.

When you execute the RPC, the label and a colon are included in the output for that field.

The comma statement appends a comma to the node’s value in the output. It is used in conjunction with the space statement to create comma-delimited fields in a line of output. For example:

To generate a comma and a space after a node’s value in the output field, include the comma and space statements within the format statement. The placement of the statements within the format statement determines the scope. Placing the statements within a single field generates a comma and space for that field only. Placing the statements directly under the format statement applies the formatting to all fields.

If you omit the comma statement in the formatting instructions in this example, the fields are separated using only a space. Junos OS automatically omits the comma and space after the last field in a line of output.

The default-text statement specifies the text to display when the node corresponding to an output field is missing.

To define the string to display in the formatted ASCII output when the node mapped to a field is missing, include the default-text statement and string within the field statement for that node.

When the node is missing in the RPC reply, the CLI output displays the default text.

The explicit statement is only used in Junos OS RPCs and cannot be included in custom RPCs.

The line and field statements define lines in the RPC’s formatted ASCII output and the fields within those lines. These statements can also be used with the picture statement to create a more structured table that defines strict column widths and text justification.

To define a line in the formatted ASCII output, include the line statement within the format statement. Within the line statement, include field statements that map the leaf nodes in the output tree to fields in the line. The field statement’s argument is the leaf identifier. Fields must be emitted in the same order as you defined the leaf statements.

The CLI output for the following RPC is a single line with three values. Note that you can include other ODL statements within the field and line statements to customize the formatting for either a single field or all fields within that line, respectively.

The fieldwrap and wordwrap statements enable you to more logically wrap content when a line’s width is greater than the width of the display. By default, content that extends past the edge of the display wraps at the point where it meets the right margin, without concern for word boundaries.

The fieldwrap statement wraps a field’s complete contents to the next line when the current line is so long that it extends past the right edge of the display. If you do not use this statement, the string wraps automatically but without regard for appropriate word breaks or the prevailing margin.

Consider the following lines of output:

If the display is narrower than usual, the line could wrap in the middle of a word as shown in the following sample output:

When the fieldwrap statement is included for a field, the entire field is moved to the next line.

The wordwrap statement is only used on the rightmost column in a table to wrap sections of a multiword value to subsequent lines when the current line is too long. This effectively creates a column of text. In the following example, the wordwrap statement divides the description string at word boundaries:

To improve the wrapping behavior in the RPC’s formatted ASCII output, include the fieldwrap statement in each field’s formatting instructions. To wrap the rightmost column in a table, include the wordwrap statement in the rightmost field’s formatting instructions.

You can create tables in the RPC’s formatted ASCII output by defining a header statement, a picture statement, and one or more line statements. The optional header statement defines the column headings for a table, but it can also just define general text. The picture statement graphically depicts the placement, justification, and width of the columns in a table. The line and field statements define the table rows and their fields.

The argument for the picture statement is a string that includes the at (@), less than (<), greater than (>), and vertical bar (|) symbols to define the placement, justification, and width of the table columns. The @ symbol defines the leftmost position in a column that a value in a field can occupy. The <, >, and | symbols indicate left, right, and center justification, respectively. Repeating the <, >, or | symbol defines the column width. Table 1 summarizes the symbols. You can also insert one or more blank spaces between columns.

The following picture statement defines a left-justified column, a centered column, and a right-justified column that are each six characters wide and separated by a single space:

To define a table row, include the line statement, and map leaf nodes to fields in the line. The field statement’s argument is the leaf identifier.

When a table field must include one of several mutually exclusive values, you can repeat the @ symbol in the picture statement for each potential value and include the float statement within the field statement for each mutually exclusive value after the first value. Then if the first element does not have a value, subsequent possible elements with the float statement are tested until a value is returned. The value floats into the position defined by the first @ symbol instead of leaving a blank field.

For example, the following picture statement causes the output to include one of two mutually exclusive values in the second column:

You can also use the float statement when you know a tag corresponding to a specific table field might be missing in certain situations, and you want to eliminate the extra blank space.

The truncate statement guarantees that a field’s value does not exceed the width of the column defined by the picture statement. The truncate statement causes the output to omit any characters in the node’s value that would cause it to exceed the width of the field. If the truncate statement is omitted, and the output exceeds the width of the field, the complete contents are displayed, which might distort the table. You should use this statement with care, particularly with numbers, because the output does not provide any indication that the value is truncated.

The CLI formatting for the following RPC defines a small table with two columns. The comment field includes the float and truncate statements. If the state output element contains a value, the value is placed in the second column. However, if the state output element is empty, the value for the comment node, if one exists, is included in the table and moved into the second column. If the comment exceeds the width of that column, it is truncated to fit the column width.

When you execute an RPC on a device running Junos OS, it returns the RPC reply as an XML document. Container and leaf nodes under the RPC output statement translate into XML elements in the RPC reply. In YANG RPCs for devices running Junos OS, you can also define custom formatted ASCII output that is displayed when you execute the RPC on the Junos OS command-line interface (CLI) or request RPC output in text format.

Starting in Junos OS Release 17.3, to create custom command output for a specific RPC output container, define the format statement. The format statement defines the CLI formatting for the parent container and is not included as a node in the XML data of the RPC reply. Within the format statement, map the data for the parent container to output fields, and use statements from the Junos OS ODL extensions module to specify how to display the output for that parent container.

To create custom command output for a specific RPC output container in Junos OS Release 17.2 and earlier releases, see cli-format.

The header statement enables you to define a header string that precedes a set of fields in the RPC’s formatted ASCII output, and the header-group statement causes only the first header string to be emitted when two or more headers in the same header group would be included in the output.

To define a header string and associate it with a header group, include the header and header-group statements, respectively, within the format statement. The header-group argument is a user-defined string that identifies a particular header group. Every format statement that includes the header-group statement with the same identifier belongs to the same header group. The following example defines a format statement associated with the header group color-tags.

When multiple format statements are associated with the same header group, and the tags emitted by two or more of those statements are present in the output, the CLI output only emits the first header it encounters and suppresses any subsequent headers belonging to that header group.

To emit only the first header string for a header group in the RPC’s CLI output, include the header-group statement and identifier in all format statements belonging to that header group. The following sample RPC output statement associates two containers and their format statements with the header group color-tags.

Consider an RPC reply with the following XML tags:

When the RPC reply is rendered in the CLI and the same header-group statement is present in each format statement, only the first header string is emitted in the output, which in this case is the header string defined in the format statement with the identifier red-format.

If you omit the header-group statement from the format statement, the header string defined for each set of fields is included in the output.

The indent statement causes all of the lines in the scope of the statement other than the header row to be indented by the specified number of characters.

To indent lines, include the indent statement and the number of spaces to indent the lines at the top level of the format statement The formatted ASCII output for the following RPC displays a line that is indented by 10 spaces in the output.

When you execute the RPC, the header is left justified, and the line containing the two fields is indented ten spaces.

The no-line-break statement is used to display multiple values on the same line in the case where the output emits multiple entities with the same tag names. When you include the no-line-break statement, repeated formats are placed on the same line. If you omit the statement, repeated formats are placed on separate lines.

For example, you might want to display all SONET errors together on the same line.

To place the tags for multiple entities within the same line of output, include the no-line-break statement in the format statement for that container.

If the RPC output returns multiple entities, the output places each repeated set of fields on the same line.

If you omit the no-line-break statement, the output places each repeated set of fields on its own line.

The space statement appends a space to the node’s value in the RPC’s formatted ASCII output. For example:

The space statement is often used in conjunction with the comma statement to delimit fields in a line of output with a comma followed by a space.

To generate a space after a value in the output field, include the space statement within the format statement. The placement of a statement determines the statement’s scope. Placing the statement within a single field generates a space after that field only.

The style statement defines one of several formats for the RPC output. For detailed information about using the style statement to create different levels of output, see Define Different Levels of Output in Custom YANG RPCs for Junos Devices.

The template statement explicitly defines the format for an output field for a given node, including the output string and placement of the node’s value within the string. If the template statement is defined for a leaf node, the corresponding output field automatically uses the template string.

To create a template string for a node, you must include the template statement in the definition of the node, and define the string. The placeholders %s and %d within the string define the type and placement of the node’s value. Use %s to insert a string value, and %d to insert an integer value. For example:

If you define a template statement for a node, the output field for that node automatically uses the template text.

When you execute the RPC, the template is used in the output for that field.