Section 3.2 - DDL for Operational Commands

UI Infrastructure Programmer's Guide

3.2.1. Defining Data Hierarchy

For operational mode, the basic commands ('show', 'clear', 'request', etc.) are predefined in JUNOS; the rest of the command structures are distributed in the individual daemon DDL input files, *.cmd.dd.

Instead of 'object' and 'attribute', 'command' is the container and 'argument' is the terminal node in operational mode. They behave very similarly to their configuration counterparts. Each command can contain other commands and arguments, and each argument has to have a type specified.

Choose the appropriate data type to ensure proper user input. The type should accurately characterize this input.

It is important to construct the operational commands with self-explanatory structures, naming keywords for {command, argument} so that they can be easily understood by users.

Following are the available types for the operational mode:

Operational Mode

These are the data types in the operational mode. Since inputs in operational mode are mainly to query the system for various runtime information, there needs to be fewer data types.

Common data types
-----------------
numerical: type sbyte
	   type ubyte
	   type short
	   type ushort
	   type int
	   type sint
	   type uint
	   type int64
	   type sint64
	   type uint64
	   type sfloat
	   type ufloat
string:	   type string
boolean:   type toggle

Network-related types
---------------------
IP address:   type ipaddr
              type ipv4addr
              type ipv6addr
              type ipprefix
              type ipv4prefix
              type ipv6prefix
	      type ipprefix-optional
	      type ipv4prefix-optional
	      type ipv6prefix-optional
MAC address:  type mac-addr
interface:    type interface-device
	      type interface-unit
	      type interface-wildcard

Special-function types
----------------------
	      type filename
	      type time

        command test-command {
            help "Example of a command";

            argument test-argument {
                help "Example of an argument";
                type toggle;
            }
        }

3.2.2. Defining Help Messages

Help messages are displayed when users type '?' to query the available commands. Hence, it is important for programmers to supply the appropriate help messages.

The only rule to help messages is that they have to begin with capital letters. It is prudent that such messages are precise and concise so that they can be displayed in the limited space.

Example 1 help messages

        user@router> show test?
        Possible Completions:
        test-command            Example of a command

        user@router> show test-command t?
        test-argument           Example of an argument

        user@router>

3.2.3. Characterizing DDL entities

Once the {command, argument} entities are defined, it is essential to add the other statements to characterize these UI keywords in more detail.

Constraints

Using constraints can ensure proper user input. Add constraints when the DDL input is first implemented, as adding constraints later may break backward compatibility. The following are the possible constraints one can apply:

The match Statement

'match' is a very simple constraint statement. It limits user inputs to match the pattern (using regular expression) defined by the DDL programmer.

Flags

'Flag' is a generalized function in DDL to characterize DDL entities. In addition to supplying constraints, flags can be used to affect the DDL entities in display (presentation in the CLI), augment or provide specialized purpose of the data type, or provide special instructions for mgd to communicate the data entity to other daemons or processes.

Each DDL entity can contain one or more flags, which control aspects of that entity. Most of these flags can modify any of the major entities, including commands and objects, attributes and arguments, and even choices.

Flags are defined using the 'flag' keyword. The level in the DDL structure at which the flag is defined is the level for which it is active. Multiple flags can be defined on a single line and multiple lines of flags work identically as if they are defined on the same line.

Display-related flags
---------------------
	config
	iso8601
	k1000
	kilo
	twoset

Constraint flags
----------------
	allow-atmvpn
	allow-iso-addr
	allow-iso-prefix
	allow-iso-sysid
	allow-mask
	allow-no
	date-only
	disallow-martians
	long
	multicast-only
	no-fips
	on-all-re
	multicast-only
	time-only

Special Purpose
---------------
	advanced
	as-user
	explicit
	implicit
	no-xml
	positional

Other DDL statements

Similar to the available DDL flags, there are other DDL statements which can be used as constraints, and other purposes.

Actions

Operational commands are used to retrieve real-time data from the system. Such data can either preside with the daemon or can be retrieved using an independent process. 'action execute' is used to determine which process is contacted for the data.

Syntax

action execute <daemon_or_process_name>;

Example 2: action execute

        #define DNAME_JNX_EXAMPLED "jnx-exampled"

        require-names jnx-example;

        command juniper-command {

            /*
               Example service commands
             */
            command show {
                command jnx-example {
                    require jnx-example;
                    help "Show example service information";

                    command statistics {
                        help "Show statistics";
                        action execute DNAME_JNX_EXAMPLED;
                    }
                }
            }
        }

2007-2009 Juniper Networks, Inc. All rights reserved. The information contained herein is confidential information of Juniper Networks, Inc., and may not be used, disclosed, distributed, modified, or copied without the prior written consent of Juniper Networks, Inc. in an express license. This information is subject to change by Juniper Networks, Inc. Juniper Networks, the Juniper Networks logo, and JUNOS are registered trademarks of Juniper Networks, Inc. in the United States and other countries. All other trademarks, service marks, registered trademarks, or registered service marks are the property of their respective owners.
Generated on Sun May 30 20:23:10 2010 for JUNOS UI Programmer's Guide by Doxygen 1.4.5