Avaya Writing Technician Interface Scripts User Manual

Writing Technician Interface Scripts

BayRS Version 13.00 Site Manager Software Version 7.00

Part No. 303563-A Rev 00 October 1998

4401 Great America Parkway 8 Federal Street Santa Clara, CA 95054 Billerica, MA 01821

and recomm endations in this document are believed to be accurate and reliable , but are presen ted without express or implied warranty. Users must take full responsibility for their applications of any products specified in this document. The information in this documen t is proprietary to Bay Networks, Inc.

The software described in this document is furnished under a license agreement and may only be used in accordance with the te rms of that license. A summary of the Software License is incl uded in this document.

Trademarks

ACE, AFN, AN, BCN, BLN, BN, BNX, CN, FRE, LN, Optivity, PPX, Quick2Config, and Bay Networks are registered tradema rks and Advanced Remote Node, ANH, ARN, ASN, BayRS, BaySecure, BayStack, BayStream, BCC, BCNX, BLNX, EZ Install, EZ Internetwork, EZ LAN, FN, IPAutoLearn, PathMan, RouterMan, SN, SPEX, Switch Node, System 5000, and the Bay Netwo rks logo are trademarks of Bay Networks, Inc.

Microsoft , MS, MS-DOS, Win32, Windows, and Windows NT are registered trade m arks of Microsoft Corporation. All other trademarks and registered trademark s are the property o f their respective owners .

Restricted Rights Legend

Use, duplication, or disc losure by the United States Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227- 7013.

Notwithstanding any other license agreem ent that may pertain to, or accompany the delivery of, this computer software, the rights of the United States Government regarding its use, reproduction, and disclosure are as set forth in the Commercial Computer Software-Restricted Rights clause at FAR 52.227-19.

Statement of Conditions

In the interest of improving internal design, operational function, and/or reliability, Bay Networks, Inc. reserves the right to make changes to the products described in this document wi thout notice.

Bay Networks, Inc. does not assum e any liability that may occur due to the use or application of the product(s) or circuit layout(s) described herein.

Portions of the code in this software product may be Copyright © 1988, Rege nts of the University of Californ ia. All rights reserved. Redis tribution and use in source and binary forms of such port ions are permitt ed, provided that the above copyright notice and this paragraph are duplicated in all such forms and that any documentation , advertising materials, and other materials related to such distribution and use acknowledge that such portions of the software were deve loped by the University of California, Berkele y. The name of the University may not be used to endor se or promote products derived from such portions of the software without specific prior written permission.

SUCH PORTIONS OF THE SOFTWARE ARE PROVIDED “ AS IS” AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

In additi on, the program and information contained herein are licensed only pursuant to a license agreement that contains restrictions on use and disclosure (that may incorpor ate by reference certain limitat ions and notices imposed by thir d pa rt ie s).

303563-A Rev 00

Bay Networks, Inc. Software License Agreement

NOTICE: Please carefully read this license agreement before copying or using the accompanying software or instal ling the hardwa re unit with pre-enabled softw are (each of w hich is referred to as “Softw are” in this Ag reement). BY COPYING OR USING THE SOFTWARE, YOU ACCEPT ALL OF THE TERMS AND CONDITIONS OF THIS LICENSE AGREEMENT. THE TERMS EXPRESSED IN THIS AGREEMENT ARE THE ONLY TERMS UNDER WHICH BAY NETWORKS WILL PERMIT YOU TO USE THE SOFTWARE. If you do not accept these terms and conditions, return the product, unused and in the original shipping container, within 30 days of purchase to obtain a credit for the full pur chase price.

1. License Grant. Bay Networks, Inc. (“Bay N etworks”) grants the end user of the Software (“Licensee”) a p ersonal, nonexcl usive, nontransferable license: a) to use the Soft w are either on a single computer or, if applicable, on a si ngle authori zed de vi ce ide ntified by host ID, fo r whi ch it was origi nal ly acq uired ; b) to cop y the Sof tw ar e so le ly for bac kup purposes in support of authorized use of the Softwar e; and c) to use and copy the associated user manual solely in support of authorized use of the Software by Licensee. This license applies to the Software only and does not extend to Bay Networks Agent softwa re or other Bay Networ ks software products. Bay Networks Age nt software or other Bay Networks software products are licensed for use under the terms o f the applicable Bay Networks, Inc. Software License Agreement that accompanies such software and upon payment by the end user of the app licable license fees for such software.

