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 capitalizes the value 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.

A node’s formal name, or label, is the text that precedes a node’s contents in the output. To create a label for a node, you must include the formal-name statement in the definition of the leaf node. Additionally, you must include the leading statement in the formatting instructions for that node’s output field.

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 output inserts the node’s label and a colon before the node’s value. 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 output for that field includes the label and a colon.

The comma statement appends a comma to the node’s value in the output. It is used 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 in the formatted ASCII output when the node corresponding to an output field is missing.

To define the string to display 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. You cannot include this statement in custom RPCs.

The line and field statements define lines in the RPC’s formatted ASCII output and the fields within those lines. You can also use these statements 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 you include the fieldwrap statement for a field, the entire field is moved to the next line.

You should only use the wordwrap statement 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 statement 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.

Sometimes a table field must include one of several mutually exclusive values. In the picture statement, you can repeat the @ symbol for each potential value. Then you 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 you omit the truncate statement, 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 indicate when it truncates a value.

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 output places the value in the second column. However, if the state output element is empty, the output places the value for the comment node, if one exists, in the table's second column. If the comment exceeds the width of that column, the output truncates it to fit the column width.

When you execute an RPC on a device running Junos OS or a device running Junos OS Evolved, 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 Junos devices, you can also define custom formatted ASCII output. The device displays the formatted ASCII output when you execute the RPC in the CLI or when you request RPC output in text format.

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. The RPC reply does not include it as a node in the XML data. 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.

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

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. The output suppresses any subsequent headers belonging to that header group.

To emit only the first header string for a header group, 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 device renders the output and the same header-group statement is present in each format statement, it emits only the first header string in the output. In this case, the format statement with the identifier red-format defines the first header string.

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

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 indents the line by 10 spaces.

When you execute the RPC, the output left justifies the header and indents the line containing the two fields by ten spaces.

The no-line-break statement displays 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, the output places repeated formats on the same line. If you omit the statement, the output places repeated formats on separate lines.

For example, you might want to display all interface 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 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. The definition includes the output string and placement of the node’s value within the string. If you define the template statement 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.