CLI*manager 4.2.

1
Command Line Interface Manager

Copyright 2009 Nortel Networks Corporation. All rights reserved. Documentation version 4.2.1A

Software License
IMPORTANT NOTICE: Please carefully read this license agreement (License) before downloading, installing, using or accessing the CLI*manager software (Software). BY DOWNLOADING, INSTALLING, ACCESSING AND/OR USING THE SOFTWARE, YOU ("CUSTOMER") ACCEPT ALL OF THE TERMS AND CONDITIONS OF THIS LICENSE. The Software is licensed, not sold, and no rights are granted other than those expressly set forth in this License. 1. License. Nortel Networks Limited and/or its subsidiaries (Nortel Networks) grant Customer a personal, nonexclusive, nontransferable, nonassignable, nonsublicenseable license to internally: a) install and execute the copy of the Software provided by Nortel Networks solely for the purpose specified in the Documentation in the country where the Software was delivered (the Licensed Use), b) use the associated documentation provided by Nortel Networks solely in support of such Licensed Use (Documentation); and c) make a single copy of the Software and associated Documentation provided by Nortel solely for backup purposes. Nortel Networks and/or its suppliers (as applicable) retain all right, title and interest in and to the Software and Documentation, including any derivatives thereto and copies thereof. 2. Restrictions. Except as expressly authorized in accordance with the Licensed Use, Customer shall not a) use, copy, adapt, translate, publish, display, sublicense, rent, lease, lend, transfer or distribute the Software, Documentation, or any copy thereof; b) modify or make any other derivatives of the Software, Documentation or any copy or part thereof. Except to the extent expressly required under the Software Directive enacted by the Council of European Communities Directive dated 14 May, 1991, Customer shall not reverse assemble, reverse compile, reverse engineer or otherwise translate or decode the Software or any part thereof. Customer shall not destroy, remove or otherwise alter any copyright notice(s) on the Software and Documentation, or any copy thereof. Customer acknowledges that the Software and Documentation are and/or contain trade secrets and agrees to treat the same as Confidential Information. All Software and Documentation provided under this License is commercial computer software and commercial computer software documentation, respectively, and, in the event Software is licensed for or on behalf of the United States Government, the respective rights to the Software and associated Documentation are governed by Nortel Networks standard commercial license in accordance with U.S. Federal Regulations at 48 C.F.R. Sections 12.212 (for non-DoD entities) and 48 C.F.R. 227.7202 (for DoD entities). 3. Limitation of Liability. Nortel Networks provides the Software on an AS IS BASIS WITHOUT WARRANTIES OF ANY KIND. Nortel Networks makes no warranties written or oral, statutory, express or implied with respect to the Software, including but not limited to the implied warranties, representations, or conditions of merchantability or fitness for a particular purpose or against infringement. In no event shall Nortel Networks or its agents or suppliers be liable to Customer for any actual direct damages regardless of the cause and whether arising in contract, tort or otherwise. This limitation will not apply to claims for damages for bodily injury (including death) and damage to real property and tangible personal property for which Nortel Networks is legally liable. IN NO EVENT SHALL NORTEL NETWORKS OR ITS DIRECTORS, OFFICERS, EMPLOYEES, AGENTS, RESELLERS OR SUPPLIERS BE LIABLE FOR ANY OF THE FOLLOWING: A) DAMAGES BASED ON ANY THIRD PARTY CLAIM EXCEPT AS EXPRESSLY PROVIDED FOR HEREIN; B) LOSS OF, OR DAMAGE TO, CUSTOMERS RECORDS, FILES OR DATA; OR C) INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR LOST SAVINGS), EVEN IF NORTEL NETWORKS IS INFORMED OF THEIR POSSIBILITY. 4. Term and termination. Customer may terminate this License at any time. This License and all Customer rights hereunder, will automatically terminate if Customer fails to comply with any of the

terms and conditions of the License or if Customer should file a voluntary petition in bankruptcy, cease conducting normal business operations or if Customer is otherwise dissolved. Upon termination for any reason, Customer will immediately destroy the Software, Documentation, and all copies thereof. Notwithstanding the foregoing, the following sections of this License shall survive any termination: Section 2 (Restrictions), Section 3 (Limitation of Liability), and Section 5 (General). 5. General. Customer agrees not to export, either directly or indirectly, the Software or Documentation or any copy thereof in whole or in part, without having first obtained clearance or a licence to export or re-export from the applicable Government as required. This license is governed by the laws of the Province of Ontario. No conflict of law provision of any jurisdiction shall apply. If any part of this License is found to be void or voidable, then the remaining provisions of this License shall be enforced to the maximum extent allowable by law. CUSTOMER AGREES THAT THIS LICENSE IS THE ENTIRE AND EXCLUSIVE AGREEMENT BETWEEN NORTEL NETWORKS AND CUSTOMER AND SUPERSEDES ALL PRIOR AGREEMENTS AND COMMUNICATIONS BETWEEN THE PARTIES OR ANY OTHER DOCUMENTATION PERTAINING TO THE SUBJECT MATTER OF THIS LICENSE. ANY TERMS AND CONDITIONS ON ANY PURCHASE ORDER OR OTHER DOCUMENTATION ISSUED BY CUSTOMER WHICH CONFLICT WITH THE TERMS AND CONDITIONS OF THIS AGREEMENT SHALL BE NULL AND VOID, EVEN IF ACKNOWLEDGED IN WRITING BY NORTEL NETWORKS.

CLI*manager Overview
CLI*manager is a tool that can speed up and simplify operations and provisioning for a variety of switches and routers. This section provides a quick summary of features, and general information about this guide. Feature Summary Available Device Types What This Guide Doesn't Cover Next Section: Installing CLI*manager

Feature Summary
Connecting
A Connect Window allows users to store login information for all of their devices, for quick recall. Login information is stored in encrypted Address Books that can be shared and updated from within CLI*manager using centralized File Server Profiles. Address book data can be easily Imported from external sources. Connections can be made using both IP and Serial (local port or modem). IP Connections can be made using Telnet, SSH, and Rlogin. Many different kinds of Proxies can be used to set up connections through gateways firewalls, and modem pools. Sessions can be either managed based on a predefined target Device Type, or unmanaged using a Dumb Terminal mode. File transfers can be done using FTP, SFTP, and TFTP. SSH Tunnels can be used to tunnel through intermediate SSH devices. SSH X11 port forwarding allows X applications to run through an encrypted SSH channel.

User Interface
Session Tabs allow users to control and monitor multiple CLI sessions at the same time. Split windows can show sessions side-by-side, and control of these sessions can be linked. Hyperlinks are automatically generated in some command responses, which build other commands and navigate the tree. This allows many command-line functions to be done without typing. A customizable User Button toolbar allows users to build their own toolbars of buttons that run commands and scripts, open URLs, store notes, and start external applications. Buttons can be organized into context-sensitive groups that appear automatically when certain devices or device types are connected. For MSS-related device types there is a graphical Node Tree view for browsing hierarchies. Trees can be shown from both live connections and saved ASCII provisioning files. Flowcharts can be drawn and shared among users, for processes such as failure recovery scenarios, etc. Symbols on flowcharts can run sets of CLI commands and link to other charts. A set of linked Hierarchical Network Maps can be generated and maintained from within CLI*manager, or imported from an external source. All supported device types can be shown on the same map. Connections can be opened from devices on the map. Some CLI commands control the map. A common Command History is available for all device types. The up/down arrow keys pop up a window window that lets users navigate easily through their recent commands. On some switch types, a Component History is kept for quick access to recent device components. Any number of users can Collaborate by sharing sessions with each other and typing on the same command line. For many device types, Autotext can complete commands as they are being typed.