2. Restrictions on use; reservation of rights. The Software and user manuals are protect ed under copyright laws. Bay Networks and/or its licensors retain all ti tle and ownership in both the Software and user manuals, including any revis ions made by Bay Networks or its licenso rs. The copyright notice must be reproduced and included with any copy of any por tion of the Sof tw are or use r manua ls . Licens ee may not modif y, transla te, dec ompi le , disas se mble , use for any compe ti ti v e an al ysis, r e v erse e ngi ne er , dis tr ib ute , o r c rea te der i vative w ork s f ro m the Softw are or u se r man ual s or any copy, in whole or in part. Except as expressly provided in this Agreement, Licensee may not copy or transfer the Softw are or user manuals, in w h ole or in part. The Sof tw are and user manuals embody Bay Networks’ and its licenso rs’ confidenti al and proprietary intellectual property. Licensee shall not sublicense, assign, or otherwise disclos e to any third party the Software, o r any informatio n about the operation, design, performance, or implementation of the Softw are and user manuals that is confi dential to Bay Networks and its lice nsors; however, Licensee m ay grant permission to its consultants, subcontractors, and agents to use the So ftware at Licensee’s f acility, provided they have agreed to use the Software only in accordance with the ter ms of this license .

3. Limited warranty. Bay Ne tworks warrants each item of Software, as delivered by Bay Netw orks and properly installed and operated on Bay Ne tw orks hardware or other equipment it is origi nally licensed for, to function substantially as described in its accompanying user manual during its warranty period, which begi ns on the date Softwar e is fi r st shi pped to Licen see . If any it em of Soft war e fai ls to so func ti on du ring i ts warr anty pe ri od, as t he so le remedy Bay Ne tworks will at its discretion provide a suitable fix, patch, or workaround for the problem that may be included in a future Software release. Bay Networks further wa rrants to Licensee that the med ia on which the Softwar e is provided will be free from defects in materials and workmanship under normal use for a period of 90 days from the date Software is first shipped to Licensee. Bay Networks will replac e defective me dia at no charge if it is returned to Bay Networks during the warranty period along with proof of the date of shipment. This warranty does not apply i f the media has been damag ed as a result of accident, misuse, or abuse. T he Licensee as sumes all re sponsibility for selection of the Software to achieve Licensee’s intended results and for the installation, use, and results obtained from the Software. Bay Networks does not warrant a) that the functions contained in the software w ill meet the Licensee ’s requirements, b) that the Software wil l operate in the hardware or software combin ations that the Li censee may select, c) that the operation of the Software will be uninterrupted or error free, or d) that all defects in the operati on of the Softwar e w ill be corrected. Bay Network s is not obligated to remedy any Software defect that cannot be repro duced with the latest Software release. These warranties do not apply t o the Software if it has been ( i) altered, except by Bay Networks or in ac cordance with its instructions; (ii) used in conjunction with another vendor’s product, resulting in the defect; or (i ii) damaged by impr oper environm ent, abuse, misuse, accident, or negligence. THE FOREGOING WARRANTIES AND LIMITATIONS ARE EXCLUSIVE REMEDIES AND ARE IN LIEU OF ALL OTHER WARRANTIES EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Licensee is responsible for the security of

303563-A Rev 00

iii

its own data and informat ion and for maintai ning adequate pro cedures apart from the Software to re construct lost or altered files, data, or programs.

4. Limitation of liability. IN NO EVENT WILL B AY NETWORKS OR ITS LICENSORS BE LIABLE FOR ANY COST OF SUBSTITUTE PROCUREMENT; SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ; OR ANY DAMAGES RESULTI NG FROM INACCURATE OR LOST DATA OR LOSS OF USE OR PROFITS ARISING OUT OF OR IN CONNECTION WITH THE PERFORMANCE OF THE SOFTWA RE, EVEN IF BAY NETWORKS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT SHALL THE LIABILITY OF BAY NETWORKS RELATING TO THE SOFTWARE OR THIS AGREEMENT EXCEED THE PRICE PAID TO BAY NETWORKS FOR THE SOFTWARE LICENSE.

5. Governmen t L icensees. This provision applies to all Sof tware and documentation acquired directly or indirectly by or on behalf of the United States Government. The Software and documentation are commercial products, licensed on the open market at market pri ces, and were developed entirely at private expense and without the use of any U.S. Government funds. The lic ense to the U.S. Gov ernment is granted only with restric ted rights, and use, duplication, or disclos ure by the U.S. Government is subject to the restrictions set forth in subparagraph (c )(1) of the Commercial Computer So ftware––Restric ted Rights clause of FAR 52.227-19 and the li mi tations set out in this license for civilian agencies , and subparagrap h (c)(1)(ii) of the Rights in Technical Data and Compu ter Software clause of DFARS

252.227-7013, for agencies of the Departmen t of Defense or their successors, whi chever is app licable.

6. Use of Software in the European Community. This provision applies to all Software acquired for use within the European Comm unity. If License e uses the Software within a country in the European Community, the Softw are Directive enacted by the Council of European Communities Directive dated 14 May, 1991, w ill apply to the examination of the Softwar e to facilitate interoperability. Licensee agr ees to notify Bay Netw orks of any such intended examination of the Software and may procure support and assistance from Bay Networks.

7. Term and termination. This license is effective until terminated; however, all of the restrictions with respect to Bay Networks’ copyright in the Software and user manuals will cease being effective at the date of expiration of the Bay Networks copyright; those restrictions relating to use and d isclosure of Bay Networks’ confidential informati on shall continue in effect. Licensee may terminate this license at any time. The license will automatically terminate if Licensee fail s to comply with any of the terms and conditions of the license. Upon terminat ion for any reaso n , Licensee will immediately destroy or return to Bay Networks the Software, user manuals, and all copies. Bay Networks is not liable to Licensee for damages in an y form solely by reason of the termination of this license.

