Amanda Work Group 7xx Installation Manual

							Chapter 11:
Programming Amanda
Using Tokens
The Token Programming Language allows you to write programs for 
Amanda. These programs consist of tokens entered in Extension fields 
(defined per mailbox using Amanda Administrator’s Mailbox window or 
Amanda Standalone’s Users screen) and/or in Method fields (defined per 
mailbox using Amanda Administrator’s Notify window or Amanda 
Standalone’s Notify Screen). This section describes the language and 
introduces you to common programming terms. Understanding these terms 
can help you understand any programming language.
A token is a sequence of one or more characters that represents an action that 
Amanda can perform. The tokens that you use most often are simple and 
perform routine actions such as dialing an extension. However, a program 
can be much more complicated than that.
With the Token Programming Language, you can use tokens to do either of 
the following:
 Enhance Amanda’s normal processing of the Extension and Method 
fields. Normally, she uses Programmed Call Progress Monitoring 
(PCPM).
In this case, you add the tokens where appropriate within the field.
For example, 147H is a sequence of four tokens that tells Amanda to 
dial the DTMF digits 147 (for extension 147) and then hang up. Notice 
that the tokens are not separated by spaces (or any other characters). 
You write tokens one right after the other.  
						

							150 Installing [email protected]
 Stop Amanda’s normal processing of the fields and tell her what to 
do.
In this case, the first character in the field is @. Then you add the tokens 
that tell Amanda what to do.
For example,
@
R(G1,%S1)
assigns the DTMF digits entered by the caller to a variable named %S1. 
This starts with an @ to indicate that you are NOT processing this 
Extension field normally.
Normal processing for the Extension field: Amanda plays “Please hold 
while I try that extension,” puts the caller on transfer hold, then evaluates the 
tokens in the field. Unless told to do otherwise, she listens for call progress 
tones and an answer.
The @ stops Amanda from performing the dial code that puts a caller on 
transfer hold (also known as the dl_dtwait dial code). As explained in 
Installing [email protected]/DOS, you use the Setup utility (selection 1) 
to set or view the dial codes. The codes are stored in 
C:\AMANDA\PBX.DB\1001.PBX, which you can view or edit using the 
JOVE utility.
Normal processing of the Notify Method field: Amanda tries to access a 
port for an outbound notification call. The @ stops Amanda from going off-
hook.
When most people think of a program, they think of a series of lines, each of 
which contains a single action or command. The Token Programming 
Language is similar, but each line become the contents of a different field, 
using the Extension field of a mailbox.
If the program contains only a few lines, sometimes you can use just one 
Extension or Method field for the entire program. However, when you need 
more fields, you use the Extension fields from additional mailboxes. Even if 
a Method field must be extended, you extend it to the Extension field in 
another mailbox.  
						

							Chapter 11: Programming Amanda 151
You use additional fields for any of the following reasons:
 The logic of the program branches or repeats. You use a G() com-
mand or I() command to create the branch or loop. See “Flow of 
Control: Branching and Looping” on page 162 for more details.
 The length of the string of tokens exceeds 65 characters, so you are 
forced to continue in another field. You use a G() command to ex-
tend the token string to a new Extension field.
Mailbox Settings
If you are using a mailbox’s Extension field for token programming, you 
must use all of the following settings:
 Do Not Disturb must be off. Amanda ignores the Extension field al-
together if Do Not Disturb is on.
 Call screening must be off. 
Success and Failure
Amanda evaluates tokens from left to right. If Amanda performs a token 
successfully, she goes on to the next token. 
When all the tokens have been performed successfully in an Extension field, 
Amanda goes to the RNA Chain field. If the RNA field is blank, she goes to 
the Done Chain field for the company greeting mailbox (usually mailbox 
990). 
When all the tokens have been performed successfully in the Notify Method 
field, Amanda goes to the next Notify Method field (if there is one). If there 
are no more Notify Method fields, Amanda goes to the Done Chain field for 
the current mailbox.
If the token is unrecognized (because of a syntax error or a typographical 
error) or fails, Amanda immediately goes to the Done Chain field without 
processing the rest of the tokens in the field. If the last successful token gives 
Amanda an invalid mailbox, she processes the Done Chain field for the 
mailbox associated with the current port because she cannot locate a Done 
Chain field for the invalid mailbox. (The mailbox associated with the port is 
usually 990, the Company Greeting mailbox.)  
						

							152 Installing [email protected]
For a literal or system variable, there is no such thing as failure. The token 
always succeeds. Some tokens define almost any behavior as successful. For 
example, you can have Amanda spell an empty string. Amanda doesn’t say 
anything, but no failure occurs either. 
Tracing Token Execution
Amanda’s trace files can let you know where and how a token program is 
failing. This is an invaluable debugging tool. 
Amanda creates trace files as she runs, because the following trace command 
should be in the AUTOEXEC.BAT file.
amanda /t5 /s1300
Like the default trace command, this command creates 
C:\AMANDA\TRACE.OUT file and limits its size to the last 1.3MB of data. 
(A file this size will fit on a 3 1/2-inch floppy disk.) What is different about 
this command is that it writes to the trace file every 10 lines. In this way, if 
Amanda crashes while running your token program, no more than ten lines 
of trace information can be lost. You can use /t with a number less than 10 if 
you need to, but it will slow down the system.
You can also display trace information on-screen.
To display trace information for a standalone system:
1. Press Ctrl+Home.
2. Press Alt+T.
Pressing any key stops the display. On-screen traces are stored by default in 
C:\AMANDA\SCREEN.OUT. To change the name of this file, use the Setup 
utility to change the setting for the configuration option screen_save.
To display trace information on Amanda Voice Server:
Press T. 
						

							Chapter 11: Programming Amanda 153
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]/DOS. 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). 
						

							154 Installing [email protected]
Variables
Each variable is the name of a storage location within the computer that can 
store a string or a whole 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 11: Programming Amanda 155
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.  
						

							156 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.
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.” 
						

							Chapter 11: Programming Amanda 157
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 
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. 
						

							158 Installing [email protected]
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.