Summary of JUNOS XSLT Extension Functions

The JUNOS extension functions provided for use in commit, op, and event scripts enable you to perform operations that are difficult or impossible to achieve with XPath. All JUNOS extension functions have the jcs: prefix on their names to indicate they belong to the jcs: namespace. This section lists the functions in alphabetical order.

jcs:break-lines()

Syntax

jcs:break-lines(expression)

Description

Break a simple element into multiple elements, delimited by newlines. This is especially useful for large output elements such as those returned by the show pfe command.

var $lines = jcs:break-lines($output);
for-each ($lines) {
    ...
}

jcs:close()

Syntax

jcs:close(connection)

Description

Close a previously opened connection handle.

In the following example, $connection is a connection handle generated by a call to the jcs:open() function:

expr  jcs:close($connection);

jcs:dampen()

Syntax

jcs:dampen($tag, max, interval)

Description

Prevent the same operation from being repeatedly executed. The dampen function returns true or false based on whether the number of calls to the jcs:dampen() function exceeds a max number of calls in the time interval interval. The function parameters include an arbitrary string, $tag, that is used to distinguish different calls to the jcs:dampen() function. This tag is stored in the /var/run directory on the router. The max parameter specifies the maximum number of times that the jcs:dampen() function with the corresponding $tag parameter can be called within the time interval interval before it returns false. The time interval is specified in minutes.

In the following example, if the jcs:dampen() function with the tag 'mytag1' is called less than three times in a 10-minute interval, the function returns true. If the function is called more than three times within 10 minutes, it returns false.

if (jcs:dampen('mytag1', 3, 10)) {
     /* Code for situations when jcs:dampen() with */
     /* the tag 'mytag1' is called less than three times */
    /* within 10 minutes */
} else {
    /* Code for situations when jcs:dampen() with */
     /* the tag 'mytag1' exceeds the three call maximum */
    /* limit within 10 minutes */
}

jcs:empty()

Syntax

jcs:empty(node-set)
jcs:empty(string)

Description

Return true if the node set or string arguments are empty.

if ( jcs:empty($set) ) {
   /* Code to handle true value ($set is empty) */
}

jcs:execute()

Syntax

jcs:execute(connection, rpc)

Description

Execute an RPC within the context of a specified connection handle. Any number of RPCs may be executed within the context of the connection handle until it is closed.

var $results = jcs:execute($connection, $rpc);

jcs:first-of()

Syntax

jcs:first-of(object, + "expression")

Description

Return the first nonempty (non-null) item in a list.

In the following example, if the value of a is empty, b is checked. If the value of b is empty, c is checked. If the value of c is empty, d is checked. If the value of d is empty, the string "none" is returned.

jcs:first-of($a, $b, $c, $d, "none")

In the following example, the function returns the description of a logical interface. If a logical interface description does not exist, the function returns the description of the (parent) physical interface. If the parent physical interface description does not exist, the function returns the concatenation of the physical interface name with a period (.) and the logical unit number.

<xsl:variable name="description"
        select="jcs:first-of(description, ../description, concat(../name, '.', name))"/>

jcs:get-input()

Syntax

jcs:get-input(string)

Description

Invoke a CLI prompt and wait for user input. The user input is defined as a string for subsequent use.

var $user-input = jcs:get-input("Enter input: ");

jcs:get-secret()

Syntax

jcs:get-secret(string)

Description

Invoke a CLI prompt and wait for user input. The input is not echoed back to the user, which makes the function useful for obtaining passwords. The user input is defined as a string for subsequent use.

var $password = jcs:get-secret("Enter password: ");

jcs:hostname()

Syntax

jcs:hostname(expression)

Description

Return the fully qualified domain name associated with a given IPv4 or IPv6 address.

<xsl:variable name="name" select="jcs:hostname($dest)"/>
<xsl:value-of select="concat($address, ' is ', jcs:hostname($address))"/>

jcs:invoke()

Syntax

jcs:invoke(rpc)

Description