8. Export and Re-export. Licensee agr ees not to export, directly or indirectly, the Software or related techn ical data or information without first obtaining any required export licenses or other governmental approvals. Without limiting the fore going, Licensee, on behalf of itself and its subsidiaries and affiliates, agrees that it will not, without first obtaining all export licenses and approvals required by the U.S. Government: (i) export, re-export, transfer, or divert any such Sof tware or technical data, or any dire ct product thereof, to any country to whi ch such exports or re-exports are rest ricted or embargoed under United States export control laws and regulations, or to any national or resident of such rest ricted or embar goed countries; or (ii) provide the Software or related technical data or information to any military end user or for any military end use, including the design, development , or production of any ch em ical, nuclear, or biological weapons.

9. General. If any provision of this Agreement is held to be invalid or unenforceable by a court of competent jurisdiction, the remainder of the provisions of this Agreement shall remain in full force and effect. This Agreement will be governed by the laws of the state of California.

Should you have any questi ons concerning this Agreement, contact Bay Networks, Inc., 4401 Great Americ a Parkway, P.O. Box 58185, Santa Clara, California 95054-8185.

LICENSEE ACKNOW LEDGES THAT LICENSEE HAS READ THIS AG REEMENT, UNDERSTANDS IT, AND AGREES TO BE BOUND BY ITS TERMS AND CONDITIONS. LICENSEE FUR THER AGREES THAT THIS AGREEMENT IS THE ENTIRE AND EXCLUSIVE AGREEMENT BETWEEN BAY NETWORKS AND LICENSEE, WHICH SUPERSEDES ALL PRIOR ORAL AND WRITTEN AGREEMENTS AND COMMUNICATIONS BETWEEN THE PARTIES PERTAINING TO THE SUBJECT MATTER OF THIS AGREEMENT. NO DIFFERENT OR ADDITIONAL TERMS WILL BE ENFORCEABLE AGAINST BAY NETWORKS UNLESS BAY NETWORKS GIVES ITS EXPRESS WRITTEN CONSENT, INCLUDING AN EXPRESS WAIVER OF THE TERMS OF THIS AGREEMENT.

303563-A Rev 00

Preface

Before You Begin ..............................................................................................................xi

Text Con ventions ............................... .................................... ....................... ....................xii

Acronyms .........................................................................................................................x iv

Bay Networks Technical Publications ..............................................................................xiv

How to Get Help ..............................................................................................................xv

Chapter 1 Creating a Script File

About Variables ..............................................................................................................1-2

Local, Global, and System Variables .......................................................................1-4

Special Variables ............................................................................................................1-4

Input Parameters ...................................................................................................... 1-4

Prompting for Input .................................... ..... ....... ....... .......... .. ....... ....... ..... ....... ......1-5

Polling the Console for Input ...................... ....... ............ ....... .............. ............ ....1-5

Accessing MIB Information ......................................................................................1-6

Formatting a MIB Entry ............................................................................................1-7

Defining a Pseudo-Variable Array ................................................... ..... ....... ....... ....... ..... .1-8

Creating and Using Variables ......................................................................................... 1-8

Viewi ng Variables .................................. ................................... ........................ ........1-8

Setting Variables ......................................................................................................1-9

Deleting Variables ................................... .................................... ...........................1-10

Setting the Current Volume or Directory .......................................................................1 -11

Controlling Program Flow .............................................................................................1-11

Writing Messages to the Console .................................................................................1-12

Saving Console Messages to a File ............................................................................. 1 -12

Performing Error Recovery ...........................................................................................1-12

Inserting Comments ..................................................................................................... 1 -13

Debugging a Script File ................................................................................................1-13

303563-A Rev 00

Saving and Restoring Var iables .............................................................. .....................1-13

Running a Script File ........................................................ .. .......... ....... .. ....... .......... ......1-14

Creating Menus ............................................................................................................1 -14

Chapter 2 Command Reference

arrayenv ..........................................................................................................................2- 3

cutenv .............................................................................................................................2-4

echo ................................................................................................................................2-6

enumenv ......................................................................................................... ................2- 7

export ..............................................................................................................................2-8

getenv .............................................................................................................................2-9

gosub ............................................................................................................................2 -10

goto ...............................................................................................................................2-11

if ....................................................................................................................................2-12

instenv ..........................................................................................................................2-16

let ................................................................................................................................ .. 2 -18

mibget ........................................................................................................................... 2-23

octetfmt .........................................................................................................................2 -26

on error .........................................................................................................................2 -28

pause ............................................................................................................................ 2-29

printf ..............................................................................................................................2-30

record ...........................................................................................................................2-33

return ............................................................................................................................2-35

run ................................................................................................................................2-36

save env ................................ .................................... ........................ ...........................2-38

setenv ...........................................................................................................................2-39

