Amanda Amanda Portal Telephone Features User manual

Amanda Portal System Reference Manual
Version 1.27E
The Amanda Company, Inc.
January 9, 2003

Contents
1 Introduction 5
1.1 CoreFeatures............................................. 6
1.2 Tcl As An Extensible Glue Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2.1 An Introduction to Tcl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2.2 Tcl and Multithreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
1.2.3 Tcl and State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
1.2.4 Assigning Scope to Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
1.3 ControlFlow ............................................. 32
1.4 Waiting for Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
1.5 LoadableDLLs ............................................ 35
1.6 Resource Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2 Security Model 40
2.1 Ancestors and Descendents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.2 Privileges ............................................... 40
2.3 Login and Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3 How Amanda Portal Interacts with Telephone Switches 46
4 Mailboxes 49
4.1 Box Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.2 BoxSettings ............................................. 54
1

5 Multimedia Objects (MMOs) 63
5.1 Messages and Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5.2 MMODatabase............................................ 80
5.3 Announcements............................................ 84
5.4 PublishedMMOs........................................... 88
6 Voice and Fax Devices 90
6.1 OOPModel.............................................. 90
6.2 Interconnection Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.3 Make local and Default Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
6.4 Network Device Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.5 VPCommands ............................................ 98
6.6 PortMessages.............................................109
6.7 Miscellaneous Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
7 Fax Commands 113
8 Internet E-Mail 115
9 Serial Devices 121
10 Miscellaneous Databases 125
10.1 List Mapping Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
10.2 Trie Mapping Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
11 The Configuration Database 133
12 Triggers 138
12.1 Autoschedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
12.2 Notifications and the Job Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
12.2.1 The Notify Record Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
2

12.2.2 The Notify Instance (Job Queue) Database . . . . . . . . . . . . . . . . . . . . . . . . 144
12.2.3 The Notify Template Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
12.3 Data Triggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
13 Persistent Procedures 162
14 Integration 164
14.0.1 Serial Integration Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
15 Call Queueing 168
16 Connecting to External Databases (ODBC) 191
17 Miscellaneous 197
17.1 The tokens Command........................................200
17.2 Time Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
17.3 Terminating Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
17.4Logging ................................................207
17.5 Speech Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
17.6 Web Client Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
17.7 TCP Client Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
17.8 VoIP Appliance Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
17.9COM/OLE ..............................................217
A Error Codes and Messages 218
3

Preface
In all of the function definitions in this document, if there is a ‘*’ next to the function name, you can execute
the function when you aren’t logged in. Otherwise, you must be logged into the system. In a related vein,
many functions have the notion of a current box. When you don’t give the -box option, they operate on the
current box. When you are not logged in, there is no notion of a current box and these functions require the
-box option.
Commands syntax is verb noun. Normally, if a command can return one or more results, the ‘s’ suffix is
left off the command (e.g.,set box setting rather than set box settings). This makes it easier for the
programmer to remember the name of the command. Commands that require a box parameter (e.g.,is box)
do not use the -box syntax; the box is simply given as a required parameter. The -box syntax is for options
only.
A fundamental theme in Amanda Portal is the notion of the box hierarchy and permissions related to the
box hierarchy. Boxes create other boxes in an ancestral tree structure. Generally, unless specified otherwise,
boxes only have permission to modify their box settings and the settings of their descendents. They cannot
modify the setting of their proper ancestors.
Every command in this document can get a “usage” error if you call the command wrong. In this case,
errorCode will be set to USAGE and interp->result will be the usage of the function.
Many commands in this system may process half an argument list before discovering an error. This means
that half of the arguments changed values in the database and the other half didn’t. Care is taken to
alleviate this problem as much as possible though, for example, by checking the syntax of the arguments
before executing transactions against the database.
4

