JUNOS Extension Functions Overview

XSLT Syntax

<?xml version=”1.0”?>
 <xsl:stylesheet version=”1.0”
         xmlns:jcs="http://xml.juniper.net/junos/commit-scripts/1.0">
    ...
</xsl: stylesheet>

SLAX Syntax

version 1.0;
ns jcs = "http://xml.juniper.net/junos/commit-scripts/1.0";

The jcs:break-lines() function breaks a single element into multiple elements, delimited by newlines. This function is especially useful in dealing with large output elements, such as those returned by the show pfe command. The function syntax is as follows:

var $lines = jcs:break-lines($output);

The jcs:close() function closes a previously opened connection handle. The function syntax is as follows:

expr jcs:close($connection);

The jcs:dampen() function is used in a script to prevent the same operation from being repeatedly executed. The function returns true or false based on whether the number of calls to the jcs:dampen() function exceeds a max number of calls in a 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 function syntax is as follows:

var $rc = jcs:dampen($tag, max, interval);

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. 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 */
}

The jcs:empty() function returns true if a node set or string argument is empty. The function syntax is as follows:

jcs:empty($set)

The following example shows how the jcs:empty() function can be used:

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

The jcs:execute() function executes an RPC within the context of a specified connection handle. Any number of RPCs can be executed within the context of the specified connection handle until that connection handle is closed with the jcs:close() function. The function syntax is as follows:

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

The jcs:first-of() function returns the first nonempty (non-null) item in a list. The function syntax is as follows:

var $result = jcs:first-of(object, "expression")

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))"/>

The jcs:get-input() function invokes a CLI prompt and waits for user input. The user input is defined as a string for subsequent use. This function cannot be used with event scripts. The function syntax is as follows:

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

In the following example, the user is prompted to enter a login name. The user’s input is stored in the variable $username:

var $username = jcs:get-input("Enter login id: ");

The jcs:get-secret() function invokes a CLI prompt and waits for user input. Unlike the jcs:get-input() function, the input is not echoed back to the user, which makes the function useful for obtaining a password. The user input is defined as a string for subsequent use. This function cannot be used with event scripts. The function syntax is as follows:

var $user-input = jcs:get-secret(prompt);

The following example shows how to prompt for a password that is not echoed back to the user:

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

The jcs:hostname() function returns the fully qualified domain name associated with an IPv4 or IPv6 address. The function syntax is as follows:

var $name = jcs:hostname($address);

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')"/>

The jcs:open() function returns a connection handle that can be used to execute RPCs using the jcs:execute() function. The connection handle is closed with the jcs:close() function. The function syntax is as follows:

var $connection = jcs:open(remote-hostname, username, passphrase) 

The following example shows how to connect to a local device:

var $connection = jcs:open()

The following example shows how to connect to a remote device:

var $connection = jcs:open(remote-hostname)

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") 

The jcs:output() function generates unformatted output text. The text appears in the CLI. The function syntax is as follows:

expr jcs:output(string);

For example:

expr jcs:output("The VPN is up.")

The jcs:parse-ip() function evaluates an IPv4 or IPv6 address and returns an array containing the following information:

• 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)

The function syntax is as follows:

var $output = jcs:parse-ip("ipaddress/(prefix-length | netmask)");

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");

The jcs:printf() function generates 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', '')"/>

The jcs:progress() function issues a progress message containing its single argument to the script log file. The function syntax is as follows:

expr jcs:progress(string);

For example:

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

The jcs:regex() function evaluates a regular expression against a given string argument and returns any matches. The function syntax is as follows:

var $pattern = "(evaluation-pattern)";
var $output = ($pattern, string)

For example:

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]

The jcs:sleep() function causes 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. The function syntax is as follows:

jcs:sleep(seconds, <milliseconds>)

The default time unit is seconds. The milliseconds argument is optional. In the following 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)"/>

The jcs:split() function splits a string into an array of substrings delimited by the regular expression pattern. The function syntax is as follows:

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

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"

The jcs:sysctl() function returns a sysctl value as a string or an integer. Use the "i" argument to specify an integer. Use the "s" argument to specify a string. The function syntax is as follows:

var $value = jcs:sysctl(sysctl-value, "s");

For example:

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

The jcs:syslog() function logs messages with a specified priority to the system log file. The function syntax is as follows:

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

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 as in the previous example. In this example, however, there are additional string parameters. For this case, the concatentated string "mymessage mymessage2" is output to the system log file.

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

Table 6: Facility Strings

Table 7: Severity Strings

For example:

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