source env ................................ ....................... .................................... .........................2-40

sprintf ............................................................................................................................2-41

unsetenv .......................................................................................................................2-42

verbose ......................................................................................................................... 2-4 4

303563-A Re v 00

Appendix A Sample Scripts

Menu Script ......... ................................... .................................... ....................... ............A-1

FDDI.MNU Script ........................................................................................................... A-2

FDDI.BAT Script ......... ........... .................................... ................................... ................. A-3

Index

303563-A Rev 00

vii

Tables

Table 2-1. Script Commands ...................................................................................2-1

Table 2-2. Arithmetical Operators ...........................................................................2-19

Table 2-3. Logical Operators ...................................................................................2 -19

Table 2-4. Special Charac te rs .................................................. ..............................2-31

303563-A Rev 00

This guide describes creating and editing Technician Interface scripts.

Before You Begin

This guide is intended for network administrators with the following background:

• Knowledge of the UNIX operating system and the C programm ing language

• A general under standing of local area and wide area networking fundamentals

• An understanding of the transmi ssion and management protocols used on your network

Preface

303563-A Rev 00

Before using this guide, you must load the router software from the release medium. This guide assumes that you are fa miliar with the Technici an Interface. For information on this interface, refer to Using Technician Interface Software.

Writing Technician Interface Scripts

Text Conventions

This guide uses the following text conventions:

angle brackets (< >) Indicate that you choose the text to enter based on the

description inside the brackets. Do not type the brackets when entering the command. Example: If the command syntax is:

bold text

<ip_address>

ping ping 192.32.10.12

Indicates text tha t you need to enter and command

, you enter:

names and options. Example: Enter

Example: Use the

show ip {alerts | routes

command.

dinfo

}

braces ({}) Indicate required elements in syntax descriptions

where there is more than one option. You must choose only one of the options. Do not type the braces when entering the command. Example: If the command syntax is:

, you must enter either:

show ip {alerts | routes show ip alerts or show ip routes

}

brackets ([ ]) Indicate optional elements in syntax descriptions. Do

not type the brackets when entering the command. Example: If the command syntax is:

, you can enter either:

show ip interfaces [-alerts show ip interfaces

]

show ip interfaces -alerts

xii

ellipsis points (. . . ) Indicate that you repeat the last element of the

comman d as need ed . Example: If the command syntax is:

ethernet/2/1 ethernet/2/1

parameter> <value>

and as many parameter-value pairs as

] . . .

, you enter

needed.

303563-A Re v 00

Preface

italic text Indicates file and directory names, new terms, book

titles, and variables in command syntax descriptions. Where a variable is two or more words, the words are connected by an underscore. Example: If the command syntax is:

show at <

valid_route

valid_route>

is one va riable and you subs titu te one value

for it.

screen text Indicates system output , fo r exa mple, prompts and

system messages. Example:

Set Ba y Netw orks Tr ap Mo nito r Fil ters

separator ( > ) Shows menu paths.

Example: Protocol s > IP identifies t he IP option on the Protocols menu.

vertical line (

) Separates choices for command keywords and

arguments. Enter only one of the choices. Do not type the vertical line when entering the command. Example: If the command syntax is:

show ip {alerts | rou tes} show ip alerts

show ip routes

, you enter either:

, but not both.

303563-A Rev 00

xiii

Writing Technician Interface Scripts

Acron yms

ANSI American National Standards Institute ARP Address Resolutio n Protocol ASCII American Stan d ard Co de fo r In formation Interch a n ge ATM asynchronous transfer mode FDDI Fiber Distributed Data Interface MAC media access control MIB management information base OSI Open Systems Interconnec tion OSPF Open Shortest Path Fi rst RIP Routing Information Protocol SNMP Simple Network Management Protocol

Bay Netwo rks Technical Publications

xiv

You can now print Bay Networks te chnical manuals and release notes free, directly from the Int ernet. Go to support.bayn etworks.com/libr ary/tpubs/. Fi nd the Bay Networks product for which you need doc umenta tion. Then locate the specific category and model or version for your hardware or software product. Using Adobe Acrobat Reader, you can open the manuals and release notes, sear ch for the sections you need, and print them on most standard printers. You can download Acrobat Reader free from the Adobe Systems Web site, www.adobe.com.

You can purchase Bay Networks document ation sets, CDs, and selected technical publications through the Bay Networks Collat era l Catalog. The catalog is located on the World Wide Web at support.baynetworks.com/catalog.html and is divided into sections arran ged alpha betically:

• The “CD ROMs” section lists available CDs.

• The “Guides/Books” section lists books on technical topics.

• The “Technical Manuals” section lists available printed documentation sets.

303563-A Re v 00

Make a note of the part numbers and prices of the items that you want to order. Use the “Marketing Collateral Catalog description” link to place an order and to print the order form.

How to Get Help

For product assista nce, support contracts, or information about educational services, go to the following URL:

http://www.baynetworks.co m/corporate/contacts/

Or telephone the Bay Networks Technical Solutions Center at: 800-2LANWAN