Invoke a remote procedure call (RPC). The function can be called with one argument, either a string containing a JUNOS XML or JUNOScript RPC method name or a tree containing an RPC. The result is the contents of the <rpc-reply> element, not including the <rpc-reply> tag element itself.

In the following example, there is a test to see if the interface argument is included on the command line when the script is executed. If it is, the operational mode output of the show interfaces terse command is narrowed to include information about that interface only.

<xsl:param name="interface"/>
<xsl:variable name="rpc">
    <get-interface-information>
        <terse/>
        <xsl:if test="$interface">
            <interface-name>
                <xsl:value-of select="$interface"/>
            </interface-name>
        </xsl:if>
    </get-interface-information>
</xsl:variable>
<xsl:variable name="out" select="jcs:invoke($rpc)"/>

In this example, the jcs:invoke() function calls an RPC without modifying the output:

<xsl:variable name="sw" select="jcs:invoke('get-software-information')"/>

jcs:open()

Syntax

jcs:open(remote-hostname, username, passphrase)

Description

Return a connection handle that can be used to execute RPCs using the jcs:execute() extension function. The connection handle is closed with the jcs:close() function.

The following example shows how the user bsmith with a passphrase password obtains a connection handle to the server fivestar.

var $connection = jcs:open("fivestar", "bsmith", "password");

jcs:output()

Syntax

jcs:output('expression')

Description

Generate unformatted output text. The text appears in the CLI.

XSLT syntax:

<xsl:value-of select="jcs:output('The VPN is up.')"/>

SLAX syntax:

expr jcs:output('The VPN is up.');

jcs:parse-ip()

Syntax

jcs:parse-ip("ipaddress/(prefix-length | netmask)")

Description

Evaluate an IPv4 or IPv6 address and return an array containing:

Host address (or NULL in the case of an error)
Protocol family (inet for IPv4 or inet6 for IPv6)
Prefix length
Network address
Netmask (for IPv4 address; left blank for IPv6 addresses)

In the following example, an IPv4 address and an IPv6 address are parsed and the resulting output is detailed:

var $addr = jcs:parse-ip("10.1.2.10/255.255.255.0");

$addr[1] contains the host address 10.1.2.10.
$addr[2] contains the protocol family inet.
$addr[3] contains the prefix length 24.
$addr[4] contains the network address 10.1.2.0.
$addr[5] contains the netmask for IPv4 255.255.255.0.

var $addr = jcs:parse-ip("080:0:0:0:8:800:200C:417A/100");

$addr[1] contains the host address 80::8:800:200C:417A.
$addr[2] contains the protocol family inet6.
$addr[3] contains the prefix length 100.
$addr[4] contains the network address 80::8:800:2000:0.
$addr[5] is blank for IPv6 ("").

jcs:printf()

Syntax

jcs:printf('expression')

Description

Generate formatted output text. Most standard printf formats are supported, in addition to some JUNOS Software–specific formats.

The %j1 operator emits the field only if the field was changed from the last time the function was run.

The %jc operator capitalizes the first letter of the format output.

The %jt{TAG} operator emits the tag if the field is not empty.

<xsl:value-of select="jcs:printf('%-24j1s %-5jcs %-5jcs %s%jt{ - -> }s\n',
             'so-0/0/0', 'up', 'down', '10.1.2.3', '')"/>

jcs:progress()

Syntax

jcs:progress('expression')

Description

Issue a progress message containing the single argument to the script log file.

XSLT syntax:

<xsl:value-of select="jcs:progress('Working...')"/>

SLAX syntax:

expr jcs:progress('Working...');

jcs:regex()

Syntax

jcs:regex(expression, string)

Description

Return the set of strings within string that are matched by the given regular expression. This function requires two arguments: the regular expression and the string within which to search for the expression.

var $pattern = "([0-9]+)(:*)([a-z]*)";
var $a = jcs:regex($pattern, "123:xyz");
var $b = jcs:regex($pattern, "r2d2");
var $c = jcs:regex($pattern, "test999!!!");
 