Chapter 1
Introduction
The Amanda Portal system consists of a core set of functionality, which defines basic building blocks from
which a variety of call processing systems can be built. A variety of plug-in modules, in the form of Windows
DLLs, can be installed which augment the functionality of the core. By using plug-in DLLs, a system can
be configured to load only the code and features that it requires. Since third parties can also develop these
DLLs, there is a great deal of flexibility and extensibility in the system. The core and the plug-in modules
together define an API which is similar to that of an operating system. They define a security model, provide
networking features, etc.
Above this “API” layer is a scripting language, the Tool Command Language (Tcl), which is now familiar
to over one million programmers world-wide. The scripting language serves two different purposes:
1. It acts as a “glue” to tie together the functionality of the different loadable modules (DLLs). As such,
it acts as a very high level language for voice processing needs.
2. It allows quick and easy customization of an existing system, or rapid development of whole new voice
processing solutions. The entire [e-mail] Telephone User Interface (TUI) consists of
only a few thousand lines of Tcl code.
This architecture has several advantages:
•It separates functionality (how a particular task is implemented) from behavior (why a particular task
should happen, such as a certain sequence of DTMF digits were input by a user).
•Because Tcl is the only interface to the system, network and telephone clients use exactly the same
interface to accomplish tasks within the system. There is exactly one function which can be used to
send voice mail to a mailbox, for instance; this function is used by all types of clients.
•Because the functionality is implemented in C++, it operates very efficiently, while the telephone user
interface is scripted because this is where a great deal of flexibility is required. The TUI Tcl script
is basically just implementing flow of control across all the possible functional calls (record, play, get
digits, send voice mail, etc.).
•Since all the functionality is implemented in C++ and is not maliable, it is possible to implement a
secure system. Users are allowed to execute any Tcl commands that are made available to them but
cannot side-step the security model that is built into the system at the lower level.
5

•This architecture allows the TUI to be completely flexible without having to reimplement any func-
tionality at lower levels. For instance, it would be quite possible to build a speech-recognition based
voice mail system which would be quite different from the DTMF-based, [e-mail]-like
interface that is currently provided. The menuing system would presumably be much “flatter,” but
the underlying features such as sending and listening to voice mail, changing mailbox settings, etc.,
would remain exactly the same at the C++ level.
1.1 Core Features
The core module implements a number of fundamental objects in the system: mailboxes, MultiMedia Objects
(MMOs), a number of databases (the MMO lookup table, the voice mailbox database, etc.), an autoscheduler,
a notifier and outbound call job management system, etc.
As part of the system’s security model, mailboxes are arranged in a hierarchy. Every mailbox has a “parent”
mailbox which is the one which created it. A mailbox may be given the right to create subordinate, or
children, mailboxes. A top-level mailbox’s parent is itself, since no mailbox created it, and such a box is
referred to as a superbox in this manual. Such a mailbox is given certain special privileges in Amanda Portal,
similar to the “root” user on a Unix system. Unlike Unix, however, there can potentially be more than one
top-level mailbox (a “forest” of mailbox trees), although it is unlikely that this feature will be needed in
practice.
Mailboxes have several components: they have some settings (the list of settings is extensible to make
development of new applications more flexible), they have a set of privileges which have known semantics to
the core, they may have messages which they have received, and the messages in turn may have zero or more
MMOs associated with them. Boxes may “publish” MMOs for others to use, such as greeting recordings.
Boxes can establish autoschedule and notify records which cause the system to execute Tcl code on their
behalf when certain events happen or certain times arrive.
1.2 Tcl As An Extensible Glue Language
Tcl makes a good embedded systems language because it is high-level, easy to extend the language by adding
C functions as Tcl primitives and has security mechanisms built in using the nested interpreter model and
“code injection”1. Nested interpreters give you an operating system like “system call” interface where you
write your “system calls” in Tcl. In this model, the system calls always exist in your interpreter. If you are
not allowed to perform a call, the system call returns an error. The master interpreter operates in “kernel”
mode and the slave interpreter operates in “user” mode.
Code injection works slightly differently. The protected calls you need to use don’t check whether you have
permission to execute them; instead, the calls don’t exist in your interpreter until a specified event happens
(such as you log in). At this point, the call is inserted into your interpreter and you can use the new calls.
When you log out, the calls are removed from your interpreter.
Tcl is a Lisp like language so writing code with it is quite “functional.” You often write code like
eval modify elements [get elements handle]
1A tAA defined term.
6