Preface

303563-A Rev 00

Chapter 1

Creating a Script File

The Technician Interface script facility allows you to r ead and execute Technician Interface commands from a script file. You create and edit script files on a remote workstation and transfer the files to the router via TFTP or XMODEM. For instructions on using TFTP or XMODEM, see Using Technician Interface Software.

We provide several script programs that let you manage the router using information store d in the manageme nt information base (MIB). You can use the scripts to display information about protocols and network services and to enable and disable protocols, circuits, line s, and services. You may also choose to write your own scripts, using this manual as a guide. Technician Interface scripts are very similar to UNIX shell sc ri pts.

303563-A Rev 00

This chapter d escri b es how to perfo r m the following tasks, using the Technicia n Interface script commands:

• Prompting the user for input, using the special variable

• Referen ci ng and using MIB information, using the special variable

, the

mibget

formatting MIB entries using the

• Creating, using, and dele ting variables, using the

enumenv, getenv, instenv, let, setenv, sprintf

• Changing a local variable into a global variable, using the

• Evaluat ing an ari thmetic or logical expression, using the

• Parsing a text string, using the

cutenv

• Controlling the e xecution of the script, using the

commands

return

and

octetfmt

comman d

instenv

commands, and

command

arrayenv, cutenv

, and

unsetenv

let

if, goto, pause, gosub

commands

export

command

comman d

, and

1-1

Writing Technician Interface Scripts

• Writing messages to the console, using the

• Recording console message s to a file, using the

• Handling and recovering from errors, using the

