Amanda Work Group Installation Manual

							Chapter 15: Programming Amanda 179
Press O to stop the display. On-screen traces for Amanda Voice Server are 
not stored in a file. You can create trace files using Amanda Monitor. For 
details, see Administering [email protected]. You can use Amanda 
Monitor to display on-screen traces as well.
Kinds of Tokens
Tokens fall into the following categories: 
 Literals
Variables
 Commands
Literals
A literal is an exact value such as the whole numbers 4 or 1144. Notice that 
you do not use commas within numbers. You use 1144—not 1,144.
The DTMF digits and most single-character tokens are literals. For example, 
the comma (,) that causes a pause is a literal.
Another type of literal is the string. In the Token Programming Language (as 
in most programming languages), a string is a sequences of characters. For 
example, JAMES DOLE is a 10-character string that starts with the letter J 
and ends with the letter E. To clearly show where a string begins and ends, 
programming languages require delimiters (characters that enclose the 
string, but are not part of it. In the Token Programming Language, you use 
single or double quotation marks as string delimiters. So JAMES DOLE 
becomes JAMES DOLE or JAMES DOLE. 
9, is a string that Amanda might dial for an outside line. It consists of the 
DTMF digit 9 followed by the comma for a pause.
A string that has no characters is called the empty string. It often occurs in 
programming and is written as  or .
If you use one kind of quotation mark within a string, you should use the 
other kind as the string’s delimiters: Amandas or Do not use  (the double 
quotation character). 
						

							180 Installing [email protected]
Variables
Each variable is the name of a storage location within the computer that can 
store a string or a -hole number. After you store something in a variable, you 
can use that variable’s name instead of typing the string or the number. This 
is useful because:
 Amanda’s variables have simple names (no more than four charac-
ters) and save you typing time. (You are less likely to make a mistake 
typing a short variable name than a long string.)
 You can change the contents of the storage location and still use the 
same variable. 
 Amanda can perform the same set of tokens over and over again with 
different values because the tokens use the variables rather than the 
values. For example, if you change the telephone number stored as a 
variable, Amanda dials the new number without you having to 
change any tokens.
The Token Programming Language has system, port, and global variables. 
Each of them starts with a percent sign (%).
System variables are controlled by Amanda. For example, %D contains the 
amount of available disk space, and %C contains the number of the port 
currently in use.
Port variables are controlled by you. Their names range from %S0 to %S19. 
Port variables provide 20 locations in which to store information on a per-
port basis. The %S0 accessed by Amanda while using one port is not the 
same location as the %S0 accessed by Amanda while using another port.
Global variables are also controlled by you. Their names range from %G0 to 
%G9. These 10 locations are used by all the ports. The %G2 accessed by 
Amanda while using one port is exactly the same location as the %G2 
accessed by Amanda while using another port. 
						

							Chapter 15: Programming Amanda 181
Assignment
You control port and global variables. For example, you can assign numbers 
or strings to them and later change those numbers or strings. For example, 
you might assign the value of 65 to %G4 and the value Amanda to %S9. 
Assigning a value to a variable copies that value to the variable’s storage 
location. 
Initially, each port and global variable has the empty string as its value. 
Assignment is done in the Token Programming Language using the 
assignment command, which starts with the equal sign (=). When the 
variable contains a number, you can add to that number or subtract from it 
using the command that starts with a plus sign (+).
For example, =(%S1,24) puts the number 24 in the variable named %S1. 
+(%S1,15) adds 15 to the 24 in %S1 and then stores the sum 39 in %S1.
+(%S1,-10) subtracts 10 from the 39 in %S1 and then stores the difference 
29 in %S1.
Commands
Commands are more complex than literals and variables. Commands 
perform actions. For example, a command may tell Amanda to play a 
particular message or go to another mailbox. 
Each command has a name followed by a series of parts called parameters. 
Some parameters contain information that Amanda needs to perform the 
command. Others contain information that Amanda obtains for you as she 
performs the command. Each parameter is a literal, variable, or another 
command. 
The parameters are delimited (surrounded) by parentheses and separated by 
commas. For example, P(M8) tells Amanda to play message number 8. The 
command name is P, and its only parameter is M8, which is surrounded by 
parentheses.  
						

							182 Installing [email protected]
The command P(0745,T) tells Amanda to say the number 0745 as a time. It 
also has the command name P, but it has two parameters: the number 0745 
and the literal T. 
						

							Chapter 15: Programming Amanda 183
When a command is referred to by name in this guide, the parentheses 
appear after the command’s name. For example, the command named P is 
referred to as the P() command, which is read as “the P command.”
Parameters
Parameters can be required or optional. The syntax places brackets […] 
around optional parameters.
Parameters can also be for input or for output. Input parameters provide the 
information that Amanda needs in order to perform the action that you 
requested. For example, Amanda might need the name of the file in which to 
store a fax or the telephone number for a pager. You supply the input 
parameters and make sure that the information in them is correct. Input 
parameters can be literals, variables, or other commands. 
Output parameters are parameters that store information you asked Amanda 
for. Output parameters are always variables because Amanda must store the 
information you requested in a storage location. Usually one command asks 
for the information, Amanda stores the information in a variable, and 
another command uses that variable. For example, you might use the V() 
command to retrieve a telephone number from a file. If the output parameter 
for the telephone number is %S5, Amanda stores the telephone number in 
the variable %S5. Then you use %S5 in a T() command to send a fax using 
that telephone number. 
The syntax in the guide does not indicate which parameters are input and 
which are output. This is clear from the descriptions of the command and 
parameters. 
When a string is used as a parameter, you don’t always need the quotation 
marks, because the commas and parentheses serve as delimiters. You must 
use the quotation marks when a variable is part (but not all) of the string. For 
example, if %S0 is MARY and %S5 is HU, the string MARY HU can be 
used as a parameter with or without quotation marks, but the strings %S0 
HU, %S0 %S5, and %S0 %S5 must have quotation marks. Most 
programming languages do not allow you to put variables within strings. The 
Token Programming Language allows this, but it only checks for variables  
						

							184 Installing [email protected]
within a string if you delimit that string with quotation marks. You cannot 
use a number from 0 to 9 after %S1 in a string because Amanda assumes that 
you meant the variable %S10 or %S11, etc.
Most system variables do not have parameters. However, a couple of system 
variables have parameters that affect the contents of that system variable. For 
example, to use %I, the system variable that retrieves data from specific 
fields of specific messages, you use parameters to indicate which field, 
message number, and mailbox you want the data from.
Syntax
The exact sequence of characters for each token is defined by its syntax, so 
you have to learn to read syntax. The following table shows the conventions 
used in this guide. They are similar to the syntax conventions used for other 
programming languages.
For example, the following is the syntax for %I:
Syntax:
%I(
field,
msg_no[,
mailbox])
Syntax ConventionMeaning
boldBold is used for characters that must be 
used by you exactly as they appear—if 
you use them at all.
italicsItalics are used for characters that you 
must replace with real strings, numbers, 
variables, or other commands. 
[   ]The syntax inside the brackets is optional. 
If you don’t use this syntax, its default is 
used.
{   }The syntax inside braces can be repeated.  
						

							Chapter 15: Programming Amanda 185
%I() has three parameters: field, msg_no and mailbox.
Because the %I and parentheses are bold, you know that you have to include 
them in the command. The commas are bold, but the one in front of mailbox 
is inside brackets […], which surround optional parts of the syntax. If you 
use the bracketed part of the syntax, you must use the comma.  
						

							186 Installing [email protected]
Because field is italicized, you know that it is a place holder for information 
that you must provide. Field can be any one of the following fields 
associated with messages:
D for the Date field
T for the Time field
F for the From field
Because msg_no is also italicized, you know that it is a place holder for 
information that you must provide. For example, to find out the date for 
message number 8, you replace msg_no with the number 8. Because mailbox 
is inside brackets, you replace it only if you use that part of the syntax. For 
example, you may want to delete a message belonging to mailbox 151.
Whenever a parameter is optional, such as mailbox, it has a default. A default 
is the value that is used for the parameter whenever the parameter is missing. 
The default for mailbox is the current mailbox.
Using the syntax, you can create any number of %I() commands. For 
example, %I(D,8) provides the date for message 8 for the current mailbox, 
and %I(T,6,151) provides the time for message 6 for mailbox 151.
Both the Extension and Notify Method fields can contain up to 65 characters. 
If you need more than 65 characters for your program, you use:
 A command that reads additional tokens from a file
 The G() command to tell Amanda to go to the Extension field for an-
other mailbox and process the tokens she finds there 
						

							Chapter 15: Programming Amanda 187
Files and Directories
This section points out what you need to know about files and file names 
when using the Token Programming Language. It assumes that you already 
know the following and other facts about files and directories:
 DOS files are stored in directories.
 The complete name for a file starts with the root directory (usually 
C:), lists the subdirectories leading to the file, and ends with the 
name of the file, each of which is separated by a backslash (\). 
When you use a DOS file name as a parameter, you must replace each 
backslash (\) found in the name with either two backslashes (\\) or one 
forward slash (/). For example, C:\AMANDA\FOOBAR.TXT must become 
either C:\\AMANDA\\FOOBAR.TXT or C:/AMANDA/FOOBAR.TXT.
You can use variable names as parts of the file name. For example, if %S1 is 
C:, and %S2 is Amanda, you can use %S1\\%S2\\FOOBAR.TXT.
Amanda can read text files (also called ASCII files) as well as files in dBase 
format. The former have file names that usually end with .TXT, and the latter 
have file names that end with .DBF. Amanda can read from, write to, and 
search files that contain database records. A record is a way to group pieces 
of information. For example, your name and address is a record in a database 
for any company that sends you supplies. The individual parts of your name 
and address are fields of that record. In a database, another name for a record 
is a row, and another name for a field is a column.
Sample Address Record: 
First Name: MARY Last Name: HU
Street Address: 28291 HOOVER ST.
City: WINTER FALLS State: MI
Zip: 48444 
						

							188 Installing [email protected]
Text files that contain database records should have commas separating each 
field of each record and a carriage return/linefeed separating one record from 
another. (A carriage return/linefeed is the pair of ASCII characters placed in 
a file when you press Enter on your keyboard.) 
Sample Address Record as a line in a text file:
MARY,HU,28291 HOOVER ST.,WINTER FALLS,MI,48444
When Amanda reads records from a text file, you tell her the number of the 
fields you want to read or change the data in. The fields are numbered 
starting with 1. In our example, First Name is 1, and Last Name is 2.
dBase files are created using dBase, a database software product. For dBase 
files, you tell Amanda the name of the field instead of its number. When 
Amanda reads data from a dBase file, she deletes any spaces at the end of the 
data as she stores the data into a variable. For example, if the field contains 
MARY             , Amanda reads only MARY.
Flow of Control: Branching and Looping
When programming Amanda, you often type the tokens for a program in 
more than one field. This is not because you have exceeded the 65-character 
limit for the Extension or Notify Method field, but because you want to 
control the flow of token processing. For example, the only way to have 
Amanda perform different actions based on the value of a variable, is to put 
the tokens for one set of actions in another Extension field. 
The commands that control the flow of tokens are:
 The I() command which compares two values. (Notice that this is not 
the same as the %I() command/system variable discussed earlier in 
this chapter.) This command is similar to the If command or If state-
ment in other programming languages. It is used to branch in either 
of two directions, depending on whether the comparison is true or 
false. If the comparison is true, Amanda goes to another mailbox’s 
Extension field and processes the tokens there. If the comparison is 
false (for example, %S1 is not equal to the empty string), Amanda 
continues processing tokens where she is.