where get elements returns the operands to operate on as a Tcl list and modify elements operates on
those operands. Tcl also helps extensibility by being interpreted. This means that you can add code on the
fly to your program and modify the behavior of the code shipped with the system. Tcl also has associative
arrays built in; these are the regular Tcl array variables. Internally, they are implemented as hash tables
so lookup on them is very speedy. Multi-dimensional arrays can be simulated in Tcl by using concatenated
indices in regular arrays.
1.2.1 An Introduction to Tcl
Safe interpreters are simply regular interpreters with certain “unsafe” calls removed; that is, they are inter-
preters where some unsafe code has already been “dejected.” All Tcl interpreters in Amanda Portal are of
the “safe” variety, and as such, they have only the following standard Tcl commands: append,array,break,
case,catch,concat,continue,error,eval,expr,for,foreach,format,gets,global,if,incr,info,
interp,join,lappend,lindex,linsert,list,llength,lower,lrange,lreplace,lsearch,lsort,proc,
regexp,regsub,return,scan,set,split,source,string,switch,time,trace,unset,uplevel,upvar,
and while.
This subsection gives a brief description of each of these commands. Those who are already familiar with
Tcl should skip ahead to the next section. There are many books available which cover the Tcl language,
including Tcl and the Tk Toolkit, by Tcl’s author, John Ousterhout, and Tcl For Dummies, in the famous
“Dummies” series. While those books should be consulted for in-depth examples, they also cover many more
features of Tcl, plus the Tk graphical extensions, which are not used in Amanda Portal.
Tcl Variables
Programming languages contain two fundamental elements: variables and procedures. Object-oriented lan-
guages combine these two features into objects (naturally). Variables in Tcl have three attributes:
name The variable’s name allows access to its contents.
scope The scope of a variable determines how long it will live. When it goes out of scope, a variable is
automatically destroyed.
value Finally, each variable has a value.
In many programming languages, variables have a fourth attribute, a type, which determines the kind of
data that the variable can have as its value, the size of the date (range of values, length of a string, etc.). In
these languages, variables are declared, and a variable can exist without having a defined value.
Tcl’s variables, like those of [e-mail], do not have a specific type. Internally, they are all
represented as strings and are converted on-the-fly as needed to other types (floating point, integer) when
necessary. This feature makes Tcl programming easier. A variable springs into existence the first time it is
used. This also means that it’s impossible to have a variable which does not have any value.
To create a variable in Tcl, you use the set command, like this:
set variable value
For example, to set the variable myname to Tim, you would simply type
7

set myname Tim
To access the value of a variable, put a dollar sign in front of its name. For sample, to copy the value of the
variable myname to a second variable called firstname, you would type
set firstname $myname
This process is called variable substitution: the name of the variable is replaced by its value.
Each executable statement in Tcl consists of a single command line, which is terminated with a newline or
a semicolon. For instance,
set x 14
set y 27
could just as easily be written
set x 14; set y 27
Tcl evaluates each command line using a two-step process: parsing and execution. During parsing, the
command line is divided into space-separated arguments, then variable substitution and other processing is
performed on the arguments. At this point, Tcl doesn’t attach any meaning to the arguments themselves;
it’s just doing simple string substitutions.
In the execution step, the first argument of the line is treated as a command name to be run. The other
arguments on the command line are passed on to the command, which will apply meaning, if any, to them.
The command will return a string value as the result of its processing. In each of the examples above, the
command name was set.
What would happen if you tried to execute the command
set name Tim Morgan
This is a problem because set will see three arguments rather than the two it’s expecting (a variable to set
and a value to set it to). Just as in Amanda/DOS, we can overcome this problem by using quotation marks
to “hide” the space from the parser:
set name "Tim Morgan"
Now suppose that we have two variables, firstname and lastname, and what we need is the person’s full
name. We can achieve this by writing
set name "$firstname $lastname"
8