• Inserting comments into a scr ipt file, using the pound sign (#)

• Debugging a script file, using the

• Saving or restoring variable s to or from a file , using the

env

• Running a script file with co mmand line arguments, using the

• Documenting a script file with command lines

About Variables

A variable is a location in the computer’s memory for storing a value. A varia ble name identifies the location. Variable names can consist of up to 15 alphanum eric characters and the underscore character (_). The first character of a variable name must be an alphabetical character. The Technician Interface stores the value of a variable as a string of ASCII characters. The maximum string le ngth is 255 characters.

commands

verbose

echo

and the

record

on error

comman d

printf

command

save env

run

commands

source

and

command

1-2

You can assign a value to a variable using one of the set variable commands

arrayenv, cutenv, enumenv, instenv, let, setenv, mibget,

(

sprintf

). For

instructions on using these commands, see Chapter 2. After you have assigned a value to a variable, you can refer to the variable on a

command line withi n the s cript f ile b y e ntering a dollar s ign ($) bef ore the v aria ble name (for example,

When you refer t o a variable, the Technician Interface substitutes the value set for the variab le itself. If you want to prevent or delay the substitution of the va riable, enter the backslash c haracter (\) before the $. The backslash character, also called the escape character, indicates that special characters follow.

In the following sc ript, the value of

setenv a blue setenv b “My color is \$a” echo $b

My color is blue

appears on the user’s console.

is substituted for

when b is executed.

303563-A Re v 00

Creating a Script File

To prevent a var iable from being expanded, enter two dollar signs ($$) before the variable name, as sho wn in the following example:

setenv a blue setenv b “My color is \$a” echo $$b

My color is $a

appears on the user’s console.

You may embed variables in quote d strings, as shown in the previous example. The follo wing command line enc loses the va ria ble names

and b in braces (

{ }

) to

separate the v aria ble names from other data within the string.

echo “The sum of ${a}+1=${b}”

Note:

If the variable name is followed by a space or an end-of-line character

(carriage retu rn), the b rack ets are optional.

A variable name is usually a literal string of characters preceded by a dollar sign ($). The v ariable name can als o be “b ui lt” dynami cally when the scri pt is e x ecuted by using a combination of lite ral text and the text stored in other variables.

For example, if you have a va riable named array_10, you can reference this variable by entering variable name b y concatena ting the te xt st rings assign the variable index the value 10, using the command

$array_10

on a command line. You can build this same

array_

and 10. For exampl e, if you

let index = 10

, then you can bu ild the v ariab le name arr ay _10 dynamic ally on the c ommand line usi ng the followi ng syntax:

${array_[$index]}

. Notice the use of the brack ets (

[ ]

) within the variable name. Any literal text or variable name specified within the brackets is first expanded to replace any variables with their values and then concatenated onto the preceding characters of the variable name. To use brackets, you must enclose the entire variable name being built within braces (

{ }

303563-A Rev 00

1-3

Writing Technician Interface Scripts

Local, Global, and System Variables

When you first define a variable, the computer stores it in the local environment variable table. Local variables are only accessible from within the script in which they were cr eated. Y ou cannot access them from another sc ript file. When a script routine ends, any local variables that you defined are automatically deleted.

Global variables are stor ed in the global environment variab le table and may be accessed by any script file. You create global variables by using the command to change a local variable to a global variable. For more information about the

export

deleted when a script f ile ends. System variables, which are read-only, are create d only dur ing a Telnet session. You cannot have the same variable name in the local and the global variable

tables. You can delete local and global va riab les b y using the You can also change the value of a global variable by using an y of the set variable commands (

sprintf

). For more information about these commands, see Chapter 2.

command, see Chapter 2. Globa l variables are not automatic ally

arrayenv, cutenv, enumenv, instenv, let, mibget, setenv

export

unsetenv

command.

, or

The value of a v ariable in the local or g lobal ta ble tak es p recedence ove r

Note:

a variable with the same name in the system variable table.

Special Variables

This section describes how to use input variables, how to prompt for user entry from the console, and how to acce ss and format information from the MIB.

Input Parameters

The Technician Interface reserves the following variable s as input parameters for a script file: $1, $2, $3, $4, $5, $6, $7, $8, $9 and $#. The special variab le contains the number of parameters entered on the command line following the script file name. It is set to zero if no parameters are entered. For more information about input parameters, see “

1-4

” in Chapter 2.

run

303563-A Re v 00

Prompting for Input

The input prompt varia ble allows you to create a prompt that accepts user input from the Technician Interface console. The syntax of the input prompt variable is

<prompt_string>

you entered between the bracke ts (< >). In the following script,

setenv ans “$<Enter your name: >” echo “Your name is $ans”

Creating a Script File

. The Technician Interface pro mpts the user with the message

Enter your name:

T echnician Interface substitutes the value for

name is

followed by the name entered by the user.

For instruct ions on using the

appears on the user’s console. After the user enters a val ue, the

Your

setenv

and displays the message

ans

command and the

command, see

echo

Chapter 2.

Polling the Console for Input

You can spec ify how much time a user has to respond to a prompt (that is, to press Return) before the system times out. If you do not specif y a timeout value, the system prompts the user for input until the user responds.

To specify a timeout value, enter the fol lowing command, where

<value_in_seconds>

is the length of ti me, in seconds, th at the s ystem will wa it for

a response before timing out.

let SYS_IO_TIMEOUT = <value_in_second s>

The timeout value cannot exceed the timeout specified by one of the following MIB object s: wfSerialPort.wfSerialPortTimeOut.0 or wfTelnet.wfTelnetSerialPortTimeOut.0. For example, if you speci fy a timeout of 600 seconds and the timeou t specif ied b y wfSeri alPort.wfSerialPortTimeOut.0 = 5 minutes, the system uses the timeout value given by wfSerialPort.wfSerialPortTimeOut.0.

303563-A Rev 00

For instruct ions on using the

command, see Ch a pter 2.

let

1-5

Writing Technician Interface Scripts

In the following sc ript, if the user does not press Return before the time specifie d for SYS_IO_TIMEOUT has elapsed, console:

let SYS_IO_TIMEOUT = 10 setenv ans “$<Enter your name: >” echo “Your name is $ans” if “$ans” = “” then; \ echo “nothing entered”

To change the timeout back to an indefinite waiting period, use the following command:

unsetenv SYS_IO_TIMEOUT

For more information about using the commands in the prece d ing examp l es, s ee Chapter 2.

Accessing MIB Information

The Technician Interface scri p t facility al lows you to assign the value of a MIB attrib ute to a v a riable . Using the synt ax to the following types of MIB variables:

nothing entered

appears on the user’s

, you can refer

1-6

• Counter varia bles, which keep track of how many times an ev ent occurs.

• Display string v aria bles, which spe cify a pi ece of inf ormation s tored i n ASCII

characters, and which the syste m can display for the user to read. The string must be shorter than 255 characters.

• Gauge variable s, which keep track of values that fluctuate.

• Integer v ariables, which specify information in the form of a simple integer.

303563-A Re v 00

Creating a Script File

The variabl e values

is the name or identifie r of the object (for exampl e, wfSnmp).

is the name or identifie r of the attr ibute (for example,

, and

are defined as follows:

wfSnmpDisable).

is the identifie r of a nontabular obje ct or the index value of a tabular

object (for exampl e, 1). For more information about

, see Using Technician

Interface Software.

Using the syntax

, you can refer to the

following type s of data:

• Opaque string data

• Octet string data Opaque and octet string data are hexadecimal numbers that start with 0x. The variable value index is the byte offset into the opaque or octet string data. An

offset of 0 r eturns the lengt h of the data in b yte s. Each b yt e is a ccessed, one b yte a t a time, using the index number. For example, to acces s the v alue of a byte in an octet string, use the following procedure:

Enter

object.attribute.instance

$(wfHwBase.wfHwBpRev.0[0])

The system returns the number of bytes in the octet string (for example, 4).

Enter

object.attribute.instance[n

$(wfHwBase.wfHwBpRev.0[3])

example, the third byte).

Formatting a MIB Entry

octetfmt

The using the specif ied format type. Fo r more info rmation about using the command, see Chapter 2.

303563-A Rev 00

command formats a MIB entry with an Octet or Opaque data type

(for example,

[0]>

) to get the length of the da ta i n by tes.

(for example,

) to get the value of the sele cte d by te (for

octetfmt

1-7

Writing Technician Interface Scripts

Defining a Pseudo-Variable Array

The Technician Interface scri p t facility al lows you to define a pseudo-variable array. A true array is a set of consecutiv e memory locations used to store data. Each item in the array is called an element. An element is a variable. To reference an element of an array, you use a number called the index. In a pseudo-variable array, the elements (variables) are not in consecutiv e memory locations. To create a pseudo-array, use variable names that end in numbers (for example,

). The following script shows how to access a member of an array using an

index:

setenv a1 one setenv a2 two setenv a3 three let index=2 echo “a[$index]=${a[$index]}”

a1, a2

, and

a[2]=two

is displayed on the user’s console.

For specific instructions on using the commands in the previous example, see Chapter 2.

Creating and Using Variables

This section explains how to view local and global variables, how to set variables, and how to delete them.

Viewing Variables

You view the current list of variables stored in the local and global environment variable tables using the

getenv a

the system responds You can also use the For specific instructions on using the

getenv

a = blue

echo $

<variable_name>

command. For example, if you enter

command to view a variabl e.

getenv

and

commands, see Chapter 2.

echo

1-8

303563-A Re v 00

If you access the Technician Inter fa ce via Telnet, the Technician Interface also displays the v ariables in the system environment v ariable table. Variables in this table are read-only from the Technician Interface. If your Telnet client supports the environment variable option, you can use Telnet to send your UNIX envir onment variables to the T echnician Interface’s system list. See your Telnet client documentati on for instructions.

Note:

table, have the same name, the one in the local or global table is used.

Setting Variables

The Technician Interface provides several ways to set variables, depending on what you want to accomplish in y our script. Th is sec tion lists the ways you can set variable s. For details on each of the following commands, see Chapter 2.

• To assign an ASCII string or numeric value to a variable in the local

environment variable table, use the

Creating a Script File

If two vari ables, one in the system table and one in the local or global

setenv

command.

303563-A Rev 00

When you assign a value to a variable, you do not type the

before the

variable. If the value contains spaces or tabs, place double quotes (“”) around the value string. In the following command, you assign the value

to the variabl e a.

Menu setenv a “Statistics Menu”

Statistics

• To define a pseudo-var iable array that contains the list of MIB instance IDs

for a give n MIB object name, use the The

instenv

command builds a pseudo-variable array by appending an index

instenv

command.

number to the v ariable name specified on the command line. Each member of the pseudo-va riable array contains a single instance ID. The size of the pseudo-array is store d at ind ex 0.

We recommend that you use the

Note:

instenv

command. The

mibget

50 percent faster than the

mibget

command accesses MIB tables appr oximately

instenv

comman d.

command instead of the

• To select parts of a text string and write them to a pseudo-variable array, use

the

cutenv

comman d.

1-9

Writing Technician Interface Scripts

• To convert and for mat text, and save the result in a specified variable for later

use, use the

sprintf

• T o e v al uate a simpl e arithmeti cal or logical expr ession and assi gn the result to

a given var i a b l e , use th e

command evaluates an expre ssion from left to right (def ault). You can

let

The use parentheses to change the order of the evaluation.

• To write a list of command line arguments into a pseudo-variable array , use

the

arrayenv

command.

You can append arg uments to the end of an existing vari able array with the option. If an argu ment conta ins spaces, place double quote s (“”) around it ( for example,

“enclose this one”

command.

let

command.

-a

• To assign a sequence of values to a list of variable names, use the

command. You must indicate a starting number and, optionally, you can specify a value by which to incr ement the v al ues in the series . You can use the sequence you have created as named indices of an array variable. Primari ly, you use this command with the created by that command.

Deleting Variables

To delete one or more variables from the local or global environment variable table, use the

unsetenv a

the system deletes v ariable a from the table. You cannot delete a variable from the system environment variable table. You can delete all var iables that are part of a pseudo-variable array by using the

wildcard character *. For example, to delete all variable s that begin with enter the following command:

unsetenv array_*

unsetenv

arrayenv

command to index the value s

command. For example, if you enter

enumenv

array_

1-10

For specific instructions on using the

unsetenv

command, see Chapter 2.

303563-A Re v 00

Setting the Current Volume or Directory

When you set the current working v olume or directory using the cd (change directory) command, you are set ting the global variable “PWD” to the value you specify in the command, as sho wn in the following script:

cd 3: echo $PWD 3: getenv PWD PWD = “3:”

Controlling Program Flow

The Technician Interface provides several commands to control program flow in your script. For details on each of the following commands, see Chapter 2.

Creating a Script File

• To specify the next line to be exec ute d from the script file, use the

goto

command. With in the script file, use the

command with a label. A label begins and

goto

ends with a colon (:), consists of up to 15 alphanu meric characters and the underscore character (_), and must be on its own line, beginning in column 1.

• T o evaluate whether an e xpressio n is t rue, use th e

command. The express ion

can compare two numerical v a lues or two ASCII strings. If the expression is true, the script interpreter executes any additi onal commands that are on the same command line as the

command. If the expression is false, the script

interpreter does not execute the if command. You use a semicolon (;) to e nd an

command. The semicolon separates the if

command from the commands you want ex ecute d if the if command is true.

• To suspend the Tec hnician Interface’s operation for a given interval, use the

command. During this time the router is still running.

pause

• To call a subroutine inside the same script file, use the

gosub

command. It must be the last command on a line. You can nest subroutines up to 10 deep. You use the When the

return

the instructions on the line following the line containing the

command in a subroutine to return to the calling routine.

return

command executes, the script interpreter begins executing

gosub

command.

303563-A Rev 00

1-11

Writing Technician Interface Scripts

Writing Messa ge s to the Cons o le

The Technician Interface provides two commands to display messages on the console:

• Use the

command to display command line arguments to the user’s

echo

terminal.

• Use the

command to convert, format, and print input arguments on the

printf

T echnician Interface’s console.

For details on each of these commands, see Chapter 2.

Saving Console Messages to a File

To save to a file all messages that are written to the console terminal, use the

record

command.

The record fi le must be opened before re cording, and the fi le must be cl osed when recording is completed. The file will be lost if it is not closed before the file system is unmounted or the router is reset.

For specific instructions on using the

record

Perf orming Error Recovery

T o spe cify an error handler la bel withi n a script f ile , use the a command returns an error or if you attempt to abort the scr ipt file, the script interpreter goes to the error handler label defined in the file. If you press Ctrl-c to abort the script, the Technician Interface displays the following prompt:

command, see Cha p te r 2.

on error

command. If

1-12

Terminate script file? (y/n):

You can use the

on error

without returning an error messa ge if the

command with the -s flag to allow the scr ipt to rec over

on error

command cannot locate a

specifie d script f ile . The follo wi ng e xample sh o ws t he

flag:

-s

on error -s :ERROR_HANDLER:

For more information about the

on error

command, see Chapter 2 in this manual.

on error

command with the

303563-A Re v 00

Inserting Comments

You can insert comments into the script file. Comments begin with a pound sign (#) in column 1, as shown in the following example:

# The 'echo' command is used to # output messages to the user’s console.

When you execute a script file, the system does not display the comments on the user’s console.

Debugging a Script File

Creating a Script File

To enable the debug trace facility, use the the trace facility, the Technician Interface displays each command read from the script file before and after its variables have been expanded. For instructions on using the

verbose

command, see Chapter 2.

Saving and Restoring Variables

To save the current list of local and global variables to a file, use the command. For example, to save the variables to a file named test, enter the following c ommand:

save env test

To read and execute the commands in a Technician Interface script file, and to ensure that the router saves (restores) all local variables when the script ends, use the

source env

For example, to run the script file test on volume 2, and to restore upon completion all local va riables saved previously to test, enter the following command:

source env 2:test

T o lo cate script errors, use the command. The Technician Interface displays each line from the file before it executes the line, enabling you to easily locate errors.

command.

verbose on

verbose

command. When you enable

command and then use the

save env

source env

303563-A Rev 00

For more information about the Chapter 2.

sa ve env

and

source env

commands, see

1-13

Writing Technician Interface Scripts

Running a Script File

To read and execute the commands in a Technician Interface script file, and to ensure that the router deletes all local variables when the script ends, use the command.

For example, to run the script file test on volume 2, deleting upon script completion all local va riables saved previously to test, enter the following command:

run 2:test

run

To locate script errors, use the command. The Technician Interface displays each line from the file before it executes the line, enabling you to locate errors easily.

You can use the returning an error message if the file. The following example shows the

run -s install.ba

The

Note:

the script file name you specify. If you issue the command system fir st looks for a file named install. If it cannot find this file, it looks for a file named instal l.bat.

For more information about the

Creating Menus

The menu utility allows you to edit existing script menus and to create your own menus. For instructions on using the menu utility, refer to Using Te chnician Interface Scripts.

verbose on

command with the -s flag to prevent the system from

run

command automatically appends the .bat suffix to the end of

run

command, see Ch ap ter 2.

run

command and then use the

command cannot locate the specified script

command with the -s flag:

run

run install

run

, the

1-14

You can also edit a script menu by directly editing the appropriate .mnu file. Appendix A shows exam ples of a script menu and a script.

303563-A Re v 00

+ 86 hidden pages

Avaya Writing Technician Interface Scripts User Manual

Writing Technician Interface Scripts

Contents

Tables

Before You Begin

Preface

Text Conventions

Acron yms

Bay Netwo rks Technical Publications

How to Get Help

About Variables

Local, Global, and System Variables

Special Variables

Input Parameters

Prompting for Input

Polling the Console for Input

Accessing MIB Information

Formatting a MIB Entry

Defining a Pseudo-Variable Array

Creating and Using Variables

Viewing Variables

Setting Variables

Deleting Variables

Setting the Current Volume or Directory

Controlling Program Flow

Writing Messa ge s to the Cons o le

Saving Console Messages to a File

Perf orming Error Recovery

Inserting Comments

Debugging a Script File

Saving and Restoring Variables

Running a Script File

Creating Menus