Amanda Work Group Manual

							Chapter 9: Miscellaneous111
To have different company greetings:
 In the Per Port Settings of the Setup utility, change the mailbox for the company 
greeting on a per port basis. 
The Setup utility’s basic operation is explained in “Logging On to Amanda” on 
page 5.
Suppose the first company uses ports 1 and 2, and the second company uses ports 3 
and 4. Then box_grt for ports 1 and 2 might be set to mailbox 990, while box_grt for 
ports 3 and 4 might be set to mailbox 880.
Per port settings are stored in the install.cfg file.
To have different employee directories: 
 In the Per Port Settings of the Setup utility, change the mailbox for the employee 
directory on a per port basis. 
For example, box_idx for ports 1 and 2 might be set to mailbox 411, while box_grt for 
ports 3 and 4 might be set to mailbox 311. 
						

							112 Installing [email protected]/Windows
Per port settings are stored in the install.cfg file.
To use different mailboxes for direct messaging:
 In the Per Port Settings of the Setup utility, change the mailbox for the direct mes-
saging on a per port basis.
For example, box_snd for ports 1 and 2 might be set to mailbox 998, while box_grt 
for ports 3 and 4 might be set to mailbox 888.
Per port settings are stored in the install.cfg file. 
						

							Chapter 9: Miscellaneous11 3
If two departments share an Amanda system, you might use the default mailboxes for one 
department and create another set for the other department. If you intend to use the 
defaults, don’t overwrite these mailboxes when you create new mailboxes for employees. 
For more information about default mailboxes, see “Using Default and Recommended 
Mailboxes” on page 53.
Queuing Unanswered and Busy Calls
In certain environments (such as Automatic Call Distributors—ACDs), a combination of 
two global settings parameters allows you to queue all unanswered calls, not just busy 
calls. 
You set both treat_rna_as_busy and auto_queue to True.
The other way to accomplish this, by putting the ring tones in the tone table with a BUSY 
code, does not allow you to set the number of rings that must occur before the busy signal 
is returned. 
						

							114 Installing [email protected]/Windows 
						

							Chapter 10:
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) and/or in Method fields (defined per mailbox 
using Amanda Administrator’s Notify window). 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. Nor-
mally, the system 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 sepa-
rated by spaces (or any other characters). You write tokens one right after the other. 
 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, the system 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 “Using Setup to Define Codes, 
Integration Patterns, and Other Parameters” on page 7, 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. 
						

							116 Installing [email protected]/Windows
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. 
You use additional fields for any of the following reasons:
 The logic of the program branches or repeats. You use a G() command or I() com-
mand to create the branch or loop. See “Flow of Control: Branching and Looping” 
on page 124 for more details.
 The length of the string of tokens exceeds 65 characters, so you are forced to con-
tinue in another field. You use a G() command to extend 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 altogether 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, the 
system 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, the system 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, the 
system processes the Done Chain field for the mailbox associated with the current port 
because the system cannot locate a Done Chain field for the invalid mailbox. (The 
mailbox associated with the port is usually 990, the Company Greeting mailbox.) 
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.  
						

							Chapter 10: Programming Amanda 117
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 the system 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:
Press T.
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]/Windows. 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. 
						

							118 Installing [email protected]/Windows
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).
Any string can contain the following special characters:
\A Attention, which is a bell sound (Ctrl+G)
\B Start of transmission (STX; Ctrl+B)
\D End of transmission (Ctrl+D)
\N Newline (Ctrl+J)
\R Return (Ctrl+M)
\T T
AB (Ctrl+I)
\\  Backslash, the actual \ character
\octal_numberAllows any ASCII character to be specified. Replace octal_number with any 
number in octal, rather than decimal, format. The Windows calculator allows you 
convert decimal numbers to octal numbers with characters ranging from 0–8.
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 characters) 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 val-
ues 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.
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.  
						

							Chapter 10: Programming Amanda 119
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 the system 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. 
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. 
						

							120 Installing [email protected]/Windows
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 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.