$a[1] == "123:xyz"    # string that matches the full reg expression
$a[2] == "123"         # ([0-9]+)
$a[3] == ":"              # (:*)
$a[4] == "xyz"           # ([a-z]*)
$b[1] == "2d"           # string that matches the full reg expression
$b[2] == "2"             # ([0-9]+)
$b[3] == ""               # (:*)   [empty match]
$b[4] == "d"             # ([a-z]*)
$c[1] == "999"         # string that matches the full reg expression
$c[2] == "999"         # ([0-9]+)
$c[3] == ""               # (:*)   [empty match]
$c[4] == ""               # ([a-z]*)   [empty match]

jcs:sleep()

Syntax

jcs:sleep(seconds, <milliseconds>)

Description

Cause the script to sleep for a specified number of seconds and (optionally) milliseconds. You can use this function to help determine how a routing component works over time. To do this, write a script that issues a command, calls the jcs:sleep() function, and reissues the same command.

In this example, jcs:sleep(1) causes the script to sleep for 1 second, and jcs:sleep(0, 10) causes the script to sleep for 10 milliseconds.

<xsl:value-of select="jcs:sleep(1)"/>
<xsl:value-of select="jcs:sleep(0, 10)"/>

jcs:split()

Syntax

jcs:split(expression, string, <limit>)

Description

Split a string into an array of substrings delimited by a regular expression pattern. If the optional integer argument limit is specified, the function splits the entire string into limit number of substrings. If there are more than limit number of matches, the substrings include the first limit-1 matches as well as the remaining portion of the original string for the last match.

In the following example, the original string is "123:abc:456:xyz:789". The jcs:split() function breaks this string into substrings that are delimited by the regular expression pattern, which in this case is a colon(:). The optional parameter limit is not specified, so the function returns an array containing all the substrings that are bounded by the delimiter(:).

var $pattern = "(:)";
var $substrings = jcs:split($pattern, "123:abc:456:xyz:789");

returns:

$substrings[1] == "123"
$substrings[2] == "abc"
$substrings[3] == "456"
$substrings[4] == "xyz"
$substrings[5] == "789"

The following example uses the same original string and regular expression as the previous example, but in this case, the optional parameter limit is included. Specifying limit=2 causes the function to return an array containing only two substrings. The substrings include the first match, which is "123" (the same first match as in the previous example) and a second match, which is the remaining portion of the original string after the first occurrence of the delimiter.

var $pattern = "(:)";
var $substrings = jcs:split($pattern, "123:abc:456:xyz:789", 2);

returns:

$substrings[1] == "123"
$substrings[2] == "abc:456:xyz:789"

jcs:sysctl()

Syntax

jcs:sysctl(expression, "i")
jcs:sysctl(expression, "s")

Description

Return the value of the given expression or object as a string or an integer. Use the "i" argument to specify an integer. Use the "s" argument to specify a string.

var $value = jcs:sysctl("kern.hostname", "s");

jcs:syslog()

Syntax

jcs:syslog(priority, message, <message2>, <message3> ...)

Description

Log messages with the specified priority to the system log file. The priority can be expressed as a facility.severity string or as a calculated integer (see jcs:syslog() Function for more information about calculating the priority as an integer). The message argument is a string or variable that is written to the system log file. Optionally, additional strings or variables can be included in the argument list. The message argument is concatenated with any additional parameters, and the concatenated string is written to the system log file. The syslog is specified at the [edit system syslog] hierarchy level of the router configuration file.

The following three examples log pfe messages with an alert priority. The string "mymessage" is output to the system log file. All three examples are equivalent:

expr jcs:syslog("pfe.alert", "mymessage");

expr jcs:syslog(161, "mymessage");

var $message = "mymessage";
expr jcs:syslog("pfe.alert", $message);

The following example logs pfe messages with an alert priority similar to the previous example. In this example, however, there are additional string parameters. For this case, the concatenated string "mymessage mymessage2" is output to the system log file.

expr jcs:syslog("pfe.alert", "mymessage ", "mymessage2");

jcs:trace()

Syntax

jcs:trace('expression')

Description

Issue a trace message, which is sent to the trace file.

<xsl:value-of select="jcs:trace('test')"/>