On the other hand, if we write
set name {$firstname $lastname}
then no variable substitution will be performed. We can also mix and match:
set salary "$firstname $lastname \$30,000"
This would expand the values of firstname and lastname, but it would leave the dollar sign before 30,000.
Be careful of the following types of commands:
set x 4
set y x
set z x+y
set $y 5
The first sets xto 4, as expected, but the second command sets yto the string x, not to the value of x.
Remember that Tcl does not associate any meaning with the arguments as it parses them. Therefore, the
third command simply sets variable zto the string x+y. We’ll learn how to accomplish addition shortly.
The last command sets xto 5, not y.
We have already seen an example of backslash substitution when we used $to produce a literal dollar sign
character in a string. Many of the backslash substitutions are the same as those in Amanda/DOS:
Symbol Meaning
\a Audible alert (bell)
\b Backspace
\f Formfeed
\n Newline
\r Return
\t Tab
\v Vertical tab
\ddd Octal value
\xhh Hex value
\newline Single space
\$ Dollar sign
\\ Backslash
\[ Open square bracket
Tcl Lists
A Tcl list is an ordered collection of strings. In its simplest form, a list is simply a string, with spaces
separating the list’s elements. In this case, the elements cannot contain spaces.
Lists are usually written surrounded by curly braces. Sublists, or elements with spaces, are denoted by inner
braces. For example,
9

set x {a b {c d e} f}
sets xto a list containing four elements. The third element is the list (or string) cde.
Tcl contains a number of built-in functions for manipulating lists.
Built-In Commands and Procs
So once the command to execute has been determined, and Tcl knows what the arguments are, what happens
next? Tcl will look up the command name to verify that it’s valid. If it isn’t, then an error is generated.
If it is a valid command, then there are two possibilities: the command is a “built in” one or it’s a “Tcl
procedure.”
Commands (procedures, or “procs”) which you define in Tcl are indistinguishable from the built-in com-
mands, except that the built-in ones are faster and can access operating system and device driver level
calls.
A “built in” Tcl command has its underlying implementation in C. In this case, Tcl invokes the corresponding
C procedure and processing of the command is done in compiled code. The set command is a built-in, for
example.
Tcl defines a number of built-in commands, and applications using Tcl can define additional built-in com-
mands. Not surprisingly, Amanda Portaldefines quite a few application-specific commands which will be
covered in the Amanda PortalProgramming class.
So far, we’ve seen two kinds of substitutions which happen automatically to commands: variable and back-
slash. We also know that all Tcl commands (procedures) return a value. This leads to the third type of
substitution, command substition. To illustrate it, we’ll introduce another built-in command, expr.
Expressions
The expr command concatenates all its arguments into one long string, then it evaluates that string as an
expression, and it returns the resulting value as its procedure value (remember that all procedures return a
value in Tcl).
Here are some example interactions with Tcl:
% expr 2*3
6
% set x 4
4
% expr $x * 7
28
% expr ($x * $x) / 2
8
%
10

Now we’re ready to discuss the third type of substitution, command substitution. Recall that every command
returns a string result. Command substitution allows us to replace a complete Tcl command with its result
for use in an enclosing command. To use it, just enclose a command inside square brackets: []. For example:
% set x 4
4
% set y 7
7
% set z [expr $x * $y]
28
%
Arrays
So far, the variables we’ve used have been simple variables, also called scalar. Tcl also provides another
kind of variable, called an associative array. An associative array is a collection of different values which are
indexed by a string (the element name). This is a very powerful mechanism, and associative arrays are used
extensively in Amanda Portal.
Array elements thus have two names: the name of the array plus the name of the element. The element
name is enclosed in parentheses. It may be a constant or a variable (or a combination), so long as it doesn’t
contain a space. If the element name has a space, then the entire variable name must be quoted to “hide”
the space.
For example, we could collect information on a person this way:
set person(name) "Tim Morgan"
set person(age) 37
set person(address) "23822 Brasilia Street"
set person(city) "Mission Viejo"
set person(state) California
set person(zip) 92691
On the other hand, if we have information about a number of people, we might use one array per attribute,
and use the names as the indices:
set age(Tim) 37
set address(Tim) "23822 Brasilia Street"
set city(Tim) "Mission Viejo"
set state(Tim) California
set zip(Tim) 92691
set age(Siamak) 36
set address(Siamak) "26321 Eva Street"
set city(Siamak) "Laguna Hills"
set state(Siamak) California
set zip(Siamak) 92656-3108
We can use the values in the array pretty much just as with simple variables:
11

% set foo $age(Tim)
37
% set name Tim
Tim
% set foo $age($name)
37
% set foo [expr $age(Tim) + $age(Siamak)]
73
%
Besides set, Tcl defines a few other built-in functions for working with variables:
append Appends one or more values to a variable.
incr Adds a value to an existing numeric variable.
unset Deletes one or more variables.
array Returns various information about array variables.
The syntax for the append command is as follows:
append varname value . . .
If varname is an existing variable, then value will be appended to it, as will any additional values.
If varname didn’t exist previously, then it is set to value as if the set command had been used.
Like set,append returns the new value of varname as its result.
The incr command is exactly like the +token in Amanda/DOS. It allows you to do an arithmetic addition
to an existing numeric variable. The value added may be positive or negative, and it defaults to 1.
% set i 1
1
% incr i
2
% incr i 2
4
% incr i -3
1
%
The variable must exist and have an integer value. The incr function returns the new value as its result.
The unset command is used to delete a variable and its associated value(s). If an array variable is deleted,
then all of its elements are deleted. The general syntax for the command is:
unset var . . .
12

The unset command always returns an empty string as its result:
% set age(Tim) 37
37
% set age(Siamak) 36
36
% unset age
%
The Array Command
The array command allows you to obtain information about a Tcl array. The general syntax is:
array cmd name args
where cmd is a special keyword for the array command. Some of the available keywords are:
names ary Returns a Tcl list of the names (valid indices) for array ary.
size ary Returns the number of elements in array ary.
exists var Returns whether var exists and is an array.
get name pattern Returns a list of pairs of element names and values from the array name. If pattern is
specified, then only those elements whose names match pattern will be returned. A list of name and
value pairs is called an a-list.
set name list Sets elements of the array name from list which should be of the same form as is returned
by array get.
Normally, the array command will be used in conjunction with command substitution along with some other
commands which we’ll examine next week. In the mean time, here are some standalone examples of array,
using the age array we defined earlier:
% array size age
2
% array names age
Tim Siamak
Notice that the result of the array names command will list the names in arbitrary order. If you want it
sorted a particular way, you can use the lsort command discussed on page 16.
Tcl Expressions
Expressions combine values with operators to produce a new value. Simple examples follow everyday arith-
metic rules. For example:
13

% expr (8+4) * 6.2
74.4
%
In addition to the usual binary operators +,-,*, and /, there are a number of other important unary and
binary operators (and there are some less important ones which we won’t mention). There’s also %, which
computes the remainder from a division (this is the “mod” or “modulo” operator).
Most operators are called binary because they work on two values. For instance, +is a binary operator since
it is used to add two different values, which are written on either side of it.
Unary operators, in contrast, are operators which work on a single value which comes after the operator.
The most familiar one of these is unary minus, which negates the value of its operand.
% set x 4
4
% set y [expr -$x]
-4
%
The other important unary operator is logical not, which is written !. It changes true values to false, and
false values to true.
In Tcl, as in C, logical values are represented as numeric values. A false value is represented as 0, while a
true is any non-zero value. Therefore,
% set x 4
4
% set y [expr !$x]
0
% set x [expr !$y]
1
%
Relational operators are binary operators to compare one value to another. They all work on integer, real
(floating point), and string values.
Syntax Result
a<b 1 if a < b else 0
a>b 1 if a > b else 0
a<=b 1 if a≤belse 0
a>=b 1 if a≥belse 0
a==b 1 if a=belse 0
a!=b 1 if a6=belse 0
Often you want to combine the results of more than one logical test. The logical operators allow you to do
so. They follow the same syntax as in the C language.
14

Logical and is represented as &&. The expression a&&b is true (1) if both the expressions aand bare non-zero,
and zero otherwise.
Logical or is represented as ||. The expression a||b is true (1) if either of the expressions aor bis true,
and zero otherwise.
As in C, these operators are short-circuit: the second operand is not evaluated if the first shows the result
of the whole thing.
Here are some examples of logical operators:
% set a 1
1
% set b 0
1
% expr a&&b
0
% expr a || b
1
% expr b || a
1
% expr b && exp(sin(sqrt(2.0))) > 4
0
% expr a || exp(sin(sqrt(2.0))) > 4
1
%
In the last two examples, function foo is not called, because the result can be determined from the value of
the first argument alone.
List Commands
Tcl defines quite a few commands for operating on lists. We’re going to look at the following ones:
lindex Retrieves individual elements from a list.
llength Returns the length of a list.
lsort Returns a new list resulting from sorting an existing list.
lappend Appends new items to an existing list (variable).
split Returns a list by spliting up a string at each point where a given substring occurs.
The lindex function returns as its value an element of a list. The general syntax is:
lindex list index
The index must evaluate to an integer. The first element of the list is number 0. For example:
15

% set mylist {a b {c d e} f}
ab{cde}f
% lindex $mylist 1
b
% lindex $mylist 2
cde
%setx{abcde}
abcde
% lindex $x 4
e
%
The llength function simply returns the number of elements in a list. Its syntax is
llength list
Continuing from the previous example:
% llength $x
5
% llength $mylist
4
% set len [llength [lindex $mylist 2]]
3
%
The lsort command returns a new list which is created by sorting an existing list. The syntax is:
lsort flags list
The flags parameter can be a combination of a type and a direction. The types are:
-integer Treat the list elements as integers.
-ascii Treat the list elements as strings (default).
-real Treat the list elements as floating point (real) numbers.
The direction can be one of the following:
-increasing Sort the items in ascending order (default).
-decreasing Sort in decending order.
Here are some examples of lsort:
16

% set x {22 12 9 97}
22 12 9 97
% lsort $x
12 22 9 97
% lsort -integer $x
9 12 22 97
% set sorted_list [lsort -integer $x]
9 12 22 97
%
The lappend command appends one or more values to a variable as list elements. It creates the variable if it
doesn’t already exist. It differs from append because with lappend, the items are appended with separating
spaces and will be given braces where necessary to keep items separate; append simply appends each string
as-is.
The general syntax is:
lappend varname value . . .
The lappend function returns the new value of varname as its result value.
Here are some examples:
% set x {a b c}
abc
% lappend x d e f
abcdef
% lappend x "Tim Morgan" "Carl Doss"
a b c d e f {Tim Morgan} {Carl Doss}
% llength $x
8
%
Notice that in the second lappend command, two values are being appended. This is reflected in the result
of llength: there are eventually 8 items in the list.
The split command creates a new list by splitting up a string. You can specify a set of separator characters
as the second argument, or let it default to standard white-space characters.
% split "abc/def/ghi" "/"
abc def ghi
% split "abc.def/ghi" "/."
abc def ghi
%
17

* linsert
Description
linsert can be used to insert items into an existing list variable at a particular index.
* lrange
Description
lrange can be used to extract a range of items from a list (returning a new list).
* lreplace
Description
lreplace can be used to create a new list from and old list with a range of items replaced by a new set of
items (not necessarily the same number of items).
Eval
One final note on parsing. Sometimes you have a list of items in a variable, and you want to pass that list
as arguments to some command, such as lappend. Here’s an example of the problem:
% set mylist {a b c}
abc
% set additional_items {d e f}
def
% lappend mylist $additional_items
abc{def}
%
What we really wanted was to get a resulting list of {abcdef}, not {a b c {d e f}}. The eval
command lets us solve this and other similar problems.
18

The eval command takes one or more arguments and concatenates them into one long string. It then
evaluates (executes) this string as as a Tcl command. Let’s look at how we’d use eval in the previous
example:
% set mylist {a b c}
abc
% set additional_items {d e f}
def
% eval lappend mylist $additional_items
abcdef
%
Why does this work? The eval command sees three arguments: lappend,mylist, and a string “def”
(the quotation marks aren’t part of the string). It appends all of these strings together, with separating
spaces, arriving at the new command string “lappend mylist d e f” (again, the quotation marks aren’t
part of the string). Then eval executes the command, and mylist gets three new elements instead of one
sublist element.
Control Flow
Normally, a program is executed sequentially, one statement after the previous one. Most programming
languages, including Tcl, provide two basic ways to vary this.
Branching means skipping to or past some statements. This is provided with the if and switch commands.
Looping allows a set of statements to be repeated zero or more times. This is provided by the while,for,
and foreach commands, along with their helper commands break and continue.
The general syntax for the if statement is:
if test1 body1 [elseif test2 body2 . . . ] [else bodyN]
The testnvalues may be any expression which evaluates to a Tcl boolean value (zero or non-zero). Typically,
they will include relational operators. The bodynvalues may be any Tcl statement or list of statements.
Remember that statements may be separated by semicolons or returns, and uninterpreted lists may be
written using curly braces, and they “hide” any embedded returns.
19