Syntax Enhancements
Users can easily run Commands on Multiple devices simultaneously. Enhanced Notations (-, +, &, ~, # and $) and Enhanced Commands are available on some device types that can add power to the native syntax. The MSS device type uses CLI Tables to display results in a tabular format. Customizable Translations can convert from one command syntax to another.

Logging and Monitoring

Files are automatically collected for all CLI*manager Session Logs, Device Logs, WATCH Logs, and MSS Alarm Logs. A Log Viewer window allows users to browse log files organized hierarchically by date, session, and device. Watch Mode can monitor statistics for any component in near real-time. Graphs are generated for watched statistics as they are collected. The Background Polling feature collects data much like Watch Mode, but saves the results to file in the background while you work. Alarms from MSS device types are color coded in output from the session.

Scripting
Two scripting languages are provided: Batch Jobs for simple automation tasks, and CLI*script for more advanced programming. The Script Recorder feature can automatically generate scripts from live sessions. A Script Director feature allows both types of scripts to be run against any number of target devices, with results shown in a tabular format. A built-in Script Editor provides syntax validation, coloring, and a language help sidebar. A CLI*script Debugger allows users to step through CLI*script execution, examine variables, set breakpoints, etc. An Organize Scripts window groups jobs logically and makes them easily accessible through the Batch menu, and provides mechanisms to share batch jobs through remote folders. Related Links: The CLI*manager Interface Available Switch Types Legal Statements

Available Device Types

CLI*manager can connect to a large and growing number of device types. The basic feature set is available for all of these device types, and enhanced features are available for specific types, where they apply. Application Switches Alteon Alteon Switch Firewall System Alteon Web Switch 184 Alteon Web Switch AD3 Alteon Web Switch AD4 Ethernet Switches / Routers BayStack BayStack 450 BayStack 460 BayStack 470 Business Policy Switch (BPS) Centillion Ethernet Routing Switch Ethernet Routing Switch 1200 Ethernet Routing Switch 1600 Ethernet Routing Switch 4500 Ethernet Routing Switch 5500 Ethernet Routing Switch 8100 Ethernet Routing Switch 8600 Metro Ethernet Switching Unit Metro Ethernet Switching Unit 1800 Metro Ethernet Switching Unit 1850 Nortel Secure Router Nortel Secure Router 1000 Nortel Secure Router 3120 Nortel Secure Router 6230 Nortel Secure Router 6280 MultiProtocol Routers BayRS Access Remote device (ARN) Router Access Stack device (ASN) Router Backbone Concentrator device (BCN) Router Backbone Link device (BLN) Router MultiService Switches / Edge Avici MPE 9000 Passport 4400 Multiservice Access Passport Multiservice Switch (MSS) Passport 6400 Multiservice Edge Passport 7400 Multiservice Switch Passport 15000 Multiservice Switch Passport 20000 Multiservice Switch Services Edge Router 5500 Non-Nortel Airvana Airvana DOM Other UNIX / Linux VSE Platform VT100 Terminal Secure Shell (SSH) (for generic access) Telnet (for generic access) Storage Networking BCS 3000 (Business Continuity System) Voice / Multimedia Business Communication Manager (BCM) Border Control Point Border Control Point 7100 Border Control Point 7200 Circuit Switching DMS Spectrum Peripheral Module SuperNode Data Manager XA-Core Communication Servers Communication Server 1000 Communication Server 1500 Communication Server 2000 Communication Server 2000 - Compact Gateways and Gateway Controllers Internet Telephony Gateway (ITG) Media Gateway 9000 MG9K Element Manager Neura BTX21 Media Gateway Neura BTX4K Media Gateway Neura BTX8K Media Gateway Neura NetConductor Succession GWC USP (SS7 Signaling) Universal Signaling Point (USP) Universal Signaling Point Lite CICM Integrated Element Management System MCS 5100 Meridian-1 SAM21 Shelf Controller Session Server Lines Session Server Trunks Signaling Server Succession Media Card VPN Routers Contivity 1000 Wireless Networks

Airvana RNC CVX IOS Juniper T/M/J Series Optical Optical Core HDX Long Haul 1600 OC12 OC192 OC48 OPerations Controller (OPC) OPTera DX TN4X TN16X TN64X Optical Metro Common Photonic Layer EC1 Optical Packet Edge (OPE) Optical Metro 1000 Optical Metro 3300 Optical Metro 3400 Optical Metro 3500 Optical Metro 5000 Optical Multiservice Edge Optical Multiservice Edge 1010 Optical Multiservice Edge 1030 Optical Multiservice Edge 1060 Optical Multiservice Edge 6500 Optical Multiservice Edge 6500BB Optical Multiservice Edge 6110 Related Links: Connecting to devices

ASG 5000 ASG 5100 BTS (Base Transceiver System) BTS 1060 BTS 5000 ST CPE DMS-MSC (Mobile Switching Center) DMS-MTX (Circuit Switching Platform) PDSN 16000 (Packet Data Serving device) Wireless AP 7220 Wireless LAN 2x00 Series WLAN Access Point 2220 WLAN Access Point 2221 WLAN Access Point 2300 WLAN Security Switch 2700 GGSN (GPRS Support device) GSM / UMTS Media Gateway R4 GSM / UMTS Media Gateway R5 InterWorking Function (IWF) Media Gateway (CDMA) PCUSN (Packet Control Unit Serving device) PDSN - Shasta (Packet Data Serving device) RNC (Radio Network Controller) SGSN (GPRS Support device)

What This Guide Doesn't Cover

This manual describes CLI*manager and its enhancements to standard switch syntax. It does not describe operation and provisioning of its switch-types. You should refer to switch-specific documentation for this information. Related Links: CLI*manager Overview

Installing CLI*manager
This section describes how to install CLI*manager in several operating systems and installation environments. Choosing an Installer Running a Graphical Installer Running a Console Installer Activating a License Previous Section: CLI*manager Overview Next Section: CLI*manager Startup

Choosing an Installer
CLI*manager installers are available for several operating systems. The name of the installer file specifies the version number, the target operating system, and whether or not the installer includes a bundled Java Virtual Machine (VM).
CLImanager_4.2.1_w32_vm.exe CLImanager_4.2.1_w32_novm.exe CLImanager_4_2_1_solaris.bin CLImanager_4_2_1_solaris_novm.bin CLImanager_4_2_1_linux.bin CLImanager_4_2_1_linux_novm.bin CLImanager_4_2_1.bin

Windows installer with a bundled Java VM Windows installer without a Java VM Solaris installer with a bundled Java VM Solaris installer without a Java VM Linux installer with a bundled Java VM Linux installer without a Java VM Generic UNIX installer other platforms

It is simplest to choose an installer with a bundled copy of Java (one that includes "_vm" in the filename). If you already have Java 1.4 installed, CLI*manager installers that don't include Java are smaller downloads and require less disk space on your system if you are sharing a Java VM with another application. If you choose to run CLI*manager with your own copy of Java, these are some things you should know: 1. Unlike previous versions of CLI*manager, version 4.2 requires a minimum of Java 1.6. It will not work with earlier versions of Java. 2. If you want to use serial (COM port) features in CLI*manager, you will need to add the optional Java Communications library to your own copy of Java. This library is available from the Sun web site at http://java.sun.com/products/javacomm/. If you install CLI*manager with a bundled copy of Java, this library is included automatically. Once you have chosen an installer, there are two ways to run it. Running a Graphical Installer Running a Console Installer Related Links: Installing CLI*manager

Running a Graphical Installer

By default, all CLI*manager installers start in a graphical mode, which will open windows to ask typical installation questions. You can start the installer as you would any other application. To start a UNIX/Linux installer from the command line, make sure it is executable and then run it, like this:
chmod a+x CLImanager_4_2_1_solaris.bin ./CLImanager_4_2_1_solaris.bin

After the installer starts, it will run through several steps. The screen shots shown here are from the Windows installer, but the installation windows are very similar on other platforms. The first step is the License Agreement. You must read and accept the license agreement in order to continue.

The next step is choosing the install folder. You can install CLI*manager into any directory, as long as there is enough disk space on the target drive.

The next step is choosing a Java 1.4 Virtual Machine. If you are using an installer that has its own bundled

copy of Java, you can either install that Java VM specifically for this application, or choose one that is already on your system. If the Java VM you want to use is not shown on the list, press the "Choose Another..." button.

The next step is choosing a Shortcut Folder.

The final step before installation begins is the Pre-Installation Summary. Check the settings in this window to make sure everything is correct before you begin.

The installer will then install CLI*manager with the settings you have specified. Related Links: Installing CLI*manager Running a Console Installer Activating a License

Running a Console Installer

By default, all CLI*manager installers start in a graphical mode, which will open windows to ask typical installation questions. If you are installing CLI*manager remotely through telnet or other console session, the installer can also be run in Console mode, which uses your console's standard input/output to help you configure installation options. First you must make sure that the installer file is executable, as shown below. You may need to change the name of the file in the command to match your chosen installer.
chmod a+x CLImanager_4_2_1_solaris.bin

To start the installer in console mode, use the "-i console" option, as shown below. While the installer is running, you can go back to the previous menu by typing "back", and cancel the installation by typing "quit". Console Installer: Starting
./CLImanager_4_2_1_solaris.bin -i console Preparing to install... Extracting the JRE from the installer archive... Unpacking the JRE... Extracting the installation resources from the installer archive... Configuring the installer for this system's environment... Launching installer... Preparing CONSOLE Mode Installation... =========================================== (created with InstallAnywhere by Zero G) ------------------------------------------=========================================== Introduction -----------InstallAnywhere will guide you through the installation of CLImanager. Respond to each prompt to proceed to the next step in the installation. If you want to change something on a previous step, type 'back'. You may cancel this installation at any time by typing 'quit'. PRESS <ENTER> TO CONTINUE:

The first step is the License Agreement. You must read and accept the license agreement in order to continue. Console Installer: The License Agreement
================= License Agreement ----------------Installation and use of CLImanager requires acceptance of the following License Agreement: Software License IMPORTANT NOTICE: Please carefully read this license agreement (?License?) before downloading, installing, using or accessing the CLI*manager software (?Software?). BY DOWNLOADING, INSTALLING, ACCESSING AND/OR USING THE SOFTWARE, YOU ("CUSTOMER") ACCEPT ALL OF THE TERMS AND CONDITIONS OF THIS LICENSE. The Software is licensed, not sold, and no rights are granted other than those expressly set forth in this License.

...etc... DO YOU ACCEPT THE TERMS OF THIS LICENSE AGREEMENT? (Y/N):

The next step is choosing the install folder. You can install CLI*manager into any directory, as long as there is enough disk space on the target drive. Console Installer: Choosing an Install Folder
===================== Choose Install Folder --------------------Where would you like to install? Default Install Folder: /user/bretts/CLImanager ENTER AN ABSOLUTE PATH, OR PRESS <ENTER> TO ACCEPT THE DEFAULT :

The next step is choosing a Java 1.4 Virtual Machine. If you are using an installer that has its own bundled copy of Java, you can either install that Java VM specifically for this application, or choose one that is already on your system. If the Java VM you want to use is not shown on the list, use the "Choose a Java VM..." option. Enter an option number. Console Installer: Choosing a Java VM
=============================== Choose Java 6 Virtual Machine ------------------------------Please choose a Java 6 VM for use by the installed application ->1- Install a Java VM specifically for this application 2- /usr/bin/java 3- Choose a Java VM already installed on this system ENTER THE NUMBER FOR THE JAVA VM, OR PRESS <ENTER> TO ACCEPT THE CURRENT SELECTION:

The next step is choosing a Link Location. Enter an option number. Console Handler: Choosing a Link Location
==================== Choose Link Location -------------------Where would you like to create links? ->1- Default: /user/bretts 2- In your home folder 3- Choose another location... 4- Don't create links ENTER THE NUMBER OF AN OPTION ABOVE, OR PRESS <ENTER> TO ACCEPT THE DEFAULT :

The final step before installation begins is the Pre-Installation Summary. Check the settings shown here to make sure everything is correct before you begin. Console Handler: Ready to Install
======================== Pre-Installation Summary

-----------------------Please Review the Following Before Continuing: Product Name: CLImanager Install Folder: /user/bretts/CLImanager ...etc... ================ Ready To Install ---------------InstallAnywhere is now ready to install CLImanager onto your system at the following location: /user/bretts/CLImanager PRESS <ENTER> TO INSTALL:

The installer will then install CLI*manager with the settings you have specified. Related Links: Installing CLI*manager Running a Graphical Installer Activating a License

Activating a License
When you first start up CLI*manager, the software will try to obtain a new license from the internal Nortel. If the user is internal, then the license will be downloaded in the background and the user won't see a thing. If the user is an external Nortel user, then a message will pop up telling the user to follow the link. The image below is what the message interface could look like.

When you obtain a new license file, temporarily save it anywhere (such as your desktop). Press the "Open License File" button and locate the new license. The file will be copied into your CLI*manager installation directory, and you can then remove it from the temporary location. Related Links: CLI*manager License Files Installing CLI*manager Running a Graphical Installer Running a Console Installer

CLI*manager Startup
This section describes CLI*manager startup, and options that can affect its user environment, security and behavior. Startup Arguments CLI*manager Startup Modes Single-User, No Startup Password Multi-User, Password Protected Multiple Launches Checking for Upgrades (where available) CLI*manager License Files Previous Section: Installing CLI*manager Next Section: The CLI*manager Interface

Startup Arguments
CLI*manager accepts the following startup arguments, all of which are optional:
climanager [-readonly] [-script <filename>] [-log <filename>] [-connect <address> <username> <password> <type>] [nodename1 [nodename2 ...]] -script <filename>

This option runs the specified script as soon as CLI*manager startup is complete, and then exits.
-readonly

In some environments it may be considered necessary to prevent users from modifying CLI*manager configuration settings. When this argument is used, most configuration changes are not allowed including changes to devices, proxies, address books, etc.
-log <filename>

Logs CLI*manager output to the specified filename.

-connect <address> <username> <password> <type>

Connects to a device using settings passed from the command-line. This allows connections to be automatically set up after startup without an address book entry. The type argument is
nodename1 [nodename2 ...]

The specified nodes will be automatically connected after startup, using address book login settings. Related Links: CLI*manager Startup

CLI*manager Startup Modes

CLI*manager can be configured to start in two different security modes, depending on user environment and security requirements: "Single User, No Password" and "Multiple Users, Password Protected". Single User, No Startup Password Multiple Users, Password Protected Signing In Creating New Users Resetting Forgotten Passwords Changing Your Password The startup mode can be changed in the Tools -> Options window, under the "Startup" heading.

Press the "Change..." button to open another window that allows you to change the current mode. When you change from Single to Multiple user mode, you will be asked for a password that will protect your current settings. When you change from Multiple to Single user mode, other users' settings will be retained, but the current user will become default and its startup password will be removed, making current settings available to all users.

Single User, No Startup Password

With this mode (which is the default), CLI*manager uses one collection of settings and cached address book passwords, and it does not prompt for a password during startup. This is the simplest mode and is sufficient for most cases where CLI*manager is running on a personal computer. However, if more than one user has access to the computer then they will have unrestricted access to each other's settings and passwords.

Multiple Users, Password Protected

This mode is more secure than "Single User, No Startup Password". Each user has a completely separate group of settings and cached address book passwords. Whenever CLI*manager starts up in this mode it will prompt for a username and password before continuing. Note that in some cases you may want to use this mode even if you are the only user, to protect your CLI*manager settings with a startup password. Signing In When CLI*manager starts up in multi-user mode, the startup banner will contain a login form like the one shown below. CLI*manager will not start until you sign in with a valid password. Buttons along the bottom provide other sign-in functions: the "Reset" button resets the password for the selected user; the "New" button creates a new CLI*manager user with default settings; and the "Exit" button exits CLI*manager without signing in.

Creating New Users New users can be created by anyone, using the "New" button in the sign-in form. You must enter a new CLI*manager name and a password with at least 8 characters. The new account will have default settings and no cached passwords. After entering the required information, press the OK button and you will be signed in as the new user. Pressing the "Cancel" button will return to the sign-in form.

Resetting Forgotten Passwords

If you forget your CLI*manager password, there is no way to recover it. You can reset your password to a new one and login with your saved settings, but in doing so you will erase all of your cached passwords. If your address books are encrypted with passwords, you will need to re-enter them. This prevents other users from gaining access to your address books. The "Cancel" button will return to the sign-in form.

Changing Your Password After you have signed in, you can change the password for your user with the "CLI*manager Password" item in the Tools menu.

Related Links: CLI*manager Startup

Multiple Launches
By default, if more than one instance of CLI*manager is launched on the same machine, new windows will be opened each time. Separate windows consume more memory, and it is sometimes better to keep all of your CLI*manager sessions within the same window. Another option is provided that detects multiple launches and brings them together into the same window, with a new CLI Tab for each launch.

Related Links: CLI*manager Startup

Checking for Upgrades (where available)

Users who are running CLI*manager on Nortel's internal network can automatically detect new versions during startup, or with the "Check for Upgrades" item in the Tools menu. "Released" versions only offer to upgrade to newer "released" versions, and "beta" versions offer to upgrade to any newer version. "Test" versions can be chosen manually, but they do not alert you automatically.

Related Links: CLI*manager Startup

CLI*manager License Files

During startup, CLI*manager checks for a valid license file, which contains information such as the registered user name, version number, and expiry date. After the expiry date has past, you will need a new license file in order to continue using CLI*manager. For external users, 30 days before your license expires you will be shown a warning message like the one below every time CLI*manager starts up. To download a new license file, follow the instructions in the message. When you download a license, make sure that you select the correct version, as well change the filename as requested on the site. When you obtain a new license file, temporarily save it anywhere (such as your desktop). Press the "Open License File" button and locate the new license. The file will be copied into your CLI*manager installation directory, and you can then remove it from the temporary location.

If the expiration date passes before you obtain a new license, the next time you start up CLI*manager you will be halted until you get a new one. You will be forced to either update the license or exit. If there are any errors with retrieving your license, or with the license itself, you will get a similar message to the one below.

To see your license details at any time, use the "View License" item in the Help menu, which will open a window like the one below. If your license is valid and is not expiring in under thirty days, then the background should be green.

Related Links: Activating a License CLI*manager Startup

The CLI*manager Interface

This section gives a general outline for working with the CLI*manager window - its buttons, menus, and graphical components. More detailed descriptions for some features can be found in other sections. The CLI*manager Window Main Toolbar Menus The Options Window Session Tabs User Buttons The Node Tree Flowcharts FTP/SFTP File Server Profiles File Synchronization The Table Viewer Log to CSV Command History Component History Auto-Text Notes Searching for Text Previous Section: CLI*manager Startup Next Section: Connecting to Devices

The CLI*manager Window

The main CLI*manager window has a number of toolbar buttons to give you quick access to common features. Session tabs at the bottom allow you to quickly switch between sessions, and monitor sessions that are running in the background. Buttons inside the CLI window allow you to open a new connection, or reopen other recent connections.

Other buttons and controls appear around the main window depending on the current context. For example, some device types show alarm lights in the bottom corner when alarms are received. The collaboration state is shown in the bottom corner, if a server is active or a remote session has been connected. Related Links: The CLI*manager Interface

Toolbar Buttons
The toolbar at the top of the main window provides quick access to commonly-used features. Some buttons are only available in certain contexts, based on the current device type.

Connect Address Book Connect Terminal Logout

opens the Connect window, which allows you to define devices and store their connection details in an Address Book. Press the arrow beside the button for a list of recent connections. opens a window that allows you to manage multiple address books, for storing addresses, passwords, maps, etc. opens the Connect Terminal window, which allows you to connect in Dumb Terminal mode to any device using Telnet, SSH, Rlogin, or Modem Pool. Logs out from currently connected devices. The arrow beside this button opens a drop-down menu with more choices such as logging out from specific devices, and logging out from all devices in all CLI tabs. "Logout All" logs out from all connected devices in the all CLI Tabs. "Logout Current" logs out from all connected devices in the current CLI Tab.

Search Watch Node Tree Maps Alarms Log Viewer

searches for text in the main CLI window. prompts you for a command or component to watch, then starts WATCH mode. shows the Node Tree on the left of the CLI window, for displaying a hierarchical diagram of components in connected switches. This item is only available when you are connected to an MSS device type. opens a new window pane above the CLI window for displaying and generating Network Maps. opens the Log Viewer window and selects the current MSS alarms log. The arrow beside this button may appear if more than one alarm source is available (e.g. alarms from the current session plus alarms from a CLI*server). opens a new Log Viewer window for organizing and reviewing several types of log files. The Log Viewer button in the main toolbar has a drop-down menu with these items: "Log Viewer" opens the Log Viewer window. "Start New Log Files" closes all log files in the current CLI Tab, and opens a new set of files. Use this when starting a new activity that should be logged separately. An optional label can be entered that will be included as part of the log filename. "Log File Upload Queue" shows a list of log files that need to be (or have been) automatically uploaded to a server. This queue can be important for cases where the upload server is not reachable for some reason: logs will be kept in the queue and uploaded later when the server becomes available. Log files appear in this queue automatically whenever they are closed - such as when the session is logged out or CLI*manager

exits. In addition, extra files can be dragged into the list, and they will be added to the queue. Information about logs that have been uploaded successfully will be kept in the queue for one day, for reference. Files that have not been uploaded successfully will remain in the queue until they are either uploaded or manually deleted from the local machine. Background Polling opens the Background Polling window, which collects statistics in the background by repeatedly running sets of commands. User Buttons History Table Viewer Console Run Script Script Editor Collaborate Related Links: The CLI*manager Interface shows the User Buttons toolbar at the bottom of the main window. opens a new Command History window that shows previous commands and allows for quick recall. opens a new Table Viewer window for viewing large tables in a spreadsheetlike format. opens a new window that shows raw output from all selected switches. This can be useful for debugging purposes, especially when users have problems connecting to a switch. allows you Run a Script from your local disk or from a URL. This can also be done from the command line with the SCRIPT command. Press the arrow beside the button for a list of recent scripts. opens a Script Editor, which can be useful for editing CLI*scripts, batch jobs, proxy scripts, etc. Press the arrow beside the button for a list of recently edited files. connects with another user's CLI*manager session using Collaboration.

The Connect Menu

Connect from Address Book opens the Connect window, which allows you to define devices and store their connection details in an Address Book. Connect Dumb Terminal Connect from Server Recent Connections Login Again As Set device Type opens the Connect Terminal window, which lets you connect to any device in Dumb Terminal mode using Telnet, SSH, Rlogin or a Modem Pool script connects using information from an Address Server database. opens a window that lists information about recent connections made from CLI*manager, including the device type and time of last connection. logs out from the current device(s), and logs in again with a different user. converts an active plain telnet or SSH session (which do not provide device-specific features) into a defined CLI*manager device type. This can be useful for cases where proxy connections are difficult. Telnet or SSH to reach the target device manually, and press the Set device Type button once you are logged into the device. logs out from the current devices. logs out from all devices - including background connections that are may not be in use. drops the current connections, without logging out. This may be necessary in cases where a device session is hung or unresponsive. sends a telnet break sequence to active target connections. This is initially intended only for MCS 5100 configuration through terminal servers. when this item is selected, key-presses will be sent periodically to all open connections to avoid automatic logout due to inactivity. closes the current window and exits CLI*manager.

Logout Logout All Hang Up Send Break Keep Alive Exit Related Links: The CLI*manager Interface Menus

The Edit Menu

Cut Copy Paste Copy and Paste Select All Clear Clear All Tabs Search Search Again Add Note Line Wrap Auto-Logging Local Echo Log to File cuts selected text from the main CLI window and places it in the clipboard. copies selected text from the main CLI window and places it in the clipboard. pastes text from the clipboard into the command prompt. copies selected text from the main CLI window and pastes it into the command prompt. selects all text in the main CLI window. clears all text from the main CLI window. clears all text from all open Session Tabs. searches for text in the main CLI window. See Searching for Text. repeats the previous search for text in the main CLI window. adds a short text note to the CLI window, which will be highlighted in the window and stored in open log files. This text will not be sent to any devices. See Notes. toggles line wrapping on and off. By default lines are wrapped at your window width. When line wrap is disabled a horizontal scrollbar will appear that can be used to show content outside of the window width. toggles Auto-Logging on and off for the current session. toggles local echo on and off for plain telnet sessions. This menu item does not appear unless a dumb terminal session is active. logs the session from the current CLI Tab to a file. This log will be in addition to the automatic logs that are available in the Log Viewer window.

Log Tables to CSV logs results from all CLI Table commands to a CSV file. CSV is a commaseparated file format that can be loaded directly into most spreadsheet applications. (Note that this menu item is only available when the connected device type is capable of CLI Tables.) See Log to CSV. Related Links: The CLI*manager Interface Menus

The View Menu

The View menu provides a number of new windows and window options. Each menu item has a checkbox that can be toggled to enable or disable the corresponding view. Some menu items are only visible in certain contexts, such as the selected device type or tab status. Node Tree Maps User Buttons History Console Table Viewer adds a new frame at the left of the CLI window for displaying a hierarchical diagram of components in connected switches. This item is only available when you are connected to an MSS. opens a new window pane above the CLI window for displaying and generating network maps. shows the User Buttons toolbar at the bottom of the main window. opens up a new History window that shows previous commands and allows for quick recall. opens a new window that shows raw output from all selected switches. This can be useful for debugging purposes, especially when users have problems connecting to a switch. opens a Table Viewer window that displays tables from MSS commands in a graphical, spreadsheet-like format.

New CLI Tab starts a new CLI*manager session, and adds a tab for it at the bottom of the window. New tabs can also be added by pressing the "+" button beside the tabs. Remove Tab Next Tab Previous Tab removes the current CLI tab. This function is not available if only one tab is open, or if more than one tab is selected. switches to the next tab to the right. switches to the next tab to the left.

Split Tab View splits the main window to show all of the current sessions. Link CLI Tabs links control of the selected sessions. Keys typed into any session will be forwarded to other sessions. New Window Related Links: The CLI*manager Interface Menus opens a new CLI*manager window.

The Script Menu

The Batch menu provides a number functions that allow you to run and organize batch jobs. Each menu item has a checkbox that can be toggled to enable or disable the corresponding view. Some menu items are only visible in certain contexts, such as the selected device type or tab status. Run Script... Script Director... Script Editor Record Script allows you to choose a file from your local disk or URL, and run it as a CLI*script or batch job. opens the Script Director, which sets up and controls scripts for very large numbers of devices. opens the Script Editor for editing CLI*scripts, batch jobs, proxy scripts, or other text documents. automatically generates a script from the current session.

Organize Script Menu... opens the Organize Scripts window that allows you to add scripts to the Script menu for easy access, and group them logically into submenus as necessary. This is similar to the "Favorites" feature in web browsers. Refresh Remote Folders queries all defined remote XML files for changes to remote batch jobs. This item is only visible if at least one remote batch job source has been defined. The Organize Batch Jobs window can define other items and submenus below these Batch menu items, providing easy access to your jobs. Related Links: The CLI*manager Interface The Organize Scripts Window Menus

The Tools Menu

The Tools menu provides access to a variety of features and configuration options. Watch Log Viewer FTP/SFTP Collaborate Run SPAT File Synch MSS ASCII File prompts you for commands to monitor, then starts WATCH mode. opens a new Log Viewer window for organizing and reviewing several types of log files. opens the FTP/SFTP Window for transferring files starts a Collaboration session another CLI*manager user. starts a SPAT module. SPAT is an external perl utility that can be plugged into CLI*manager. opens the File Synch window, which copies sets of CLI*manager files from remote file server directories into local CLI*manager directories. opens the Node Tree window with the specified ASCII provisioning file.

Background Polling opens the Background Polling window, which collects statistics in the background by repeatedly running sets of commands. Flowcharts Address Books Proxies opens the Flowchart Window, which allows users to draw flowcharts of decision trees such as failure recovery scenarios, etc. opens the Address Books Window, which allows you to manage multiple address books, for storing addresses, passwords, maps, etc. opens the Proxy Configuration Window, which allows you to list and adjust proxy details for indirect access to devices.

File Server Profiles opens a window for defining File Server Profiles, which are used by some CLI*manager features such as Shared Address Books. SSH Keys CLI*servers opens the SSH Keys Window, which lists cached host keys and generates key pairs for SSH authentication. adds and configures remote CLI*servers, which provides centralized information to CLI*manager clients.

Check for Upgrade checks for new versions of CLI*manager. This feature is only available to users on the Nortel intranet. Options Related Links: The CLI*manager Interface Menus opens the Options window, which allows you to customize the CLI*manager interface.

The Options Window

You can change many properties of your CLI*manager interface with the Options window, in the Tools menu.

The Backup and Restore buttons can be used to save and load your full set of CLI*manager preferences (options, encrypted cached address book passwords, etc) to an XML file. This can be useful for backup purposes, and for sharing settings with other users. Options are grouped into categories to make them easy to find. The table below lists details for each option. General Options Address Book Folder Address Books can be stored in any local directory. The directory specified here will be scanned during startup for new books. When you create books they will be stored in this directory by default. This sets the maximum number of commands to store in the Command History. Sets the number of seconds that commands can run before enabling the command beeper. If any commands takes longer than this duration to run, CLI*manager will beep to let you know when it is complete. When this option is selected, pressing the up/down arrow keys in the main terminal window will pop up a list of recent commands. When this option is enabled, selected text in the CLI window will be automatically copied to the clipboard, and right-clicking will paste. When this option is not selected,

Store <x> recent commands in the history buffer Beep when commands finish after more than <x> Show command history popup Auto-copy selected text, and paste with right mouse button

selected text will not be automatically copied, and rightclicking will pop up a context menu with copy and paste functions. Scroll to the bottom for new output When this option is not selected (the default), if the user scrolls the CLI text area up above the current command prompt, the text area no longer scrolls down to the bottom when new output is printed. This allows the user to view results higher up in the log while results are still being printed. When the user scrolls back down to the command prompt, normal output scrolling is re-enabled. This turns pagination on and off. If enabled, command responses that are too long to fit in your CLI window will prompt you for "More" before continuing. Turns the Component History on and off. If enabled, you can scroll through a cache of recently-used components while typing a command. Turns the Hyperlinks feature on and off. By default windows keyboard shortcuts for copy and paste (ctrl-c and ctrl-v) are disabled when in plain telnet or SSH mode. Checking this option will enable the copy and paste keyboard shortcuts for telnet and SSH. When this option is selected, CLI*manager will make a sound when there is a failure, such as a dropped connection, etc. You can select your own waveform file to play when this happens. If no file is specified then a default beep will be used. CLI*manager can start up in two different modes, depending on user environment and security requirements. The default mode is "Single User, No Startup Password", which uses only one set of stored settings and does not require a password during startup. The other mode is "Multiple Users, Password Protected", which uses completely separate settings for each user and requires users to enter a password when CLI*manager starts up. See CLI*manager Startup Modes for more information. Checks for other CLI*manager sessions running locally during startup. If another CLI*manager session is found, this option will either open a new window or add new tabs to the existing window. Some systems have graphics driver compatibility problems with the Java VM, which can sometimes cause CLI*manager to crash on exit. Disabling DirectDraw can sometimes help with this problem. When DirectDraw is disabled, graphics performance within CLI*manager will be slightly reduced. Changes to this setting will take effect the next time CLI*manager is started. Specifies the maximum number of recent connection

Prompt for "more" Enable a browsable history of recent CAS components Generate hyperlinks within command responses Enable keyboard shortcuts for Telnet and SSH sessions Play sound on failure

Startup and Shutdown Options Startup Mode

If more than one instance of CLI*manager is launched Disable DirectDraw

Show <x> recent connections

in startup headers Protected shutdown

hyperlinks that will be shown when CLI*manager starts up. These hyperlinks can be clicked to quickly re-open a connection made recently. When selected, exiting the CLI*manager application will cause a more cautious shutdown than normal. This may be necessary to avoid crashes on some systems - especially those with very low memory. If you are not experiencing crashes when exiting CLI*manager, it is recommended that you leave this option deselected. This option is off by default. Use the size selection and font chooser button to change the font in the main CLI window. Only fixed-width fonts are allowed. These options specify the colors used by the main CLI window. This option sets the maximum number of lines in the scroll buffer. Note: Setting this value too high could result in memory problems. When this option is selected, the cursor in the main CLI window will be a rectangle, instead of a vertical line. This option is off by default. This option decides whether the cursor in the main CLI window should be blinking or solid. When this option is enabled, CLI*manager auto-detects the name of the device during login (for some device types), and uses this name in the command prompt instead of the name from the address book. If this option is disabled then the command prompt will show names from the address book. Updates device names stored in Address Books to reflect actual names that are auto-detected while logging in. This feature is not available for all device types. Also, this option is available only when the option above ("Detect device names during login") is enabled. When this option is selected, CLI*manager will download a standard set of modem pool proxies and proxy scripts for connecting through Nortel's supported modem pools. CLI*manager will automatically check for updates to these files once per day. When this option is enabled, a window pops up the first time you connect to a new SSH host, showing the fingerprint and asking if you want to continue. If the expected fingerprints are known, this can be useful for verifying new hosts and preventing eavesdropping.

Appearance Options CLI Font Background, Foreground, Cursor and Hyperlink color Keep up to <x> scroll lines in the CLI window Block cursor Blinking cursor Connection Detect device names during login (where available)

Update device names in address books

Use a synchronized list of Nortel modem pool proxies

SSH Warn about unauthenticated SSH keys from new hosts

Enable X11 forwarding, where available

When this option is enabled, X applications can be forwarded through an encrypted SSH channel. You can connect to the remote host using any CLI*manager SSH connection, and the DISPLAY variable will be automatically configured for you on the remote host so that X applications will be sent to your machine through the encrypted channel. Note that this feature requires an X server on your local machine such as Exceed, Cygwin/X, X-Win32, etc. By default this feature is disabled. Sets the port to be used for all local serial connections that are stored in address books. Sets the port to be used for all modem connections that are stored in address books. Sets an initialization string to be sent to the modem before dialing, for modem connections stored in address books. Specifies the local directory where log files will be stored for reference by the Log Viewer. When enabled, this feature will automatically upload all log files to the specified file server profile (in a new subdirectory for the current username) whenever they are closed. Uploaded files can be monitored using the Log Upload Queue. Specifies the number of days that log files should be kept, for reference by the Log Viewer. CLI*manager can log curses driven terminal data to file by taking a snap shot of the screen every 800 ms by default. The user can manipulate the period of each frame by changing this value. Note: CLI*manager must be restarted in order for the new value to take effect. Writes all output from all connections to debug files. This option should normally be turned off, but it can be enabled to help troubleshoot CLI*manager issues. Turns the Translator on and off. You can press the Setup button for more translation settings. After the "activate" command is issued in an MSS session, CLI*manager can automatically issue a "confirm" command when the activation is complete, preventing accidental rollback. This is normally safe, because if the activation caused the switch to become unreachable then CLI*manager would not be able to confirm. Enables Range Notation. This option is enabled by default, but users can uncheck it to disable range notation if it interferes with their native command syntax. Enables Range Block syntax, which can be used to run a

Serial Port to use for local serial Modem Port Modem Init Log Log Folder Upload log files to <x>

Remove log files older than <x> days. Log curses screen shots every <x> milliseconds.

Dump all output to debug log files Syntax Enable syntax translation Auto-confirm provisioning after activation

Enable range notation Enable range block syntax

block of commands for each instance in a range. If you experience cases where this syntax conflicts with native syntax, you can disable it with this option. Auto-confirm provisioning Hide response timestamps within ranges Watch Watch graph line width Watch graph samples before Scrolling Color Watch values Show raw Watch results Record changing values only Scripts Log trace() output to file Validate CLI*script syntax in the Editor as you type Use syntax coloring in the Editor Enable script restrictions CLI Tables Enable CLI Tables turns CLI Tables on and off (for MSS only). If enabled, results from all "display" and "list" commands will be automatically formatted into tables. If disabled, normal raw output from the command will be shown. CLI Tables can also be enabled and disabled with the CLITABLES command. Turns Table Summarization on and off for tables. If enabled, identical components in tables will be summarized by combining them into ranges. Turns Context Hyperlinks on and off for tables. If enabled, CLI*manager will generate a list of "Context" hyperlinks to related commands and components in the context of each table. Specifies whether or not CLI Tables should be used for TL1 device types (OPTera, etc.). This option is disabled Logs debug output from the CLI*script trace() function to file. Checks for CLI*script syntax errors in the Script Editor, as you type. Colors text in the Script Editor based on keywords for the specified scripting language. Prevents a list of commands from being executed by scripts, batch jobs, and plugins. This can be useful for security purposes. Sets the width of lines on WATCH graphs. Sets the number of samples to show in the WATCH graph at a time (default 100). Older samples can be shown by scrolling. Shows values in the WATCH results window with the color of its corresponding line in the graph. Shows all watch results in the main CLI window, not just in the WATCH window. When this option is enabled, WATCH results will be logged to file only when they change. Automatically confirms provisioning on Passport MSS device types after every activation. When running a command against a large number of components using Range Notation, timestamps and their ok/failed result can be hidden to reduce clutter in the output.

Summarize identical sequential components Generate context hyperlinks

Enable CLI Tables for TL1 device types

by default. Remove saved tables after <x> days Alarms Store a maximum of <x> Show a warning light for <x> Sets the maximum number of alarms to store in the Alarms window, before discarding the oldest alarms. Sets the number of seconds that the Alarm Lights should remain colored after an alarm is received. Specifies the number of days that saved results will be kept, after being saved by the "-save" command-line option.

Show alarms in the CLI window Turns alarms on and off for the main CLI window. If enabled, alarms will be sent to the Alarms window and they will be shown in the main CLI window. If disabled, alarms will only be sent to the Alarms window. Color alarms by severity in the CLI window TFTP Disable the built-in TFTP server Sets the built-in TFTP server to disabled by default. Allow scripts to enable the build-in TFTP server when required Use the built-in CLI*manager TFTP server Use an external TFTP server on this host Upgrade Upgrade Server Location Check for upgrades during startup The web server address to use when checking for CLI*manager upgrades. For users who have access to the Nortel intranet, CLI*manager can check for availability of new versions and offer the option to upgrade. "Released" versions check only for newer "released" versions, and "beta" versions check for any newer version. See Checking for Upgrades for more information. When the built-in TFTP is disabled by default, this option allows scripts to enable the it. Enabled the built-in TFTP server Disables the built-in TFTP server, and uses another server installed on this host instead. When alarms are shown in the main CLI window, they can be colored based on severity (red for critical, etc).

Related Links: The CLI*manager Interface

Session Tabs
The Session tabs at the bottom of the main window allow you to quickly switch between multiple active CLI sessions. Each tab shows the names of the active devices in its session, along with a small icon showing the current status of the session. These icons indicate states like no-connection, command-in-progress, watch mode, and user-intervention-required.

Compared to opening new windows, session tabs are faster and more efficient with memory and screenspace. Session tabs can be added and removed by pressing the and buttons beside the tabs. Typing "quit cli" from a session's CLI also removes the current session tab. Sessions from multiple tabs can be shown and controlled at once. To enable this feature, hold down the Shift key and click on multiple CLI tabs. The main CLI window will be split to show all of the selected tabs. Also, three new buttons , and will appear in the bottom-left corner of the window. These controls are also available from the View menu.

Toggle the button to join or split control of the selected tabs. When tabs are "joined" in this way, all commands that are typed into one tab will be automatically copied to the other tabs. The other two new buttons and control whether the CLI window will be split horizontally or vertically to show multiple tabs. Related Links: The CLI*manager Interface

User Buttons
The "User Buttons" toolbar is an optional toolbar that can be shown at the bottom of the main CLI*manager window. It can be toggled on and off with the " User Buttons" item in the main toolbar and in the View menu.

A select-box is shown on the left side of the toolbar that lets the user switch between multiple button groups. Users can add their own button groups with the " New Button Group" option in the popup menu. Also, two enhanced button groups are available by default: Current Type Automatically changes the available buttons based on the connected device type. This can be used to set up different buttons for each type. When you are connected with at least one device, it's type name is shown in the select-box. Current Device Automatically changes the available buttons based on the connected device. This can be used to set up different buttons for each device. When you are connected with at least one device, that device name is shown in the selectbox. Users can add their own buttons to each group by pressing the " Add New Button" button.

These types of buttons can be added: "Command" buttons issue predefined commands in the main CLI window. "Note" buttons open a window that allows the user to enter freeform text notes. A "Run Selected" button in the Notes window runs lines in the selected text as commands. "Web Page" buttons open a predefined URL in the system's default browser. "Script" buttons run a predefined Script in the current CLI Tab. "Application" buttons start external applications on the local machine. Once added, buttons can be edited and deleted by right-clicking on them. Buttons can be reordered within the toolbar by dragging.

Press the " " arrow beside the " group:

Add New" button for a menu of actions to perform on the current button

"New Button Group" creates a new button group, which you can choose from the select box on the left side of the toolbar. "Share Button Group" opens a window that allows the user upload/download button groups to/from remote File Servers. "Rename Button Group" changes the name of the current group. Predefined groups (Current Type and Current Device) change their names dynamically and cannot be manually renamed. "Delete Button Group" deletes the current group. Predefined groups (Current Type and Current Device) cannot be deleted. "Add New Button" adds a button to the current group.

Sharing Button Groups

The "Share Button Group" item in the popup menu opens the window below, which allows users to upload/download button groups to/from remote File Servers, similar to the way that Address Books can be shared. This allows button groups to be shared among multiple users.

Related Links: The CLI*manager Interface

The Node Tree

The "Node Tree" feature displays a graphical tree for components in the connected MSS. It can also show trees based on saved ASCII provisioning files.

Node Tree Usage

Open the Node Tree from the View menu or from the main toolbar. Double-click on a component to either display it in the CLI window, or add it to the end of a command you've already started typing. Right-click on a component for quick access to commands that can be run in the CLI window, such as "display -p", "list", etc. Expand all subcomponents of the selected component by selecting the "Expand All" item in the right-click menu. Note that this can sometimes be slow due to the number of commands necessary to discover subcomponent structure, so it is best to expand small branches at a time if possible. Refresh an single branch either through the right-click menu or by collapsing and then re-expanding a tree branch. If more than one device is connected in the current CLI Tab, the tree for each device can be shown by selecting the device name from the drop-down above the tree.

Node Tree Buttons

Open ASCII Opens an ASCII provisioning file from your local system. To obtain an ASCII file from an MSS device, use the command "save -ascii prov", and transfer the file to your local machine. This action is also available from the Tools menu. Refresh Close Related Links: The CLI*manager Interface Refreshes the entire tree. Closes the Node Tree view.

Flowcharts
CLI*manager allows users to draw flowcharts that integrate with the command-line. Buttons on flowchart symbols can run commands and scripts, and can link to other flowcharts. This feature can be useful for decision trees such as failure recovery scenarios, configuration procedures, etc. The flowchart window is available from the Tools menu.

Toolbar Buttons
New Open Save Save As Edit Show/Hide Tree Creates a new flowchart, and starts Edit mode. Opens a flowchart file that may be outside of the Chart directory structure (and therefore not shown in the tree).. Saves the current flowchart. Saves the current flowchart using a new filename. Starts/Ends Edit mode. Shows and hides a tree on the left side of the window that lists all flowcharts in the Charts directory. To show a flowchart in the tree, just select it.

Show/Hide Path Highlights When this button is selected, symbols along your path through the tree will be highlighted in blue. Highlighting is not shown while in Edit mode. Clear Path Highlights Clears all highlights around symbols along your path.

Edit Toolbar Buttons

While in Edit mode, these additional buttons are shown in the toolbar:

Select Start Decision Action Go To

Allows you to select and move flowchart symbols. Starts adding a new "Start" flowchart symbol, which is typically shown at the beginning of the chart, and provides one connector arrow to the next symbol. Starts adding a "Decision" flowchart symbol, which provides two labeled arrows that branch from the decision point. Starts adding an "Action" flowchart symbol, which represents an action that must be done at that stage of the process. One arrow is provided that connects to the next symbol. Starts adding a "Go To" flowchart symbol, which links to another flowchart.

Terminator Starts adding a "Terminator" flowchart symbol, which represents the end of a decision tree. Delete Deletes selected symbols from the flowchart.

Creating a New Flowchart

To create a new flowchart, press the "New" button. The new flowchart will automatically have one start symbol where your process will normally begin. You can edit the label beside the symbol, and the labels on its arrows, by clicking and typing.

To add another symbol to the chart, click one of the symbol buttons in the Edit toolbar. You can then move your mouse into the chart and position the new symbol. As you move the new symbol, if the new symbol overlaps an unattached arrow endpoint the arrow will be highlighted with a green circle. Click to attach the symbol to the indicated arrow. Again, labels can be edited by clicking and typing.

Existing symbols can be moved by clicking and dragging. When a symbol is moved, all of the downstream connected symbols will also be moved.

Arrow endpoints can be moved by clicking and dragging. This can be used to connect the arrow to a different symbol, or to another point around the edge of the same symbol. When the arrow is over a valid connection point, it will be highlighted with a green circle.

The starting point of an arrow can be moved to another point around its originating symbol, by clicking and dragging. The start point of an arrow cannot be moved to another symbol.

Double-click on a symbol to pop up a window for editing its properties. The "Short Label" field specifies text to be shown in the center of the symbol. If the selected "Action Type" is anything other than "No action", a button will be shown in the symbol's center that, when pressed, runs the specified commands or a script. This applies to all symbol types other than "Go To".

Double-click on "Go To" symbols (orange circles) to specify another chart that will be shown when the symbol's button is pressed. The "Link to Chart" field has a drop-down list of charts in the same directory. The folder button beside the field allows you to choose any file.

Related Links: The CLI*manager Interface

The FTP/SFTP Window

CLI*manager includes a simple FTP/SFTP window (available from the Tools menu) that transfers files to and from remote devices. The remote device can be specified using either an address book entry, or manually by supplying an address, username and password. The left side of the window shows local directories and files. The right side of the window first shows a form for choosing the remote device. With FTP (not SFTP), address book devices are allowed to use certain types of Proxies, as long as the proxy involves some sort of UNIX/Linux server near the endpoint.

Once a remote device has been connected, the right side of the window shows files and directories found on the remote end.

Files can be transferred by dragging them from one side of the window to the other. Related Links: The CLI*manager Interface SFTP Command CLI*script Functions ftpget, ftpmget, ftpput CLI*script FTP and SFTP Objects

File Server Profiles

File Server Profiles are used by a number of features in CLI*manager including Shared Address Books and auto-uploading Log Files. Profiles are defined using the window below, which can be reached from the Tools menu or by pressing the button wherever it appears.

To add a new profile, press the New Profile button to open the window below. A "Profile Name" must be assigned to every profile for reference purposes.

Three profile "methods" are available: FTP This method is capable of both upload and download. You must supply an address, username and password for a remote server. The "Directory" field is optional, but if present it will specify the main directory on the remote server that should be accessed. URL This method is capable of downloading files from a remote web server. Uploading is not possible. Mapped Path This method copies files to/from a specific path from/to the local CLI*manager Address Book directory. The path can be a shared drive (E:, H:, etc), an NFS mounted file system, etc. Keeping a local copy of files such as address books avoids contention issues and improves speed. Related Links:

File Synchronization
The File Synch feature in the Tools menu copies sets of CLI*manager files from remote file server directories into local CLI*manager directories, and checks for updates either periodically or on demand. By default, files are copied in the background after startup the first time CLI*manager starts in each day. Several types of files can be synchronized, including Script Files, Proxy Files, and Flowcharts. When file synchronization is in progress for a certain type of file, users may be delayed from using that type of file until synchronization is complete.

Add Edit Delete

Adds a new file synchronization entry. Edits the selected file synchronization entry. Deletes file synchronization entries in the selected rows.

Copy Now Starts file synchronization immediately. If no rows are selected in the table then all entries will be synchronized. If some rows are selected then only entries in those rows will be synchronized. Close Closes the window.

The "Add" and "Edit" buttons open a window for specifying which remote files will be synchronized.

Copy files of type

the type of files to be copied from the remote server: Script Files, Proxy Files, or

Flowcharts. From file server a predefined File Server Profile from which the files will be copied. All profile methods can be used. The FTP and Mapped Drive methods can copy entire directories of files matching the file type. With the "URL" method, the target URL is expected to be an HTML web page, and all hyperlinked files on the page will be downloaded if they match the file type.. the local directory to which files will be copied. This can be either automatically set to the default directory for the file type, or manually set to a specific directory by the user. If this option is selected then local files with the copied filename will be overwritten. If not selected then the local file will be preserved and the file will not be copied from the remote server. If this option is selected then subdirectories of the target directory on the remote server will also be copied, along with all files matching the copied file type. A maximum subdirectory depth prevents too much directory recursion. This option has no effect on File Server Profiles that use the "URL" method.

From remote directory the directory at the remote end from which files should be copied. To local directory Overwrite local files that already exist Copy subdirectories to a depth of <x>

Also synchronize If this option is not selected (the default), then file synchronization will take place periodically every <x> the first time the CLI*manager is started within each day, or when the "Copy minutes Now" button is pressed. If this option is selected then CLI*manager will also copy changed files from the remote server at the interval specified. Related Links: The CLI*manager Interface

The Table Viewer

The Table Viewer displays tables from MSS commands and TL1 commands on optical nodes in a graphical, spreadsheet-like format. When this window is opened, you can either type commands into the command field at the top-left of the window, or into the main CLI window. Any command that results in a table will be shown in both the CLI window and the Table Viewer.

The viewer's mode menu (shown as "Rate/s" above) allows you display WATCH-like statistics in the table instead of raw values themselves. Refresh Flip refreshes the table by re-running the command. flips the table by converting rows to columns, and columns into rows.

Save As... saves contents of the table to a tab-delimited text file, suitable for importing into spreadsheet applications. You can copy data from the table viewer by selecting cells and pressing Ctrl-C. (This option is also available from a right-click menu.) Row and column headers from the selected cells are automatically included in the copy. The copied cell data is in tab-delimited format, and can be pasted directly into many text editors and spreadsheet applications.

Related Links: The CLI*manager Interface CLI Tables Log to CSV

Log to CSV
This window allows you to set up a log file for results from all CLI Table commands. (The log will ignore results from other commands.) All rows and columns from each table will be added to the specified file in CSV comma separated format.

Enter a file name for the CSV log sets the destination file name. Use the file button on the right to browse your local file system. You can also use the drop-down list to recall recent CSV log files. Append When this option is selected, results will be appended to the existing file. Otherwise, the existing file will be overwritten with new results.

Once you have logged table data into a CSV file, it can be imported directly into spreadsheet applications such as Microsoft Excel. It is also possible to write your own programs to process and manipulate data stored in this format.

Related Links: The CVSLOG Command

Command History
Previous commands can be recalled by using standard up-and-down arrow keys, which opens a pop-up window for navigating recent commands. The pop-up window can be disabled and enabled from a checkbox in the Tools -> Options -> General window.

Previous commands can also be recalled by typing an exclamation mark followed by the starting segment of a command in the history. For example, "!watch" will re-run the previous WATCH command. Two exclamation marks ("!!") run the previous command. Related Links: The CLI*manager Interface

Component History
For MSS, CLI*manager keeps an internal cache of all of the components you have referenced recently. While typing a command, you can scroll through this cache by pressing Ctrl-P and Ctrl-N (Previous and Next). This saves typing by allowing you to quickly recall components you have already worked with. The size of the component cache depends on the size of the command history buffer (which is configurable under Tools -> Options). After you find the component you want, just continue typing to finish your command.

In the example above, the user typed "d" and then pressed Ctrl-P to recall the component used in the previous command. Related Links: The CLI*manager Interface

Autotext
If you press the Tab key while you are typing a command, CLI*manager will try to display a list of valid choices to complete your command. You can then use the arrow keys to select a choice, or continue typing to filter the available choices. In the example below, the user has started to type a command, and then pressed the Tab key. CLI*manager has provided a list of possible attributes and subcomponents of the CA component, which the user can select from with the arrow keys or mouse. The list can be filtered by typing a prefix. For example, by typing "ma" below this list would be filtered to show only those attributes that start with "ma".

Another useful example for MSS occurs when your partial command ends with a slash ("/") character. In this case, CLI*manager will list available components that match your command, as shown below.

Note that this feature is not available on all device types. Related Links: The CLI*manager Interface

Notes
You can add notes at any point in your CLI session for future reference in log files. These notes are not sent to any connections, but they are highlighted in your CLI window and recorded in log files if any are open. To add a note, choose the "Add Note" item in the Edit menu or press Alt-N. You can then type a note and press Enter when you are finished. Pressing Alt-N again (instead of pressing Enter) will cancel the current note.

In the example above, the user pressed Alt-N and then typed a note about the previous command. After pressing Enter, the user was returned to the normal command prompt. Related Links: The CLI*manager Interface

Searching for Text

CLI*manager has a simple search feature that can find specified text anywhere in its CLI window. Choose "Search..." from the Edit menu (or press Ctrl-S), and a search area will appear at the bottom of the terminal window.

Type some search text and press Enter to search backwards, or press the Previous and Next buttons. Related Links: The CLI*manager Interface

Connecting to Devices
Users can connect to several different types of devices, and can connect to multiple devices simultaneously. This section outlines the ways that users can establish and manage these connections. The Connect Window The Connect Terminal Window The * Command Address Books The Address Books Window Sharing Address Books Proxies Proxy Scripts
Example Proxy Script Proxy Script Variables Proxy Script Commands

Login Defaults Set Device Type The ABIMPORT Utility Secure Shell (SSH) SSH Host Keys Local SSH Key Recent Connections Login Again As... Logging Out Nortel Modem Pool Related Links: Available Device Types

Previous Section: The CLI*manager Interface Next Section: Command-Line Enhancements

The Connect Window

To open the connect window, choose "Connect..." from the Connect menu, or press the " " Connect button in the toolbar. This window lets you store and manage login details for all of your devices. It also lets you connect to a device or whole groups of devices.

Opening Connections
In its simplest view, the Connect Window shows only a list of devices for the selected Address Book. You can filter the list by typing into the Name field, and by selecting certain device types, regions or sites. Columns in the list can be sorted by clicking on the headings. You can sort on multiple columns by Ctrlclicking on more than one heading. To open a connection with devices in the list, double-click on them or select them from the list and press the "Connect" button. You can select multiple devices by dragging or using the Shift and Ctrl keys. When more than one device has been selected a "Separate Tabs" checkbox appears, which tells CLI*manager to connect to with each device in a different CLI Tab.

Editing Login Details

Press the "Show Details" button to edit details for a device or to add a new device. Enter its details into the fields on the right, and press the Apply button to store them into the address book.

These are some of the common fields in the Details form: A name for the device, which will be shown in the address book and used by the "*" Command. The name cannot contain spaces, and it must be unique within the address book. Type The device type. This is a very important detail, because choosing the wrong type may prevent CLI*manager from successfully logging in or managing the session. The and buttons toggle the type selection between a tree (organized by category), and a plain list. Address An IP address or DNS name for the device. You can specify more than one address, separated by commas. CLI*manager will try to connect to each address (in order), until a connection is successful. This can be useful for routers with multiple interfaces - some of which might be out of service. Port Port numbers can be left blank for the relevant default port, or specified if necessary. User Name The login username for the device. Password The login password for the device. Proxy Enables the use of intermediate Proxies like intermediate workstations and corporate firewalls. After Login Allows you to define a set of native commands to run automatically after logging onto the device. Commands attached in this way must be native syntax (i.e. no CLI*manager enhancements, etc.) and their responses will be ignored. This can be useful for cases where you always want to turn on logging or disable timeout, etc., for particular devices. Name

Comments Can contain any notes you have about each device, and it is not used when connecting. Each type of device can also have its own set of specific fields. For example: BayRS routers have a field that enables automatic entry to BCC mode after login. OPTera Packet Edge connections have fields that allow access through an "NP Punch Through", which allows CLI*manager to connect through an NP rather than directly to the card. Secure Shell (SSH) can be used for encrypted connections to some device types, by selecting the "Secure Shell" checkbox in this window.

Groups of Nodes
Multiple devices can be collected into groups, and connected all at once by using a group name. For example, you might want to connect to all devices in a particular city or region. To create a group, choose "Group" from the device-type list (in the "Other" category) and enter a name for the group. Then press the "Edit Group" button, select devices from the main list and press the "Add" button. After you have chosen all of the devices you want in the group, click again on the "Edit Group" button. Devices can be removed from the group by selecting them from the Group list on the right and pressing the "Remove" button In the example below, all devices in Hong Kong have been added into a group, and they can all be connected by pressing the Connect button or by typing "em hongkong" from the CLI.

Related Links:

The * Command
In addition to the graphical Connect window, you can also connect to devices from the CLI command-line by using the command "* <devices>". (The "EM" command is also accepted for backward compatibility with earlier versions of CLI*manager.)

The + and - commands can be used to make modifications to the currently-connected list of devices. The + command connects to the specified devices and adds them to the prompt. The - command removes the specified devices from the prompt. Any number of devices can be connected in this way, as long as their login details have been configured in an Address Book. The names of currently-selected devices are shown in the command prompt, and any commands typed by the user are sent to all of those devices. Device names can be shortened when using the * command. As long as a unique match for the specified name is found in the configuration (from the Connect Dialog), that device is connected. If more than one is found, a list of matching device names is shown.

The * and + commands can be cancelled by pressing the Ctrl-C key. This can be useful for cases where a device name was typed incorrectly and a large number of address books need to be searched. Related Links: Connecting to Devices

Address Books
Connection information (addresses, passwords, maps, etc.) is stored in Address Books. When you create an address book, you must choose a password that will be used to encrypt information in that book. If someone sends you an address book, you will need to know the password to open it. After you enter the password, it will be cached locally in settings for your local user account, so you won't be asked for it again unless the it changes.

The Address Books Window

Address books can be managed with the "Address Books" window (available from the Tools menu, the main toolbar, and the Connect window). Existing books are listed in the order that they will be searched when making connections. Books in the list can be reordered with the arrows beside the list.

The buttons above and below the list of address books provide functions for managing your list of address books. Create Add Get New Refresh adds a new empty address book. adds an existing address book from your local file-system. The file will be copied into your main Books directory. downloads a new address book from a remote FTP server. refreshes the list of address books, and refreshes the contents of selected books.

Get Updates downloads updates for the selected address book from a remote FTP server, if configured. Send Import uploads the selected address book to a remote FTP server. imports device information from a text file. See ABIMPORT for the expected file format.

Password Save As Delete

sets or changes the password for the selected address book. saves the selected address book with a new name, or in another format. deletes the selected address book (as long as it is not in use).

The status of each book is shown by the icon beside its name. For example, a "key" icon represents a password-protected book for which the password is known, and a "lock" icon represents a book for which the password is not known. An asterisk (*) icon is shown for new books that have not been loaded yet. And a red X icon is used for books that have problems, such as a failed auto-update. No Password Password Known represents an address book that has no password assigned to it. The book is still encrypted, but any copy of CLI*manager can read it. represents an address book for which the password is known. After you correctly enter the password for an address book, it is remembered for future access.

Password Not Known represents an address book for which the password is not known. The book cannot be opened until you enter its password. New Address Book Failed to Update represents a new address book that has never been opened locally. represents an address book has failed to download an auto-update.

Sharing Address Books

Address Books can be stored on a centralized server for access by any number of users, using FTP, mapped drives, or HTTP URLs. This is configured through the "Get Updates" and "Send" buttons in the Address Books window.

The "Profile" field at the top of the window specifies a File Server Profile to use for downloading and uploading the address book. When you are downloading a new address book from the remote server, the available books are listed. Before uploading or downloading any address book, you must enter a password into the "Book Password" field. The options at the bottom of the window control address book sharing. Overwrite existing entries When address book updates are downloaded from a in the local book remote server, this option decides if devices in the remote book should overwrite devices with the same name in the local book. Discard entries that are When address book updates are downloaded from a only in the local book remote server, and there are devices in the local book that are not found in the remote book, this option decides if the local devices should be automatically deleted. Selecting this option can prevent old devices from staying around after they have been deleted in the remote book. Automatically download When this option is selected, CLI*manager will updates to this book automatically download updates for this book from the remote server whenever the book is opened. This can be useful for keeping the local book up to date. Automatically upload all When this option is selected, CLI*manager will changes to this book automatically upload updates to the remote server whenever it is changed locally. This can be useful for keeping the remote server up to date. Related Links:

Proxies
Proxies are used to connect to devices that cannot be reached directly. The Proxy configuration window can be opened by pressing a button beside the proxy in the Connect IP window, or "Proxies..." in the Tools menu.

Proxies are normally stored in Address Books, which is convenient if the address book file is shared with other users or copied to another host. Proxies that are stored in the Local Proxy Archive are available in the Connect window lists no matter which address book is selected, which is convenient when the same proxies need to be by multiple books. The "Proxy Name" is simply a name that you can use to reference the proxy, and it can be any text. The "Method" tells CLI*manager how the proxy works, and it has a number of options which decide what the other proxy parameters will be. Available methods include: "Remote Workstation Telnet" connects to a UNIX workstation at the specified address, uses the specified username and password to login to the workstation, and then runs a "telnet" command to the destination device. "NMC Remote Access " connects to device through the Nortel NMC, using two gateways and an NMC-supplied access code. "User@IP_Address" connects to a terminal-server that expects the device's IP address to be passed as part of the terminal server's user name, like "user@47.1.2.3". "Gateway to Workstation " connects outward through a gateway to a UNIX workstation, then runs a "telnet" command to the destination device. "Proxy Script" runs a specified script before attempting to login to the destination device. This provides a great deal of flexibility when users need to connect through complex proxy configurations, like tunneling through a firewall or through multiple workstations. For more detail on the syntax used for writing proxy scripts, see Proxy Scripts. "Proxy CLI*script" runs a CLI*script to set up a connection. This is similar to the "Proxy Script" method above, but it provides a more powerful scripting language. Certain functions and predefined variables are added to CLI*script when a proxy CLI*script is running. "Remote Workstation SSH " connects to the specified workstation using secure shell (SSH). Once it

reaches the workstation, it then runs either telnet or ssh to connect to the destination device, depending on the device's configuration in the address book. "Modem to Workstation " calls a remote UNIX workstation using a modem on the local PC, then runs telnet (or SSH depending on settings in the device itself) to the destination device. "Device in Address Book" uses any device defined in your address books as a proxy to reach other devices. CLI*manager will connect to the proxy device, and then run either a "telnet" or "ssh" command to reach the target device. "Multiple Hops" allows for long chains of connections to be defined. Up to 10 hops can be defined - each with an address, user name, and password. Beside the address field there is an "SSH" checkbox, which allows SSH to be enabled or disabled for each hop to the destination. Beside each username and password field there is a "Prompt" checkbox that can be used to specify any parameters that should be prompted from the user as the connection is set up. "SSH Tunnel" can be used to tunnel SSH connections through another SSH host to reach the target device. After a proxy has been configured, it can be assigned to a device through the Connect dialog. When you make changes to a proxy, those changes are reflected in all devices that use that proxy. Related Links: Connecting to Devices Proxy Scripts

Proxy Scripts
Sometimes users need to connect through complex proxy configurations, like tunneling through a firewall, a modem pool, or multiple workstations to get to destination switches. CLI*manager provides a flexible solution for these situations, in the form of proxy scripting. Users can write their own proxy scripts using a plain text editor (such as the Script Editor). Proxy scripts are embedded in address books, so if you share your address book with another user, the scripts will be automatically included. Proxies can be written in two languages: CLI*script and a custom "Proxy Script" language. CLI*script is more powerful, because it provides core JavaScript language constructs such as loops, code blocks, math, etc. The proxy script language is simpler. When a proxy script finishes (by parsing to the end of the file or by reaching an exit command), CLI*manager assumes that it will receive login prompt from the device as if it was directly connected. The exceptions are the loggedin() function and the LOGGEDIN command, which tell CLI*manager that the device is already logged in when the script finishes.

Proxy Scripts
Predefined Proxy Variables Proxy Script Functions CLI*script Proxy Functions Example CLI*script Example Proxy Script Predefined Proxy Variables These predefined proxy script variables return settings for the target device from the address book: The CLI*script variables below are predefined only when the script is being run by a proxy. CLI*script Variable
address phonenumber serialspeed

Proxy Script Variable

$address $phonenumber $serialspeed

Description the IP address defined for the target device the modem phone number defined for the target device the serial speed (baud) defined for the target device the serial settings (e.g. "8-None-1" or "7-Even-1") defined for the target device the number of serial data bits defined for the device (e.g. 8) the of serial parity defined for the device (even or odd) the number of serial stop bits defined for the device (e.g. 1)

serialsettings $serialsettings serialdatabits serialparity serialstopbits

Proxy Script Functions These are functions available for Proxy Scripts. Note that there equivalents for many of these as CLI*script Functions, listed in the next section.

CALL CALLLOCAL CALLMODEM CALLSSH CRLF DOMENU ECHO ENDPROMPTS EXIT FAIL FTPPROXYPOINT IFFOUND IFNOTFOUND LOGGEDIN PASSWORDARG PASSWORDPROMPT SEND SLEEP STARTPROMPTS TEXTARG TEXTPROMPT WAITFOR
call "<address>"

Connects to the specified address. By default it connects to the telnet port (23), but other ports can be specified by using a colon notation like "1.2.3.4:5678", or with the <port> option in CLI*script.
calllocal "<speed>,<settings>"

Connects through a local COM port (defined for each CLI*manager instance in the Options window), using the specified baud rate and settings. The expected speed and settings are usually found in the serialspeed and serialsettings variables.
callmodem "<speed>,<settings>,<phonenumber>"

Connects through a locally-attached modem (defined for each CLI*manager instance in the Options window), using the specified baud rate, settings, and phone number. The expected speed, settings, and phonenumber are usually found in the $serialspeed, $serialsettings, and $phonenumber variables.
callssh "<address>,<user>,<password>"

Connects to the specified address with secure shell (SSH), using the specified username and password.
crlf <on | off>

Specifies whether or not CLI*manager will send both carriage return and line-feed after input lines. If this setting is off (the default), only a line-feed is sent.
domenu "<menu1>[/<menu2> ...]" "<prompt>"

This command can be used to automate some menu-driven connection methods. The first parameter is a slash-separated list of text from the expected menu items. (This would normally

be passed in the $address variable from the Address field in the Connect window.) The second parameter is the prompt expected at the end of each menu. The remote device is expected to send a numbered list of menu items like this:
1. Site A 2. Site B 3. Site C Choose a site: 2 1. device AA 2. device BB Choose a device: 1

To respond to a menu like this, a proxy script could use this DOMENU command to connect to device AA.
domenu "Site B/device AA" "device:"

For each menu item, the proxy script will wait for the specified prompt ("device:" in this case), then look in the previous response for a line containing the specified menu item text ("Site A"), along with a number near the beginning of the line. If found, the script will automatically enter the corresponding number and move onto the next prompt, until all menu items have been entered. If any of the expected menu items is not found, the proxy script will fail with a message telling the user which menu item was not found. A typical implementation of this would use a common proxy script to connect to multiple devices through the same menu system. The slash-separated menu item list could be entered into the Connect Window in the address field for each device, which would be accessible to the proxy script in the "$address" field:
domenu "$address" "device:" echo "<text>"

Prints the specified text to the user's CLI window. This command is primarily used for debugging proxy scripts.
exit

Stops running the script. CLI*manager will assume that the proxy script was successful and that it can now expect a login script from the switch.
fail ["<message>"]

Stops running the script. CLI*manager will print the specified message (if present) and abort the switch login process.
ftpproxypoint

If this proxy is being used by the CLI*script functions ftpget(), ftpmget() or ftpput(), then the proxy script stops at this point. At this point it is assumed that the proxy has logged into a UNIX/Linux device. Transferred files will be stored temporarily on this server, and deleted when the transfer is complete.
iffound ["<text>"] <commands>

Runs the specified command if the specified text was received by the last WAITFOR

command. If no text is specified then the command is run if any of the WAITFOR strings were received in the last WAITFOR command.
iffound ["<text>"] ... endif

Runs all of the commands up until the next ENDIF statement if the specified text was received by the last WAITFOR command. If no text is specified then the commands are run if any of the WAITFOR strings were received in the last WAITFOR command.
ifnotfound ["<text>"] <command>

Runs the specified command if the specified text was not received in the last WAITFOR command. If no text is specified then the command is run if none of the WAITFOR strings were received in the last WAITFOR command.
ifnotfound ["<text>"] ... endif

Runs all of the commands up until the next ENDIF statement, if the specified text was not received by the last WAITFOR command. If no text is specified then the commands are run if none of the WAITFOR strings were received in the last WAITFOR command.
loggedin

Tells CLI*manager that the device has been logged in. Otherwise, when a proxy script finishes CLI*manager assumes that it will receive the normal login prompt from the device.
passwordarg "<userprompt>" <variablename>

Defines a password argument for the script. The <userprompt> message will be shown in the proxy configuration window, where the user will be asked to provide a value. When the script runs, the value provided by the user can be referenced by prefixing the <variablename> with a "$" sign. The PASSWORDARG command is identical to the TEXTARG command, except that in this case the user's input in the proxy configuration window will be hidden.
passwordprompt "<label>" <variable_name>

Prompts the user for a variable value. A window will pop up with the specified label and an empty password field that hides the entered value. The user will be forced to either enter a nonempty value and press OK, or press Cancel.
passwordprompt "Enter a password" password echo "Password: $password"

The script above would open a window that looks like this:

If multiple prompts are necessary in the same pop-up window, multiple TEXTPROMPT and

PASSWORDPROMPT commands can be placed inside of a STARTPROMPTS ... ENDPROMPTS block. The PASSWORDPROMPT command is similar to the PASSWORDARG command. The difference is that PASSWORDARG values are preconfigured and saved in address books, so that users do not need to re-enter them every time they connect.
send "<text>"

Sends the specified text to the connection, followed by a newline. The effect is the same as a user typing the text and pressing Enter. Note: It is an error to issue a "send" command before a connection has been opened with one of the CALL commands.
sleep <seconds>

Pauses the script for the specified number of seconds.

startprompts ... endprompts

The STARTPROMPTS and ENDPROMPTS commands specify a block of proxy script lines that contain TEXTPROMPT and PASSWORDPROMPT commands to be added to the same prompt window. Once the ENDPROMPTS line is reached, a window will pop up with all of the specified prompts. The user will be forced to enter non-empty values for all prompts and press OK, or press Cancel.
startprompts textprompt "Enter a Username" username passwordprompt "Enter a Password" password endprompts echo $username echo $password

The script above would open a window that looks like this:

If only one variable is required in a prompt window, the TEXTPROMPT and PASSWORDPROMPT commands can also be used outside of a STARTPROMPTS ... ENDPROMPTS block.
textarg "<userprompt>" <variablename>

Defines a text argument for the script. The <userprompt> message will be shown in the proxy configuration window, where the user will be asked to provide a value. When the script runs, the value provided by the user can be referenced by prefixing the <variablename> with a "$" sign. The TEXTARG command is identical to the PASSWORDARG command, except that in this case the user's input in the proxy configuration window will be visible.
textprompt "<label>" <variable_name>

Prompts the user for a variable value. A window will pop up with the specified label and an empty text field. The user will be forced to either enter a non-empty value and press OK, or press Cancel.
textprompt "Enter a Username" username echo "Username: $username"

The script above would open a window that looks like this:

If multiple prompts are necessary in the same pop-up window, multiple TEXTPROMPT and PASSWORDPROMPT commands can be placed inside of a STARTPROMPTS ... ENDPROMPTS block. The TEXTPROMPT command is similar to the TEXTARG command. The difference is that TEXTARG values are preconfigured and saved in address books, so that users do not need to re-enter them every time they connect.
waitfor "<string1>"[,"<string2>"...][,<seconds>]

Waits for any of the specified strings from the connection. By default, the command will wait for 10 seconds before giving up, but other timeout values can be specified as a number of seconds. Results from the WAITFOR command can be checked with the IFFOUND and IFNOTFOUND commands. CLI*script Proxy Functions The CLI*script functions listed below are available only when the script is used as a proxy. They have equivalent functionality to their Proxy Script namesakes listed above. Most of the Standard CLI*script Functions will also with when used as a proxy.
call(<address> [, <port>]) callssh(<address>, <user>, <password>) calllocal(<speed>, <settings>) callmodem(<speed>, <settings>, <phonenumber>) setcrlf([true | false]) proxyarg(<label>, <variablename>) proxypassword(<label>, <variablename>) proxyloggedin()

Example Proxy CLI*script This example CLI*script calls the address of a UNIX workstation, logs in using a fixed username and password, and then runs the "telnet" command to an address defined in the Connect window.
/* This example script connects through a UNIX * workstation to a destination device. */

// These are arguments, which the user will be // prompted for in the proxy configuration. proxyarg("Address", "workstation"); proxyarg("User", user); proxypassword("Password", password); // Call the workstation's address call(workstation); // Wait for the login prompt if (!waitfor("login:", 10)) fail("No login prompt"); // Send the workstation username send(user); // Wait for the password prompt if (!waitfor("Password:",3)) fail("No password prompt"); // Send the workstation password send(password); // Wait for the UNIX command prompt if (!waitfor(new Array("1>","Login incorrect"),10)) fail("No command prompt"); if (found("Login incorrect", true)) fail("Login incorrect"); // Telnet to the address defined for this node // in the CLI*manager connect dialog send("telnet "+address);

Example Proxy Script The example below demonstrates most of the accepted commands and syntax in the Proxy Script language. As shown, comments can be written using both double-slash ("//") and slash-star ("/* ... */") syntax. The example script calls the address of a UNIX workstation, logs in using a fixed username and password, and then runs the "telnet" command to an address defined in the Connect window.
/* This example Proxy Script connects through a UNIX * workstation to a destination device. */ // These are arguments, which the user will be // prompted for in the proxy configuration. textarg "Address" workstation textarg "User" user passwordard "Password" password // Call the workstation's address call "$workstation" // Wait for the login prompt waitfor "login:" ifnotfound fail "No login prompt" // Send the workstation username send "$user" // Wait for the password prompt waitfor "Password:",3 ifnotfound "Password:" fail "No password prompt" endif // Send the workstation password send "$password" // Wait for the UNIX command prompt waitfor "1>","Login incorrect",10 iffound "Login incorrect" fail "Login incorrect" ifnotfound "1>" fail "No command prompt" // Telnet to the address defined for this node

// in the Connect window. send "telnet $address"

Related Links: Connecting to Devices Proxies The Text Editor

Login Defaults
If you attempt to connect to a switch using the "*" command and the device name is not found in any address book, CLI*manager searches its address books for the first instance of a device with the name "default". For example, if most of your devices use a common username and password, define a device called "default" with those settings. CLI*manager will attempt to determine the IP address of the device through DNS, or through your local host table, or through the host table of a proxy if one is specified. Related Links: Connecting to Devices The Connect Window The * Command

Changing the Device Type

Sometimes it is easiest to connect manually to target devices using the Connect Terminal window, or a simple Telnet, SSH or Rlogin command. This is especially true if the method to reach the target device is complicated and cannot be automated using a Proxy. However, these connection methods put CLI*manager in a Dumb Terminal mode where many CLI*manager features are disabled. To re-enable CLI*manager enhancements, you need to tell CLI*manager what type of device you are connected with. After you have manually logged into the target device, choose a device type from the menu on the main toolbar. This section of the toolbar always shows what type CLI*manager thinks it is connected with. You can then continue your session with CLI*manager enhancements enabled.

At any time you can return to Dumb Terminal mode by choosing Dumb Terminal from the menu again. Then you can connect to other devices or device types without dropping the connection. Related Links: Connecting to Devices The Telnet Command The SSH Command

The ABIMPORT Utility

The ABIMPORT utility can be used to manage address books from outside of CLI*manager. This can be useful for generating and manipulating address books based on data from external sources, such as databases or spreadsheets. Typically, ABIMPORT is used in scheduling services such as UNIX cron jobs. Devices are added to address books using either tab-delimited text input files or the "-add" option. In both cases, imported fields and their ordering can be specified with the "-format" option. By default, the import format is "nupatsr", which translates to the following fields:
devicename user password address devicetype site region

The fields in the import file can be customized with the -format option. Proxy and CLI*server definitions can also be added to address books using other options. Syntax for command:
abimport -p <bookpassword> [options] <bookfile> [<inputfile>]

Available options:
-p bookpassword

Sets the password for opening the address book (and for saving the address book if the -np option is not used). This is a required option for all abimport functions. Leave the bookpassword field blank if the default address book (CLImanager.abk) is being opened and the password has not been set.
-np newpassword

Sets the password for saving the address book. If this option is not found then the p password will be used for both loading and saving.
-format fieldorder

Sets the order of fields expected for each device imported, using one letter per field and specified as one word. If this option is not found then the default format is "nupatsr". n device name a address u user name p password t device type s site name r region name c comment x proxy name h ssh: y/n (default n) m method: ip/direct/modem (default ip) # modem phone number b serial baud rate (default 9600) d serial data bits: 7/8 (default 8)
-new

Creates a new address book. If the book file already exists then it will be overwritten.
-add <field1> [<field2> ...]

Adds a single device to the address book. The arguments following are expected to be fields that describe the device, with the order and number specified by -format.
-ws proxyname address user password

Adds a proxy workstation to the address book.

-script proxyname filename

Adds an embedded proxy script to the address book.

-serv servername address port [-servp password] [-collab] [-alarms]

Adds a CLI*server to the address book.

-ftp address username password filename

Sets an FTP auto-update server for this address book.

-cd

Clears all device information from the book before importing. If this option is not found then new devices will be appended to the address book.
-cp

Clears all proxy information from the book before importing. If this option is not found then new proxies will be appended to the address book.
-cs

Clears all CLI*server information from the book before importing. If this option is not found then new CLI*servers will be appended to the address book.
-remove devicename

Removes the specified device from the address book.

-profile filename

Specifies a profile filename that contains any/all of the options above. This import method may be more secure because passwords in the options do not appear in process lists. File permissions should be used to protect the profile file.
-typenames

Prints a list of device type-name abbreviations that can be used in the "t" field of the input file, then exits.
-list

Lists all device names in the address book, then exists. When this option is in effect, multiple <bookfile> names are allowed as long as they all have the same book password.

-count

Prints a count of all devices in the address book, then exists. When this option is in effect, multiple <bookfile> names are allowed as long as they all have the same book password.
-help

Prints this help information, then exits. Related Links: Connecting to Devices Address Books Address Book Commands

Secure Shell (SSH)

Secure Shell (SSH) is a protocol for secure remote login and other secure network services over an insecure network. CLI*manager has built-in support for SSH2, which can be used in several ways: Some CLI*manager device types (e.g. Alteon, BayStack, Passport MSS, Passport 8600) have "Secure Shell" checkboxes in their Connect window settings. There is a "Remote Workstation SSH" Proxy type, which can be used for secure connections through intermediate UNIX workstations. There is a device type called "Secure Shell (SSH)", which behaves just like the "Plain Telnet" device type other than the connect method. This is intended for generic access. CLI*script has a callssh(<address>, <user>, <password>) function that sets up a new SSH connection from the local machine to the address. Proxy scripts can use a CALLSSH command to automate proxy connections through custom environments. You can use a SSH command to connect in a Dumb Terminal mode. In this mode, most of CLI*manager's enhanced features are disabled. SSH X11 forwarding allows X applications to be run with all X traffic forwarded through an encrypted SSH channel. By default this feature is disabled, but it can be enabled in the SSH section of the Options Window. When enabled, you can connect to the remote host using any CLI*manager SSH connection, and the DISPLAY variable will be automatically configured for you on the remote host so that X applications will be sent to your machine through the encrypted channel. This feature requires an X server on your local machine such as Exceed, Cygwin/X, X-Win32, etc.

SSH Host Keys

The "SSH Host Keys" window, available from the Tools menu, allows users to view and remove cached host keys from SSH connections. These keys are used to detect eavesdropping attacks. You may need to remove keys from the cache if they are changed on the remote hosts.

Local SSH Keys

The "Local Keys" tab in the "SSH Keys" window allows you to generate new SSH key pairs, and export public keys if necessary. These features are only necessary when connecting to SSH servers that require public key authentication.

Generate New Key The "Generate New Key" button opens the window below, which allows you to choose the key type and length. Key types are either DSA or RSA. Key lengths range from 512 to 2048 bits. Longer keys have better security, and shorter keys are faster.

Delete Key Deletes the selected key pair files. Export Public Key Exports the public half of the selected key pair, using either OpenSSH or IETF key file format. Some SSH servers only support certain public file formats. After exporting a public key file, you will need to transfer the file to the server in order to use the corresponding private key to authenticate. Related Links:

Recent Connections
Every time users connect to devices using the Connect window or the * command, an entry is added to the bottom of the Connect button in the main toolbar. This provides a quick way to return to connections you've made recently. The "Recent Connections" item in the Connect menu lists information about recent connections made from CLI*manager, including the device type and time of last connection.

Also, whenever you start CLI*manager, the most-recent connections will be shown as buttons in the startup banner, for easy access. Related Links: Connecting to Devices

Login Again As...

Sometimes users need to logout from devices and log back in again with a higher-powered user. This can be done with the "Login Again As..." item in the Connect menu. After a new user and password have been entered, all of the currently selected devices (the ones shown in the command prompt) will be logged out, and reconnected using the new user account.

If the "Use for future connections" checkbox is selected, the specified account will be used for all future connections in this session, so that you don't need to manually reconnect every time. This function is also available from the CLI with the RELOGIN command. Related Links: Connecting to Devices

Logging Out
CLI*manager automatically logs out from a device after its connection has not been used for 10 commands. This means that if you connect to a set of devices, then connect to a different set of devices and work with them for a while, the first set of devices will be automatically disconnected. Users can also log out from all connected devices either by issuing a LOGOUT command from the command-line, or by pressing the logout button in the toolbar, or by choosing "Logout from All" from the Connect menu. Also, all connected devices are automatically logged out when CLI*manager is shut down. Related Links: Connecting to Devices

Nortel Modem Pool

Note: This functionality is only available to users who have an internal Nortel license to use CLI*manager. External customers do not have access the modem pool functionality. The modem pool functionality allows users to connect to a remote device via a dialup modem or X25 connection. There are various servers on the Nortel intranet which contain pools of modems that allow connections to be established. A predefined set of proxy scripts have been developed to allow connections to be established with a minimum of manual steps. Also, users can perform CLLI or short CLLI lookups in the NARS database to find modem phone numbers and contact information for a site. A certain amount of setup needs to be done to configure CLI*manager to use the latest and greatest modem pool proxies. The steps for that setup and the use of the modem pools are outlined here. This functionality replaces the modem pool proxies used in the MSAT tool which is no longer being supported.

Setting up File Synch

The modem pool functionality is configured with several proxy scripts and a configuration file. The master copy of these files are stored on a central server and CLI*manager can be configured to automatically download a copy of these files to a user's local machine on a daily basis. This ensures that all modem pool users have up-to-date information. The File Synch functionality is used to automatically refresh a user's modem pool configuration. There is a quick shortcut to set this up by following these steps: 1. Go to Tools -> Options -> Connection. 2. Ensure the checkbox "Use a synchronized list of Nortel modem pool proxies from:" is checked off. 3. Ensure that the field contains \\Zrtpd0mb\groups4\Automation_Repository\SiteAccess\ModemProxies which should be the default value. 4. Click on the "Download Now" button. 5. Click on "OK"

Setting up a Connection
1. From the Connect window, click on the "Modem Pool" radio button. The Connect window should look similar to the image below. 2. From the "Modem Pool" pulldown list select a modem pool listed. The list should be familiar to MSAT users. In the example below, MULTI-RTP3 has been chosen as the modem pool to use. 3. From "Settings" pulldown lists select the desired baud rate and parity. In the example below the baud rate selected is 2400 and the parity is 8-None-1 4. In the "Phone Number" field enter the phone number or look up the phone number in the NARS database by clicking on the button located on the right. Note that the proper prefix must be added to any phone number and it will be different depending on where the modem pool is located and whether the number is local, national or international. CLI*manager DOES NOT automatically figure out the correct prefix! 5. Click on the "Apply" button.

Command-Line Enhancements
CLI*manager provides a number of enhancements to standard device syntax to do things like running commands against whole ranges of components, or provision based on information that has already been displayed. There are also custom commands for controlling parts of CLI*manager itself, such as address books, maps, etc. This section explains these changes to the command-line. Commands to Multiple Devices Targeting Specific Devices New or Enhanced Commands Enhanced Notations The "-find" Option CLI Tables (for Passport MSS) Disabling CLI*manager Syntax Previous Section: Connecting to Devices Next Section: Log Files

Commands to Multiple Devices

One of the basic features of CLI*manager is its ability to connect to multiple devices and send commands to them all at once. To connect to more than one device, simply drag or use the Ctrl and Shift keys while clicking on more than one device name in the Connect window, then press Connect. Or you can use the "*" command with more than one device name, separated with spaces. After the connection has been made, all of the target device names will be shown in the command prompt.

In the example above, the user connected to two devices. Their names (TBRWPCN2 and TBRWPCN3) were then shown in the prompt. The user then entered a "start prov" command, which CLI*manager sent to both devices. The response from each device is shown in the same order that the device names were shown in the prompt. Related Links: Command-Line Enhancements "&" Notation: Commands for Each Device

Targeting a Specific Device

Normally, commands are sent to all connected devices (shown in the command prompt). To send a command to specific devices rather than all of them, type their names at the beginning of a command. The specified device must be one that has already been connected.

In the example above, two devices were connected (TBRWPCN2 and TBRWPCN3), but a command was sent only to one of them (TBRWPCN3). Related Links: Command-Line Enhancements

New or Enhanced Commands

Most commands are unchanged from normal device syntax, but some have been added or enhanced by CLI*manager. This section describes only those commands that are changed from the normal device syntax. General Commands MSS Commands BCM Commands Address Book Commands Map Commands Optical Metro Commands Related Links: Command-Line Enhancements

Enhanced Notations
The enhanced notations described in this section apply only to certain device types. On other device types, the special characters used (-, #, &, etc.) are sent to the device normally, without any special processing by CLI*manager. Currently, these notations work with MSS, Alteon, Shasta, Avici, MPE9000, Passport 8x00, and SER5500. "-" Notation: Ranges of Components "+" Notation: Non-sequential Components "&" Notation: Commands for Each Device "#" Notation: Referencing Table Cells "$" Notation: Referencing Table Values "*" Notation: Enhanced Wildcards Related Links: Command-Line Enhancements

The "-find" Option

The "-find" option can be used to filter command responses for certain text. The option is available on all device types, and can be placed either in the middle of a command or at the end. Syntax: -FIND <string> shows only lines that contain the specified string. Standard regular expressions can be used in <string>. -After <n> shows <n> lines after each occurance of the matching string, when used with the -find option above. -Before <n> shows <n> lines before each occurance of the matching string, when used with the -find option above. Example: This Alteon command would dump the configuration and print out only lines containing the IP address "1.2.3.4", along with the 3 lines before the address and 5 lines after.
/cfg/dump -find 1.2.3.4 -b 3 -a 5

Related Links: Command-Line Enhancements

CLI Tables
For the MSS, results from all "display" and "list" commands are automatically formatted into tables. In most cases, these tables are able to display components side-by-side for easy comparison, even when the components are on different devices. If you don't want to use tables in your CLI session, you can disable them for each command with the "-notab" option, or disable them completely with an option in the General tab of the Options window. CLI Tables are also available for optical nodes with TL1 ports, but by default they are disabled. TL1 commands that start with "RTRV", such as RTRV-INVENTORY or RTRV-EQPT, can be formatted as tables. CLI Tables can be enabled for TL-1 in the Options window. CLI Table Example CLI Table Options CLI Table Statistics Provisioning from a Table Table Summarization Comparing Table Attributes Turning CLI Tables On and Off Related Links: Command-Line Enhancements

Disabling CLI*manager Syntax

In rare cases you might want to issue commands without using CLI*manager's enhanced syntax. For example, you might want to use an ampersand or dash to fill in a comment field - without interpreting those characters as targeted instances or ranges (see above). To send a command to all selected devices without applying any of CLI*manager's enhanced syntax, just type a tilde character ("~") at the very beginning of the command.

Related Links: Command-Line Enhancements

Log Files
The Log Viewer window allows you to browse and view log files of multiple types, organized hierarchically by date, session, and device. Log files can be automatically uploaded to a remote server using the Upload Queue. Log Viewer Overview Log Viewer Types Text Logs WATCH Logs MSS Alarm Logs Log Upload Queue Previous Section: Command-Line Enhancements Next Section: Watch Mode

Log Viewer Overview

CLI*manager automatically stores multiple types of logs to file for later reference. The Log Viewer window, which is available in the Tools menu and on the main toolbar, allows you to browse and view these log files. The Log Viewer can also be run a separate program (outside of CLI*manager). Logs are organized hierarchically by date, session, and device.

The left side of the window is a tree containing all available log files. When you select a file in the tree it will be shown in the main viewer pane on the right side, using an appropriate viewer component for that type of log. Log files are compressed to reduce the amount of disk space consumed, and are temporarily uncompressed when you open them in the Log Viewer. Logs are are automatically deleted after a number of days specified in the Options window.

Transferring Log Files

Log files can be transferred to other applications in a number of different ways: Selected logs can be dragged from the tree directly to another application, such as into an email or file-system folder. The files will be automatically decompressed before they are copied. The Save As button saves the current log anywhere you specify. Different file formats are available based on the log type. The ZIP button and ZIP context menu item will add all selected log files to a ZIP archive. This can be useful for transferring multiple files together. The "right-click" context menu in the log tree has a "Copy" function, which copies the selected files. You can then paste them into other applications or file-system directories.

Controls
A common toolbar is shown in the top-left containing the buttons below. Other controls appear at the top of

the window based on the current log type. Sidebar On/Off Refresh Open File Save As ZIP... Delete File(s) Related Links: Log Viewer Types Log Upload Queue Log Viewer Shows or hides the left sidebar containing the log tree Refreshes the log tree and the current file Opens a log file that is not in the log tree Saves the current log file Compresses the selected log files into a ZIP archive Deletes the selected log files

Log Viewer Types

The Log Viewer can show several types of logs, and automatically switches its view mode based on the selected file. Text Logs WATCH Logs MSS Alarm Logs

Text Logs
CLI*manager automatically logs the text from all sessions. There are two types of standard text logs: Session Logs Logs for whole CLI*manager sessions in a CLI Tab are shown at the second level in the tree, labeled with the time when the session was started. When you open multiple CLI Tabs, separate session logs will be kept for each tab. Device Logs Sevice Logs are shown below session logs in the tree. Each device log contains text from a specific device that was connected during the session. Only raw text from the device is kept. Enhanced CLI*manager formatting, such as CLI Tables, is not included. The Text viewer includes a Search field that finds text in the current log file, with buttons that control the search direction (up and down) and case-sensitivity. All matching strings in the log are highlighted with yellow as you type into the search field. The up and down search buttons cycle through matching strings, highlighting each current match in green.

WATCH Logs
Graph data from watch sessions is automatically logged to file. It becomes available in the Log Viewer as soon as the watch session is stopped - not while watch is still running. A scrollbar below the graph allows you to scan visually to any timeframe in the log. Individual graph lines can be toggled on and off by clicking on their entries in the legend. Numeric details for any point can be shown by holding your mouse over the graph. A right-click context menu allows you to show/hide all lines, copy the image, and save the

graph data in a number of formats.

MSS Alarm Logs

MSS Alarm logs are shown in the Log Viewer tree with yellow triangle icons. Alarms that are collected during CLI*manager sessions will be shown in the tree below their sessions. If a CLI*server is supplying alarms then the log file will be shown at the top level of the tree and marked as "CLI*server Alarms".

If the selected alarm file is from an active session then the alarm viewer will update itself. If the "Scroll To New Alarms" button is selected then the viewer will scroll to the most recent alarms as they are received.

Alarm logs are shown in a table color-coded by alarm severity. Double-click on an alarm to open the full text from that alarm in a bottom pane of the window. Right-clicking on an alarm provides these functions: Filter: <device name> sets up a filter that shows alarms from only this device Fitler: Hide <device name> sets up a filter that shows alarms from all devices except this one Filter: All devices removes filters so that alarms are shown from all devices Connect connects to devices in the selected alarms Connect in New Tab connects to devices in the selected alarms using a new CLI Tab Show Alarm Detail shows detail for this alarm in a pane at the bottom of the Log Viewer window Copy Alarm copies text from the selected alarms into the clipboard Show NTP shows NTP documentation for this alarm (only shown if a CLI*server has been set up to provide an alarm stream) Alarms can be sorted by clicking on the column headings. When alarms are received (even if the alarm window isn't opened), they are indicated by alarm lights at the bottom-right of the main window, colored according to severity. Alarm lights remain colored after an alarm has been received for a specified duration (5 seconds by default, but configurable in the General tab of the Tools -> Options menu). Clicking on any of the lights opens the alarm window.

Related Links: Log Viewer Log Viewer Types WATCH Mode

Log Upload Queue

Log files can be automatically uploaded to a remote server (any File Server Profile) for sharing and audit purposes. This can be set up using either the Options Window or the Log File Upload Queue in the log toolbar drop-down menu:

This menu item opens the Log File Upload Queue window below, which lists files that have been uploaded or that are waiting to be uploaded. Each log file is uploaded whenever it is closed, such as when a connection is logged out, a CLI Tab is closed, a WATCH session is stopped, etc.

Server Log File Naming

By default, log files are stored on the server in a subdirectory that is named for the current user. This can be customized by placing a file named "clilog.xml" in the main directory configured in the File Server Profile. The example clilog.xml file below would disable upload for all log types except for device logs. Files would be stored in subdirectories named for the device's CLLI, below parent directories named for the first letter of the device's CLLI. Remote file names would be generated based on the device name followed by the specified date and time formats.
<?xml version="1.0" encoding="utf-8"?> <LogConfiguration enabled="false"> <DeviceLog enabled="true" subdirectoryFormat="{cllistart}/{clli}" filenameFormat="{devicename}_{yy}{MM}{dd}_{HH}{mm}{ss}"/> </LogConfiguration>

The root of the XML file is expected to be a LogConfiguration element, where default attribute values can be specified for all log types. These values can then be overridden for each log type separately using subelements. Recognized element types below the root level are:
SessionLog DeviceLog

AlarmLog SpatLog PollLog UserLog TraceLog WatchLog

All element types, including the root LogConfiguration element, have the same attributes:
enabled subdirectoryFormat filenameFormat

The subdirectoryFormat and filenameFormat attributes can be any text, and can contain variables surrounded by {} brackets. Recognized format variables include:
username devicename deviceaddress devicetype logtype region site siteid siteid2 clli cllistart book

(first letter of the clli )

date and time formats such as yyMMdd and HHmmss. Related Links: Log Viewer

Watch Mode
WATCH mode allows users to monitor switch components in real-time. Graphs can also be generated in real-time for changing numeric values. This section explains how to use the WATCH feature. Watch Overview Starting Watch Mode Example Watch Session Watch Mode Controls Adding Commands to be Watched Previous Section: Log Files Next Section: Background Polling

WATCH Overview
WATCH repeatedly displays the specified components or attributes, refreshing the display regularly at the rate you specify. The default refresh interval for most device-types is 1 second). You can use CLI*manager features like ranges, etc., to specify components to be watched. Multiple commands can be watched at the same time, even on multiple switches. Watch Mode can generate real-time graphs for watched statistics. All changing numeric values are automatically included on the graph, which will automatically scale to the largest visible value. A legend is shown for MSS graphs, and other platforms use color-coding in the WATCH window itself to identify each graph line. Individual graph lines can be shown and hidden by clicking on their entry in the legend. Graphs can be turned on and off with a toggle button at the top of the WATCH window. As a safety measure, WATCH automatically slows down the polling interval when connected devices are slow to respond. Starting Watch Mode An Example Watch Session Watch Mode Controls

Starting WATCH Mode

WATCH mode can be started from the Tools menu. A window like the one below appears asking what commands should be run on what devices. The Add button allows multiple commands to be added to the same WATCH session.

To start a watch from the command-line, use the WATCH command. Multiple commands can be watched at the same time by surrounding each command with quotes, as shown below.
watch "<command1>","<command2>",...

Table Options can be used to set the initial statistic mode or conversion factor, and the Find Option can be used to filter for lines containing specific text.
watch d atmif/140-142 -avr -mult 0.424

WATCH output looks like normal output from the command you specified, except that a variety of statistics can be displayed instead of just the attribute values. Values that change between WATCH updates are highlighted in reverse type. If you are graphing WATCH results, there is no limit on the number of statistics that can be

shown in a single graph. However, it is sometimes advisable to restrict the number of attributes in your command response wherever possible. On the MSS, this can be done by watching specific attributes, like "watch atmif/140-142 txcell,rxcell". On other platforms, you can often use "show" commands for only specific ports. This helps to make your graphs more readable.

Example WATCH Session

In the example below, an ATM interface is being watched. All attributes are shown in the window pane at the bottom - the same way they would have appeared from a normal CLI "display" command, except that numeric values are replaced with their watched statistics, and graphed values are shown with the corresponding line color.

The graph at the top is updated in real-time, as values are collected. The graph auto-scales vertically to show the highest visible value. Conversion factors (from the button, see below) multiply the vertical scale by the specified factor. The horizontal scale shows the time of day. The WATCH graph shows a scrollbar along the bottom whenever more than 100 samples have been collected. (The number of samples can be adjusted in Tools->Options->Watch.) This allows the graph to be scrolled backwards to view any segment of data collected in that WATCH session. The legend below the graph shows a color and label for each graph line. For cases where WATCH is not able to automatically assign a label to a graph line, custom labels can be entered manually by double-clicking on the legend items. Values in the CLI output window are shown with their corresponding graph color. Individual lines can be toggled on and off by clicking on their entries in the legend. The legend can be resized by the user. Right-clicking on the graph opens a pop-up menu from which you can hide and show all of the graph lines, and copy the graph to the clipboard.

WATCH graph data is automatically logged to file, so graphs can be viewed after the WATCH session is complete using the Log Viewer. Holding the mouse over a watch graph line pops up a window with details about the series and sample under the mouse. This is useful for looking up specific values, and for identifying lines in crowded graphs.

Watch Mode Controls

A set of controls is available along the top of the WATCH window. WATCH mode can now be controlled with the keyboard. Press "P" to toggle the pause button, "R" to refresh a paused watch, "C" to clear the statistics, and "Q" to quit WATCH and return to the command-line. Set Watch adds or changes watched commands. This allows users to Commands watch more than one command at the same time, for cases where users want to monitor different types of components in the same window. Command shows the command executed at every WATCH refresh. This is a drop-down that lists all commands that are being watched. If more than one command is being watched, they can be selected separately to filter the output and graph only that command's results. allows you to choose the statistic displayed in the WATCH window. Available statistics include current, minimum and maximum rates per second; minimum and maximum value; total change since WATCH started; average value; average rate per second; current value; and 1-interval change. allows you to specify the delay between WATCH refreshes. Preset intervals can be selected from the drop-down, or users to enter their own refresh intervals. stops WATCH until you press the button again, allowing you to view the results.

Mode

Delay Pause

Auto-Pause tells WATCH to automatically pause after a specified time. This can be useful for monitoring for fixed periods. To use this feature, press the Auto-Pause button and enter a duration. Durations can be specified either as a number of seconds or in "hh:mm:ss" format (the default is 1 minute). The time remaining will be updated in this field as it counts down. Refresh Clear Graph Convert refreshes the WATCH display on-demand. This button is only available while WATCH is paused. clears and restarts all historical WATCH statistics, such as average rates, averages, and total change. toggles the watch graph on and off. This graph setting is remembered for future watch commands. multiplies all WATCH statistics by a fixed factor. A menu of common conversion factors is provided, such as Cells-to-Bits and Bytes-to-Bits. Other factors can be specified by typing them into the field. It is important to note that all statistics are multiplied by this factor, regardless of whether the factor applies or not.

Justification allows you to manually toggle left/right justification of WATCH statistics. For some device types, WATCH normally tries to auto-detect whenever statistics from a device are right-justified, but it can sometimes be wrong, which results in badly formatted output. Highlight toggles the preservation of statistic highlights. With this feature enabled, all attributes that have changed will remain highlighted in reverse-type until WATCH is cleared or preservation is turned off. saves the currently visible WATCH results to a file. Available save formats include CSV, tab-delimited text, JPEG, PNG, and CLI*manager WATCH file. Only data from the selected graph lines is saved. Lines that have been hidden by turning off their legend items are not saved. Also, data is saved only for the current mode (Rate/s or Value). logs results as they are collected from the current WATCH session to a tab-delimited text file, suitable for import and graphing by spreadsheet applications. Note that watch graph data is also available in the Log Viewer. ends WATCH mode and returns CLI*manager to the CLI prompt.

Save

Log to File

Stop

Adding Commands to be Watched

The "Set Watch Commands" button in the WATCH toolbar makes it possible to watch more than one command at the same time, for cases where users want to monitor different types of components in the same window. Related Links: The WATCH Command

Background Polling
Like Watch Mode, the Background Polling feature can be used to monitor statistics. The difference is that the polling feature is intended for ongoing collection with little user interaction. Background Polling Overview The Background Polling Window Adding Poll Commands Collection Schedules Result Formats Triggers Viewing Results The CLIPOLLER Utility Previous Section: Watch Mode Next Section: Hyperlinks

Background Polling Overview

The Background Polling feature can be used to monitor device statistics. A set of commands is run in the background on a regular interval, and numeric values are extracted from the output. Results are logged to file and graphs can be shown in the Log Viewer. This feature is similar to Watch Mode. The difference is that background polling is intended more for ongoing collection with little user interaction. Users can configure any number of commands, press Start, and it will quietly collect in the background without tying up a CLI tab.

The Background Polling Window

Polling commands are monitored and controlled by the Background Polling window, which can be opened from the Tools menu and with the button in the main toolbar.

All configured polling commands are listed, with the last time that each command was polled and the last status of the last poll. Commands can be enabled and disabled by clicking their checkboxes. New Poll Item adds a new item to be polled. Edit Delete Start Stop edits the selected poll item. deletes the selected poll item. starts polling all selected items in the background. stops background polling.

After polling has been started, the Background Polling window can be closed, and polling will continue. Polling will also continue after CLI*manager exits.

Adding Poll Commands

To add a command, press the Add button in the Background Polling window to open the form shown below. After entering the required parameters, press the Test button to make sure that results can be collected successfully using the configured settings.

Description a readable name for the polling item. This is the name that will be shown in the Background Polling window, and it will also be used to name the log file. Device(s) a comma-separated list of devices on which the command will be run. Press the Choose button to search for devices in your address books. Add Opens a window that adds a command to be issued in each polling interval. The command Command must be native syntax on the target devices. CLI*manager enhancements (like ranges, etc) are not allowed. The search filter is an optional filter on the command output. With a Simple filter, numbers will be parsed only from output lines that contain the filter text. With a Regex filter, numbers will be parsed from all Regular Expression matching groups.

Collection Schedules
Each polling item can be set up which its own schedule, which allows for polling to stop after a period of time, repeated collections, etc.

Result Formats
Polling results can be stored as CLI*manager graph data, to be shown later in the Log Viewer. They can also be stored in CSV comma-separated format, for access by other applications.

Triggers
For data that is collected from Passport MSS-related device types, triggers can be used to inject alarms into an MDM system whenever a threshold is exceeded by data in a collected attribute.

Viewing Results
After at least one polling interval has been completed, log files will appear in the Log Viewer window for all enabled poll commands. Polling results can be viewed as they are collected, or reviewed at any time.

The CLIPOLLER Utility Once configured, the poller can be started either with the Start button in the Background Polling Window, or from outside of CLI*manager with the CLIPOLLER utility. If started with the Start button, collection will only take place while CLI*manager is running; after you exit, collection will stop. If started with the CLIPOLLER utility, collection will continue until the process is killed. Syntax:
clipoller [-u <username] [-p <password>] [-f <filename>]

Options:

-u username -p password -f filename

Sets the CLI*manager username to use when accessing cached address book passwords, if required. If this option is not specified then the current username will be used. Sets the CLI*manager password to use when accessing cached address book passwords, if required. Specifies which XML poll configuration file to load. If this option is not specified then the default filename for the current user will be used.

Related Links: WATCH Mode The Log Viewer

Hyperlinks
Context-sensitive "hyperlinks" are shown in the CLI window for a number of purposes. For example, the initial banner when a CLI window is opened includes hyperlinks to quickly connect to recent devices. And some device types (BayRS, Passport 8600, MSS, and ITG) automatically generate hyperlinks in command responses, to build other commands and navigate the tree. Hyperlinks Overview Alteon Hyperlinks BayRS Hyperlinks Passport 8600 Hyperlinks MSS Hyperlinks Other Hyperlink Examples Previous Section: Background Polling Next Section: Translations

Hyperlinks Overview
Hyperlinks are areas of text that CLI*manager generates in command responses from some (not all) device types, which allow users to quickly run related commands by clicking on them.

Related Links: Hyperlinks

Alteon Hyperlinks
Alteon menu items are shown as hyperlinks. Clicking on a menu item runs the highlighted command immediately.

Related Links: Hyperlinks

BayRS Hyperlinks
CLI*manager generates BayRS hyperlinks for "?" commands, and for incomplete commands that list possible completions.

Related Links: Hyperlinks

Passport 8600 Hyperlinks

CLI*manager generates Passport 8600 hyperlinks for "?" commands. Also, whenever you click on a hyperlink that changes the position in the command tree, CLI*manager automatically issues a "?" command and generates hyperlinks for commands at the new level.

Related Links: Hyperlinks

MSS Hyperlinks
CLI*manager generates MSS hyperlinks for all components that are shown in tables, and for components that are shown in some other responses (such as "check prov"). For list and display commands, CLI*manager also generates a list of "Context" hyperlinks to related commands and components in the current context.

In the example above, the user clicked on "AtmIf/70" in the first list table, which automatically issued a "display" command for that component. Context links were generated for the subcomponents (CA, VCC/*, Vpt/*, and Pm). The "-oper" context link displays an operational view of same component. And the ".." context link displays or lists one level up in the component hierarchy (which in this case would list all of the top-level components). Instead of clicking on hyperlinks, users can also type them (or just portions of them) as commands into the CLI. In the example below, the user typed "vcc" to list the VCC subcomponents. This is much faster than having to type the equivalent full command "l atmif/70 vcc/*", especially for components that are deep in the tree.

Related Links: Hyperlinks CLI Tables

Other Hyperlink Examples

CLI*manager also generates hyperlinks in other situations, such as * commands where more than one device matches the specified name, as shown below. Another example is a "Reconnect?" hyperlink that is shown when connections to devices drop unexpectedly.

Related Links: Hyperlinks Connecting to devices

Translations
The "translation" feature allows you to define conversions from one command syntax to another. This can be useful for simplifying some commands. It is also possible to use translations to build a common syntax for available switch types. Translations Overview Creating a Translation Variable Types (optional) Previous Section: Hyperlinks Next Section: Scripting

Translations Overview
Translations are a flexible way to map one command syntax into another. Each translation consists of a "from" and a "to" end, which are described using a simple syntax. Each translation applies only to a specific device type. To view and build translations, choose "Translation Setup" from the Tools menu.

With this form, users can add, remove, edit, and rearrange their own translations. CLI*manager includes a basic set of pre-defined translations (shown in bold), which cannot be edited, removed, or rearranged. Each translation can be enabled and disabled with the checkboxes on the left side of the list. Also, the translator itself can be completely disabled and enabled with the Enable Translator checkbox in the top-right corner of the window. Whenever CLI*manager sends a command to a device, it first checks to see if the command matches with any of these translations. It searches the list of translations in the order shown, and applies only the first match. The order is important, because there may be cases more than one translation applies. "Export" and "Import" buttons at the bottom of the Translation Setup window allow translations to be shared by saving them to file and then importing them into another user's Translation window. Related Links: Translations

Creating a Translation
A useful example from the predefined translations is the "traceroute" command. The syntax for the traceroute command is different on the Passport 7400, BN, and Passport 8600. Since the predefined translations include a common syntax for all three device types, users can connect to all three (even at the same time), and issue the same command. Without translations, this would result in syntax errors. An example translation is shown below, which translates commands like " traceroute vr/2 1.2.3.4" into "ping -traceroute -ip(1.2.3.4) vr/2 ip icmp ".

The From and To ends of the translation follow a simple grammar. Text that is surrounded by "<" and ">" symbols is taken to be a variable name, which is read from the "From" end and inserted into the "To" end of the translation. Variables found in the "To" end must exist in the "From" end for the translation to be valid. If there are initial capitals in a word (as in TRACERoute, above), those characters are taken to be significant - which means that the word can be shortened to those characters, like "tracer". There is a special "<*>" variable that can be used in the "To" side of a translation, which copies all remaining words from the "From" command. Related Links: Translations

Variable Types (optional)

Variable names can optionally start with a type, separated with a space. The "ip" in "<ip address>" above specifies an expected type for the "address" variable. This can be useful for making sure that the translation applies to a given command. Currently only two types are recognized: "ip" and "number". The "ip" type simply makes sure that the given parameter contains an IP address (four numbers separated by periods). Related Links: Translations

Scripting
CLI*manager has two scripting languages, each with its own strengths: Batch Jobs and CLI*scripts. Batch jobs provide simple scripting of pre-defined sets of commands, sometimes with user-prompted parameters. CLI*script is a more powerful scripting language, intended more for programmers. Running CLI*scripts and Batch Jobs The Run Script Window Scripts with Parameters The Script Editor The CLI*script Debugger CLI*script Syntax Overview Functions for connecting and controlling devices Functions for checking command responses Functions for prompting variables from the user Functions for proxy scripting General-purpose functions Functions for fetching data from CLI Tables (where available) Functions for building and managing network maps Batch Jobs Writing a Batch Job Special Batch Job Commands Special Batch Variables Batch Prompts Running Batch Jobs with a Data File Organizing Scripts The Script Director CLIBATCH: Running a Scripts Outside of CLI*manager Stopping and Pausing Scripts Restricted Commands Previous Section: Translations Next Section: Network Maps

Running CLI*scripts and Batch Jobs

CLI*scripts and Batch Jobs can both be started in several ways: by selecting the "Run Script..." item from the Script menu, by pressing the Run Script button in the main toolbar, or by running a SCRIPT command . Recent scripts can be chosen quickly by pressing the " " beside the Run Script button. You can also run both CLI*scripts and Batch Jobs outside of CLI*manager by using the CLIBATCH utility.

The Run Script Window

If you press the Run Script button or use the "Run Script" item in the Tools menu, a window will open that allows you to select a script. The Run button starts execution of the selected script. The Debug button opens the Debugger, only when a CLI*script file is selected. The Edit button opens the Script Editor for the selected file.

The "Run Script from URL" option allows you to run scripts from a centralized web server. You can either enter a URL to a specific script, or a URL for a simple web page that contains scripts. A preview window will show you the script or web page.

The "Run Recent Script" option allows you to choose from a list of scripts that have been run recently on your local machine.

Press the Run button to start the job.

Scripts with Parameters

If there are no parameters in the script, it will start immediately. Otherwise a window like this one will appear, asking for parameter values:

After you have provided values for all parameters, press the "OK" button. (All values must be entered in order for the script to start.) Commands and device responses will be shown in your main CLI window. Related Links: CLI*script Batch Jobs Scripting Running a Batch Job Outside of CLI*manager

The Script Editor

Although CLI*manager scripts (CLI*scripts, Batch Jobs and Proxy Scripts) can be written in any text editor, the built-in Script Editor includes enhancements that are specific to these languages.

Features include: Multiple Documents can be open at once, using a tabbed layout. Syntax Coloring for CLI*script, Batch Jobs, and Proxy Scripts. Syntax Validation for CLI*script. Script syntax is checked as you type. If there is an errors then it will be shown at the top of the window, and the error line number will be highlighted in the margin. Script Helper Sidebar provides syntax help. When your cursor is on a recognized word, it will be automatically looked up in the index. Double clicking on an index item will insert it into the document at the current cursor position. The sidebar can be toggled on and off with the button. The Run Button runs either the current script file, or the selected segment if any text has been selected. Whole lines can be selected by clicking and dragging in the line number margin. The Debug Button runs the current CLI*script file in the Debugger window. Line Numbers are shown in the margin. Clicking on a line number selects the whole line, and dragging in the margin selects multiple lines. The Script Type Select Box allows you to specify which scripting language should be used for features like syntax coloring and script help. When opening an existing file, the script type is usually detected automatically, but in some cases (such as when you are creating a new script) you may need to specify the type manually.

Toolbar Functions
New Creates a new editor tab with a new empty file. Any number of editor tabs can be open at once.

Open Save

Opens an existing file from your local file system. Saves the file in the current editor tab.

Save Saves current file with a different name, encrypted with a password. This can be used for Encrypted encrypting batch jobs that contain sensitive information (such as passwords). Note that the As... text editor cannot re-open its own encrypted files, and so you should keep a local unencrypted version for reference. If these files are run as batch jobs, users will be prompted for the password before the job can start. Cut Copy Paste Find Replace Run Debug Script Help Related Links: CLI*script Batch Jobs Proxy Scripts Cuts the currently selected text and places it in the clipboard. Copies the currently selected text and places it in the clipboard. Pastes text from the clipboard. Searches for text in the current file. Replaces text in the current file. Runs either the current file or the selected script segment, in the current CLI Tab. This button is only visible while editing a CLI*script or Batch Job. Runs the current file in the Debugger window. This button is only visible while editing a CLI*script. Toggles the Script Help sidebar on and off.

The CLI*script Debugger

The CLI*script debugger can be used for finding problems in scripts, following script execution, checking variables, setting breakpoints, etc.

Features include: The current line is highlighted in red, with an arrow in the margin Controls for stepping through the script line-by-line, into functions, over functions, and out of functions A list of all variables and their current values A configurable list of expressions that will be evaluated and updated as you step through the script Breakpoints that can be toggled for any line by double-clicking on the line number in the margin A console shows text output from trace() functions, as well as results from any expression that you enter A stack trace that shows the function calls used to reach the current execution point

Toolbar Functions
Resume Pause Stop Resumes the script. While the script is resumed other debugging features are disabled, but the current line is tracked. Pauses the script after the current line has finished executing. Once the script is paused, other debugging features can be used including the step buttons, variables, expressions, etc. Stops the script and exits the debugger.

Step Into Step Over Step Out

If the current line references another file or function, this button follows execution into the contained code. If no function of file is referenced then the current line is executed. This button steps over the current line without following its execution into referenced functions or files. Resumes execution until the current file or function is complete.

Skip All If this toggle button is selected then all breakpoints will be ignored for the current Breakpoints debugging session. Deselecting the button re-enables breakpoints. Related Links: Script Editor CLI*script

CLI*script
CLI*script is a powerful scripting language based on JavaScript 1.5, with a set of predefined functions specific to CLI*manager. All features of JavaScript are supported including objects, regular expressions, and the EMCAScript for XML extension (E4X). Scripts can also open and control their own customized graphical windows, using the ScriptWindow object. Integrated syntax help for CLI*script is available in the Script Editor sidebar. Global Variables Functions for connecting and controlling devices Functions for checking command responses Functions for prompting variables from the user Functions for persistent storage of variables Functions for proxy scripts General-purpose functions Functions for fetching data from CLI Tables (where available) Functions for building and managing network maps Array Object Date Object File Object FTP and SFTP Objects Math Object RegExp Object ScriptWindow Object String Object WindowsComponent XML Object

Global Variables
args[] The args[] array contains arguments passed to the script from the command-line. These arguments are available from both the CLI command-line, and from the external CLIBATCH utility.

Functions for connecting and controlling devices

connect(<name>) connect(<address>, <type>, <user>, <password> [, <ssh>]) connect(array[]) cmd(<command> [, <prompt>, <answer> [, ...]) cmd(<command> [, <expected_prompts>, <timeout>]) expectedprompts(<prompt1> [,<prompt2> ...]) logout() send(<string>) setwaitfortimeout(<seconds>) setwaitforprint(<boolean>) switchnodetype(<type> [, <subtype>]) waitfor(<string>, <seconds>) waitforsilence(<milliseconds>)

connect(<name>)

Logs into the specified device. The name parameter can can be either a string or objects that contain required properties. If a "name" property is found in the object then it must be found in an address book. If "address", "user", "password" and "type" properties are found then no address book entry is needed. An optional "ssh" property can be set to "true" to enable SSH for the connection. Multiple devices can be connected by separating names with spaces (or with an array - see connect(names[]). This is equivalent to using the "*" and "EM" commands in the regular CLI*manager interface. Returns an array the names of successfully connected devices. Examples:
connect("tbrwpcn1 tbrwpcn2"); var mydevice = {address: "47.9.195.30", type: "pp7400", user: "overlord", password: "OSCMD"}; connect(mydevice); connect(<address>, <type>, <user>, <password> [, <ssh>])

Connects to a node that is not in an address book. The address can be an IP address or hostname. Multiple address can be separated by spaces, in which case the same type, user, password and ssh settings will be used for each. The type parameter is expected to be a recognized type name (the same names used by the ABIMPORT utility). The ssh parameter is optional, and if it is true then the node will be connected using SSH where available. Example:
connect("1.2.3.4", "pp7400", "myuser", "mypw"); connect(array[])

Connects to all devices specified in an Array. Elements in the Array can be either names or objects that contain required properties. If a "name" property is found in the object then it must be found in an address book. If "address", "user", "password" and "type" properties are found then no address book entry is needed. An optional "ssh" property can be set to "true" to enable SSH for the connection. Example:
var devices = new Array("node1", "node2", "node3"); connect(devices); cmd(<command> [, <prompt>, <answer> [, ...]])

Sends a command to all selected devices. After the command argument, other arguments are optional and must be specified in pairs of prompts and answers. While the command is running, if one of the specified prompts is detected from the device, CLI*script will respond with the corresponding answer. Prompts must be specified in the expected order. The command is considered complete when the next command prompt is received.

Example:
cmd("show ip int");

Commands that are exactly two characters long and begin with "^" (such as "^D") are translated into their corresponding Control sequences. Example:
cmd("^D");

Example: In the example below, the "set bootorder" command is sent to the switch normally. CLI*script then watches for the string "flags (f)" and responds by sending "" (nothing) and pressing enter. Then it watches for the string "boot file1 (f1)", etc. Answers can contain control characters specified with the caret character like "^D", which are automatically translated from caret notation to the corresponding control code.
cmd("set bootorder", "flags (f)", "", "boot file1 (f1)", "", "boot file2 (f2)", "/disk/image/ggsns2.0.5/cmc", "boot file3 (f3)", "^D"); cmd(<command> [, <expected_prompts>, <timeout>])

This is a different flavor of the cmd(...) function described above. It has similarities, but several differences. If the only parameter specified is command, this function will behave exactly as the cmd(...) function above. All special CLI*manager syntax enhancements will be interpreted. If the optional parameters expected_prompts and timeout are added, cmd(...) will behave as a wrapper for the send(...) and waitfor(...) functions in combination. CLI*manager syntax enhancements will be ignored and will be sent directly to any device that is connected. The expected_prompts parameter must be an Array of Strings which specifies additional prompts that CLI*manager should scan for to determine if a command has been completed. This can be useful in situations where CLI*manager encounters a prompt that it has no knowledge of, yet the script writer is fully aware of. This adds flexibility to situations where CLI*manager cannot detect when a command has finished running. The timeout parameter can be used as a safety valve in a script so that if none of the known and expected prompts are detected the cmd(...) function will at least return. This will prevent a script from hanging. However, it is up to the script writer to determine how to handle a timeout situation. Example: In this example we will run a script that is already connected to an XACORE. The script will remlogin to an EIU which is not a recognized device type in CLI*manager. Using the traditional cmd(...) function will cause the script to hang

since CLI*manager cannot detect when a command is complete on an EIU. CLI*manager assumes that it is still connected to an XACORE. The solution would be to add an array of prompts to cmd(...) so that CLI*manager can detect when a command has completed on the EIU:
cmd("date"); // Get date from XACORE. cmd("remlogin EIU 0", new Array("EIU0> ")); // Send remlogin command // and look for extra prompts. cmd("date", new Array("EIU0> "); // Get date from EIU. cmd("remlogout"); // We are going back to XACORE. // No need to scan for extra prompts.

Here is the equivalent script using send(...) and waitfor(...). Note that we only need to use send(...) and waitfor(...) when connected to the EIU. When connected to the XACORE we can still continue to use cmd(...) .
cmd("date"); // Get date from XACORE. send("remlogin EIU 0"); // Send remlogin command waitfor(new Array("EIU0> ")); // Wait for prompt. send("date"); // Get date from EIU. waitfor(new Array("EIU0> ")); // Wait for prompt. cmd("remlogout"); XACORE. extra prompts. send(<string>) // We are going back to // No need to scan for

Sends a string to all selected devices (followed by carriage return), without waiting for the command to complete. After sending a string to the device in this way, it is up to your program to control the session using waitfor() and/or other send() commands, at least until the next command prompt is reached. Example:
send("yes");

Strings that are exactly two characters long and begin with "^" (such as "^D") are translated into their corresponding Control sequences. Example:
send("^D"); setwaitfortimeout(<seconds>)

Sets the default value for the timeout parameter in future calls to the waitfor() function. Example:
setwaitfortimeout(true);

setwaitforprint(<boolean>)

Sets the default value for the print parameter in future calls to the waitfor() function. Example:
setwaitforprint(true); waitfor(<string>, <seconds>, <checkForPrompts>, <print>)

Waits for the string from all selected devices, for up to the number of seconds specified (the default is no time limit). If checkForPrompts is true then the wait will also finish successfully if a command prompt from the target device is detected. The default is false or is set by setwaitfortimeout() . If print is true then the response will be printed as it is read. The default is false or is set by setwaitforprint() . Returns true if the string was found by all devices, otherwise it returns false . Example:
if (waitfor("Press return to continue", 5)) send(""); else fail("Press return not found"); waitforsilence(<milliseconds>)

Waits for a specified period of silence from the incoming stream. All input from the stream is ignored, but stored for future reference.
expectedprompts(<prompt1> [,<prompt2> ...])

Adds prompts that CLI*Manager will search for when parsing session output.
logout()

Logs out from all selected devices.

switchnodetype(<type> [, <subtype>])

Allows a script to change node types on the fly. This is useful when telneting from one device type to another within a script. The first parameter, type is mandatory and the second parameter, subtype, is optional. The values can be the long name of the node type which you will find listed in the "Type" field of the "Connect From Address Book" window. You can also use the import string for a device which is used by the ABIMPORT utility. If you wish to switch to a gateway controller device you can use the long name as it appears in the "Connect From Address Book" window. Example:
switchnodetype("Succession GWC");

You can also use the import string used by the ABIMPORT utility to specify the

device type. Example:

switchnodetype("SGWC");

Functions for checking command responses

getlastresponse() getlastresponse_raw([<nodename>]) found(<string> [,<ignorecase>]) failwherefound(<string>) failwherenotfound(<string>) cimresult() getlastresponse()

Returns a string with the full response from the last command, as it was shown to the user.
getlastresponse_raw([<nodename>])

When no node is specified, raw output from the active connection will be returned. If more than one connection is active then the raw responses will be appended together. When a nodename is specified, the raw response will be returned for only that device. If no active connection matching the nodename is found, the function returns null .
found(<string> [,<ignorecase>])

Returns true if the string was found in the last response. By default the match is case-sensitive, but this can be changed by passing true to the optional ignorecase argument.
cmd("d sh ca/15 inserted"); if (found("cp", true)) println("Found a cp card in slot 15"); failwherefound(<string>)

Declares that the script has failed for all devices where the specified string was found in the last response. These devices will be deselected so that they will not be targeted by further commands in the script. If no selected devices remain, the script will terminate. Example:
cmd("d sh ca/2 operationalstate"); failwherefound("disabled"); failwherenotfound(<string>)

Declares that the script has failed for all devices where the specified string was not

found in the last response. These devices will be deselected so that they will not be targeted by further commands in the script. If no selected devices remain, the script will terminate. Example:
cmd("start prov"); failwherenotfound("The edit view is identical"); cimresult()

Returns the last result from a BCM show or list command in a format that is easy to work with in scripts. The object returned has an "instances" array, and each instance contains arrays for "properties" and "keys" and a "getProperty(name)" method. Each property and key has fields for "name" and "value". Example:
cmd("show BCM_System"); var result = cimresult(); println(result.instances[0].getProperty("SystemVersion").value); println(result.instances[0].getProperty("LastChangeTime").value);

Returned Object: cimresult() command instances[] getProperty(name) properties[] name value keys[] name value

Functions for prompting variables from the user:

First, note that variables can also be prompted from the user with the ScriptWindow object, which provides a more flexible framework for designing windows. Most of the commands in the list below add fields to a prompt window. Any number of prompts (of any type) can be added to the same window, but the window will not appear until the showpromptwindow() function is called.

In addition to the basic format which use individual pairs of label and variable, all of the prompt functions below also accept arrays of labels. When calling each function, if the label argument is an array, then separate prompts will be shown for each element of the array, and the resulting varname variable will be an array with values for each label. This makes the prompt features more capable of dealing with large numbers of dynamic prompts.
addtextprompt(<label>, <varname> [,<optional> [, <defaultText>, <editable>]]) addpasswordprompt(<label>, <varname> [,<optional>]) addselectprompt(<label>, <varname>, <values[]>) addcheckboxprompt(<label>, <varname>, <text>, <onvalue>, <offvalue>, [<defaultvalue>]) addnumberprompt(<label>, <varname> [, <min>, <max>]) addaddressbookprompt(<label>, <varname>) addfileprompt(<label>, <varname>) addtopdescription(<message>) addbottomdescription(<message>) showpromptwindow([<TitleText>, <hideSaveCheckBox>]) clearpromptwindow() addtextprompt(<label>, <varname> [,<optional> [, <defaultText>, <editable>]])

Adds a simple freeform text field to the prompt window, marked with the label text. The user's value will be stored in a new variable with the specified varname. By default all text prompts must be non-empty to be accepted by the prompt window, but prompts can be made optional by passing true to the optional argument. If the user wishes, they can set the text field to be filled with a string by default, and decide if this text is to be editable or not. In order to include the defaultText and editable parameters, the user must include all earlier parameters. The check box that saves parameter values must be unchecked due to the fact that it will overwrite your default text when the same prompt is displayed to the user a second time. If the label argument is an array, then separate prompts will be shown for each element of the array, and the resulting varname variable will be an array with values for each label. Example:
addtextprompt("Variable 1", "var1"); addtextprompt("Variable 2", "var2", true); addtextprompt("Variable 3", "var3", false, "must be

filled", true); showpromptwindow(); addpasswordprompt(<label>, <varname> [,<optional>])

Adds a simple freeform password field to the prompt window, marked with the label text. The user's value will be stored in a new variable with the specified varname . By default all text prompts must be non-empty to be accepted by the prompt window, but prompts can be made optional by passing true to the optional argument. If the label argument is an array, then separate prompts will be shown for each element of the array, and the resulting varname variable will be an array with values for each label. Example:
addpasswordprompt("Password", "var1"); addpasswordprompt("Re-type Password", "var2", true); showpromptwindow(); addselectprompt(<label>, <varname>, <values[]>)

Adds a drop-down select box to the prompt window, marked with the label text. The user's value will be stored in a new variable with the specified varname. Possible choices in the select box are taken from the values array. If a value in the array contains an "=" sign, then text before the sign will be shown in the select box, and text after the sign will be returned by the variable. If the label argument is an array, then separate prompts will be shown for each element of the array, and the resulting varname variable will be an array with values for each label. Example:
var options = new Array("Option 1", "Option 2", "Option 3"); addselectprompt("Choose one", "choice", options); showpromptwindow(); addcheckboxprompt(<label>, <varname>, <text>, <onvalue>, <offvalue>, [<defaultvalue>])

Adds a checkbox to the prompt window, marked with the label text. The user's value will be stored in a new variable with the specified varname. The specified text is shown to the right of the checkbox. If the checkbox is selected then varname returns the onvalue , otherwise it returns the offvalue . A defaultvalue may also be specified, which must be either onvalue or offvalue . If the label argument is an array, then separate prompts will be shown for each element of the array, and the resulting varname variable will be an array with values for each label. Example:
addcheckboxprompt("Card state:", "state", "Enabled", "enabled", "disabled"); showpromptwindow();

addnumberprompt(<label>, <varname> [, <min>, <max>])

Adds a number field to the prompt window, marked with the label text. The user's value will be stored in a new variable with the specified varname. The field only accepts numbers, and it has up/down buttons that increase and decrease the value. Minimum and maximum acceptable values can be specified with min and max. If the label argument is an array, then separate prompts will be shown for each element of the array, and the resulting varname variable will be an array with values for each label. Example:
addnumberprompt("Slot", "slot", 1, 14); showpromptwindow(); addaddressbookprompt(<label>, <varname>)

Adds a select box to the prompt window that is pre-populated with all of the user's Address Book names. The name of the book chosen by the user will be stored in a new variable with the specified varname. This can be useful in combination with the getbooknodes() function, which gets lists of nodes in an address book.
addaddressbookprompt("Choose an address book:", "book"); showpromptwindow(); addfileprompt(<label>, <varname>)

Adds a label, textfield, and a button to the prompt window. The button is used for getting the filename, while the textfield is used for displaying it to the prompt window. The name of the file chosen by the user will be stored in a new variable with the specified varname.
addfileprompt("Choose a file:", "fileName"); showpromptwindow(); addtopdescription(<message>)

Adds a message that will be displayed above the custom prompts that are desired by the script writer. When the clearpromptwindow() command is called, the message is hidden erased from the prompt window. This command can be used in conjunction with addbottomdescription(). Example:
addaddressbookprompt("Choose an address book:", "book"); addtopdescription("Please select the appropriate address book from the list below."); showpromptwindow(); addbottomdescription(<message>)

Adds a message that will be displayed below the custom prompts that are desired by the script writer. When the clearpromptwindow() command is called, the message is hidden erased from the prompt window. This command can be used in conjunction with addtopdescription() .

Example:
addaddressbookprompt("Choose an address book:", "book"); addbottomdescription("Please select the appropriate address book from the list above"); showpromptwindow(); showpromptwindow([<titleText>, <hideSaveCheckBox>])

Shows the prompt window, with all of the fields added by previous commands. The script will wait until the window is closed before continuing. If no prompts have been added, this command does nothing. If the user has set the titleText parameter, then the prompt window title will be changed to the string that the user has set. If the the user has set the hideSaveCheckBox parameter, then the "Save Parameter Values" checkbox will be unchecked and hidden from the prompt window.
clearpromptwindow()

Clears the prompt window so that it can be shown again without prompts from the previous window.

Functions for persistent storage of variables

The functions below allow for persistent storage of variables even after the script has finished, so that they can be references by future scripts. This can be useful, for example, in audit scripts: one script could collect information and store it, and a second script that is run later could fetch the stored information and compare it to current values. Variables are referenced based on a "datasetname" (any short title that describes the collection of variables) and optionally a "nodename" (usually the name of the device from which the data was collected).
storenodedata(<datasetname> [,<nodename>], <varname>, <value> [,<true|false>]) fetchnodedata(<datasetname> [, <nodename>], <varname> [,<true|false>]) removenodedata(<datasetname> [,<nodename>] [, <varname>]) storenodedata(<datasetname> [,<nodename>], <varname>, <value> [,<true|false>])

Stores value in a variable called varname in the data set called datasetname, optionally marked as being from the specified nodename . The last parameter if set to true will store the data in temporary RAM which will be lost when CLI*manager is closed. This is useful for storing sensitive data such as passwords. This parameter is optional and by default is set to false which means the data set will be stored permanently on disk. Example:
storenodedata("myauditscript", "TBRWPCN1", "lastrunningtime", "42"); fetchnodedata(<datasetname> [, <nodename>], <varname> [,<true|false>])

Gets the value of a variable called varname from the data set called datasetname, optionally marked as being from the specified nodename . The last parameter which can be true or false is optional and is by default false . If set to true it will search for the data set in temporary RAM, and if false it will search permanent storage on disk. Note that if you save a data set in RAM using storenodedata and then you try to retrieve the data set from disk, it will return null since the data will not be found. Example:
var lasttime = fetchnodedata("myauditscript", "TBRWPCN1", "lastrunningtime"); removenodedata(<datasetname> [,<nodename>] [, <varname>] [,<true|false>])

Removes a variable called varname from the data set called datasetname, optionally marked as being from the specified nodename . If no varname is specified then all variables in the specified dataset and nodename will be removed. The last parameter is optional and is by default always set to false . If it is set to true it will remove a data set that has been stored in temporary RAM. When false it will remove a data set from persistent storage on disk. Example:
var lasttime = removenodedata("myauditscript", "TBRWPCN1", "lastrunningtime");

Functions for Proxy Scripts

The functions below are usable when writing a CLI*Script that will be used as a proxy script for connecting to a node. If one of these functions is called outside of a proxy, the script will terminate with an error message.
call(<address> [, <port>]) calllocal(<speed>, <serialsettings>) callmodem(<speed>, <serialsettings>, <phonenumber>) callssh(<address>, <user>, <password>) proxyarg(<label>, <variablename>) proxypassword(<label>, <variablename>) setcrlf(<boolean>) proxyloggedin()

The following variables are predefined when the CLI*script is being used as a proxy script, based on address book settings for the target node.
address modempassword phonenumber serialsettings serialdatabits serialparity serialstopbits

call(<address> [, <port>])

Connects to the specified address. By default it connects to the telnet port (23), but other ports can be specified by using the variable port . Example:
call("47.165.187.12"); call("47.165.187.12", "8000"); calllocal(<speed>, <serialsettings>)

Connects through a local COM port (defined for each CLI*manager instance in the Options window), using the specified speed and serialsettings . If these parameters are not specified then values will be taken from the address book entry for the target device. Examples:
calllocal("9600", "8-None-1"); calllocal(); callmodem(<speed>, <serialsettings>, <phonenumber>)

Connects through a locally-attached modem (defined for each CLI*manager instance in the Options window), using the specified speed , serialsettings , and phonenumber. If these parameters are not specified then values will be taken from the address book entry for the target device. Examples:
callmodem("9600", "8-None-1", "6136844357"); callmodem(); callssh(<address>, <user>, <password>)

Connects to the specified address with secure shell (SSH), using the specified username and password . Example:
callssh("47.101.120.35", "user", "pwd"); proxyarg(<label>, <variablename>)

Adds a text argument to the proxy script, which the user will be required to supply in the Proxy Configuration window before the proxy can be used. Example:
proxyarg("IP Address:", "ip"); proxyarg("Port:", "port"); println(ip + ":" + port); proxypassword(<label>, <variablename>)

Adds a text argument to the proxy script, which the user will be required to supply in the Proxy Configuration window before the proxy can be used. Example:
proxypassword("Password:", "pwd"); setcrlf(<boolean>)

Specifies whether or not CLI*Manager will send both carriage return and line-feed after input lines. If this setting is off (the default), only a line-feed is sent.
proxyloggedin()

This function tells script controller that the proxy script will end while being logged into the node, rather than at the login prompt. It does not need to be placed at the end of script, but can be called anywhere in the body of the code.

General-purpose functions:
addnode(<dname>, <ip>, <username>, <password>, <type> [, <ssh> [, <proxyname> [, <book>]]]) addproxy(<proxyname>, <nodename> [, <book>]) confirm(<message>, [<positiveButtonText>, <negativeButtonText>]) countstatus(<boolean>)

end(<string>) fail(<message>)

filedecrypt(<password>, <inputFile>, <outputFile>) fileencrypt(<password>, <inputFile>, <outputFile>) findline(string, searchstring, [wordnum [, delimiters]]) ftpget(nodename, remotefile [, localfile]) ftpmget(nodename, remotefiles [, localdirectory]) ftpput(nodename, localfile, remotefile) getbooknodes(<bookname>) getclishelllevel() getcurrentnodetype() getdefaultaddressbookname() getftperror() gettftpdirectory() getdatestamp() gethostaddress(hostname) getlocalipaddresses() getnodeinfo(<nodename>) getoption(<name>) getoptionkeys() getproperties() getproperty(<key>) getpropertynames() getscriptpath() getselectednodes() getselectednodecount() gettimestamp() getword(string, wordnum [,delimiters])

hide(<string>) include(<scriptname>) issilentfor(<milliseconds>) makelogfilename([<name>]) newlogfile([<label>]) next_counter_value(<varname> [, <increment>]) openbrowser(<url>) okwindow(<message>) onfinish() ontargetsfinished() openpassthrough(<devicename>) parallelprocess(<scriptfile>, <devices>, <multithreadcount>) pause([<seconds>]) pdtlogin() print([<string>]) println([<string>]) removenode(<dname> [, <book>]) removeproxy(<proxyname> [, <book>]) returnvalue(<varname>, <value>) runcommandfile(filename) runmultiple(<scriptname>, <targets> [, <threads>]) runmultiplewithargs(<scriptname>, <targets>, <threadcount>, <args>) runvbscript(<filename>, <arg1>, <arg2>, <arg3>, <arg4>, <arg5>, <arg6>, <arg7>, <arg8>, <arg9>) savelogfile(filename [,nodename]) sendemail(<hostname>, <from>, <to>, <subject>, <text> [, <attachments>]) sendpassword() setaddressbook(<book>) setalarmsenabled(<enabled>) setautoconfirmenabled(<boolean>) setecho(<enabled>) settablabel(<label>) settargettitle(<title>) settracetologfile(<enabled>) setuserinputallowed(<boolean>) startswdld(hostname)

starttftpserver() stoptftpserver() trace(<message>) zip(<infiles>, <outfile>) ziptargetlogfiles([<filename>]) addnode(<dname>, <ip>, <username>, <password>, <type> [, <ssh> [, <proxyname> [, <book>]]])

Adds a climanager node to an address book with the specified attributes. If the user does not set the address book, then the node will be added to the currently selected address book. You can also set the address book by using the setaddressbook() function. Example:
addnode("Device Name 1", "user", addnode("Device Name 2", "user", true); addnode("Device Name 3", "user", false, "Proxy1"); addnode("Device Name 4", "user", true, "Proxy2", "CLIbook"); addproxy(<proxyname>, <nodename> [, <book>]) "password", "TYPE"); "password", "TYPE", "password", "TYPE", "password", "TYPE",

Adds a proxy to the proxy list for a given address book. Currently only a previously created node can be used as a proxy. If the address book is not specified, the currently selected address book will be used. You can also set the address book by using the setaddressbook() function. Example:
addproxy("My Proxy", "Device Name 1"); addproxy("My Proxy", "Device Name 1", "CLIbook"); confirm(<message>, [<positiveButtonText>, <negativeButtonText>])

Pops up a window with the message and buttons for Yes and No. Returns true if the user presses Yes, and false if the user presses No. If the code writer wants to change the text labels for the Yes and No buttons, then the positiveButtonText and negativeButtonText strings must be included as parameters in the command. Example:
if (confirm("Do you want to do step 2?")) { // Step 2 if (confirm("Do you want to shutdown?", "Shutdown", "Cancel")) { // Step 3 ... } // Step 4 ... } countstatus(<boolean>)

Specifies whether or not OK and FAILED counts should be tracked for following command responses. These status counts are shown in a summary when scripts finishes. This feature is only available for some node types.
end([<message>])

Prints the message, and stops the script. Example:

end("Stopping the script."); fail([<message>])

Declares that the script has failed, and stops immediately. Example:
fail("Not enough data to complete."); filedecrypt(<password>, <inputFile>, <outputFile>)

This function will change an encrypted inputFile into a decrypted outputFile by using the keyword password which was used to encrypt the file. If the incorrect password is provided, then the decryption will fail. If you do not want to create a new file and just want to overwrite the encrypted file, simply pass the same filename for the input and output. Example:
fileencrypt("123456", "D:\file.abc", "D:\encrypted.abc"); filedecrypt("123456", "D:\encrypted.abc", "D:\decrypted.abc"); fileencrypt(<password>, <inputFile>, <outputFile>)

This function will change an encrypted inputFile into a decrypted outputFile by using the keyword password which was used to encrypt the file. In order to read this file, you will need to call filedecrypt() and use the same password that was used to encrypt the file. Example:
fileencrypt("123456", "D:\file.abc", "D:\encrypted.abc"); findline(string, searchstring, [wordnum [, delimiters]])

Searches string for lines and/or delimited words that contain searchstring. This can be useful for parsing device output. By default the whole line that contains searchstring is returned, but the wordnum argument can be used to retrieve only specific word numbers. By default, words are delimited by space, newline, carriage return and form-feed characters. Delimiters can also be specified with the optional delimiters argument.
ftpget(nodename, remotefile, localfile)

Uses FTP to retrieve a file from a defined device and save it locally. This function works both directly to the node and through certain proxy configurations. For proxy configurations, the node's proxy must be either one of the predefined "workstation" proxy types or a proxy script that has an FTPPROXYPOINT statement. This function returns true if the transfer was successful, otherwise it returns false and records an error message that can be retrieved with the getftperror() function. If no local filename is specified then the retrieved file will be stored in the main Log directory using a name based on the remote filename. The Log Viewer window will list these files as subitems below the current session's log file. Example:
connect("tbrwpcn3"); cmd("save -ascii prov"); ftpget("tbrwpcn3", "/provisioning/prov.full.016/ascii", "tbrwpcn3.txt"); ftpmget(nodename, remotefilenames [, localdirectory])

This function works like ftpget() , except that it retrieves multiple files at once. The remotefilenames parameter must be an Array of filenames. Retrieved files will be stored in the localdirectory , if one is specified, otherwise they will be stored in the main Log directory. The Log Viewer window will list these files as subitems below the current session's log file. The function returns true if all transfers were successful, otherwise it returns false and records an error message from the last transfer, which can be retrieved with the getftperror() function. If no local filename is specified then the retrieved file will be stored in the main Log directory using a name based on the remote filename. The Log Viewer window will list these files as subitems below the current session's log file. Example:
var filenames = new Array("file1", "file2") if (!ftpmget("dbrw1", filenames)) println(getftperror()); else println("All transfers SUCCESSFUL"); ftpput(nodename, localfile, remotefile)

Uses FTP to send a file to a defined device. This function works both directly to the node and through certain proxy configurations. For proxy configurations, the node's proxy must be either one of the predefined "workstation" proxy types or a proxy script that has an FTPPROXYPOINT statement. This function returns true if the transfer was successful, otherwise it returns false and records an error message that can be retrieved with the getftperror() function. Example:
ftpput("tbrwpcn3", "myfile", "tmp/myfile"); getbooknodes(<bookname>)

Returns an array with basic information about all devices in the specified address

book. Each element in the array has four properties: name , type , site and region. This allows you build a list of target devices, possibly filtered based on any of the four properties. Example:
var devices = getbooknodes("mybook"); for (var i=0; i<devices.length; i++) { print(devices[i].name); print("\t"+devices[i].type); print("\t"+devices[i].site); print("\t"+devices[i].region); println(); } getdatestamp()

Returns a date stamp for the current day in the format "MonDD_YY", as in "Feb01_06". This can be useful for generating filenames. Example:
var today = getdatestamp(); var filename = "logfile"+today; getclishelllevel()

Returns an string with the current shell level of active connections. If more than one device is connected and they are at different shell levels then this function returns the string "MULTIPLELEVELS". If no devices are connected then this function returns null . Example:
var level = getclishelllevel(); if (level == "PROV") println("In provisioning mode"); getcurrentnodetype()

Returns the short name of the device type that a script is currently executing on. Example:
var nodeType = getcurrentnodetype(); println("You are connected to a " + nodeType + "."); getdefaultaddressbookname()

Returns the address book that was last select in the connect window. This is the address book that is searched first when CLI*manager tries to connect to a specific node name when you call connect(<node>) .
getftperror()

Returns an error message from the last FTP command ( ftpget, ftpmget, ftpput), or null if there was no error.
gettftpdirectory()

Returns the local directory where TFTP files are stored. This directory is configured by the user in the Options window.
gethostaddress(<hostname>)

Returns a string containing the IP address for the specified hostname, or null if the hostname could not be found.
getlocalipaddresses()

Returns an array of local IP addresses.

getnodeinfo(<nodename>)

Returns an object containing basic information about a specific device. The device does not need to be connected. If no matching device is found in any address book then the function returns null . The returned object has these properties: name , type , address , user , region, site , and comment . Example:
println("Connected to these devices:"); var selectednodes = getselectednodes(); for (var i=0; i<selectednodes.length; i++) { var info = getnodeinfo(selectednodes[i]); println(info.name+" "+info.type); } getoption(<name>)

Returns the value of a main CLI*manager option or null if not found. For example, to get the path to the log directory, Example:
var logRoot = getOption("logfiledirectory"); println("option = " + logRoot + ".");

To get a full listing of all main option names, see the getoptionkeys() function.
getoptionkeys()

Returns the names of all CLI*manager options in an Array . For example, to print out all CLI*manager options and their values,
for (var i = 0; i < optionNames.length; i++) { println("option " + i + ": |" + optionNames[i] + "| => |" + getoption(optionNames[i]) + "|"); } getproperties()

Returns an object array containing the information from CLI*manager license. Example:
var properties = getproperties()

for (var i=0; i<properties.length; i++) { println(properties[i]); } getproperty(<key>)

Returns an object containing the license value according to the key provided. All valid keys are shown in the example below. Example:
println(getProperty("license.serialnumber")); println(getProperty("license.email")); println(getProperty("license.company")); println(getProperty("license.hostname")); println(getProperty("license.version")); println(getProperty("license.custname")); println(getProperty("license.ip")); println(getProperty("license.samid")); println(getProperty("license.custid")); println(getProperty("license.expiry")); println(getProperty("license.internal")); getpropertynames()

Returns an object array containing the license keys that are available to be used. Valid keys can be found in getproperty(<key>) . Example:
var keys = getpropertynames() for (var i=0; i<keys.length; i++) { println(keys[i]); } getscriptpath()

Returns the absolute path to the directory where the current script is found. This can be useful if you need to open data files that are in the same directory as the script, using the File object. Example:
var currentdir = getscriptpath(); var f = new File(currentdir, "input.txt") getselectednodes()

Returns an array with the names of currently selected devices. Example:

var devicelist = connect("tbrwpcn1 tbrwpcn2"); var selecteddevices = getselectednodes(); for (var i=0; i<selecteddevices.length; i++) println(" "+selecteddevices[i]); getselectednodecount()

Returns the number of currently selected devices.

Example:
var count = getselectednodecount(); if (count == 0) println("No devices are selected"); gettimestamp()

Returns a time stamp for the current time in the format "HH:MM:SS", as in "18:55:24". This can be useful for generating filanemes. Example:
var now = gettimestamp(); var filename = "logfile"+now; getword(string, wordnum [,delimiters])

Returns specific word numbers from a string. Word numbers are counted starting with 1. By default, words are delimited by space, newline, carriage return and form-feed characters. Delimiters can also be specified with the optional delimiters argument. Example:
// Prints the word "simple" println(getword("This is a simple test", 4)); hide(<string>)

Hides the specified text wherever it appears in the command output, by masking it with "*" characters. This can be useful for hiding passwords, etc. Example:
var mypassword="abcdefg"; hide(mypassword); // The user will see "set password *******" cmd("set password "+mypassword); include(<scriptname>)

Includes the contents of another CLI*script file. This allows you to include functions from other files and build libraries of re-usable functions. The <scriptname> parameter can be either a local filename or a URL. Example:
include("passportfunctions.txt"); include("http://myserver/testscript.txt"); issilentfor(<milliseconds>)

Returns a Boolean value based on whether the proxy login stage or the node has been silent for the specified number of milliseconds.

Example:
if (issilentfor(1000)) println("Node silent for 1 second."); makelogfilename(<name>)

Generates a unique filename based on the name you specify, within the file structure used by the Log Viewer window. You can then write your own data into this file using other CLI*script functions such as File.open(), File.writeln() , etc. The Log Viewer window will list these files as subitems below the current session's log file.
newlogfile([<label>])

Closes all open log files in the current session and re-opens a new set of files, optionally with the specified label. This can be useful if you want to use separate log files for different stages of their execution.
next_counter_value(<varname> [, <increment>])

This function creates and increments synchronized global numeric counter variables. These variables are global in the sense that their values are shared among all CLI Tabs and windows that may be running at the same time, as long as they were started by the same CLI*manager window. By default the counter is incremented by 1, but other values can be specified. The returned counter value is guaranteed to be unique among all threads, so that no two scripts that are running simultaneously will receive the same value. This can be useful for synchronizing activities among multiple scripts, such as those started by the Script Director. Example:
next_counter_value("linenumber"); openbrowser(<url>)

Opens the specified URL in the user's default web browser.

okwindow(<message>)

Pops up a window with the specified message and waits for the user to press its OK button.
onfinish()

If you write your own CLI*script function with this name, it will be called automatically whenever the CLI*script finishes, whether it was successful or not. This can be useful for cleanup purposes. Example:
function onfinish() { println("The script is complete."); }

ontargetsfinished()

If you write your own CLI*script function with this name, it will be called automatically after all targets in a Script Director window have finished, or after the Script Director "Stop" button has been pressed. This can be useful for cleanup purposes. Example:
function onfinish() { println("Script targets are complete."); } openpassthrough(<devicename>)

Opens a port that allows a remote client to take over the existing connection to the specified device. The device must already be connected. This function returns an object with "port" and "password" fields, which remote clients will need to connect to the pass-through. All traffic between the device and the remote client is sent through CLI*manager exactly as it was received, so to the session will appear to be native to both ends (i.e. no CLI*manager enhancements). This can be useful for integrating connected devices with external applications. To reduce security concerns, a warning is shown to the CLI*manager user asking them for permission to open the pass-through. Each passthrough generates its own random password, which can only be used once. And each passthrough accepts only one connection attempt, which must occur within 2 seconds of the passthrough being opened. When the client connects to the port, they will need to supply the expected devicename (as the "login") and the pass-through password. Example:
connect("TBRWPCN1"); var server = openpassthrough("TBRWPCN1"); println("port="+server.port); println("login=TBRWPCN1"); println("password="+server.password); parallelprocess(<scriptfile>, <devices>, <multithreadcount>)

Runs a script file on a set list of devices, multithreaded across multiple CLI*manager tabs with one node per tab.
pause([<seconds>])

Pauses execution of the script. If a value for seconds is supplied, the script will automatically un-pause itself after that amount of time. Otherwise, the script is paused until the user presses the Pause button in the lower-right corner of the main window. Example:
cmd("d atmif/* stats"); pause(10); cmd("d atmif/* stats"); println("Average rate per second over 10 seconds:"); println(gettablestatistic("txCell","av"));

pdtlogin()

Attempts to enter PDT mode in the current CS1K connection, looking up the username and password from address books if necessary. Returns true if PDT mode was successfully entered.
print(<string>)

Prints the string, without a newline, to the user's output. Example:

print("Starting"); print(" checks..."); println([<string>])

Prints the string, followed by a newline, to the user's output. If no string is given, prints only a newline. Example:
println("Starting checks..."); removenode(<dname> [, <book>]]])

Removes a climanager node from an address book. If the user does not set the address book, then the node will be removed from the currently selected address book first, if it is found, then the other address books are searched. You can also set the address book by using the setaddressbook() function. Example:
removenode("Device Name 1"); removenode("Device Name 2", "CLIbook"); removeproxy(<proxyname> [, <book>])

Removes a proxy from the proxy list for a given address book. If the address book is not specified, the currently selected address book will be used. You can also set the address book by using the setaddressbook() function. Example:
removeproxy("My Proxy"); removeproxy("My Proxy", "CLIbook"); returnvalue(<varname>, <value>)

Adds a return value to the script results, which are shown in the Summary when the script is complete. Example:
returnvalue("variable1", "value1"); returnvalue("variable2", "value2");

runcommandfile(filename)

Runs commands from a plain text file as if they were typed at the CLI*manager prompt. Example:
runcommandfile("testcommands.txt"); runmultiple(<scriptname>, <targets> [, <threads>])

Runs the specified scriptname on all devices in the targets array. By default the script will be run simultaneously in up to 5 threads, one thread per device. More threads can be requested by passing a number in the threads argument. By default the new script is assumed to be in the same directory as the script that is currently running. Script results from returnvalue() will be shown in the output window where the original script was running. Raw results for each thread will be shown in separate CLI tabs. Example:
var targetdevices = new Array("TBRWPCN1","TBRWPCN2","TBRWPCN3"); runmultiple("multipletask.txt", targetdevices, 5); runmultiplewithargs(<scriptname>, <targets>, <threadcount>, <args>)

This function has the same functionality as runmultiple() except that this one will arguments if it is a requirement from your script. Example:
var targetdevices = new Array("TBRWPCN1","TBRWPCN2","TBRWPCN3"); var args = new Array("arg1","arg2"); runmultiple("multipletask.txt", targetdevices, 5, args); runvbscript(<filename> [,<arg1> [,<arg2> ...]])

Runs the specified VBScript file. Note that the script is executed outside of CLI*manager, and so the current CLI*script will continue executing immediately after the VBScript file has been started. This function is only available on Windows platforms. Example:
runvbscript("D:\myVBScript", "arg1"); savelogfile(filename [,devicename])

Saves the log file for the current session to a specified filename. If the nodename argument is supplied then the log file for the specified device will be saved, instead of the log for the entire session. Examples:
// Saves the log for the whole session

savelogfile("fullsession.txt"); // Saves the log only for the TBRWPCN3 device savelogfile("TBRWPCN3.txt", "TBRWPCN3"); sendemail(<hostname>, <from>, <to>, <subject>, <text> [, <attachments>])

Sends an email message. The hostname is expected to be the address of an SMTP mail server. The from and to parameters are email addresses, subject is the subject of the email, and text is the actual body text of the message. The attachments parameter is optional, and if present it is expected to be either a filename or an array of filenames to be attached to the email. Example:
sendemail("mysmtpserver", "john@smith.com", "jane@smith.com", "My Subject", "Hello"); sendpassword(<devicename>)

Looks up the specified device name in the address book and sends its password to the current connection. Returns true if the name was found and the password was sent.
setaddressbook(<book>)

Sets the default address book within climanager. This address book will be searched first when adding and removing nodes and proxies, as well as when connecting to nodes with the same name but are in different address books. Example:
setaddressbook("CLIbook"); setalarmsenabled(<enabled>)

Enables and disables alarms on Passport MSS and related platforms. Example:
setalarmsenabled(false); setautoconfirmenabled(<boolean>)

Allows scripts to control the auto-confirm option programmatically, which confirms provisioning changes on MSS platforms after an activate command. After the script finishes the option is returned to its user-configured value. Example:
setautoconfirmenabled(false); setecho(<enabled>)

Enables or disables the echoing of command responses to the user. If echo is set to false then all command output will be hidden from the user. Other script output, such as from the println command, is always shown regardless of this setting.

Example:
setecho(false); // This command and its output will be hidden cmd("show ip int"); // This println output will be shown println("The show command is complete."); settablabel(<label>)

Sets the name of the current tab in the main window. Note that this custom label only applies while the script is running, and it will be changed to its default setting (the names of connected nodes) if the list of connected nodes changes. Example:
settablabel("Checking"); settargettitle(<title>)

Sets the title at the top of the Script Director. This function has no effect if the Script Director is not in use. Example:
settargettitle("My Target Window"); settracetologfile(<enabled>)

Enables or disables logging of output from trace() functions to file. The default setting is specified in the CLI*manager Options window under Scripts.
setuserinputallowed(<boolean>)

Enables or disables user input.

startswdld(<hostname>)

Starts a Passport software download from the currently connected device to the specified hostname . The address, user and password of hostname are retrieved from an address book. This function returns true if the download was successful.
starttftpserver()

Starts a TFTP (Trivial FTP) server that will accept calls and requests from remote devices. The user can configure whether or not scripts are allowed to start this server, in the Options window.
stoptftpserver()

Stops the TFTP server, if it is running.

trace([<message>])

Adds text to the CLI*script Debugger window, in the "Console" tab. Also, if trace() logging to file is enabled (see settracetologfile) then the message will be

saved to file.
zip(<infiles>, <outfile>)

Creates a new compressed ZIP file containing the specified set of files, and returns true if at least one file was successfully added. The <infiles> parameter can be either a path name or an array of path names. If a directory is included in <infiles> then all files and subdirectories of that directory will be added to the zip. The <outfile> parameter is a file name for the target ZIP file.
ziptargetlogfiles([<filename>])

Instructs the Script Director window to create a zip file containing all log files that were involved in the current script, after all target nodes have been completed. If no filename is specified then a file chooser window will pop up asking the user where to save the zip file. If the current script is not being run by a Script Director then this function does nothing.

Functions for fetching data from CLI Tables (where available):

These functions pull values from CLI Tables, displayed by a previous cmd() function. Currently CLI Tables are only for MSS and its related device types, and sometimes for TL1 device types (if enabled in the Options window).
setclitablesenabled(<boolean>) gettablevalue(<attributename>) gettablevalues(<attributename>) gettablestatistic(<attributename>, <statname>) gettablestatistics(<attributename>, <statname>) setclitablesenabled(<boolean>)

Enables and disables CLI Tables. This can be important because the user may have disabled CLI tables in the Options window. Example:
setclitablesenabled(true); gettablevalue(<attributename>)

Fetches the first value for the specified attribute from the last CLI Table. This is similar to the gettablevalues() function, but this can be more convenient when you know that the table contains only one component. If no matching attribute is found then this function returns null . Example:
cmd("d atmif/100 stats"); println("Value for txCell: "+gettablevalue("txCell")); println("Value for rxCell: "+gettablevalue("rxCell")); gettablevalues(<attributename>)

Fetches values for the specified attribute from the last CLI Table. Returns an array of objects, each with four fields: node , component , attribute and value . This is

similar to the gettablevalue() function, but this allows you to process results from tables that contain multiple components and/or multiple devices. If no matching attribute is found then this function returns null . Example:
cmd("d atmif/* stats"); var values = gettablevalues("txcell"); println("TXCELL Values:"); for (var i=0; i<values.length; i++) { print(values[i].node+"\t"); print(values[i].component+"\t"); print(values[i].attribute+"\t"); println(values[i].value); } gettablestatistic(<attributename>, <statname>)

Fetches a single statistic for the specified attribute from the last CLI Table. This is similar to the gettablestatistics() function, but this can be more convenient when you know that the table contains only one component. If no matching attribute is found then this function returns null . The statname must be one of the following:
rate

Rate per second, measured between results from the last table and the table before it. Works only if at least two tables have displayed using the same command. Minimum rate per second for all previous CLI tables that were displayed using the same command. Works only if at least two tables have displayed using the command. Maximum rate per second for all previous CLI tables that were displayed using the same command. Works only if at least two tables have displayed using the command. Average rate per second for all previous CLI tables that were displayed using the same command. Works only if at least two tables have displayed using the command. Minimum value recorded for all previous CLI tables that were displayed using the same command. Maximum value for all previous CLI tables that were displayed using the same command. Average value for all previous CLI tables that were displayed using the same command. The 1-time difference between attribute values in the previous two tables. The total change in the value, between the last table and the first table that was displayed using the same command.

minrate

maxrate

avrate min max av change1 change

Example:
cmd("d atmif/* stats"); pause(10); cmd("d atmif/* stats"); println("Average rate per second over 10 seconds:");

println(gettablestatistic("txCell","av")); gettablestatistics(<attributename>, <statname>)

Fetches statistics for the specified attribute from the last CLI Table. Returns an array of objects, each with four fields: node , component , attribute and value . This is similar to the gettablestatistic() function, but this allows you to process statistics from tables that contain multiple components and/or multiple devices. If no matching attribute is found then this function returns null . The statname must be one of the statistic names listed for the gettablestatistic() function. Example:
cmd("d atmif/* txcell"); pause(5); cmd("d atmif/* txcell"); println("TXCELL Rate/s Values:"); var stats = gettablestatistics("txcell","avr"); for (var i=0; i<stats.length; i++) { print(stats[i].node+"\t"); print(stats[i].component+"\t"); print(stats[i].attribute+"\t"); println(stats[i].value); }

Functions for building and managing network maps

CLI*manager has built-in functions for discovering Network Maps only for certain device types. To build maps for other types, and to supplement the existing discovery functionality, you can write your own CLI*scripts to build and manipulate network maps using the built-in functions below.
mapselectbook(bookname) mapadd(mapname) mapadd(parentmap, newname) mapselect([bookname,] mapname) mapaddnode(nodename [, x, y]) mapaddlink(fromname, toname, type) mapaddlink(fromname, toname, type, fromlabel, tolabel [, linklabel]) mapaddlink(fromname, toname, type, linklabel) mapsave(directoryname, mapname, format, type [, type...]]) mapsaveall(directoryname, format, type [, type...]]) mapsaveweb(directoryname, format, weblink, type [, type...]]) mapselectbook(bookname)

Selects the specified address book in the map window. This book will be used for all other map commands below. Example:
mapselectbook("My Book"); mapadd(mapname)

Adds a new map to the current address book, with the specified mapname. Returns true if the map was added successfully.

Example:
mapadd("My New Map"); mapadd(parentmap, newname)

Adds a new map below the specified parentmap , with the specified mapname. Returns true if the map was added successfully. Example:
mapadd("My New Map", "My New Submap"); mapselect([bookname,] mapname)

Finds and opens a map with the specified mapname. If bookname is specified then the map will be found in that address book, otherwise it will be found in the current address book (see mapselectbook). Returns false if the specified map or book were not found. Example:
mapselect("My Book", "My New Map"); mapaddnode(nodename [, x, y])

Adds a node to the selected map. The specified nodename must exist in the current address book. The new node's position on the map can optionally be specified with the x and y parameters. Returns true if the node was added successfully. Example:
mapaddnode("TBRWPCN1"); mapaddlink(fromname, toname, type)

Adds a link between two nodes. Map nodes with the specified fromname and toname must exist on some map in the address book. Recognized values for the type parameter include "atm", "trunk", "ip", "ethernet", and "user". Returns true of the link was added successfully. Example:
mapaddlink("TBRWPCN1", "TBRWPCN2", "atm"); mapaddlink(fromname, toname, type, fromlabel, tolabel [, linklabel])

Adds a link between two nodes. Map nodes with the specified fromname and toname must exist on some map in the address book. Recognized values for the type parameter include "atm", "trunk", "ip", "ethernet", and "user". The fromlabel and tolabel strings will be shown at the link endpoints, and the linklabel (if specified) will be shown in the middle of the link. Returns true of the link was added successfully. Example:

mapaddlink("TBRWPCN1", "TBRWPCN2", "atm", "A140", "A100"); mapaddlink(fromname, toname, type, linklabel)

Adds a link between two nodes. Map nodes with the specified fromname and toname must exist on some map in the address book. Recognized values for the type parameter include "atm", "trunk", "ip", "ethernet", and "user". The linklabel will be shown in the middle of the link. Returns true of the link was added successfully. Example:
mapaddlink("TBRWPCN1", "TBRWPCN2", "ip", "1.2.3.4"); mapsave(directoryname, mapname, format, type [, type...]])

Saves a bitmap of the map that has specified mapname into directoryname using the specified format (either "png" or "jpg"). Only the specified link types will be shown on the map. Recognized values for the type parameter include "atm", "trunk", "ip", "ethernet", "user", and "all". Returns true if the bitmap was saved successfully. Example:
mapsave("d:\\profiles\\bsinclai\\desktop", "My New Map", "png", "all"); mapsaveall(directoryname, format, type [, type...]])

Saves bitmaps for all maps in the current address book into directoryname using the specified format (either "png" or "jpg"). Only the specified link types will be shown on the map. Recognized values for the type parameter include "atm", "trunk", "ip", "ethernet", "user", and "all". Example:
mapsaveall("d:\\profiles\\bsinclai\\desktop", "png", "all"); mapsaveweb(directoryname, format, weblink, type [, type...]])

Saves bitmaps for all maps in the current address book into directoryname using the specified format (either "png" or "jpg"), and generates web pages for browsing them. Each map node will be hyperlinked to the specified weblink with the node name appended. Example:
mapsaveweb("d:\\profiles\\bsinclai\\desktop", "png", "http://myurl/mypage", "all");

Objects

Array Object
The Array object contains multiple values, indexed numerically. Example:
var myarray = new Array(); var myarray2 = new Array("value1", "value2", "value3"); length toString()

The number of elements in the array. Returns a string that contains all elements in the array, separated by commas. concat([item1 [, Returns a new array with the specified elements added at the end. item2 [, ...]]]) join() Returns a string that contains all elements in the array, separated by the specified separator (or by commas if no separator is provided). pop() Removes and returns the last element in the array. push([item1 [, Adds the specified elements to the end of the array, and returns the new item2 [, ...]]]) length. reverse() Reverses the order of all elements in the array, and returns the array. shift() Removes and returns the first element in the array. slice(start, end) Returns a new array containing elements from this array, from the start index up to but not including the end index. If start or end are negative then they will be interpreted as a number of elements before the end of the array. sort([function]) Sorts elements in the array, either by treating all elements as Strings or by using the supplied compare function. splice(start, Returns a copy of this array with deletecount elements deleted beginning deletecount, [item1 [, item2 at start , and optionally with the specified new items inserted at that [, ...]]]) position. unshift([item1 [, Adds new items to the beginning of the array. item2 [, ...]]])

Date Object
The Date object represents a point in time to within a millisecond. It is created by three constructors: Date () Date (value) Date (year, month [, date [, hours [, minutes [, seconds [, ms]]]]]) The first creates a Date object with the current time. The second creates a date from the number of milliseconds after Jan 1, 1970. The third creates a date from as many arguments as you provide.
toDateString() toTimeString() toUTCString() valueOf getTime() getFullYear()

Returns a human-readable string for the date part of this date. Returns a human-readable string for the time part of this date. Returns the number of milliseconds after Jan 1, 1970 represented by this date object. Returns the number of milliseconds after Jan 1, 1970 represented by this date object. Returns the number of milliseconds after Jan 1, 1970 represented by this date object. Returns the year from this date object, using local time.

getUTCFullYear() getMonth() getUTCMonth() getDate()

Returns the year from this date object, using universal time. Returns the month from this date object, using local time. Returns the month from this date object, using universal time. Returns the day within the month from this date object, using local time. getUTCDate() Returns the day within the month from this date object, using universal time. getDay() Returns the day within the week from this date object, using local time. getUTCDay() Returns the day within the week from this date object, using universal time. getHours() Returns the hour within the day from this date object, using local time. getUTCHours() Returns the hour within the day from this date object, using universal time. getMinutes() Returns the minutes within the hour from this date object, using local time. getUTCMinutes() Returns the minutes within the hour from this date object, using universal time. getSeconds() Returns the seconds within the minute from this date object, using local time. getUTCSeconds() Returns the seconds within the minute from this date object, using universal time. getMilliseconds() Returns the milliseconds within the second from this date object, using local time. getUTCMilliseconds() Returns the milliseconds within the second from this date object, using universal time. getTimezoneOffset() Returns the difference between local time and UTC, in minutes. setTime() Sets the number of milliseconds after Jan 1, 1970 represented by this date object. setFullYear() Sets the year from this date object, using local time. setUTCFullYear() Sets the year from this date object, using universal time. setMonth() Sets the month from this date object, using local time. setUTCMonth() Sets the month from this date object, using universal time. setDate() Sets the day within the month from this date object, using local time. setUTCDate() Sets the day within the month from this date object, using universal time. setDay() Sets the day within the week from this date object, using local time. setUTCDay() Sets the day within the week from this date object, using universal time. setHours() Sets the hour within the day from this date object, using local time. setUTCHours() Sets the hour within the day from this date object, using universal time. setMinutes() Sets the minutes within the hour from this date object, using local time. setUTCMinutes() Sets the minutes within the hour from this date object, using universal time. setSeconds() Sets the seconds within the minute from this date object, using local time. setUTCSeconds() Sets the seconds within the minute from this date object, using universal time. setMilliseconds() Sets the milliseconds within the second from this date object, using local time. setUTCMilliseconds() Sets the milliseconds within the second from this date object, using universal time.

File Object

A File object that can be used for read/write operations on local files, and for file operations such as delete and move. File objects are created with the constructors File(pathname) and File(directory, pathname) . Note that backslash characters in the pathname and directory may need to be escaped as "\\" when passing them as quoted strings. Examples:
var f = new File("D:\\profiles\\testfile.txt"); var f = new File("D:\\profiles", "testfile.txt"); File(pathname)

Creates a new File object for the specified pathname. If the pathname is not absolute then it will be relative to the current directory. File(directory, Creates a new File object for the specified pathname, below the specified pathname) parent directory. open() Opens the file and returns true if successful. This is necessary before either reading or writing the file. close() Closes the file and returns true if successful. isopened() Returns true if the file has been opened with open(). write(text) Writes the specified text to the file. Returns true if successful. This operation is only allowed if the file object has not been used for reading since the last call to open(). writeln(text) Writes the specified text to the file, followed by a newline. Returns true if successful. This operation is only allowed if the file object has not been used for reading since the last call to open(). flush() Flushes the output buffer used for writing to the file, and returns true if successful. readln() Reads a line of input from the file, or null if unsuccessful. If an error occurs then the error() function can be used to determine the problem. readAll() Reads the entire file and returns its contents in a string. If an error occurs then the error() function can be used to determine the problem. eof() Returns true of the file is at end-of-file, or if it is not open for reading. exists() Returns true of the file exists. isFile() Returns true of the file exists and is a regular file (not a directory). isDirectory() Returns true of the file exists and is a directory file (not a regular file). list() Returns an array of file/directory names in the directory specified by this file. If the file is not a directory then the function returns null . copyTo(dest) Copies the current file to the specified destination. If the current file is a directory then all of its contents are copied to the destination. Returns true if all files were copied successfully. moveTo(dest) Moves a file from one directory to another. This function will only work for files, not directories. mkdir() Creates a directory for this file, and returns true if the directory was successfully created. getLength() Returns the length of the file in bytes. lastModified() Returns a string containing the date and time when this file was last modified. remove() Deletes the file, and returns true if successful. renameTo(newname) Renames the file, and returns true if successful. canRead() Returns true if the file exists and can be read. canWrite() Returns true if the file exists and can be written. getPath() Returns the path name represented by this file. getAbsolutePath() Returns the complete path name represented by this file. isAbsolute() Returns true if this file's path is absolute.

getName() getParent() error() clearError() toString()

Returns the name part of this file's pathname. Returns the name of this file's parent directory. Returns the last error message since this file was opened or clearError() was called. Clears the error message returned by error(). Returns the path name represented by this file.

FTP and SFTP Objects

These objects can provide convenient and efficient scripting of file transfers. Both of these objects have the same functions:
connect(nodename)

Connects to the specified nodename, which must be found in an Address Book. connect(address, user, Connects to the specified address, with the specified username and password) password. cwd(path) Changes the working directory at the remote end. disconnect() Disconnects the session. errormessage() Returns the last FTP/SFTP error message, or null if no error has occured. get(localfile, Gets the remotefile and saves it in the localfile name. remotefile) isConnected() Returns true if the session is successfully connected. listDirectories() Lists subdirectories of the current remote directory. listFiles([extensions]) Lists files found in the current remote directory. Filtered filename extensions can be specified as a string or as an array of strings. mkdir(path) Creates a new subdirectory of the current remote directory. put(localfile, Sends a local file to a remote filename. remotefile) pwd() Returns the current remote working directory.

Math Object
The Math object contains a number of static constants and mathematical functions.
Math.E The base of the natural logarithms. Math.LN10 The natural logarithm of 10. Math.LN2 The natural logarithm of 2. Math.LOG2E The base-2 logarithm of e. Math.LOG10E The base-10 logarithm of e. Math.PI The approximate value of Pi. Math.SQRT1_2 The square root of 1/2. Math.SQRT2 The square root of 2. Math.abs(x) Returns the absolute value of x. Math.acos(x) Returns the arc cosine of x radians. Math.asin(x) Returns the arc sine of x radians. Math.atan(x) Returns the arc tangent of x radians. Math.ceil(x) Returns x rounded up to the nearest integer. Math.cos(x) Returns the cosine of x radians. Math.exp(x) Returns e to the power of x. Math.ln(x) Returns the natural logarithm of x. Math.log(x) Returns the base-10 logarithm of x. Math.max(val1,val2) Returns the largest of the supplied values. Math.min(val1,val2) Returns the smallest of the supplied values.

Math.pow(x,y) Math.random() Math.round(x) Math.sin(x) Math.sqrt(x) Math.tan(x)

Returns x raised to the power of y. Returns a random number between 0 and 1. Returns x rounded to the closest integer. Returns the sine of x radians. Returns the square root of x. Returns the tangent of x radians.

RegExp Object
The RegExp object represents a regular expression and its flags. It is created by the RegExp(pattern, flags) constructor. The flags parameter is expected to be a string containing any combination of the "g", "i" and "m" characters, standing for "global", "ignoreCase", and "multiline".
exec(string) Returns

an array of strings containing regular expression matches in string, or null if no match was found. test(string) Returns true if this regular expression has any matches in string. source A string containing the pattern for this regular expression. global True if this regular expression's global flag is set. ignoreCase True if this regular expression's ignoreCase flag is set. multiline True if this regular expression's multiline flag is set. lastIndex The end position where the last match was found.

ScriptWindow Object
The ScriptWindow object allows scripts to show customized graphical windows and update them during script execution. This can be useful for both displaying script output and prompting the user for input. ScriptWindow objects are described in XML, using elements from a collection of available containers and graphical components. For more detailed information and examples, see The ScriptWindow Object. Example:
var xml = <window title="Test Window" width="300"> <form direction="north"> <statusfield runningcolor="green" label="Script Status"/> <timerfield type="script" label="Elapsed Time"/> <timerfield type="time" label="Current Time"/> </form> <resultpanel id="result1" height="100"/> </window>; var window = new ScriptWindow(xml); window.show();

The example above would open a window like this:

Functions:
show() Shows the window. hide() Hides the window. setTitle(string) Changes the title of the window. getButtonAction() Returns the name of the button that

the user pressed to close the window: "OK", "Cancel", "Yes", or "No". If the user closes the window without pressing one of the buttons, this method returns null .

String Object
The String object represents character strings and provides functions for examining, manipulating and searching the string. Strings are normally created with quoted text, as in "abc". They can be concatenated with the + operator, as in "abc"+"def".
length charAt(pos) charCodeAt(pos)

The number of characters in the string. Returns the character in the string at the given position. Returns a number for the character code at the given position in the string. concat([string1 [, Adds the given strings to the end of this string. string2 [, ...]]]) indexOf(searchstring [, Returns the first index of searchstring in this string, starting at pos]) pos if it is provided. lastIndexOf(searchstring Returns the last index of searchstring in this string, starting at [, pos]) pos if it is provided. localCompare(otherstring) Returns a negative, zero, or positive number depending on whether this string is lexagraphically less than, equal to, or greater than otherstring. match(regexp) Returns either the first match (if the regexp is not global) or an array of matches (if regexp is global) for the regular expression regexp. The regexp can be either a string or a RegExp object. replace(search, replace) Returns a new string with all occurances of search replaced with replace . The search can be a regular expression, in which case the number of replacements depends on the expression's global value. search(regexp) Returns a number representing the first index in this string matching regex . The regexp can be either a string or a RegExp object. slice(start, end) Returns a new string containing characters from this string, from the start index up to but not including the end index. If start

split(separator, limit) substring(start, end) toLowerCase() toUpperCase()

or end are negative then they will be interpreted as a number of characters before the end of the string. Returns an array of no more than limit substrings found in this string, separated by separator . The separator can be a regular expression. Returns a portion of this string, from the start index up to but not including the end index. Returns a copy of this string with all characters converted to lower case. Returns a copy of this string with all characters converted to upper case.

WindowsComponent
This object provides direct access to Windows dispatch objects. For example, this can be used to directly open Excel, create a worksheet, enter values and formulas, etc. This object is only available on Windows platforms.
get(name) put(name, value) call(name, arg1, arg2, ...) callSub(name, arg1, arg2, ...) invokeGet(name, arg) invoke(name, arg)

XML Object
XML objects can be created from embedded XML content, from strings, and from files. Examples:
// Create an XML object from embedded XML var xml = <node name="DBRW1"> <card slot="0" type="CP"> <port port="0"/> <port port="2"/> <port port="3"/> </card> <card slot="5" type="3pOC3MmAtm"/> </node>; // Create an XML object from a string var xml = new XML("<node><card/><card/></node>"); // Create an XML object from a file var xml = new XML(readAll("myfile.xml"));

Once an XML object has been created, it can be manipulated and searched in a number of ways using E4X syntax. A full description is beyond the scope of this document, but a number of excellent E4X references are available on the internet. Examples:
// Get the type from the first card var cardtype = xml.card[0].@type; // Set the CPU utilization of the second card xml.card[1].@cpuutil = 15; // Get the type of the first card, and print its type var card1xml = xml.card[0]; println(card1xml.@type);

// Get an array of cards with CPU utilization greater than 10 var highcpu = xml.card.(@cpuutil > 10); for (var i=0; i<highcpu.length(); i++) println("High CPU on slot "+highcpu[i].@slot+" ("+highcpu[i].@cpuutil+"%)"); // Get an array of ports without specifying the full XML path var ports = xml..port; for (var i=0; i<ports.length(); i++) println("Slot "+ports[i].parent().@slot+" Port "+ports[i].@port);

Batch Jobs
Batch jobs provide a simple way to automate pre-defined sets of commands. They can be simple lists of commands, or they can include user-prompted parameters for use in switch commands. As an option, external tab-delimited data files (e.g. from Excel) can be used to supply parameters to a batch job. Writing a Batch Job Special Batch Job Commands Special Batch Variables Batch Prompts Running Batch Jobs with a Data File

Writing a Batch Job

Use the text editor, or another editor like Notepad or vi to create batch files. If no parameters are required, a batch file can be a simple set of switch commands. Enhanced CLI*manager syntax (ranges, +, &, and EM commands, etc.) can be used in the file just as you would type them from the command-line. If parameters are required, use the format shown in the example below:

All text between "<" and ">" symbols is treated as a parameter name. Parameters found between the STARTPROMPTS and ENDPROMPTS keywords will cause CLI*manager to ask the user for a value. In other places in the batch job, these parameters will be replaced with the values supplied by the user. See Batch Prompts for details about available prompt types.

Special Batch Job Commands

Some commands are available to Batch Jobs, but are not part of regular CLI*manager syntax: ANSWERprompt BATCHCONFIRM

BATCHSET BATCHSETHIDDEN COUNTSTATUS ECHO ENDBATCH EXPECTEDPROMPTS FAIL FAILFORNODES FOR GOTO IFFOUND IFVAR PAUSE RELATEDJOB REPEAT RETURNVALUE SENDANDRETURN SENDNODEPASSWORD SETTABLABEL SETTARGETTITLE STARTPROMPTS STOPATprompt ANSWERprompt "<prompt>" WITH "<response>" Normally, when CLI*manager sends a command from a batch file, it waits for the next command prompt before continuing. This isn't always appropriate, because some commands prompt the user for more information before completing and returning to the normal command prompt. To help with these situations, a new ANSWERPROMPT command has been added (which can be shortened to just "ANSWER"). After reading each command from a batch file, CLI*manager checks for any number of ANSWERPROMPT commands in the following lines. Then, while the initial command is running, it checks for the specified prompts in the expected order, and responds with the specified answers after 500ms of silence from the connection. The "answers" can be control characters like "^D", which are automatically translated from caret notation to the corresponding control code. Here is an example that sets the bootorder on Shasta.
;commands set bootorder answerprompt "flags (f)" answerprompt "boot file1 answerprompt "boot file2 answerprompt "boot file3 show bootorder

with "" (f1)" with "" (f2)" with "cmc" (f3)" with "^D"

In the example above, the "set bootorder" command is sent to the switch normally. CLI*manager then scans through the next lines in the batch job to check for any number of ANSWERPROMPT statements, and stops scanning when any other statement type is found. And so, while the "set bootorder" command is running, it watches for the string "flags (f)" and responds by sending "" (nothing) and pressing enter. Then it watches for the string "boot file1 (f1)", etc.

BATCHCONFIRM [<message>] This command prompts the user with a message to confirm that they want the job to continue. For example, this batch command:
batchconfirm Are you sure you want to continue?

would open a window like the one below. If the user presses OK, the batch job will continue normally. If the user presses Cancel, the batch job will stop immediately.

BATCHSET <variablename> <value> The BATCHSET command sets the value for local batch variables. If the variable name does not already exist, it is defined. The ++, --, +=, -=, *= and /= operators can also be used on existing variables. For example:
BATCHSET message "This is a test" echo <message> BATCHSET x 2 echo <x> BATCHSET x += 5 echo <x> BATCHSET x -= 3 echo <x> BATCHSET x *= 2 echo <x> BATCHSET x /= 4 echo <x>

BATCHSETHIDDEN <variablename> <value> This command works just like BATCHSET except that the value will be hidden in the main CLI window and in the console. This can be useful for hiding passwords used in batch jobs.
BATCHSETHIDDEN password "abcd1234"

COUNTSTATUS <ON | OFF> Specifies whether or not OK and FAILED counts should be tracked for following command responses. These status counts are shown in a summary when scripts finishes. This feature is only available for some node types. ECHO ON ECHO OFF ECHO <string> The ECHO ON/OFF command controls whether command output will be shown to

the user. The ECHO <string> command prints the specified string in the user's CLI window. ENDBATCH The ENDBATCH command stops the current job. EXPECTEDPROMPTS <prompt1> [<prompt2> ...] This command is only useful for batch jobs that will be running on "Plain Telnet" device types. It specifies what prompts should be expected from the telnet session after batch job commands are completed. Typically this command would be placed somewhere at the beginning of your job, before connecting to the device. From that point on, whenever your job issues a command, CLI*manager will wait for one of the expected command prompts before continuing. Further EXPECTEDPROMPTS commands override all previous prompt settings. If you don't specify an EXPECTEDPROMPTS command in your job, three default prompts are used: ">", "#", and "%". Example:
expectedprompts "ftp>"

FAIL [<message>] The FAIL command stops the current job and prints out the specified message. FAILFORNODES IFFOUND "<text>" FAILFORNODES IFNOTFOUND "<text>" Fails this batch job for any devices where the specified text is found (or is not found) in the response from that device. Any device that fails in this way will be automatically deselected, so that further commands in your job will not be send to those devices. If all of the remaining devices fail in this way, the whole batch job is aborted. This can be useful when your batch job is running against multiple target devices simultaneously. FOR <variable> FROM <start> TO <end> [STEP <step>] ... ENDFOR This command lets you set up FOR loops with an index variable. For example:
for i from 1 to 10 step 2 echo <i> endfor

GOTO <label> The GOTO command tells the batch job to go backward until it finds the specified label. Labels are defined by the first word in any line that starts with a semicolon, like ";add_cards". There is also a pre-defined label called "start" that represents the beginning of the batch job.

IFFOUND, IFNOTFOUND The IFFOUND and IFNOTFOUND commands search for a specified string in the last command response, and then run the next command(s) depending on whether the string was found or not. Both of these commands have two formats: one with a THEN keyword, and one without. The THEN keyword must be used if more than one command line is to be run based on the condition. For example:
IFFOUND OC3 BATCHSET porttype Sonet IFNOTFOUND "ok" FAIL "Aborting batch job." IFFOUND "ok " THEN echo "The command was successful." ELSE echo "The command was not successful." ENDIF

Normally IFFOUND and IFNOTFOUND search for an exact case-sensitive match with specified string. The IGNORECASE option can be used to search while ignoring case. For example:
d ns IFFOUND "synchroNIZED" IGNORECASE THEN echo "The switch is synchronized." ENDIF

IFVAR The IFVAR command acts like the IFFOUND command, except that it compares batch variables to make its decision. For example:
IFVAR <identical> = true THEN check prov ENDIF

Available comparators include =, ==, !=, <, <=, >, and >=. PAUSE [<seconds>] You can tell a batch job to pause anywhere in its execution by adding a pause command on any line. When this command is reached, the batch job will pause until the user tells it to continue. If a number of seconds is specified, then the job will pause for that amount of time unless the user tells it to continue. RELATEDJOB <filename|URL> The RELATEDJOB command allows you to provide links from one batch job to another. Hyperlinks to related jobs are shown in the Batch Job Summary when the job is complete.
RELATEDJOB myjob2

REPEAT <count> [<label>] The REPEAT command tells the batch job to repeat itself for a specified number of times. If a label is specified, the job will repeat the job starting at that label.

RETURNVALUE <name> <value> The RETURNVALUE command allows jobs to return result values. Return values are also shown in the Batch Job Summary when the job is complete. When used with the "Batch Target" feature, these return values are collected in a table for viewing results from all devices.
d sh ca/0 returnvalue "Card Type" $insertedCardType returnvalue Product $productCode

SENDANDRETURN <command> Normally, when CLI*manager sends a command from a batch file, it waits for the next command prompt before continuing. SENDANDRETURN allows you to send the command and move on to the next line in the batch job, without waiting for the command to finish. This can be useful when a long-running command (like a test) is expected to run in the background.
SENDANDRETURN start lp/14 sonet/0 test

SENDNODEPASSWORD Sends the login password for each connected device. This can be useful for automating "enable" commands on some device types. The password itself is automatically hidden in the CLI and console windows. SETTABLABEL <label> Sets the name of the current tab in the main window. Note that this custom label only applies while the script is running, and it will be changed to its default setting (the names of connected nodes) if the list of connected nodes changes. SETTARGETTITLE <title> Sets the title at the top of the Script Director. This function has no effect if the Script Director is not in use. STARTPROMPTS ... ENDPROMPTS These keywords identify a section in the batch job that contains parameters to be prompted from the user. In these sections, parameters will cause CLI*manager to ask the user for a value. The user will not be prompted for any values until the ENDPROMPTS keyword has been reached.
startprompts Provisions a voice card Card number: <cardno> Card type: <cardtype> Remote device: <remotedevice> Remote card number: <remotecard> endprompts

When the batch job is running, the section above would open a window like the one below in which the user can enter parameter values. All lines in the section that contain a parameter cause fields to be shown in the window. Lines that do not

contain parameters (such as "Provisions a voice card" in this example) will be shown as comments at the top of the window.

STOPATprompt "<text>" Stops reading the response from the previous command, when the specified text is found. You can then respond to the prompt on the next line in your batch job. This can be useful for handling intermediate prompts from multiple devices simultaneously.

Special Batch Variables

Apart from variables defined by user prompts, and those defined by the BATCHSET command, there are a few variables that are filled in automatically. LASTRESPONSE LOGTOFILE NODECOUNT NODELIST NOWDATE NOWTIME LASTRESPONSE This variable contains the complete text of the response from the last command. There are also LINE and WORD tags that can be used with this variable to extract only certain lines or words from the response. The FINDLINE tag searches for the first line that contains specified text. And the DELIM tag specifies delimiters to use when counting words in a line (instead of whitespace, which is the default). The "DEFAULT" tab specifies a default value if the specified line or word do not exist. Examples are:
echo echo echo echo echo echo <lastresponse> <lastresponse line 2> <lastresponse line 2 word 4> <lastresponse findline "deviceName" word 3> <lastresponse findline "Image Name" delim "/" word 4> <lastresponse findline "Image Name" delim "/" word 4

default "No image name">

LOGTOFILE If you want to make file-logging mandatory in a batch job, there is a new batch variable called <logtofile> that contains the current log filename, or "off" if no file is opened. So you should be able to abort batch jobs if the user cancels, with something like this:
logtofile ifvar <logtofile> == off fail "You must open a log file."

NODECOUNT This variable contains the total number of currently selected devices. NODELIST This variable contains a list of the currently selected devices, separated by spaces. NOWDATE This variable contains the current date, according to the local clock (not a clock on the target device).
echo <nowdate>

NOWTIME This variable contains the current time, according to the local clock (not a clock on the target device).
echo <nowtime>

Batch Prompts
Normally, batch job prompts defined between the "startprompts" and "endprompts" keywords of a batch file are assumed to be plain text values.
Remote device name: <remote>

Text values like this can also be specified as optional by using the " optional " keyword after the variable name. If a prompt is optional, the batch job will be allowed to run even if no value is specified. If no value is entered then the value of its variable will be an empty string ("").
Second card: <card2 optional>

There are also a few special prompt types: SELECT, CHECKBOX, NUMBER and BUTTON. All of these types must be specified in the first word of the prompt name. SELECT CHECKBOX NUMBER

BUTTON SELECT <variable> FROM <value1, value2, value3,...> In the example below, the user will be asked to select a value for the "metro" variable, from four possible values in a drop-down list.
Metro: <select metro from Toronto, Ottawa, Dallas, RTP>

CHECKBOX <variable> <label>,<value1>,<value2> In the example below, the user will be offered a checkbox labeled "Yes". If the checkbox is selected, then the variable "activate" would be given the value "Y". Otherwise it would be given a value of "N".
Activate Changes: <checkbox activate Yes,Y,N>

NUMBER <variable> [<default>[,<minimum>[,<maximum>]]] In the example below, the user will be required to enter a numeric value for the variable named "slot". The default value will be 10, and accepted values from the user must be in the range from 0 to 15. Note that the 10, 0, and 15 parameters are all optional.
Slot: <number slot 10,0,15>

BUTTON <variable> <value>,<label> In the example below, a button labeled "Type1" would be included in the prompt window. If the user presses this button, the "type" variable would be set to "1", and the batch job would start immediately as if they had pressed the OK button. Note that the button will be automatically disabled if any of the other required fields are not filled in.
Press to start type 1: <button type 1,Type1>

Running Batch Jobs with a Data File

Instead of typing batch parameters manually, tab-delimited data files can be used to supply even very large numbers of parameters. This means you could plan your attribute values in a spreadsheet or text editor, write a simple batch-file that does provisioning based on the fields in the data file, and CLI*manager will take care of the rest. This feature can be extremely powerful when planned out carefully.

To run a batch job with a data file, click on the "Data File" button in the parameter window (shown above). For each line in the data file, CLI*manager will run the batch job and automatically fill in variables with tab-delimited fields from the data file. Fields from the data file are assumed to be in the same order as they are specified in the batch file. After you have supplied a data file, press the "Run Batch Job" button. For example, if your batch job starts with this:
startprompts Enter a device name: <device> Enter a logical processor number: <lp> Enter a port number: <port> endprompts

Then you could use a data file like this (with Tabs between the fields in each line):
device1 device1 device2 device3 3 5 7 4 0 2 1 3

The batch job would run first with device1 LP 3 port 0, and then with device1 LP 5 port 2, etc. until all lines in the data file have been used. Related Links: Scripting

The Organize Scripts Window

The "Organize Scripts" window allows you to add scripts to the Scripts menu for easy access, and group them logically into submenus as necessary. This is similar to the "Favorites" feature in web browsers. Scripts can also be flagged to be shown in the CLI*manager startup banner, and to start in the Script Director.

The buttons above and below the tree provide functions for managing your scripts: Add Script Folder adds an existing CLI*script or Batch Job to the selected batch folder. adds a "folder" (not an actual folder on your file-system) that can group scripts and other script folders, for organizational purposes.

Remote Folder makes it possible to set up centralized collections of scripts on a web server that will automatically appear in the Script menu. The remote folder must contain a URL to an XML file that describes the scripts and their menu structure. There is a "Refresh Remote Folders" item to the Script menu which queries the remote XML file for changes. See Remote Remote Script Folders for more information. Import allows you to easily import whole sets of scripts from a ZIP archive into your batch directory. The archive can optionally contain an XML index file that will automatically add jobs into your Script menu. Imported script information is added beneath the selected folder in the organizer window. exports the selected folder to a ZIP archive, including index information and script settings. This can be used with the Import function to easily share collections of batch jobs. deletes the selected folder or script. shows properties for the selected folder or script. opens the selected script in the Text Editor.

Export

Delete Properties Edit

Script Properties
A number of settings are available for scripts in the organizer, in the Script Properties window.

Filename or URL Script Name

a local filename or URL that points to a CLI*manager script. Press the chooser button on the right to choose a local file, or type into the text field. specifies a readable name for the script. If no name is supplied, then the filename will be used to describe the script in the Script menu and on script buttons.

Show a button in the shows a button in the startup banner when CLI*manager starts up, and when new startup banner session tabs are opened. Pressing these buttons runs the attached script immediately, either in the main CLI window or in the Script Director depending on settings below. Disable in the Script menu disables the job in the Script menu. The script will still be visible, but it cannot be run from the menu itself.

Run using the Script specifies that the script should be started with the Script Director, instead of Director running in the CLI window.

Remote Script Folders

Remote Batch Folders are centralized collections of batch jobs on a web server that will automatically appear in the Batch menu. The remote folder points to a URL that describes the batch jobs and their menu structure. There is a "Refresh Remote Folders" item to the Batch menu which queries the remote XML file for changes.

Index URL

URL to a remote XML index file that describes and organizes remote batch jobs. Normally batch jobs are also stored in the same directory as the index file on the server. These XML files can be obtained using the "Export" button in the "Organize Batch Jobs" window, which generates the XML index and packages it with the necessary batch job files. specifies a readable name for the batch folder. If no name is supplied, then the name will be obtained from the remote server.

Folder Name

Server enabled determines whether this server should be queried for updates.

The Script Director

The Script Director (shown below) can be useful for running any CLI*script or Batch Job against any number of devices. Select devices from the "Node Finder" list on the left and then press the middle arrow buttons to move them into the "Target Nodes" list. Then you can run any script against the whole list of targets. As the script runs, it updates the Status column with states like "Connecting", "Running", "Failed", and "Successful". Then later you can select any targets you want and re-run them, or change their script.

The "devices/Run" field in the top-left is used to specify the number of devices that should run the script at the same time. In the example above, CLI*manager would run the "script.txt" script on the first 2 devices in the list simultaneously. After the job is finished on those 2 devices, it would run on the next block of 2 devices until all devices are complete. CLI*scripts and Batch Jobs can use the RETURNVALUE command to pass results to the Script Director, which it will display in extra columns in the Target table, as shown below. You can then export the results, or use the results to decide what further scripts need to be run on some devices.

Open Edit Keep On Top Nodes/Run Related Scripts

Allows you to select a CLI*script or Batch Job from your local file system. Edits the specified script with the Text Editor. Keeps the Script Director on top of the main CLI window. If this button is toggled off, then the Script Director may be moved behind the main CLI window or minimized. Specifies how many devices should run the job simultaneously. This is a drop-down list of scripts related to the currently selected batch job. This list is obtained either from a RELATEDJOB command in the batch job, or from the list of scripts in the same folder of the Organize Batch Jobs window. This field is hidden if no related scripts are known. Adds the selected devices in the Available devices list to the Target devices list. Moves the selected devices up in the target order. Moves the selected devices down in the target order. If this option is selected then the job will only be run for rows selected in the Target devices table. This option is hidden if no rows are selected. This button toggles the device Finder table on and off. This can provide more room for results when the device finder is no longer needed. Starts the script. Exports all results shown in the Target devices table to a CSV (commaseparated format) file, suitable for import into spreadsheet applications. Clears RETURNVALUE results from the Target table, but leaves the list of target devices

Add Target devices

Remove Target devices Removes the selected devices from the Target devices list. Move Up Move Down Run on selected nodes only Choose Nodes Start Export Clear Related Links: CLI*script

Running Scripts Outside of CLI*manager

CLI*scripts and Batch Jobs can be run from cron jobs and from the UNIX or Windows command-line using the "clibatch" utility, which is installed with CLI*manager. The syntax for the command is:
clibatch [options] "<file_name>" [<param1> [<param2>] ...]

Available options:
-Datafile

specifies a tab-delimited data file or URL for job parameters -gui allows CLIBATCH to connect to a graphics environment. This option is only necessary for certain graphics-related batch job commands, such as those that generate network maps with map commands. This option should not be used in cron jobs unless proper X11 authorization has been set up -quiet disables all output other than output that comes directly from the script. The startup headers and result summary are hidden. "<file_name>" either a local filename or a URL where the batch job can be found [<param1>...] parameters that will be passed as prompt responses in the order that they appear in the batch job. The CLIBATCH command always exits automatically after the job is complete. Note that the CLIBATCH utility is only installed when you use a full CLI*manager installer. Copies of CLI*manager that have been auto-upgraded from versions lower than 3.1 will not have this command installed. Related Links: CLI*script Batch Jobs Scripting The UNLOCKCLI Command Map Commands

Stopping and Pausing Scripts

While a CLI*script or Batch Job is running, extra fields are shown in the bottom-right corner of the CLI*manager window. The Pause and Stop buttons take effect after the current command is complete. For Batch Jobs, the current batch job line number out of the total line count are shown as in the "9/22" example below.

Pause Pauses the running script after the current command is complete. The script will remain paused until you press the Stop or the Pause button. Stop Stops running the script after the current command is complete. If the Stop button is pressed more than once, the second and following presses cause active connections to be logged out, which provides a more immediate way to force the script to terminate even while a script command is in progress. Related Links: CLI*script Batch Jobs Scripting The pause() CLI*script Command The end() CLI*script Command The fail() CLI*script Command The PAUSE Batch Job Command The ENDBATCH Batch Job Command The FAIL Batch Job Command

Restricted Commands
Both batch jobs and plugins provide warnings whenever they are about to issue "restricted" commands. Commands can be added and removed from the restricted command list through the "Script Restrictions" item in the Tools menu. By default, disruptive commands include DELete, LOCK, ACTivate, RESTART, and SWITCHover. Capital letters at the beginning of a command are considered significant, meaning that at least those characters must be matched.

If a restricted command is issued by a batch file or plugin, the user will be asked to choose between allowing the current command, allowing all commands, or denying the current command.

This feature can be deactivated by deselecting the "Enable Restrictions" button on the Script Restrictions window. Related Links: Scripting

Network Maps
CLI*manager includes a basic network mapping feature, which can auto-discover some types of network details. Links can also be drawn manually where necessary. Maps can be grouped into hierarchies of sites, regions, countries, etc. Once generated, these network maps can be shared among user groups. Certain CLI commands are integrated with the map. Maps Overview Map Controls Creating Maps Map Trees Map Annotations Map Details Using Maps Previous Section: Scripting Next Section: Collaboration

Maps Overview
A sharable set of network maps can be generated and maintained from within CLI*manager. The maps can contain all of CLI*manager's device types, and many of the map's details can be auto-discovered. Multiple maps can be selected from a drop-down menu. Double-clicking on a device (or set of devices) in the map opens a connection in the CLI window. Certain CLI commands will affect the map. For example, the EM command automatically displays the map that contains the specified devices. Also, trunk and PORS commands on the MSS will highlight the affected trunks. Maps are stored in Address Books, which can be shared among groups of users.

Related Links: Network Maps

Map Controls
Save Maps Select Mode Hand Mode Add Link Annotation Align devices Zoom Add devices Book: Map: Parent Map Map Tree Type: Detail: Related Links: Network Maps saves all maps in the current address book allows you to select map items and drag them around allows you to pan around the map by clicking and dragging manually adds links between devices adds annotations (shapes and text) to the map aligns selected devices to their top, bottom, left or right zooms the map to selected percentages opens a window that lets you add devices to the current map selects the address book to open for maps selects maps in the current address book changes to this map's parent in the tree allows you to create and modify a map tree structure selects the link type to show in the map selects the detail to show on map links

Discover Links automatically discovers map links

Creating Maps
To create a new map, first you need to turn maps on by selecting Maps from the View menu, or by pressing Ctrl-M. You can then create new map by choosing "Add New Map" from the Map menu. You will need to choose a unique name for the map, which will be used to select it from the drop-down menu. Adding Devices Adding Links Manually Discovering Links Automatically Importing Map Details from File CLI*script Network Map Functions Related Links: Network Maps MAPIMPORT CLI*script Network Map Functions

Adding Devices
Once the map has been created, you will need to add devices to the map by choosing "Add devices to Map" from the Map menu, or by pressing the Add devices button. A window will open that will allow you to select existing devices from your address book.

The Add Map devices window lists all of the devices in your address book that are not already shown on the map. The list can be filtered by typing device names in the "Name" field, or by selecting a device type from the "Type" drop-down list. devices can be added to the map by dragging their names from the list directly onto the map, roughly in the position you want it to be shown. Then you can drag them around the map to reorganize them. Related Links: Creating Maps Network Maps

Adding Links Manually

Each link has a type, which can be selected by selecting a type from the Type drop-down menu. Available types in this version of CLI*manager include IP Subnets, Ethernet Links, Passport Trunks, and User Links. The selected link type from this menu determines both which links will be shown, and what type of link will be drawn if the user draws one manually. You can draw your own manual links by pressing the Add Link button, and dragging a line between two devices. Related Links: Creating Maps Network Maps

Discovering Links Automatically

Some types of links can be automatically discovered. Different device types are able to collect different types of links. For example, trunks and PNNI ATM links can be auto-collected on MSS. IP subnets and Ethernet links can be collected from Passport 1200/8100/8600, BayRS (BCN/BLN/ARN/ASN), MSS, and BayStack/BPS. To start the map collection process, choose "Discover Map" from the Map menu, or press the Discover Links button.

From this panel, you can collect information from selected devices (if you have selected them on the map), or from all devices on the current map, or from all devices in all maps. You can also restrict the types of links to collect, which can speed up the process in some cases. When you press the Start button, CLI*manger will log into the affected devices and collect its information. Results from the collection will be logged.

Related Links: Creating Maps Network Maps

Importing Map Details

If you have network connectivity information in an external source, such as a database or spreadsheet, you can import this information into CLI*manager. Tab-delimited files can be imported using the MAPIMPORT command, or the "Import Map Sites" option in the Map menu. Each line in the file should have one of the formats below, separated by tab characters:
map <name> [<parent>] device <name> <map> [<type> [<x> <y>]] link <type> <from> <fromlabel> <to> <tolabel> [<linklabel>] devicename mapname

The format for each line decides the type of information that will be imported: Lines with the MAP keyword in the first column will be used to create maps. If a PARENT map name is specified then the new map will be added as a submap of that parent. Lines with the device keyword in the first column will add devices to the specified map. If no type is specified then the device is expected to exist already in the address book. For a list of accepted device type names, use the ABIMPORT Utility and type "abimport -typenames". Related Links: Creating Maps Network Maps

Map Trees
Network maps can be organized into a tree, allowing you to group maps based on site, region, country, etc. To build a tree, press the "Map Tree" button above the map pane.

From this window you can click and drag maps below each other to create tree branches and submaps. If the "Build submap links" box is checked, CLI*manager will automatically generate parent maps showing links between their sub-maps. Once a tree has been built, the Map drop-down list shows the tree structure, and the "Parent Map" button allows you to move up in the tree.

Parent maps in the tree automatically contain icons for each of their sub-maps, and discovered links between the submaps are shown in the parent map. Double-clicking on a submap icon opens that map.

Related Links: Network Maps

Map Annotations
You can add annotations to your maps, such as basic shapes and text, with the Annotation button. Three types of annotation are currently available: text, rectangle, and circle. Select one of these tools and then click or drag in the map area to draw the item. Annotations always appear below map devices and links.

To add text to a map, select the Text tool and click on the map where you want the text to be placed. A window like the one below will appear, for entering the text.

Related Links: Network Maps

Map Details
Some link types can show extra information detected during automatic discovery process. For example, IP Subnet links and Trunks can show round-trip delay. To show this extra information, use the Detail field in the top-right of the map window. The selected detail will be displayed in the middle of each link.

Each type of link has its own set of details that can be shown. Some link types already show information in the middle of the link (for example, IP Subnet links show the subnet address). This information will be hidden while the new detail is displayed, but it can be shown again by choosing "Normal" from the Detail list. Link Type IP Subnets Ethernet ATM Trunks User Links Details Normal, Round-Trip Delay Normal, Link Type (10BT, 1000BT, etc.) Normal, Link Type (Sonet, DS3, etc.) Normal, % Utilization, Round-Trip Delay Normal

Related Links: Network Maps

Using Maps
Once you have devices and links on a map, you can arrange it logically by dragging the devices around. As you drag a device, its links and labels move around to best fit the new position. You can align devices with each other by selecting more than one device and pressing the Align button. The Hand button can be used to scroll the map around. You can view or edit link details by double-clicking on a link. Each type of link has its own details. Autodiscovered link details cannot be edited - only viewed. If there are 4 or more links between a pair of devices, they are shown on the map as a single link group to simplify the map, but you can double-click on a link group to see its members.

Double-clicking on map devices opens a connection in the CLI window. When you connect to devices in the CLI window, the map for those devices will be shown automatically (if one exists). Related Links: Network Maps

Collaboration
CLI*manager has a built-in collaboration feature that can be very useful for team-based troubleshooting and training purposes. Any number of users can collaborate by sharing sessions with each other. All collaborating users are able to type on the same command-line, and see the same responses from the connected switches. Clients can connect using either another CLI*manager session, or telnet. Setting Up a Collaboration Server Connecting to Another Session Collaborating from Telnet Working in Collaboration Mode Connecting to Devices While Collaborating Disconnecting a Remote Session Previous Section: Network Maps Next Section: CLI*servers

Setting Up a Collaboration Server

Access to your own CLI*manager session is controlled by the Collaboration Status window, in the "Tools" menu.

Status

allows you to turn the collaboration server on and off. If the status is Off, then no remote users will be able to connect with your session. The status must be set to Off to change the other settings. is any free port number on your machine. This can be set to either Auto of Fixed. In Auto mode, a free port will be chosen automatically for every session (a different one for each CLI tab). In Fixed mode, you must choose a port number manually and enter it into the Fixed field.

Server Port

Accept Method determines how remote clients are allowed into your local session. In Prompt mode, a window will appear asking if you want to accept a connection from the remote user. In Password mode, the remote user must supply the correct password, and then they automatically join the session without needing your permission. Your Name specifies the name you want to use for collaboration sessions. Whenever any user takes control of the session (by typing, etc.), the name of that user is shown in the bottomright corner of the CLI*manager window.

Local Addresses is a list of IP addresses on your local server that can be called by remote collaboration clients. Related Links: Collaboration

Connecting to Another Session

To connect with another CLI*manager session, choose "Collaborate" from the "Connect" menu. A window will appear, prompting you for details about the remote session. (Note that if you are using a CLI*server, a list of known collaboration servers will be shown in the top half of the window, otherwise only the bottom fields will be visible.)

Remote Address is the IP address (or hostname) and port number of another active ("On") CLI*manager collaboration server. Your Name specifies the name you want to use for this collaboration session. Whenever any user takes control of the session (by typing, etc.), the name of that user is shown in the bottom-right corner of the CLI*manager window.

Server Password is the password expected by the remote collaboration server, if required. A password is not necessary when the remote server is configured in "Prompt" mode. Status shows the status of the connection attempt, and error messages in the event of a connection failure.

If the remote server is accepting connections with "Prompt" mode, the user at the server side will see a window like the one below. If the remote user accepts your collaboration request, collaboration mode will be started.

Related Links: Collaboration CLI*server Collaboration Directory

Collaborating from Telnet

Collaboration clients do not need to be running CLI*manager. Any client can join a collaboration session with a regular telnet program, as long as they connect to the correct port number.

Related Links: Collaboration

Working in Collaboration Mode

In collaboration mode, all users share the same command-line. Other users will see what you are typing as you type it, and you will see what they are typing. Any number of users can collaborate in this way, as long as they all connect to the same CLI*manager server and port. When a new user joins a collaboration session, all users receive a message announcing the new user. The name of the last user to control the session (by typing, etc.) is shown in the bottom-right corner of the window for all users.

The CLI tab at the bottom shows device names only on the server side, because that is where the connection actually exists. On clients, the CLI tab shows information about the collaboration session.

Related Links: Collaboration

Connecting to Devices While Collaborating

When a collaboration session is active, users can connect to devices in the usual ways - with the Connect window, the * command, etc. However, for security reasons, the address book information (address, password, etc.) for the connection comes from the user that issues the command. This way, clients cannot connect to any device that isn't in their own address books - even if it is in the address book of the server. This provides added security, in case a collaboration client wants to connect with a device to which they wouldn't otherwise have access - someone who does have access must make the connection for them. Collaboration clients that are connected using Telnet cannot connect to devices with the * command, because they have no address book. Other users in the session must connect to the devices. All device connections are made directly from the collaboration server - never from clients. Related Links: Collaboration

Disconnecting a Remote Collaboration Session

The easiest way to disconnect from a collaboration session is to press the End Collaboration button in the toolbar. You can also stop collaboration with any remote session from the Collaboration Status window, in the Tools menu. On the server side, the window looks like the one shown below. You can select any user from the list at the bottom, and press the Drop Selected button. Or you can drop all users with the Drop All button.

On the client side, the Collaboration Status window looks like the window below. All of the users that are sharing the current session are listed here. To stop collaboration with the remote session, press the Disconnect button.

Related Links: Collaboration

CLI*servers
Most CLI*manager features can work in a standalone environment, meaning that your copy of CLI*manager can connect to devices and control them by itself without requiring any extra server components. However, there are cases where a centralized server can be useful for storing and distributing information to multiple CLI*manager clients from a common point. The CLI*server is an optional component that runs on a UNIX workstation to provide centralized information to registered CLI*manager clients. Installing Your Own CLI*server Defining CLI*servers CLI*server MDM Alarms CLI*server Collaboration Directory Previous Section: Collaboration Next Section: Appendix A: Release Notes

Installing Your Own CLI*server

Copy the cliserver_xxx_solaris.tar.Z file into any directory on your workstation and extract it with the commands below. This will extract two files into a " cliserver " subdirectory below your current directory.
% % x x x uncompress cliserver_xxx_solaris.tar.Z tar xvf cliserver_xxx_solaris.tar cliserver, 0 bytes, 0 tape blocks cliserver/cliserver, 103720 bytes, 203 tape blocks cliserver/cliserver.cfg, 2051 bytes, 5 tape blocks

Next, configure your settings by editing the " cliserver.cfg " file. The comments in the file itself explain the necessary settings. The " serverport " and "serverpassword " settings are required for the server to work. The " nmspath" setting is only needed if your server is going to connect with MDM to retrieve alarms information.
####################################################################### ## SERVERPORT: The port the server should listen to. ## ## Choose any free port on your system. ## For ports < 1023 you will need to run the server as root. ## ## Example: ## serverport 1500 ####################################################################### serverport ####################################################################### ## SERVERPASSWORD: Passwords for client access to the server. ## ## The format for this option is: ## serverpassword <password> <service> [<service> [...]] ## ## The "service" parameters are the names of services to be ## activated for clients that use each password level. Accepted ## service names include: ## alarms - enables MDM alarm distribution ## collab - enables the collaboration directory ## ## Up to 16 serverpasswords can be specified here, each with ## permission for different combinations of services. ## ## Example: ## serverpassword abc123 alarms collab ## serverpassword xyz789 collab ####################################################################### serverpassword ####################################################################### ## NMSPATH: The full path to the "MagellanNMS" directory. ## ## The "alarms" service requires this path to retrieve MDM alarms. ## If this path is incorrect or not specified then no alarms will be ## sent to CLI*manager clients. ####################################################################### nmspath /opt/MagellanNMS ####################################################################### ## LOGFILE: Specifies whether the log file is ON or OFF. ## ## By default the CLI*server log file is ON, which stores server ## events in a file called "cliserver.log" in the same directory as ## the cliserver executable, or in the serverroot directory specified ## by the "-r <serverroot>" option at startup. ## ## Example: ## logfile on ## logfile off

####################################################################### logfile on

The easiest way to start the CLI*server is to run the " cliserver " executable with the "-d" option, which tells it to start in daemon mode. The server will start running in the background and return you immediately to your command line.
% cliserver -d

By default configuration files, runtime data files and log files will be stored in the same directory as the cliserver executable. This can be changed by starting the cliserver with a different server root path with the "-r <serverroot>" option.
% cliserver -d -r /opt/cliserver

If a log file has been enabled, the CLI*server will record events in the "cliserver.log" file. This can be useful for troubleshooting purposes.
% more cliserver.log 30/Nov/2004 21:22:20 ** Server started on port 1500 30/Nov/2004 21:22:33 0 47.9.16.70 COLLABDOWN:port=1257; 30/Nov/2004 21:22:35 0 47.9.16.70 COLLABUP:name=Brett port=1266; 30/Nov/2004 21:23:33 0 47.9.16.70 LISTACTIVE 30/Nov/2004 21:23:35 0 47.9.16.70 ALARMLOG 30/Nov/2004 21:23:37 1 47.9.16.70 LISTHGDS 30/Nov/2004 21:40:24 ** Server terminated

Related Links: CLI*servers Defining CLI*servers

Defining CLI*servers
To use a CLI*server you must first define it with the CLI*servers window in the Tools menu. Enter details for each server and press the Test button to make a test connection to the server. Once you know that your server settings are correct, press the Apply button to add it to your list of servers.

Server Name a readable name for the server Address Port Password State Functions Related Links: CLI*servers CLI*server MDM Alarms CLI*server Collaboration Directory a remote IP address or host name for the UNIX workstation where the server is running the remote port number where the server is running a password for the CLI*server (not a password for the workstation itself!) specifies whether the server is enabled or disabled. If disabled, connections to the server will not be made. specifies which services you want to use on this CLI*server

CLI*server MDM Alarms

CLI*servers that are running on the same workstation as Preside Multiservice Data Manager (MDM) can be configured to supply a network-wide alarm stream to CLI*manager clients. Without one of these CLI*servers, CLI*manager only collects and monitors alarms from devices to which the user is currently connected.

Alarm Streams
When a CLI*server has been configured to supply an alarm stream, a continuous stream of alarms will be collected as long as CLI*manager is running. These alarms are viewable in the Log Viewer window. Alarms that come from CLI*servers (and not from direct connections to devices) are shown at the top level of the log tree under the date-stamp for each day, with the label "CLI*server Alarms".

Alarm NTPs
CLI*servers that are supplying a alarms can also be used to look up alarm documentation. Right-click on an alarm and choose "Show NTP". A window will appear with documentation for that alarm.

Device Filters
Also, when alarms are being collected from a CLI*server, the Filter window in the Log Viewer fetches a list of available devices from the CLI*server, instead of looking only at current connections. This allows you to filter the alarm stream for certain devices.

Related Links: Alarm Logs CLI*servers

CLI*server Collaboration Directory

CLI*servers can be configured to keep a directory of CLI*manager collaboration servers on its registered clients. Without one of these CLI*servers, CLI*manager users need to know each other's collaboration addresses and ports to collaborate. When a CLI*server collaboration directory is available, the Collaborate window shows a list of known collaboration servers. To connect with a user in the list, simply select their name and enter the collaboration password (if necessary).

Related Links: Collaboration CLI*servers CLI*server MDM Alarms

DMS Patching Tools

Note: These tools are only available to users who have an internal Nortel license to use CLI*manager. External customers do not have access to these tools. The DMS Patching Tools replace functionality that was formerly covered by the MSAT tool which is no longer being supported. Users will be able to send and receive patches and other files from a DMS switch over a modem or X25 connection. CLI*manager can also run remote patching tools from an RPS server such as Poll Inform/Gen SIF. Users can configure which RPS server to use by pointing CLI*manager to their old MSAT.prop file. The following table describes the individual tools that comprise the suite of DMS Patching Tools. Send Single Patch query and send individual patches from a remote RPS server based on a short CLLI name using the Send Single Patch window. Patch Calculator perform a complete RPS Poll Inform/Gen SIF on a site based on the short CLLI name using the Patch Calculator window. File Transfer send or receive ascii and binary files from a DMS over a modem or X25 connection using the File Transfer window.

Send Single Patch

This tool allows users to query individual patches and other files from an RPS server from a particular RPS region. The patches can then be sent en masse to a DMS switch by clicking the "Send Patches" button. Note that "RPS Region" and "Remote Site ID" are required fields in order to properly query a patch. Clicking the "Add" button with a valid patch name in the "Patch ID" field will immediately trigger a query to RPS for that patch. If the patch query is successful it is listed in the left-hand side of the window. The "Open" button allows users to get their list of patch names from a local text file. This is useful if the user needs to query a large number of patches or list of patches was generated by an external tool. The file must contain a single patch name per line or else the file will not be parsed correctly. If the file is parsed, an RPS query is triggered for each patch name listed in the file.

The following table summarizes the purpose of each field and some buttons in the Send Single Patch window.

Add Open Delete Clear Patch ID Remote Device

Queries the RPS server for the patch name listed in the "Patch ID" field and adds it to the left-hand list if found. Opens a local file that has a list of patch names on each line. RPS is queried and all patches that are found are added to the left-hand list.

Removes the items that are selected in the left-hand list. Clears the entire form of all data including the left-hand patch list. A valid patch name to search in RPS. The remote device to which the patches will be sent when the "Send Patches" button is pressed. Remote Name The remote name that the file selected in the left-hand window will have when sent to the DMS switch. This field serves no functional purpose except to show the user what name the file will have on the remote switch once transferred. Record Length Allows the user to adjust the record length that is used to transfer all the files displayed in the left-hand list. RPS Region Indicates which RPS region is used to query patches and files. This field is mandatory in order to execute patch queries. By Default the RPS region is RTP, but users can use their old MSAT.prop files to trigger queries in a different RPS region. Remote Site ID This field contains what is known as the "short CLLI". It is mandatory to have this field properly data filled to execute an RPS query.

Patch Calculator
The Patch Calculator triggers a number of remote RPS tools. Everything from querying patches, executing a poll inform and generate SIF function, to sending patches and re-running failed steps can be performed from this tool. The main function of this tool is to poll a remote DMS switch for any patches that are required and then to generate and store a list in RPS for the specified "Remote Site ID". Based on the results of the most recent "Poll Inform/Gen SIF", a user can then transfer the required patches to a switch. Using the two buttons in the top right-hand corner of the window, a user can check when the more recent inform list was generated for a site or they can query a "local SIF" on their own local mahcine. This can allow users to bypass the "Poll Inform/Gen SIF" step if it already has been done recently.

The following table describes each field, button and radio button in this window. SIF This is the short CLLI used to query RPS for a list of patches calculated from the last "Poll Inform/Gen SIF" step. If the "Server" button to the right of this field is clicked, a patch query sent for this short CLLI. This is useful to see when the last "Poll Inform/Gen SIF" was performed and whether any patches are required for this site. The "Server" button will trigger an RPS query to get the results of the most recent "Poll Inform/Gen SIF" based on the short CLLI listed in the "SIF" field. The status label at the bottom of the window will show the status of the query and the right-hand list will show the list of patches that were calculated. The "SIF" field must contain a valid short CLLI in order for the query to succeed. The ''Local File" button allows users to browse for a local SIF file that contains a list of patches. If a file is selected and successfully parsed, the "SIF" field will contain the path to the file and the list of patches will be displayed in the right-hand patch list. Note that using a local file will bypass the query to RPS. This is the remote device to which patches and other files will be transferred. By default it shows SFDEV, but this can be changed to any other valid device. This is the region which determines which RPS server is queried for patches and inform lists. By default the region is RTP but this can be changed by pointing CLI*manager to your old MSAT.prop file. This field is mandatory and must contain a valid short CLLI. It is used by the "Poll Inform/Gen SIF", "Send Patches", and "Recover Previous Step" functions of this tool. This field is allowed to be

Remote Device RPS Region Remote Site ID

different from the "SIF" field which is simply used to do RPS patch queries. Moves any patches selected in the right-hand patch list to the leftRemove hand patch list. Moves any patches selected in the left-hand patch list back to the Re-Add right-hand patch list. Poll Inform/Gen SIF When this radio button is selected and the "Execute" button is pressed, RPS is triggered to poll an inform list from the site and generate a list of required patches. The "Remote Site ID" field must have a valid short CLLI in order for this step to work. Send Patches When this radio button is selected and the user presses the "Execute" button, the patches displayed in the right-hand patch list will be sent to the device or disk volume listed in the "Remote Device" field. Recover Previous Step The remote RPS server keeps track of what stage a patch upgrade process is at. If a failure occurs during one of the steps, RPS will try and pick up where it left off. So selecting the "Recover Previous Step" radio button and then pressing "Execute" will trigger RPS to try and continue where it failed. Note that RPS keeps track of the process based on the short CLLI so this information must be filled in correctly in the "Remote Site ID" field in order for it to work properly. Execute Pressing this button will trigger whatever Patch Calculator step is selected by the radio buttons.

File Transfer
This tool is designed specifically to send and receive files from a DMS switch over a modem or X25 connection. If you try and use this tool over a telnet connection it will fail. Several parameters specific to DMS file transfer can be tweaked to send or receive a file. Several transfers can be staged before pressing the "Transfer" button at which time the tool will attempt to carry out each transfer in the order in which they are listed. The status label at the bottom of the window gives information on the success or failure of the transfer. Hovering your mouse over the bottom of the window will show the history of the transfer. The "Status" column in the transfer table will show the number of bytes sent or received so users can view the progress of individual file transfers.

The following table briefly describes the controls and fields in this tool. Pull down list contains "Send" and "Receive". "Send" means the "Local File" will be sent to the DMS whereas "Receive" means the "Remote File" will be received from the DMS. Transfer Type Can be set to "ASCII" or "Binary" depending on the type of file being transferred. Record Length Determines the size of packets that are transferred. Record Type Can be set to "Fixed" or "Variable" depending on the type of file being transferred. Local File A local file to be sent or received. The button on the right of this field allows the user to browse their local file system. Remote File A remote file to be downloaded or uploaded. This field must follow the format (without the double quotes) "/<device name>/<file name>". For example to send the file TIM03BJ1$PATCH to the disk volume S00DPATCH you need to type /S00DPATCH/TIM03BJ1$PATCH . Add Adds the transfer information to the transfer table. Remove Removes any rows selected in the transfer table. Transfer Pressing this button will trigger the tool to perform all the transfers listed in the transfer table in order. Action

Using the MSAT.prop File

Users of MSAT will be familiar with the MSAT.prop file which contains configuration information for MSAT. This file can be read by CLI*manager to configure the patching tools the same way that they were configured in MSAT. Simply copy the MSAT.prop file to the ../Data directory under your CLI*manager installation and restart CLI*manager. For example, most users would find CLI*manager installed under C:\Program Files\CLImanger on Microsoft Windows. The MSAT.prop file would then be copied to C:\Program Files\CLImanager\Data\MSAT.prop. Related Links:

Appendix A: Release Notes

These are brief notes about changes in CLI*manager version 4.1.x, compared to version 4.1. Changes in 4.2.1 Previous Section: CLI*servers Next Section: Appendix B: Plugin APIs

CLI*manager 4.2 Release Notes

On the surface, CLI*manager 4.2 may not have a lot of visible changes compared to previous versions, but a large part of the architecture has been rewritten to make it faster, more standards compliant, and more stable. Among other things, the terminal emulator and protocol architecture have been completely rewritten. Also, the underlying platform has been updated to Java 6, which provides many benefits and also contributes to improved speed and stability. And, as usual, this version includes several new features and support for new device types. Major speed improvements in terminal output, especially when displaying large amounts of data. Faster application startup time. The terminal is much more usable for full screen VT100 and curses style sessions, such as vi, mapci, etc. Added support for the BCM (Business Communication Manager) device type, which is interesting because it provides both scripting capability and a command-line interface for a product that does not actually have a native command-line interface. This allows for automated data collection from BCM products, which is otherwise not easily done. Added the new device type ASG5100. The up/down arrow keys at the CLI*manager command prompt now show a pop-up window that lets users navigate more easily through their recent commands. The pop-up can be disabled and enabled from a checkbox in the Tools -> Options -> General window. When multiple instances of CLI*manager are launched on the same machine, they can added as new tabs in the same CLI*manager window. This option can be enabled and disabled in the Tools -> Options -> Startup window. Added a "Connect from Server" feature that can be used to find login information from a centralized Address Server. This is a prototype feature that requires a specialized server, currently only available within the Nortel intranet. The search feature (Ctrl-S) now opens a search area at the bottom of the window, rather than a new pop-up window. This makes searching through terminal output much more accessible and easy to use. The title of the CLI*manager window now includes information about the active connection, which may also be useful in the taskbar, etc. Added a checkbox to Tools -> Options -> Log labeled "Dump all output to debug log files". This option is disabled by default, but it can be useful when collecting logs for troubleshooting CLI*manager problems. Added a setting in Tools -> Options -> Watch that lets the user adjust the number of WATCH graph samples that will be shown before scrolling. Added features to allow CLI*manager to be integrated into ESM.

Appendix B: Plug-ins
The Plug-in feature allows users to write their own add-ons to CLI*manager. A plug-in can be as simple as an enhanced version of a batch job (issuing commands, parsing results, etc), or they can range up to full-featured add-ons with GUIs of their own. This section describes basic plug-in usage, and contains Java API documentation necessary for writing a CLI*manager plug-in. Writing a Plug-in Getting Plug-in Details Plug-in API Interface Plugin Class PluginControl Previous Section: Appendix A: Release Notes

Writing a Plug-in
Plugins must be written in Java, and they must implement a specific interface. When CLI*manager starts up it searches its "Plugin" subdirectory for ".class" file that implement the Plugin interface (which is specified in "Classes\Plugin.class"). All matching classes are treated as plugins, and added to the CLI*manager interface as specified by the command and onMenu static fields. If the onMenu field is true then an item is added to the "Plugin" menu, which is visible only if at least one plug-in menu item exists. For more detailed information on the Java classes and interfaces used by Plugins, see the Plugin API. Note that, when plugins attempt to issue switch commands, they are subject to the same "Script Restrictions" that can be specified for Batch Jobs. Related Links: Interface Plugin Class PluginControl

Getting Plug-in Details

To view details about available plugins, use the "Plug-in Control" item in the Tools menu. From this window you can see details about each plug-in as supplied by the plug-in's author. By clicking on the Enable and Disable buttons, you can control whether or not the plug-in is allowed to run. If a plug-in is disabled, its "command" is ignored, and it is removed from the Plug-in menu.

Related Links: Interface Plugin Class PluginControl

Interface Plugin
public interface Plugin The Plugin interface specifies a set of fields and methods that are required by all CLI*manager plugin classes. It consists of a number of static fields that can be overridden by user-defined plugin classes, and one start() method that is called when the user runs the plugin. A simple plugin looks something like this:
public class Hello extends Object implements Plugin { // Creates new Hello public Hello() { } // Plugin details public static final public static final public static final public static final public static final String String String String String title = "Hello World"; author = "Brett Sinclair"; version = "1.0"; description = "An example CLI*manager plugin."; command = "hello";

public void start(PluginControl control, String args) { // Turn off echoing of command responses control.setEcho(false); // Print a message to the CLI window control.println("Hello world!"); // If any devices have been selected, display trunk remotes if (control.getSelectedNodeCount() > 0) { // Send the command control.send("d trk/* remote"); // Print the response control.println("Trunks:"); control.println(control.getLastResponse()); } else control.println("No devices are currently selected."); }

This example specifies the title, author, version, and description for the plugin, which will be available to users in the "Plugin Control" menu item of the CLI*manager GUI. Since the command field is set to "hello", users will be able to start the plugin by typing "hello" from the CLI*manager command-line. The start(PluginControl, java.lang.String) method simply uses the supplied PluginControl object to display trunk information for connected devices. See Also:
PluginControl

Field Summary
static java.lang.String

author The author of the plugin. static java.lang.String command The command for the plugin. static java.lang.String description

A description of the plugin. static boolean onMenu Specifies whether this plugin should be added to the "Plugin" menu. static java.lang.String title The title of the plugin. static java.lang.String version The version of the plugin.

Method Summary void start(PluginControl control, java.lang.String args) This method is called by the CLI*manager core whenever the user issues the plugin's command , or selects it from the CLI*manager GUI's "Plugin" menu (if onMenu is true ). void runScript (java.lang.String resource) Runs the specified script, which can be a filename or URL, and returns true if the script completed successfully.

Field Detail

title
public static final java.lang.String title

The title of the plugin. This field is provided to the user for information purposes. Also, the title is used as the text for the plugin's menu item in the CLI*manager GUI if the onMenu field is set to true .

command
public static final java.lang.String command

The command for the plugin. This is a command that users can type on the CLI*manager command-line to start the plugin.

author
public static final java.lang.String author

The author of the plugin. This field is reported to the user for information purposes only.

version
public static final java.lang.String version

The version of the plugin. This field is reported to the user for information purposes only.

description
public static final java.lang.String description

A description of the plugin. This field is reported to the user in a scrollable text area for information purposes only.

onMenu
public static final boolean onMenu

Specifies whether this plugin should be added to the "Plugin" menu. If this field is true , the plugin will be added to the "Plugin" menu in the CLI*manager GUI, with the title field as its text. Method Detail

start
public void start (PluginControl control, java.lang.String args)

This method is called by the CLI*manager core whenever the user issues the plugin's command, or selects it from the CLI*manager GUI's "Plugin" menu (if onMenu is true ). Parameters:
control - A PluginControl object, provided by the CLI*manager core. This object can be used to issue CLI commands and to take control of the CLI*manager session.

- The arguments passed to the plugin from the CLI*manager command-line. This string contains the entire command-line after the command's following space. If the user starts the plugin from a menu item, args will be an empty string ("").
args

Class PluginControl
java.lang.Object | +--PluginControl

public class PluginControl extends java.lang.Object The PluginControl class provides a set of simple methods for interfacing between CLI*manager and usercreated Plugin classes. PluginControl objects are created by internal CLI*manager methods (they should not be created by plugins themselves), and passed to the plugin through the start(PluginControl, String) method in the Plugin interface. See Also:
Plugin

Constructor Summary PluginControl(Controller parent) Creates a new PluginControl object for communication between plugins and CLI*manager core methods.

Method Summary
java.lang.String int java.lang.String[] java.lang.Object[]

java.lang.Object[]

java.lang.Object[]

java.lang.String

java.lang.String

getLastResponse () Get the response from the last command issued by the send() method. getSelectedNodeCount () Get the number of devices that are currently selected. getSelectedNodes() Get the names of all devices that are currently selected. getTableAttributes () Get the attribute names from the last displayed table, in the order they were shown. getTableComponents() Get the component names from the last displayed table, in the order they were shown. getTableNodeNames () Get the nodenames from the last displayed table, in the order they were shown. getTableValue (int requestedComponent, int requestedAttribute) Get a value from the last CLI table, based on a specified component and attribute number. getTableValue (int requestedComponent,
java.lang.String requestedAttribute)

Get a value from the last CLI table, based on a specified component number and attribute name.

void void void void void void

print(java.lang.String s) Print a string to the CLI window. println() Print a newline to the CLI window. println(java.lang.String s) Print a string to the CLI window, terminated with a newline. runScript (java.lang.String resource) Runs a script found in the specified resource (a filename or a URL). send (java.lang.String command) Send a command to the CLI window, and wait for the response. setEcho (boolean b) Enable or disable the printing of command output to the CLI window.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PluginControl
public PluginControl (Controller parent)

Creates a new PluginControl object for communication between plugins and CLI*manager core methods. PluginControl objects should not be created by the plugins themselves, but only by internal CLI*manager methods. Parameters:
parent

- The internal CLI*manager control object.

Method Detail

print
public void print (java.lang.String s)

Print a string to the CLI window. Parameters:

s

- The string to print.

println
public void println (java.lang.String s)

Print a string to the CLI window, terminated with a newline.

Parameters:
s

- The string to print.

println
public void println ()

Print a newline to the CLI window.

setEcho
public void setEcho (boolean b)

Enable or disable the printing of command output to the CLI window. If true then output will be sent to the CLI window. If false then output will be hidden from the user. Parameters:
b

- True if echo should be enabled or false if it should be disabled.

send
public void send (java.lang.String command)

Send a command to the CLI window, and wait for the response. The command will be issued as if the user typed it into the CLI window and pressed the Enter key. Responses from the command will be accessible through the getLastResponse method, and possibly through getTable...() methods like getTableValue . The response will also be printed into the CLI window unless echo has been disabled by setEcho. Note that certain commands may be "restricted" by the user as a security measure. If a restricted command is issued by a plugin, the user will be asked if they want to accept or deny the command. If the command is rejected then the only response from the command will be a "Denied access to restricted script command" message. Restricted commands are typically destructive ones, like "restart", "activate" and "lock". However, users can define any command to be restricted to protect themselves from unexpected plugin behavior. Parameters:
command

- The command to be sent.

getLastResponse
public java.lang.String getLastResponse ()

Get the response from the last command issued by the send() method. The String returned will hold output from the command, exactly as it would have been displayed in the CLI window. This means that output will be formatted into tables (if applicable), and output from all connected switches will be concatenated into a single response.

Returns: the response from the last command.

getSelectedNodes
public java.lang.String[] getSelectedNodes()

Get the names of all devices that are currently selected. devices are "selected" if they were specified in the last EM command, and were connected successfully. Returns: an array of strings containing the names of selected devices.

getSelectedNodeCount
public int getSelectedNodeCount ()

Get the number of devices that are currently selected. devices are "selected" if they were specified in the last EM command, and were connected successfully. Returns: the number of selected devices.

getTableValue
public java.lang.String getTableValue (int requestedComponent, int requestedAttribute)

Get a value from the last CLI table, based on a specified component and attribute number. If the specified component or attribute number is not found, a null value is returned. Parameters:
requestedComponent requestedAttribute

- The component number, starting at 0. - The attribute number, starting at 0.

Returns: a String containing the value from the specified cell, or null if the cell does not exist.

getTableValue
public java.lang.String getTableValue (int requestedComponent, java.lang.String requestedAttribute)

Get a value from the last CLI table, based on a specified component number and attribute name. The

requestedAttribute name must be an exact match with an attribute in the last table. If the specified component number or attribute name is not found, a null value is returned. Parameters:
requestedComponent requestedAttribute

- The component number, starting at 0. - The exact (and case sensitive) attribute name.

Returns: a String containing the value from the specified cell, or null if the cell does not exist.

getTableNodeNames
public java.lang.Object[] getTableNodeNames ()

Get the device names from the last displayed table, in the order they were shown. The number of device names in a table will always be the same as the number of components returned by getTableComponents() Returns: an array of String Objects containing the last table's device names.

getTableAttributes
public java.lang.Object[] getTableAttributes ()

Get the attribute names from the last displayed table, in the order they were shown. Returns: an array of String Objects containing the last table's device names.

getTableComponents
public java.lang.Object[] getTableComponents ()

Get the component names from the last displayed table, in the order they were shown. The number of components in a table will always be the same as the number of device names returned by
getTableNodeNames()

Returns: an array of String Objects containing the last table's device names.

There are a few observations to note about using the modem pool. The "Type" selected does not matter as far as connecting to the device. When CLI*manager connects to a device using the modem pool, it connects using "Dumb Terminal" mode no matter what "Type" has been selected in the Connect window. The "User Name" and "Password" fields can be left blank since they are not used when connecting in "Dumb Terminal" mode. Also, some proxies such as CMAP and CMAP_NARS still require the user to select a baud rate and parity even though they are not required for an X25 connection. The "Apply" button will not be enabled until the user enters data in these fields. This is a bug which will be rectified in a future release of CLI*manager, but users should be aware that this problem exists.

Connecting to a Device
1. Before connecting using a modem pool proxy it is recommended to open the "Console" window. This makes it easier for the user to debug a connection that they are having difficulty establishing since modem connections are notoriously unreliable and sometimes require trial and error to establish. The "Console" can be found under View -> Console and it is also a button on the main toolbar. 2. Connect to the modem pool device as you would connect to any other device in an address book. Depending on which modem pool proxy you have selected you may be prompted for your global ID and Norpass as shown in the example below. 3. As the proxy is connecting the user will be provided with status messages as to how the connection is

4. 5. 6. 7.

progressing. The console window should be referenced to debug any problems that may occur. If the connection is successfully established the user should see a "Starting Dumb Terminal mode" message. At this point a break signal has to be manually sent to the remote device to receive a login prompt. This can be done with a convenient ctrl-b keyboard shortcut or by selecting the "Send Break" item from the "Connect" menu. If the break is received from the remote modem a ? should appear at which point the user should type "login" in the terminal. The user should then manually go through the native login prompts to access the device. Once logged in the user can then either stay in "Dumb Terminal" mode or morph to the desired CLI*manager device type using the morph menu on the main toolbar where it currently says "Dumb Terminal".

Below is an example of what a user should expect when connecting using the modem pool.

NARS Database Search

From the Connect window, when "Modem Pool" is selected, the button beside the "Phone Number" field allows users look up information in the NARS database which they can then use in the Connect window. Below is an example of a NARS look up where only the first few letters of a CLLI are known.

The above query returned several records whose CLLIs start with the letters "CHTN". Clicking on a single record then retrieves the details such as modem phone numbers and contact information for a specific CLLI. Clicking on the "OK" button will enter the selected phone number, CLLI and short CLLI into the "Phone Number", "CLLI" and "Site ID" fields respectively in the Connect window. MSAT users can use their old USER.prop file to prefill the CLLI table with all the CLLIs that they previously used in MSAT. Simply copy the USER.prop file to the "Data" directory found under your CLI*manager installation directory. For example in Microsoft Windows, most users typically have CLI*manager installed under C:\Program Files\CLImanager in which case the USER.prop file should be copied to C:\Program File\CLImanager\Data\USER.prop.

Modem Proxy Configuration

Most users should not need to read this section since the Nortel Modem Pool proxies should be configured and updated automatically. This section is intended for advanced users who need to modify or debug their modem pool proxies. All the required proxy scripts and configuration files are found in the CLI*manager installation directory under "Proxies". Currently as of this writing there are 7 files required.. cmap.txt cmap_ftran.txt cmap_icmap.txt cmap_nars.txt ma_ottawa_modempool.txt nortel_modempool.txt nortel_modempools.prx

The files ending in ".txt" are JavaScripts specifically designed to navigate through the prompts of a Nortel modem or X25 server. Some of the scripts even prompt the user for input such as their global ID and Norpass. The scripts will not be discussed in detail here since individuals can analyze the scripts themselves. Needless to say anyone can modify these scripts if, for example, a new modem server deployed by Nortel has a different AT command set and menu system for configuring a modem. For more information about writing scripts and proxies, see Related Links below. The nortel_modempools.prx file requires some explanation however. This file is an XML document that mainly tells CLI*manager how to connect to a specific modem server and what script to execute to automatically configure the modem. Below is an example of a proxy record from this file.
<proxy name ="MA-OTTAWA" method="9" scriptfile ="ma_ottawa_modempool.txt" modempool ="true"> <argument label ="IP Address" variable="IP_ADDRESS" value ="acarr001.ca.nortel.com" overwrite ="true"/> <argument label ="Port" variable="PORT" value ="6000" overwrite ="true"/> </proxy>

A few of the important tags from the above example are explained: name - This tag is what appears in the "Modem Pool" pulldown list in the Connect window. scriptfile - This the script that is called when a user selects this proxy in the Connect window argument - Used to define variables and assign them values. The variables can then be accessed within the proxy script defined by the scriptfile tag. So it is fairly easy to add or change a modem pool proxy and even add new arguments which can be passed to a proxy script. Related Links: Connecting to Devices Available Device Types Proxy Scripts Configuring Proxies

The Connect Terminal Window

To open the Connect Terminal window, choose "Connect Dumb Terminal..." from the Connect menu, or press the " " Connect button in the toolbar. This window lets you connect to any device in Dumb Terminal mode using Telnet, SSH, Rlogin or a Modem Pool script. In Dumb Terminal mode, many CLI*manager features are disabled. Once connected, you can re-enable these features by choosing a device type in the toolbar's drop-down list of managed device types.

The Address field and Phone Number fields provide drop-down lists of recent dumb-terminal connections. When these addresses and phone numbers are chosen, their previous configurations are recalled. Related Links: Connecting to Devices

General Commands
*, +, and - Commands ** Command ALLTABS BATCH CLEAR CLIMORE CLITABLES COMMANDLOG CSVLOG HANGUP HIDETEXT HISTORY LOGTOFILE LOGOUT LOGOUTALL RELOGIN SCP SCRIPT SFTP SSH TELNET UNLOCKCLI WATCH *, +, and - Commands Type "* <device names>" to connect to the specified devices. "+ <device names>" connects to the specified devices and adds them to the prompt. "- <device names>" removes them from the prompt. See The * Command for more details. (The old "EM", "EM+", and "EM-" commands are also accepted for backward compatibility with earlier versions of CLI*manager.) See Also: Connecting to Devices ** <devicename> [[,] <devicename>] This command connects to devices like the "*" command, but in multiple CLI Tabs. device names for each tab are separated by spaces, and names to be connected together in the same tab are separated by commas. For example, the command below would connect to device1 in the first tab, both device2 and device3 in a second tab, and device4 in a third tab.
** device1 device2,device3 device4

ALLTABS <command> This command runs a specified command on all open CLI Tabs. For example, the command below would start a watch session in all open tabs.
alltabs watch atmif/* stats/*

BATCH [options] "<filename>" [<param1> [<param2] ...]

This command starts the specified Batch Job. The <filename> can be a local file or URL. Parameters after the filename will be passed to the batch job as prompt responses in the order that they appear in the batch file. Available Options: -Datafile -FTP -Host -Username -Password CLEAR Clears the screen. This command is only available when no connection is active, to prevent conflicts with native syntax. CLIMORE [<ON>|<OFF>] This command turns the "prompt for more during long command responses" functionality on or off. This option is also available in the Tools menu under Options.
> climore Syntax for command: CLIMORE [<ON>|<OFF>] Prompt for "More" during long command responses is now DISABLED.

specifies a tab-delimited data file or URL for job parameters gets the batch file from a predefined FTP profile specifies an FTP host for downloading a remote batch job specifies an FTP username specifies an FTP password

CLITABLES [<ON>|<OFF>] This command turns CLI Tables on and off.

> clitables Syntax for command: CLITABLES [<ON>|<OFF>] CLI Tables are now ON.

COMMANDLOG This is a specialized Shasta-only command history feature, which is available from the Tools menu and from the command "commandlog". This feature displays the device's command history in a tabular format, which you can sort and filter as needed. Login/logout events are also tracked and added into the log. CSVLOG <file | OFF> Logs results from all CLI Table commands to a CSV file. CSV is a comma-separated file format that can be loaded directly into most spreadsheet applications. HANGUP Drops the connection to all selected devices without logging out. This is sometimes necessary, such as immediately after a reboot command - which would cause CLI*manager to lose contact with the switch anyway.

HIDETEXT <text> This command tells CLI*manager to hide the specified text wherever it appears in the CLI window or the console. This can be useful for hiding plain-text passwords that might appear when running some commands. HISTORY The HISTORY command opens the History window. LOGTOFILE [<options>] [<filename>] [OFF] Logs the CLI session to a file. With no parameters, the command opens a user dialog to ask for the filename, which the user can cancel if they want to. When logging the whole session to file, the <filename> parameter specifies the file name. When logging each device to its own file, the <filename> parameter specifies a suffix to include in each file name. The OFF argument turns logging off. Available Options: -Nodefiles -Tables -Append -Datestamp -Path logs responses from each device in its own file Uses CLI Tables in per-device log files, instead of native formatting. appends to log files if they exist, instead of overwriting them adds a datestamp to log filenames, and opens a new file for each day specifies a path to use for storing log files

LOGOUT [device1 [device2 ...]] When used with no paramters, the LOGOUT command logs out from all of the devices that are currently shown in your prompt. You can also specify a list of certain devices that should be logged out, so that you can remain logged into other devices in your prompt. See Logging Out for more information. LOGOUTALL Use the LOGOUTALL command to logout from all devices not just the ones that are currently shown in your prompt. RELOGIN [<user> [<password>]] Use the RELOGIN command to logout from all selected devices (the ones shown in your prompt) and log back in again with a different user. This command is equivalent to the Login Again As menu item. SCP <fromfile> <tofile> The SCP (secure copy) is only available from the CLI*manager command-line when no devices are connected. One of <fromfile> or <tofile> must be a remote file with the format: "user@hostname:filename" copies a file from any host "nodename:filename" copies a file from a node defined in an address book

SCRIPT [-debug] "<filename>" This command starts the specified CLI*script file or Batch Job. If a specific path is not given then CLI*manager searches the Script, Batch, and local directories for matching files. It also checks for several possible file extensions (.js, .txt, .batch, etc.) while looking for a match. The -debug option opens the CLI*script Debugger window for the specified file. SFTP [<nodename>] | [<user>@<host>] This Secure FTP command is only available from the CLI*manager command-line when no devices are connected. Once connected, type "help" from the SFTP shell for a list of available commands. The "nodename" format specifies the name of a device found in an address book, and uses its stored login settings. The "user@host" format connects to any host, and prompts the user for the password. See also: The FTP/SFTP Window. SSH [-proxy "<proxyname>"] [-l username] <address> [<port>] Connects to the specified address using Secure Shell (SSH), using the specified username. This command is only available when no other devices are connected. NOTE: In this mode, many of CLI*manager's enhanced features are disabled. Some device types can be set up to use SSH connections, with a setting in the Connect Window. If available it is usually preferable to use a defined CLI*manager device type instead of this generic SSH mode. Or use the Device Type button to convert the generic SSH session to a known device type. TELNET [-proxy "<proxyname>"] <address> [<port>] If you issue a TELNET command in CLI*manager when no devices have been selected, a "plain telnet" session is opened to the specified address. In this mode, many of CLI*manager's enhanced features are disabled. NOTE: In this mode, many of CLI*manager's enhanced features are disabled. If possible it is usually preferable to use a defined CLI*manager device type through the Connect Window instead of this generic telnet mode. Or use the Device Type button to convert the generic telnet session to a known device type. UNLOCKCLI <password> If you are running CLI*manager in "Multi-User, Password Protected" mode then your settings are locked with a CLI*manager password. With this mode, if you want to run scripts from a cron job or the command-line with the CLIBATCH command, the script will need to know your CLI*manager password to access your Address Books. To accomplish this, use the "UNLOCKCLI <password>" command at the beginning of your script. If your script contains an UNLOCKCLI command, you should protect the script with standard file permissions for your operating system. Otherwise, other users on your system could learn your CLI*manager password. WATCH "<command1>","command2>", ... Use "watch <command>" to start Watch Mode with the specified command or component.

"-" Notation: Ranges of Components

Simple Ranges Multiple Ranges Ranges of "." Separated Values Range Steps Separated Ranges Range Command Blocks Ranges of IP Addresses Leading Zeros Stopping Ranges Related Links: Enhanced Notations "+" Notation: Non-sequential Components

Simple Ranges
You can specify ranges of numeric components in your commands. This is useful for components like voice services and frame relay services, which are typically provisioned in large contiguous groups.

Related Links: "-" Notation: Ranges of Components Enhanced Notations

Multiple Ranges
Normally, whenever two ranges are specified by the same command, both ranges must span the same number of values, and they are assumed to correlate with each other. In the example below vs/201 would be linked with vs/501, vs/202 with vs/502, etc.

You can also use multiple ranges to span all permutations of all ranges in the command, instead of correlating them with each other. To do this, use a "-rangeall" option with your command. The example below would add ports 0, 1 and 2 on both Lp/9 and 10.

Related Links: "-" Notation: Ranges of Components Enhanced Notations

Ranges of "." Separated Values

Ranges can also be used to specify ranges of "." separated values, such as consecutive VCI and DLCI values, using the syntax shown below.

Related Links: "-" Notation: Ranges of Components Enhanced Notations

Range Steps
Normally, ranges increment in steps of 1, but different steps can be specified after an "s" character (short for "step). The simple example below displays every fifth voice service from 205 to 220.

Related Links: "-" Notation: Ranges of Components Enhanced Notations

Separated Ranges
Ranges can be surrounded by round brackets to separate them from the rest of the command, as shown below.

Related Links: "-" Notation: Ranges of Components Enhanced Notations

Range Command Blocks

Range commands that end with "{" symbols identify the start of a block of commands to be run for each instance in the range. Further commands can be entered, and the range will not be run until the closing "}" is typed. For example, the block below would run the "encapsulation" and "no shut" commands for every DLCI in the range from 602 to 800.

For commands within the range block, the <range> variable can be used to insert the corresponding index for the command block. The range block below runs from 2 to 200, and for each instance of the range the to-tunnel and from-tunnel would be set with the corresponding index in the range.

For range blocks with multiple ranges, special <range> variables can be used to specify which range to use. The "range" variable name can include a number at the end, as in "<range1>", "<range2>", etc. Range 1 is the first range in the range command; range 2 is the second, etc. The range block below runs both from 2 to 200, and 602 to 800. The <range2> variable would be replaced with corresponding instances from the 602800 range. If no range number is specified, the first range is used, and so <range> is the same as <range1>.

You can abort a range block in progress by pressing entering a blank line before the closing "}" symbol.

Related Links: "-" Notation: Ranges of Components Enhanced Notations

Ranges of IP Addresses
IP addresses are a special case when using ranges, because the dash character ("-") is sometimes used to specify port numbers, like "47.48.128.70-162". CLI*manager normally ignores IP addresses when it is looking for ranges, in order to avoid expanding this example to "47.48.128.70", "47.48.128.71", all the way up to "47.48.128.162". If you want to specify a range of IP addresses, use a double-dash notation ("--"), as shown below.

Related Links: "-" Notation: Ranges of Components Enhanced Notations

Leading Zeros in Ranges

If you type a leading zero at the beginning of the range, zeros will be added automatically for all range instances up to the number of digits in the range endpoint. For example, the command below would delete vrf "806_9", "807_09", up to "810_9".
del rtr/753 vrf/8(06-10)_9

Without the leading zero in (06-10), the command above would delete vrf "86_9", "87_9" up to "810_9". Related Links: "-" Notation: Ranges of Components Enhanced Notations

Stopping Ranges
Ranges are automatically stopped if certain errors are encountered, such as syntax errors and "you must be in provisioning..." errors. If you want the range to continue even if errors are received, you can use the "nostop" option.

Ranges can also be stopped manually by pressing Ctrl-C while the range is in progress.

Related Links: "-" Notation: Ranges of Components Enhanced Notations

Table Summarization
This feature summarizes identical components by combining them into ranges, where possible. For components to be combined, they must have identical attributes, they must be on the same device, and they must have consecutive instance numbers. In the example below, 5 voice services were displayed, but CLI*manager summarizes them into two ranges for easy comparison. All of the voice services from 301 to 304 are the same, and 305 is different.

The table summarization feature can be turned off for any command by using the "-nosum" option, as in "d -p -nosum vs/1201-1223 framer". It can also be turned off with a checkbox in the Options dialog (in the Tools menu). Related Links: CLI Tables Command-Line Enhancements

CLI Table Options

For commands that are shown in tables, a variety new options are available to control the table and to generate statistics. New options to the "display" commands are shown below. These options can be specified either in the normal position (after the command's verb), or at the end of a command. -SAVE stores table results for future reference by the " -load " option. Saved tables will be kept for the number of days specified in the Options under "CLI Tables". loads previously saved results (from the "-save " option) and allows for comparison with current values via attribute highlighting, the "-diff ", "-same " and "-rate " options, etc. summarizes identical components by combining them into ranges, where possible disables table summarization for a command (see above) shows only attributes that are the same for all displayed components shows only attributes that are not the same for all displayed components shows the rate per second between the last two display commands shows the lowest rate per second since the table was first displayed shows the highest rate per second since the table was first displayed shows the average rate per second since the table was first displayed shows the lowest value since the table was first displayed shows the highest value since the table was first displayed shows the average value since the table was first displayed shows the total amount that the value has changed since it was first displayed shows the amount that the value has changed since the previous display command

-LOAD

-SUMmary -NOSUMmary -SAME -DIFFerent -RAte -MINRate -MAXRate -AVRate -MIN -MAX -AV -CHange -CHANGE1 or -CH1

-MULTiply <factor> multiplies all numerical values in the table by the specified factor, similar to the convert function in watch -FIND <string> displays only those components that have an attribute value containing the specified string. For example, the command "d trk/* -find busy" would display only those trunks that had an attribute with a value of "busy". Standard regular expressions can be used in <string>.

-After <n> shows <n> lines after each occurrence of the matching string, when used with the -find option above. -Before <n> shows <n> lines before each occurrence of the matching

string, when used with the -find option above. -NORMtable Related Links: CLI Tables Command-Line Enhancements displays the "normal" table that the device would display in its native format, without CLI*manager enhancements.

Address Book Commands

The commands below can be used to manage address books from the command-line or batch jobs. Note: Most of the functions provided by these commands are included in the ABIMPORT Utility, which can be run outside of CLI*manager from the command-line or a cron job, etc. If you are automating the import of address book information from external sources, the ABIMPORT Utility may be more suitable than the commands below. These functions are also available from the Address Books window. ABADDSERVER ABCLEAR ABCLEARSERVERS ABDOWNLOAD ABIMPORT ABLOAD ABUPLOAD ABSAVE ABREMOTE ABADDServer [<options>] This command attaches settings for CLI*servers to address books. This is useful for automatically deploying server configurations to all users of a common address book. Accepted options include: -n <name> -a <address> -po <port> -alarms -collab ABCLEAR This command clears all information (devices, maps, etc.) from the address book. ABCLEARSERVERS This command removes all CLI*servers that may be attached to the address book. ABDOWNLOAD [[<options>] [<filename>]] This command downloads address book updates from an FTP server. If FTP parameters have already been defined for the book by ABREMOTE, then the options do not need to be specified. Accepted options include: specifies the server name specifies the server address specifies the server port enables a alarms from the server enables a collaboration directory for the server

-p <password> specifies the server password

-h <address> -u <user> -p <password>

specifies the FTP host specifies the FTP user specifies the FTP password

-bookp <bookpassword> specifies the book password ABIMPORT [<options>] <filename> This command imports address from a plain text file. Each line in the file can have the following fields, in the order below. The "site" and "region" fields are optional. The entries should be tab-delimited.
devicename user password address devicetype site region

For a list of accepted values in the devicetype column, use the ABIMPORT Utility and type "abimport -typenames". Accepted options to the ABIMPORT command are: -book -clear -proxy <proxy> -proxyhost <addr> -proxyuser <user> -ftp <profile> -h <address> -u <user> -p <password> imports into the specified book clears existing devices before importing sets the proxy name for all imported entries sets the proxy host for all imported entries sets the proxy user for all imported entries gets the import file from a defined FTP profile specifies an FTP host for the import file specifies an FTP user for the import file specifies an FTP password for the import file

-proxypassword <pw> sets the proxy password for all imported entries

ABLOAD [-password <password>] [<filename>] This command loads the specified address book into a temporary buffer, for modification by other address book commands described in this section. ABUPLOAD [<options>] [<filename>] This command uploads the address book to an FTP server. If FTP parameters have already been defined for the book by ABREMOTE, then the options do not need to be specified. Accepted options are: -h <address> -u <user> -p <password> specifies the FTP host specifies the FTP user specifies the FTP password

-bookp <bookpassword> specifies the book password ABSAVE [-password <password>] [<filename>]

This command saves the specified address book, usually after it has been changed by other commands in this section. ABREMOTE This command defines FTP parameters for upload and download. Accepted options are: -h <address> -u <user> -p <password> specifies the FTP host specifies the FTP user specifies the FTP password

-bookp <bookpassword> specifies the book password

"&" Notation: Commands for Each Device

When components have different instance numbers on each device, and you want to issue commands against them at the same time, you can use a special "&" notation. The order in which you specify the component numbers depends on the order in which the device names are shown in the prompt. A Simple "&" Example IP Addresses

A Simple "&" Example

In the example below, the "100" is used for HULK and "70" for BATMAN, following their order in the prompt.

IP Addresses
This syntax can also be used for specifying different IP addresses for each device. Ampersands can separate whole IP addresses or individual bytes in an address, as shown below.

Related Links: Enhanced Notations Commands to Multiple devices

MSS Commands
ACTivate Provisioning ALARMS CHACT DISPLAY ROUTE SAVECOMPonent SCOM ACTivate Provisioning On MSS, the "activate" command works the way it usually does, except that it automatically confirms provisioning after the activation is complete. This is useful because it prevents accidental switch reloads from users who forget to issue "confirm" commands. It is also safe, because if the switch became inaccessible because of the activation CLI*manager would not be able to issue the confirm command, and the switch would automatically roll back after the regular timeout. ALARMS [ON|OFF|CLION|CLIOFF] The ON and OFF settings are used to turn alarms on and off for the selected MSS devices. This is the same as entering commands like "set nmis telnet session/<x> datastreams ~ala", except that the session number is automatically filled in for you, and it requires less typing. The CLION and CLIOFF settings enable and disable the displaying of alarms in the main CLI window. This has the same effect as the "Show Alarms in CLI window" preference shown in the Options window. CHACT The CHACT command is a simple short-form MSS command for "check", "activate" and "confirm". Use it when you are confident that the check will pass, to quickly activate provisioning changes. DISPLAY The DISPLAY command on MSS formats results into CLI Tables, which provides a number of useful features. Components can be shown side-by-side for easy comparison. Statistics can be shown instead of raw values by using special options. When a display command is run more than once, attribute values that have changed are highlighted in reverse type. Special notations (# and $) can be used to reference cells and values in tables. These enhancements can be turned off by un-checking "CLI Tables" in the General tab of the Options window. ROUTE [vr/x] <address> The ROUTE command searches MSS forwarding tables for specific routes, based on both IP address and subnet mask. For example, "route 1.2.3.4" would display the forwarding table entry with the best match for that address. Vr/1 is the default, but you can specify others if necessary as in "route vr/2 1.2.3.4". Hostnames can also be used, as in "route www.nortel.com". SAVECOMPonent [options] -Comp "<component>" -File "<filename>"

The SAVECOMP command inspects existing components on Passport MSS devices, and generates a file with native CAS commands that could be used to rebuild those components with their current provisioning. This can also be useful for copying provisioning between devices. Available options include: -Append -Default -NOCache -NOSub appends to the file instead of overwriting turns on provisioning of default values turns off attribute type caching turns off collection of subcomponents

-Link <comp> follows links to components containing <comp> SCOM This is a short-form command that both Saves and COMmits provisioning on a MSS.

BCM Commands
SHOW LIST INVOKE SET HELP or ? EXIT show <Class> [[<Property>=<Value>] ...] [<Property> ...] The SHOW command shows specified properties, or all properties, for matching class instances. Matches can be filtered by specifying any number of name=value pairs. CLI*scripts can access results from the last show command by using the cimresult() function. Example:
BCM> show BCM_Account Name=1004 BCM_Account SystemCreationClassName = BCM_System SystemName = BCM CreationClassName = BCM_Account Name = 1004 CreatedBy = multitel Created = 20080825122735.000000-300 Modified = 20080825122752.000000-300 ModifiedBy = multitel ...

list <Class> [[<Property>=<Value>] ...] The LIST command lists matching class instances, along with uniquely identifying key properties. Matches can be filtered by specifying any number of name=value pairs. CLI*scripts can access results from the last list command by using the cimresult() function. Example:
BCM> list BCM_Account BCM_Account Name=1001 BCM_Account Name=1002 BCM_Account Name=1003 BCM_Account Name=1004 BCM_Account Name=1005

invoke <Class> <Method> [[<Property>=<Value>] ...] [where [<Property>=<Value>] ...] The INVOKE command invokes a Method on instances of the specified Class, with any number of name=value pairs passed as parameters. Class instances where the method is invoked can be filtered with any number of WHERE name=value conditions. Example:
BCM> invoke BCM_ViewMessageLog GetLogCounts countAcked=true BCM_ViewMessageLog Return value: 0 critical = 2 major = 0 minor = 1 warning = 6 information = 91

set <Class> <Property> <Value> [where [<Property>=<Value>] ...] The SET command sets a single Property in matching Classes to a new value. Class instances where the property is set can be filtered with any number of WHERE name=value conditions. Example:
BCM> set BCM_BackupRestoreService LogTransferAgent 5 BCM_BackupRestoreService LogTransferAgent changed from 5 to 5

help or ? Prints a summary of available BCM commands. exit Exits the current BCM session and returns to the CLI*manager prompt.

MAP Commands
The commands below can be used to create and manipulate Network Maps from the CLI*manager command-line or batch jobs. MAPIMPORT MAPSELECT MAPCOLLECT MAPSAVE MAPIMPORT [<options>] <filename> This command imports information about which devices should appear on which maps. Each line in the file should have one of the formats below, separated by tab characters. This allows you to import all details for generating network maps including maps, submaps, devices and links. This is useful for generating maps based on information from external sources such as databases, spreadsheets, etc.
map <name> [<parent>] device <name> <map> [<type> [<x> <y>]] link <type> <from> <fromlabel> <to> <tolabel> [<linklabel>] devicename mapname

Accepted options are: -clearmaps -cleardevices -ftp <profile> -h <address> -u <user> removes maps not found in the import file removes map devices not found in the import file gets the import file from a defined FTP profile specifies an FTP host for the import file specifies an FTP user for the import file

-p <password> specifies an FTP password for the import file MAPSELECT <name> This command switches the network map view to the specified map. For scripting purposes, this can be useful selecting specific maps before MAPCOLLECT and MAPSAVE commands. MAPCOLLECT <options> This command starts auto-discovery of the current map. Accepted options are: -selected -allmaps collects only the currently selected devices on the map collects all maps in the current address book

-alldevices collects all devices on the map

MAPSAVE <options> This command saves bitmap images of network maps.

Accepted options are: -all -user -ip -ethernet -trunk -atm -png -jpeg -map <map> -web Saves images for all maps in the current address book Saves the USER map view Saves the IP map view Saves the ETHERNET map view Saves the TRUNK map view Saves the ATM map view Saves with the PNG graphics format Saves with the JPEG graphics format Saves the specified map Generates web pages for each map

-weblink <prefix> Specifies the beginning of a URL (to which the devicename will be appended) to be accessed when users click on device icons in map web pages -d <directory> -f <filename> -ftp <profile> -h <address> -u <user> -p <password> Specifies a local directory for saving map images Specifies a filename for map images Specifies an FTP profile for saved images Specifies an FTP host for saved images Specifies an FTP user for saved images Specifies an FTP password for saved images

Optical Metro Commands

SWITCH RETURN SWITCH The SWITCH command is used to toggle between the TL1 and DEBUG ports on an Optical Metro device. Typing SWITCH on the CLI command line will send the native control signal to the terminal in the background. The control signal is typically a ctrl-d. SWITCH can be used in a CLI*manager SCRIPT to toggle between ports. This command is only applicable to the following device types: OM3000 series, OME series and CPL. RETURN The RETURN command is used to break from a remote telnet session on a optical metro device. Typing RETURN on the CLI command line will send the native control signal to the terminal in the background. The control signal is typically a ctrl-p for OME and CPL and a ctrl-e for OM3000. RETURN can be used in a CLI*manager SCRIPT to return from a remote telnet session. This command is only applicable to the following device types: OM3000 series, OME series and CPL.

"+" Notation: Non-sequential Components

You can also specify multiple, non-contiguous components by listing them separated by plus signs ("+"). This can be combined with ranges to quickly describe any combination of Passport components.

Related Links: Enhanced Notations "-" Notation: Ranges of Components

"#" Notation: Referencing Table Cells

After running a command that CLI*manager formats into a table (such as "display" on MSS), you can reference components and attributes by their position in the last table. For example, you can reference an attribute for a specific component by using a "#" along with both the component letter and the attribute number, like "#a2". Or you can reference a specific attribute on every displayed component by using just the attribute number, like "#2". This can be a powerful shorthand notation.

In the example above, CLI*manager would set the mainCard (in row 1) to "sh ca/1", and the logicalProcessorType (in row 3) to "sw lpt/atm".. Related Links: Enhanced Notations CLI Tables "$" Notation: Referencing Table Values

"$" Notation: Referencing Table Values

After running a command that CLI*manager formats into a table (such as "display" or "list" on MSS), you can reference table cell values by their names or prefixes. This save typing, and it can be useful in some cases for provisioning and batch file scripting. Values from DISPLAY tables Values from LIST tables Fields inside table values Separated table values

Values from DISPLAY Tables

In the example below the user displays the NS (Network Synchronization) component, and then uses "$" notation to display the primary reference.

Values from LIST Tables

This notation can also be used with tables from "list" commands. In the example below, "$" notation is used to display a listed component.

Fields Inside Table Values

Fields within table cells can also be referenced by specifying their field number with round brackets. After issuing the command below, a batch job could reference the NSAP address as "$1(5)". Fields are taken to be separated by spaces, commas and slashes.

Separated Table Values

Finally, "$" notation can be surrounded with round brackets to separate the attribute name from the rest of the command, as shown below.

Related Links:

"*" Notation: Enhanced Wildcards

Without CLI*manager, the standard MSS CAS syntax does not allow the use of wildcards ("*") with commands other than LIST and DISPLAY. CLI*manager fills in for this limitation automatically, so that wildcards can be used with other commands like SET, LOCK, DELETE, etc. Note that since this feature can make widespread changes, it should be used carefully.

Related Links: Enhanced Notations

CLI Table Example

CLI Tables enhance the native format from DISPLAY commands by arranging all components and attributes in a tabular format. Where possible, components are shown side-by-side for easy comparison. Attributes use numbers and components use letters to identify their positions in the table, which can be used with special "#" and "$" notations. If you display the same set of components more than once, changed attribute values are highlighted in reverse type (as shown below). A component count is shown below the table on the left, and the Passport's timestamp for the last command is shown in the bottom-right. Contextsensitive hyperlinks are shown above the table for components related to the ones shown.

Related Links: CLI Tables "#" Notation: Referencing Table Cells "$" Notation: Referencing Table Values MSS Hyperlinks The Table Viewer

CLI Table Statistics

When operational attributes are displayed repeatedly, Table Options can be used to generate statistics in the resulting table. In the example below, the "-rate" option is used to display the rate of change per second for all numerical attributes. Other options are available to show minimum and maximum rates, minimum and maximum values, and total change. (Note that this example places the option at the end of the command, which is acceptable only for CLI*manager options.)

Related Links: CLI Tables Command-Line Enhancements

Provisioning from a Table

In all Tables, rows and columns are indexed with letters and numbers that can be used to reference table cells. Components are indexed with letters, and attributes are indexed with numbers. Special CLI*manager notations like "#" and "$" notations can be used with SET commands to change a attribute values. Related Links: CLI Tables Command-Line Enhancements "#" Notation: Referencing Table Cells "$" Notation: Referencing Table Values

Comparing Table Attributes

The "-diff" and "-same" options can be used to filter which attributes are displayed in a table. If the "-diff" option is specified, only those attributes which are different for some components will be shown. Similarly, if the "-same" option is specified, only those attributes that are the same for all components will be shown. In the example below, the "-diff" option is used to show only the attributes that differ. All other attributes can be assumed to be identical.

Related Links: CLI Tables Command-Line Enhancements

Turning CLI Tables On and Off

In some cases you may want to disable CLI Tables - possibly because you prefer the native format, or you plan to process the results with another program. CLI Tables can be turned on and off either with the "CLI Tables" checkbox in the Options Window, or with the CLITABLES command. Related Links: CLI Tables Command-Line Enhancements

ScriptWindow Reference
The ScriptWindow object in CLI*script allows scripts to show customized graphical windows and update them during script execution. This can be useful for displaying script output, prompting the user for input, and building interactive windows that control the script. ScriptWindow objects are described in XML, using elements from a collection of available containers and graphical components. A Simple Example Creating ScriptWindow Objects XML Element Types Top-Level Window Types Containers Graphical Components Color Reference More ScriptWindow Examples Data Collection Example Dialog Example Wizard Example

A Simple Example
var xml = <window title="Test Window" width="300"> <form direction="north"> <statusfield runningcolor="green" label="Script Status"/> <timerfield type="script" label="Elapsed Time"/> <timerfield type="time" label="Current Time"/> </form> <resultpanel id="result1" height="100"/> </window>; var window = new ScriptWindow(xml); window.show(); pause(2); window.result1.addTextResult( "Sample", "This is sample output", "info"); pause(2); window.result1.addTextResult( "More Output", "More Output", "error"); pause(2); window.result1.addTextResult( "A Warning", "A Warning", "warning"); pause(4);

Creating ScriptWindow Objects

When ScriptWindow objects are created, an XML description of the window must be passed to the constructor using one of three formats: 1. an XML object 2. a String containing XML text 3. the name of a file that contains the XML. The file location is relative to the directory that contains the current script.

XML Element Types

The XML elements listed below are used to describe windows that can be shown by scripts. Top-level window types are elements that are normally at the root of the XML structure, and they decide the overall window behavior. Containers arrange the layout of their subcomponents based on different sets of rules. Graphical Components are fields and controls with which the user can interact. Top-Level Window Types Dialog Window Wizard Containers Box CardStack Arranges and stretches its subcomponents based on directions around its edges or in its center position Show only one of its subcomponents at a time. A window that always pauses the script until the window is closed, usually when the user presses one of the buttons at the bottom after providing input. A window that can either be updated by the script as it executes, or control script execution in response to window events like button presses. A window that leads the user through a series of predefined steps.

Flow Form Grid HBox VBox AddressBookField Button CheckBox DeviceChooser FileChooserField Label NumberSpinner PasswordField ProgressBar Radio ResultPanel SelectBox StatusField Table TableFilter TabPane TextArea TextField TimerField

Arranges subcomponents in a horizontal row using their normal sizes. Arranges labels along the left side, with subcomponents filling all remaining space to the right. Arranges subcomponents into a grid with a specific number of rows and columns. Arranges subcomponents in a horizontal row. Arranges subcomponents in a vertical column. A drop-down list that is pre-populated with the available address book names. A button that runs one of a set of predefined actions. A checkbox with an optional label. A panel that allows the user to select devices from address books. An editable text field with a button beside it that opens a file chooser window, which sets text in the field. A non-editable text label. A number field with buttons to increment and decrement its value. A text field with a hidden value. A progress bar that can be updated by the script as it executes. A radio button with an optional label. A panel that shows a list of bookmarks on the left side, and a text area on the right that shows text attached to the selected bookmark. A drop-down list of selectable items. A text field that shows the status of the script: running, stopped, or other script-defined text. A sortable, scrollable table with column headings A field that allows the user to filter a Table based on column values. A navigator that can contain multiple tabs, each with its own set of subcomponent containers or graphical components. A text area with multiple lines of text. A text field with a single line of text. A text field that can show several types of automatically updated timers: elapsed script time, current time, current date, and manual.

Graphical Components

DeviceChooserField A text field with a button that opens a separate window for choosing devices from address books.

Top Level Window Types

Top level window types normally appear at the root of the XML structure. All of these types can use the same containers and graphical components. By default all window types use a Box container to lay out their direct subcomponents. Dialog Window Wizard

Dialog
Dialog windows always pause the script until the window is closed, usually when the user presses one of the buttons at the bottom after providing input. The set of available buttons is specified by the buttons property. If any graphical components have their required property set to true then all dialog buttons other than "Cancel" will be automatically disabled until the user supplies non-empty values. XML Properties:
buttons = "ok | okcancel | yesno | yesnocancel | none" height = "<height in pixels>" resizable = "true | false" title = "<window title>" width = "<width in pixels>"

Methods:

- Opens the dialog window, pausing the script until the user closes the window. Returns the name of the button that the user pressed to close the window: "OK", "Cancel", "Yes", or "No". If the user closes the window without pressing one of the buttons, this method returns null .
show()

Example:
var xml = <dialog title="Test Dialog" resizable="false" buttons="okcancel"> <label text="This is a test dialog." halign="center"/> </dialog>; var dialog = new ScriptWindow(xml); println("Pressed button: "+dialog.show());

(See More Examples for a more complete dialog example.)

Window
The behavior of Window elements depends on the interactive property. If interactive is false then the script will continue execution while the window is open. This is useful for displaying output from the script, but the script itself cannot be controlled by window elements. If interactive is true then the main script thread will pause while the window is open, but window handlers will be able to run script actions in response to events like button presses. XML Properties:
alwaysontop = "true | false" interactive = "true | false" height = "<height in pixels>" resizable = "true | false" title = "<window title>" width = "<width in pixels>"

Methods:
hide() show()

- Closes the window. - Opens the window. If interactive is false then the script will continue executing after opening the window.

Example:
var xml = <window title="Test Window"> <label text="This is a test window."/> </window>; var window = new ScriptWindow(xml); window.show();

Wizard
Wizards are windows that lead the user through a series of predefined steps. Steps are listed on the left side of the window, and control buttons (Back, Next, Finish and Close) are shown along the bottom. Any number of subcomponents can be added to the wizard, each of which will appear as a separate step using a title from the element's label property. If any graphical components have their required property set to true then the Next button will be automatically disabled until the user supplies non-empty values. XML Properties:
height = "<height in pixels>" interactive = "true | false" resizable = "true | false" title = "<window title>" width = "<width in pixels>"

XML Properties for Subcomponents:

label = "<step title>"

Event Handlers:

back = "<script segment>" next = "<script segment>" finish = "<script segment>" close = "<script segment>"

Methods:
getCurrentStep() - Returns the current step number hide() - Closes the wizard. setNextAllowed(<stepnumber>, <true | false>)

in the wizard, starting at 1.

- Enables or disables the Next button for the specified step, usually because required information has not been provided or a device isn't in the required state. setStepSkipped(<stepnumber>, <true | false>) - Instructs the wizard to skip (or not skip) the specified step whenever the user reaches it by pressing the Next or Back buttons. This may be useful is a step is not required based on certain conditions. show() - Opens the wizard. If interactive is true (the default for wizards) then the script will pause until the window is closed. Example:
var xml = <wizard title="Test Wizard"> <box label="Test Wizard Step"> <label text="This is a test" direction="north"/> </box> <box label="Another Step"> <label text="Another test"/> </box> </wizard>; var window = new ScriptWindow(xml); window.show();

(See More Examples for a more complete wizard example.)

Containers
Containers have no visual representation of their own. Instead, they arrange the layout of their subcomponents based on sets of rules. More complex layouts can be created by placing containers within other containers. Box CardStack Flow Form Grid HBox VBox

Box
Box is a container that arranges and stretches its subcomponents in regions around its edges or in its center position. Subcomponents of Box containers can use the direction property to specify the region of the parent box in which they should be located. This is the default container for all top-level window types. XML Properties:
hgap = "<horizontal gap in pixels>" id = "<identifier name>" vgap = "<vertical gap in pixels>"

XML Properties for Subcomponents:

direction = "north | south | east | west | center"

Methods:
setBackground(color) - Sets the background setVisible(true | false) - Shows or hides

color. the container.

Example:

var xml = <window title="Test Box"> <box> <textfield direction="center" text="center" halign="center"/> <textfield direction="north" text="north"/ halign="center"> <textfield direction="south" text="south" halign="center"/> <textfield direction="east" text="east"/> <textfield direction="west" text="west"/> </box> </window>; var window = new ScriptWindow(xml); window.show();

CardStack
CardStack containers show only one of their subcomponents at a time. This can be useful for dynamically changing whole sections of the window. XML Properties:
id = "<identifier name>"

Methods:
selectCard(id)

- Specifies which card to show.

Example:
var xml = <window title="Test CardStack" interactive="true"> <selectbox id="sel" direction="north" change="switchCards()"> <item text="Form 1" value="form1"/> <item text="Form 2" value="form2"/> </selectbox> <cardstack id="cards"> <form id="form1"> <textfield text="field1" label="label1"/> <textfield text="field2" label="label2"/> </form> <form id="form2"> <textfield text="field3" label="label3"/> <textfield text="field4" label="label4"/> <textfield text="field5" label="label5"/> </form> </cardstack> </window>; var window = new ScriptWindow(xml); window.show(); function switchCards() { window.cards.selectCard( window.sel.getSelectedValue()); }

Flow
Flow containers arrange subcomponents in a horizontal row using their normal sizes, with optional alignment and gap. XML Properties:
align = "left | center | right" hgap = "<horizontal gap in pixels>" id = "<identifier name>" vgap = "<vertical gap in pixels>"

Methods:
setBackground(color) - Sets the background setVisible(true | false) - Shows or hides

color. the container.

Example:
var xml =

<window title="Test Flow"> <flow> <textfield text="field1"/> <textfield text="wide field2"/> <textfield text="f3"/> </flow> </window>; var window = new ScriptWindow(xml); window.show();

Form
Form containers arrange elements with labels shown along the left side, and with subcomponents filling all remaining space to the right. XML Properties:
id = "<identifier name>"

XML Properties for Subcomponents:

label = "<label shown beside the element>"

Methods:
setBackground(color) - Sets the background setVisible(true | false) - Shows or hides

color. the container.

Example:
var xml = <window title="Test HBox"> <form> <textfield text="field1" label="label1"/> <textfield text="field2" label="label2"/> <textfield text="field3" label="label3"/> </form> </window>; var window = new ScriptWindow(xml); window.show();

Grid
Grid containers arrange subcomponents into a regularly spaced rectangular grid. All rows have the same height, and all columns have the same width. XML Properties:
cols hgap id = rows vgap = "<number of columns>" = "<horizontal gap in pixels>" "<identifier name>" = "<number of rows>" = "<vertical gap in pixels>"

Methods:
setBackground(color) - Sets the background setVisible(true | false) - Shows or hides

color. the container.

Example:
var xml = <window title="Test HBox"> <grid rows="2" cols="3" vgap="15"> <label text="1,1"/> <label text="2,1"/> <label text="3,1"/> <label text="1,2"/> <label text="2,2"/> <label text="3,2"/> </grid> </window>; var window = new ScriptWindow(xml); window.show();

HBox
HBox is a container that arranges its subcomponents in a horizontal row. All subcomponents have the same height, but unlike the Grid container, subcomponents in an HBox can have different widths. XML Properties:
id = "<identifier name>"

Methods:
setBackground(color) - Sets the background setVisible(true | false) - Shows or hides

color. the container.

Example:
var xml = <window title="Test HBox"> <hbox> <label text="label"/> <textfield text="field1"/> <textfield text="field2"/> </hbox> </window>; var window = new ScriptWindow(xml); window.show();

VBox
VBox is a container that arranges its subcomponents in a vertical column. All subcomponents have the same width, but unlike the Grid container, subcomponents in a VBox can have different heights. XML Properties:
id = "<identifier name>"

Methods:
setBackground(color) - Sets the background setVisible(true | false) - Shows or hides

color. the container.

Example:
var xml = <window title="Test HBox"> <hbox> <label text="label"/> <textfield text="field1"/> <textfield text="field2"/> </hbox> </window>; var window = new ScriptWindow(xml); window.show();

Graphical Components
Graphical Components are fields and controls with which the user can interact. They are positioned and resized by parent containers. AddressBookField Button CheckBox DeviceChooser DeviceChooserField FileChooserField Label NumberSpinner PasswordField ProgressBar Radio ResultPanel SelectBox

StatusField Table TableFilter TabPane TextArea TextField TimerField

AddressBookField
AddressBookField is a drop-down list that is pre-populated with the names of available address books. XML Properties:
background = "<background color>" enabled = "true | false" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" width = "<width in pixels>"

Methods:
getSelectedValue() - Returns the value of the selected item. setVisible(true | false) - Shows or hides the component.

Example:
var xml = <dialog title="Test AddressBookField"> <addressbookfield id="book"/> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); println("Selected book: " + dialog.book.getSelectedValue());

Button
Button elements show a button that runs a script segment and/or a predefined action. Note that script segments can not be run by Window elements if their interactive property is not true . Script segments in the action property can include calls to user-defined functions. XML Properties:
background = "<background color>" foreground = "<foreground color>" height = "<height in pixels>" icon = "<image filename>" id = "<identifier name>" text = "<label text>" type = "close | savelog" width = "<width in pixels>"

Event Handlers:
action = "<script segment>"

Methods:
getText() - Returns the text shown inside the button. isEnabled() - Returns true if the button is enabled. setBackground(color) - Sets the background color of the button. setEnabled(true | false) - Enables or disables the button. setForeground(color) - Sets the foreground color of the button. setText(string) - Sets the text shown beside the button. setVisible(true | false) - Shows or hides the button.

Example 1: Predefined Action

var xml = <window title="Test Button 1"> <button type="savelog"/> </window>; var window = new ScriptWindow(xml); window.show();

Example 2: Script Segment

var xml = <window title="Test Button 2" interactive="true"> <button text="Press Me" action="println('Hello World')"/> </window>; var window = new ScriptWindow(xml); window.show();

CheckBox
CheckBox shows a checkbox with an optional label. XML Properties:
background = "<background color>" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" selecetd = "true | false" text = "<label text>" width = "<width in pixels>"

Event Handlers:
change = "<script segment>"

Methods:
getText() - Returns the text shown beside the checkbox. isEnabled() - Returns true if the checkbox is enabled. isSelected() - Returns true if the checkbox is selected. setBackground(color) - Sets the background color of the field. setEnabled(true | false) - Enables or disables the checkbox. setForeground(color) - Sets the foreground color of the field. setSelected(true | false) - Selects or deselects the checkbox. setText(string) - Sets the text shown beside the checkbox. setVisible(true | false) - Shows or hides the checkbox.

Example:
var xml = <dialog title="Test Checkbox"> <checkbox text="This is a checkbox" selected="true" id="checkbox1"/> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); println("Checkbox value: " + dialog.checkbox1.isSelected());

DeviceChooser
DeviceChooser is a panel that allows the user to select devices from address books. For a more compact component that provides similar functionality, see DeviceChooserField. XML Properties:
height = "<height in pixels>" id = "<identifier name>" multiple = "true | false"

required = "true | false" width = "<width in pixels>"

Methods:
getSelectedDevice() - Returns an object with information about the first selected device. This is a convenience method that is normally used when the multiple property is false . Otherwise the getSelectedDevices() method should be used. The returned object will contain these properties: name , address , user , region, site , comment , shorttype , longtype . getSelectedDevices() - Returns an array of objects that contain information about the selected devices. Each element in the array will contain these properties: name , address, user , region, site , comment, shorttype , longtype . If no devices are selected then an empty array will be returned. setVisible(true | false) - Shows or hides the field.

Example:
var xml = <dialog title="Test DeviceChooser"> <devicechooser id="chooser"/> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); var sel = dialog.chooser.getSelectedDevices(); for (var i=0; i<sel.length; i++) println(sel[i].name + ": " +sel[i].shorttype);

DeviceChooserField
DeviceChooserField is an editable text field, with a button beside it that opens a separate window for choosing devices from address books. This is more compact than DeviceChooser, which always displays the full device chooser. If the multiple property is true then multiple devices can be listed in the text field, separated by spaces and/or commas. XML Properties:
height = "<height in pixels>" id = "<identifier name>" multiple = "true | false" required = "true | false" width = "<width in pixels>"

Methods: - Returns an array of objects that contain information about device names in the specified string. Each element in the array will contain these properties: name , address, user , region, site , comment , shorttype , longtype . getSelectedDevice() - Returns an object with information about the first selected device. This is a convenience method that is normally used when the multiple property is false . Otherwise the getSelectedDevices() method should be used. The returned object will contain these properties: name , address , user , region, site , comment , shorttype , longtype . getSelectedDevices() - Returns an array of objects that contain information about the selected devices. Each element in the array will contain these properties: name , address, user , region, site , comment, shorttype , longtype . If no devices are selected then an empty array will be returned. getText() - Returns the string shown in the text field. setButtonLabel(label) - Sets the label on the button. setText(string) - Sets the string shown in the text field. setVisible(true | false) - Shows or hides the field.
getDeviceInfo(string)

Example:
var xml = <dialog title="Test DeviceChooserField"> <devicechooserfield id="chooser"/>

</dialog>; var dialog = new ScriptWindow(xml); dialog.show(); var sel = dialog.chooser.getSelectedDevices(); for (var i=0; i<sel.length; i++) println(sel[i].name + ": " +sel[i].shorttype);

FileChooserField
FileChooserField is an editable text field with a button beside it that opens a file chooser popup window, which sets text in the field. XML Properties:
background = "<background color>" buttonText = "<label on button>" chooserMode = "both | files | directories" directory = "<default chooser directory>" editable = "true | false" filter = "<file extension>" filterLabel = "<filter description>" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" required = "true | false" text = "<text in field>" width = "<width in pixels>"

Methods:
getText() - Returns the text in the field. setButtonText(string) - Sets the text in the button. setChooserMode("both | files | directories") - Sets the mode for the file chooser popup setDefaultDirectory(string) - Sets the default directory for the file chooser popup window. setEditable(true | false) - Sets the enabled state of both field and button. setFilterExtension(<filter>, <label>) - Sets the extension used to filter the file list. setText(string) - Sets the text in the field. setVisible(true | false) - Shows or hides both the text field and its button.

window.

Example:
var xml = <dialog title="Test FileChooserField" width="200"> <filechooserfield id="file"/> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); println(dialog.file.getText());

Label
Label is a non-editable text label. XML Properties:
background = "<background color>" foreground = "<foreground color>" halign = "left | center | right" height = "<height in pixels>" icon = "<image filename>" id = "<identifier name>" text = "<label text>" width = "<width in pixels>"

Methods:

getText() - Returns the text shown by the label. setText(string) - Sets the text shown by the label. setVisible(true | false) - Shows or hides the label.

Example:
var xml = <dialog title="Test Label"> <label text="This is a test label"/> </dialog>; var dialog = new ScriptWindow(xml); dialog.show();

NumberSpinner
NumberSpinner is a number field with buttons that increment and decrement its value. By default it uses a value of 0, a minimum of 0, no maximum, and a step size of 1. XML Properties:
background = "<background color>" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" max = "<maximum possible value>" min = "<minimum possible value>" step = "<step size>" value = "<current value>" width = "<width in pixels>"

Methods:
getValue() - Returns the current value of the field. setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setMax(int) - Sets the maximum possible value of the spinner. setMin(int) - Sets the minimum possible value of the spinner. setStep(int) - Sets the step size for incrementing and decrementing setValue(int) - Sets the current value of the spinner. setVisible(true | false) - Shows or hides the field.

the spinner.

Example:
var xml = <dialog title="Test NumberSpinner"> <numberspinner id="spinner" max="16" value="7"/> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); println(dialog.spinner.getValue());

PasswordField
PasswordField is an editable text field with a hidden value. XML Properties:
background = "<background color>" editable = "true | false" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" required = "true | false" width = "<width in pixels>"

Event Handlers:
change = "<script segment>"

Methods:
getText() - Returns the text in the password field. setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setText(string) - Sets the text in the field. setVisible(true | false) - Shows or hides the field.

Example:
var xml = <dialog title="Test PasswordField"> <passwordfield text="abc123" id="password1"/> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); println(dialog.password1.getText());

ProgressBar
ProgressBar shows percentage completion using a bar graph and an optional text label. The value of the progress bar can be updated by the script as it executes. XML Properties:
background = "<background color>" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" indeterminate = "true | false" max = "<maximum possible value>" text = "<label text>" textVisible = "true | false" value = "<current value>" width = "<width in pixels>"

Methods:
setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setIndeterminate(true | false) - Shows that work is in progress. setMax(int) - Sets the maximum possible value of the progress bar. setText(string) - Sets the text in the field. setTextVisible(true | false) - Sets the text in the field. setValue(int) - Sets the current value of the progress bar. setVisible(true | false) - Shows or hides the field.

Example:
var xml = <window title="Test ProgressBar"> <progressbar id="progress" value="10" textVisible="true"/> </window>; var window = new ScriptWindow(xml); window.show(); pause(2); window.progress.setValue(33); pause(2); window.progress.setValue(66); pause(2); window.progress.setValue(100);

Radio
Radio shows a radio button with an optional label. Radio buttons belong to groups, specified by the group property. Only one button in each group can be selected at a time. By default the first button created in each group is selected. XML Properties:

background = "<background color>" foreground = "<foreground color>" group = "<name of button group>" height = "<height in pixels>" id = "<identifier name>" selected = "true | false" text = "<label text>" width = "<width in pixels>"

Event Handlers:
change = "<script segment>"

Methods:
getText() - Returns the text shown beside the radio button. isEnabled() - Returns true if the radio button is enabled. isSelected() - Returns true if the radio button is selected. setBackground(color) - Sets the background color of the field. setEnabled(true | false) - Enables or disables the radio button. setForeground(color) - Sets the foreground color of the field. setSelected(true | false) - Selects or deselects the radio button. setText(string) - Sets the text shown beside the radio button. setVisible(true | false) - Shows or hides the radio button.

Example:
var xml = <dialog title="Test Radio"> <hbox> <radio text="Radio 1" group="g1" id="radio1"/> <radio text="Radio 2" group="g1" id="radio2"/> <radio text="Radio 3" group="g1" id="radio3"/> </hbox> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); println("Radio 2 value: " + dialog.radio2.isSelected());

ResultPanel
ResultPanel components show a list of bookmarks on the left side, and a text area on the right that shows text attached to the selected bookmark. Bookmarks are added as the script executes, and the user can click on them to view results that interest them. This can be useful for summarizing script results as they are collected. XML Properties:
background = "<background color>" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" width = "<width in pixels>"

Methods:
addTextResult(description, result [, "info" | "warn" | "error"]) - Adds a bookmark labeled with the description, containing the result text, and optionally flagged with an icon for the type. clear() - Clears all results from the list. cmd([<description>, ] <command> [, <prompt>, <answer> [, ...]]) - Runs a command and adds

its response to the result list. This is a convenience function, with the same effect the cmd() function followed by addTextResult(description, getlastresponse()) . setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setVisible(true | false) - Shows or hides the field. Example:

var xml = <window title="Test ResultPanel"> <resultpanel id="resultpanel" height="200"/> </window>; var window = new ScriptWindow(xml); window.show(); window.resultpanel.addTextResult( "Bookmark1", "This is text stored for bookmark1"); window.resultpanel.addTextResult( "Bookmark2", "Bookmark2 text", "warning");

SelectBox
SelectBox shows a drop-down list of selectable items. Items can be added to the select box either using item elements in XML, or using one of the addItem() methods. XML Properties:
background = "<background color>" enabled = "true | false" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" width = "<width in pixels>"

Event Handlers:
change = "<script segment>"

Methods:
addItem(text) - Adds an item to the select box. This may only have effect if used before show() is called. addItem(text, value)- Adds an item to the select box with separate text and value. This may only have effect if used before show() is called. addItem(itemarray) - Adds multiple items to the select box from an array. Items in the array can either be strings or objects with the properties text and/or value . This may only have effect if used before show() is called. getSelectedValue() - Returns the value of the selected item. setVisible(true | false) - Shows or hides the component.

Example:
var xml = <dialog title="Test SelectBox"> <selectbox id="box1"> <item text="Choice 1" value="1"/> <item text="Choice 2" value="2"/> <item text="Choice 3" value="3"/> </selectbox> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); println("Selected value: " + dialog.box1.getSelectedValue());

StatusField
StatusField is a text field that is automatically updated to show the status of the script: running or stopped. While running, the script can also assign its own status text with the setText() method. XML Properties:
background = "<background color>" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" runningColor = "<background color when running>" stoppedColor = "<background color when not running>"

text = "<label text>" width = "<width in pixels>"

Methods:
getText() - Returns the text shown by the status field. setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setText(string) - Sets the text shown by the status field. setRunningColor(color) - Sets the background color for the status setStoppedColor(color) - Sets the background color for the status setVisible(true | false) - Shows or hides the component.

field when the script is running. field when the script is not running.

Example:
var xml = <window title="Test StatusField"> <statusfield id="status1" runningColor="green" stoppedColor="red"/> </window>; var window = new ScriptWindow(xml); window.show(); pause(3);

Table
Table shows a sortable, scrollable table with column headings. Columns are tied to specific property names in objects added to each row. The user can filter table data if TableFilter components are included in the window that reference the table's id. XML Properties:
background = "<background color>" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" resizeMode = "off | subsequent | next | last | all" selectionMode = "single | multiple" sortable = "true | false" width = "<width in pixels>"

Event Handlers:
selectionChanged = "<script segment>"

Methods:
addItem(object) - Adds a row to the table containing fields from the specified object. The table will show properties of the object that match column elements. Other fields in object will be ignored. getColumnCount() - Returns the number of columns in the table. getItemAt(row) - Returns the item in the specified row number of the table. getRowCount() - Returns the number of unfiltered rows in the table. getSelectedItem() - Returns the first selected item in the table. getSelectedItems() - Returns an array with all selected items in the table. getSelectedRow() - Returns the number of the first selected row. getSelectedValue() - Returns the value in the first selected row and column. getValueAt(row, col) - Returns the value in the specified row and column of the table. removeItem(filter) - Removes items matching filter, which can be either an object with field values or a row number. setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setSelectedRow(row) - Selects the specified row number. setValue(filter, fieldname, value) - Sets the value for a given fieldname in rows matching a filter, which can be either an object with field values or a row number. Returns true if at least one matching row was found and updated. setVisible(true | false) - Shows or hides the component.

Column Subcomponent Properties

heading = "<column heading>" field = "<field for column in row objects>" width = "<optional fixed column width in pixels>"

Example:
var xml = <window title="Test Table"> <table id="table1" height="100"> <column heading="Device" field="device"/> <column heading="Slot" field="slot"/> <column heading="Port" field="port"/> <column heading="Status" field="type"/> </table> </window>; var window = new ScriptWindow(xml); window.show(); window.table1.addItem( {device: "SWITCH1", slot: "2", port: "0", type: "atm"}); window.table1.addItem( {device: "SWITCH1", slot: "2", port: "1"}); window.table1.setValue( {device: "SWITCH1", port: "1"}, "type", "ethernet"); var obj = new Object(); obj.device = "SWITCH2"; obj.slot = "7"; obj.port = "0"; obj.type = "ip"; window.table1.addItem(obj);

TableFilter
TableFilter is a field that allows the user to filter a Table based on values in a column. If type is auto then the TableFilter is a drop-down list that is automatically filled with maxItems (default 10) most-frequent values from the specified column. If type is text then the TableFilter is a text field where the user can type substring filter values, which will be matched using the caseSensitive property as they type. XML Properties:
background = "<tab background color>" caseSensitive = "true | false" field = "<column field name>" foreground = "<tab foreground color>" height = "<height in pixels>" id = "<identifier name>" maxItems = "<max number of auto filter items>" table = "<identifier name of table>" type = "auto | text" width = "<width in pixels>"

Methods:
setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setVisible(true | false) - Shows or hides the component.

Example:
var xml = <window title="Test TableFilter"> <box direction="north"> <grid rows="2" cols="2" vgap="0" direction="west"> <label text="Device"/> <label text="Type"/> <tablefilter table="table1" field="device" width="100"/> <tablefilter table="table1" field="type" type="text"/> </grid> </box> <table id="table1" height="100"> <column heading="Device"

field="device"/> <column heading="Slot" field="slot"/> <column heading="Port" field="port"/> <column heading="Type" field="type"/> </table> </window>; var window = new ScriptWindow(xml); window.show(); window.table1.addItem( {device: "SWITCH1", slot: "2", port: "0", type: "atm"}); window.table1.addItem( {device: "SWITCH1", slot: "2", port: "1", type: "ethernet"}); var obj = new Object(); obj.device = "SWITCH2"; obj.slot = "7"; obj.port = "0"; obj.type = "ip"; window.table1.addItem(obj);

TabPane
TabPane is a navigator that can contain multiple tabs, each with its own set of subcomponent containers and graphical components. XML Properties:
background = "<tab background color>" foreground = "<tab foreground color>" height = "<height in pixels>" id = "<identifier name>" tabPlacement = "top | bottom | left |right" width = "<width in pixels>"

XML Properties for Subcomponents:

label = "<label shown on tab>"

Methods:
setVisible(true | false)

- Shows or hides the container.

Example:
var xml = <window title="Test TabPane"> <tabpane tabPlacement="bottom" height="100"> <box label="tab1"> <textarea text="A textarea in tab1"/> </box> <box label="tab2"> <textarea text="A textarea in tab2"/> </box> </tabpane> </window>; var window = new ScriptWindow(xml); window.show();

TextArea

TextArea is a text field with multiple lines of text. XML Properties:

background = "<background color>" editable = "true | false" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" required = "true | false" scrollable = "true | false" text = "<label text>" width = "<width in pixels>"

Event Handlers:
change = "<script segment>"

Methods:
getText() - Returns the text shown by the text area. print(string) - Appends a string to the end of the text in this text area. println(string) - Appends a string and a newline to the end of the text setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setText(string) - Sets the text shown by the text area. setVisible(true | false) - Shows or hides the component.

in this text area.

Example:
var xml = <dialog title="Test TextArea"> <textarea text="Testing 123" height="100" id="textarea1"/> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); println(dialog.textarea1.getText());

TextField
TextField is a text field with a single line of text. XML Properties:
background = "<background color>" editable = "true | false" foreground = "<foreground color>" halign = "left | center | right" height = "<height in pixels>" id = "<identifier name>" required = "true | false" text = "<label text>" width = "<width in pixels>"

Event Handlers:
change = "<script segment>"

Methods:
getText() - Returns the text shown by the text field. setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setText(string) - Sets the text shown by the text field. setVisible(true | false) - Shows or hides the component.

Example:

var xml = <dialog title="Test TextField"> <textfield text="Testing 123" id="textfield1"/> </dialog>; var dialog = new ScriptWindow(xml); dialog.show(); println(dialog.textfield1.getText());

TimerField
TimerField is a text field that can show several types of automatically updated timers: date shows the current date, manual shows the amount of time since the start() method was called, script shows the elapsed time since the script was started, and time shows the current time. XML Properties:
background = "<background color>" foreground = "<foreground color>" height = "<height in pixels>" id = "<identifier name>" type = "date | manual | script | time" width = "<width in pixels>"

Methods:
setBackground(color) - Sets the background color of the field. setForeground(color) - Sets the foreground color of the field. setVisible(true | false) - Shows or hides the component. start() - Starts the timer (not necessary for script timer types). stop() - Stops the timer.

Example:
var xml = <window title="Test TimerField"> <form> <timerfield type="script" label="Elapsed Time"/> <timerfield type="time" label="Current Time"/> </form> </window>; var window = new ScriptWindow(xml); window.show(); pause(5);

Color Reference
Colors in ScriptWindow objects, for properties such as background and foreground , can be described using either predefined color names or hexadecimal sets of RGB color values. Predefined Color Names
black blue cyan darkgray gray green lightgray magenta orange pink red white yellow

RGB Color Values Colors can be defined using a " #" prefix followed by hexadecimal notation for the combination of Red, Green, and Blue color values (RGB). Each RGB component ranges from hex 00 to hex FF. Here are some example colors:
background="#FF0000" background="#0000FF"

background="#C0C0C0" background="#00FF00"

More ScriptWindow Examples

Data Collection Example Dialog Example Wizard Example Data Collection Example This example displays data in a ResultPanel and updates text fields at the top of the window with key information. This approach can be useful because it allows users to view the data as it is collected, rather than waiting for the script to complete.
var xml = <window title="Data Collection" width="600" height="400"> <grid direction="north" rows="1" cols="2" hgap="10"> <form> <textfield id="software" label="Software" editable="false"/> <textfield id="memory" label="Memory" editable="false"/> <textfield id="server" label="Call Server" editable="false"/> </form> <form> <statusfield runningcolor="green" label="Script Status"/> <timerfield type="script" label="Elapsed Time"/> <timerfield type="time" label="Current Time"/> </form> </grid> <resultpanel id="result"/> <box direction="south"> <grid direction="east" rows="1" cols="2" hgap="5"> <button type="savelog"/> <button type="close"/> </grid> </box> </window>; var window = new ScriptWindow(xml); window.show(); window.result.cmd("Module", "d -p mod"); window.software.setText("ABC123"); window.result.cmd("Cards", "d sh ca/* inserted"); window.memory.setText("12345678"); window.result.cmd("ATM", "d atmif/*"); window.server.setText("Test Server");

Dialog Example This example shows a dialog window that prompts the user for several types of input. The OK button is automatically disabled until the user supplies required fields.
var xml = <dialog buttons="okcancel" title="An Example Dialog" width="200" resizable="false"> <form> <devicechooserfield id="device" required="true" multiple="false" label="Target Device"/> <numberspinner id="card" max="16" label="Card Number"/> <hbox label="Activate"> <radio id="actyes" group="act" text="Yes"/> <radio group="act" text="No"/> </hbox> </form> </dialog>; var dialog = new ScriptWindow(xml); if (dialog.show() == "OK") { println("Target device: "+dialog.device.getSelectedDevice().name); println("Card: "+dialog.card.getValue()); println("Activate: "+dialog.actyes.isSelected()); }

Wizard Example This example shows a Wizard that leads the user through several steps. The "Introduction" step shows instructions for the user. The "Choose Target" step prompts for required information, which is then used in the "Data Collection" step to decide what data needs to be collected.

var xml = <wizard title="An Example Wizard" width="450"> <box label="Introduction"> <label direction="north" text="This is an example wizard."/> </box> <box label="Choose Target"> <form direction="north"> <devicechooserfield id="device" required="true" multiple="false" label="Target Device"/> <numberspinner id="card" max="16" label="Card Number"/> <hbox label="Activate"> <radio id="actyes" group="act" text="Yes"/> <radio group="act" text="No"/> </hbox> </form> </box> <box label="Data Collection"> <box direction="north"> <button text="Start" action="start()" direction="west"/> <label id="status" direction="east"/> </box> <resultpanel id="result" height="100"/> </box> </wizard>; var wizard = new ScriptWindow(xml); wizard.show(); function start() { wizard.status.setText("Connecting..."); connect(wizard.device.getSelectedDevice()); if (getselectednodecount() > 0) { wizard.result.addTextResult( "Connected", "Connected to " + wizard.device.getSelectedDevice().name); } else { wizard.result.addTextResult("Connect", "Failed to connect with "+ wizard.device.getSelectedDevice().name, "error"); return; } wizard.status.setText("Gathering Data..."); cmd("d -o -c shelf card/"+wizard.card.getValue()); wizard.result.addTextResult( "Operational", getlastresponse()); cmd("d -p shelf card/"+wizard.card.getValue()); wizard.result.addTextResult( "Provisioning", getlastresponse()); wizard.status.setText("Complete");