| Introduction BLAST features a sample script, Autopoll, which allows your UNIX system to call a series of remote computers and exchange information unattended. Autopoll performs the following tasks:
Autopoll checks carefully for errors while polling. If
an error is detected, the problem site is scheduled to be retried. Only
the file transfer commands that failed are attempted again.
^ top Installing Autopoll Autopoll consists of nine scripts that were copied into your BLAST directory (usually /usr/blast) when the BLAST program was installed in your system. The scripts are:
If you downloaded autopoll as a compressed archive (autopoll.tar.Z) you will need to unpack the archive in the following manner: 1. Copy the autopoll.tar.Z file to the directory in which you want to store autopoll using the cp command. For example, to copy
the autopoll.tar.Z file to /usr/blast type the following:cp autopoll.tar.Z /usr/blast 2. Get into the directory in which autopoll.tar.Z was copied using
the cd command. For example to get into the /usr/blast directory
type the following:cd /usr/blast 3. Uncompress the archive using the compress -d command.compress -d autopoll.tar.Z 4. Unpack the archive using the tar -xvf command.tar -xvf autopoll.tar The scripts may be moved to any convenient directory in your system.
For instance, you could segregate Autopoll from other BLAST files by creating
a poll directory:cd /usr/blast In addition to these script files, you must have a BLAST setup called autopoll. This setup resides in the BLAST setup directory (usually /usr/blast), and it must include a valid communications port or hunt file and other connection information, such as modem type and baud rate. Optionally, you may also specify the script autopoll.scr in the Script File field of the setup, which will simplify the command line to start Autopoll. ^ top Starting Autopoll Autopoll must be started from the directory in which the Autopoll scripts
and support files (site and transfer command files) are found. If blast.exe
is not in this directory, you need to add the full path for blast.exe
to your PATH or give the full path in the command line. If autopoll.scr
has been entered in the Script File field of the autopoll setup, the
format for invoking Autopoll from the command line is:
Here are some example command lines: blast autopoll 3 retail 10:45In the first example, a maximum of three attempts will be made to poll the sites listed in the file retail.dat, starting at 10:45 am. Notice that the command line specifies just the stub ("retail") of the site filename, retail.dat. (Autopoll appends a variety of extensions to the filename stub to determine the names of special files.)In the second example, one attempt will be made immediately to poll the sites in northwest.dat; the job will be placed in the background (&) with terminal output suppressed (-n).The third example illustrates the use of the trace option. A start time can be optionally specified with TRACE. ^ top Configuration Files Autopoll uses three separate files for configuration. At a minimum, autopoll must have a "Site File", a "Transfer Command File", and an "Autopoll Setup." This section will outline creation of these and other files which are necessary to run Autopoll. The site file is the "master list" of information about the
sites to be polled. Site files may use any valid filename, but the extension
must be ".dat". Each line in the site file holds the parameters
needed to connect with and transfer files to and from one site. Each
line, or site record, consists of five fields separated by exclamation
marks ("!", also called "bangs"), in the form:
Each line must contain four bangs. Any fields that are to be skipped must be indicated by consecutive bangs ("!!"). Blank lines and lines beginning with a pound sign ("#"), space, or tab will be skipped, so you may freely comment your site file. Lines may not exceed 100 characters in length.Examples: ....|....1....|....2....|....3....|....4....|....5....In the first example, no setup is specified so autopoll.su will
be loaded. The site name will be "Blaster", overriding the Description
field of the setup; the phone number will be 1(919)542-0939; the baud
rate will be taken from the setup since that field is blank; and the transfer
command file will default to autopoll.tcf since the field is blank.In
the second site record, the setup store06.su will be loaded. The site
name, phone number, and baud rate will default to the values given in
store06.su. The command file will be nightly.tcf.In the last site record,
the file NewYork.su will be loaded. The site name will be "Albany",
the phone number will be 782-8311, the baud rate will be set to 19.2 kbps,
and the command file will be ny.tcf.
Autopoll uses a standard BLAST Transfer Command File (TCF) to specify the files to be sent and received. You may use a unique TCF for each site or the same TCF for several sites. A complete description of the Transfer Command File format can be found in the User Manual.Autopoll treats wildcards and remote commands (such as remote print and remote rename) as "try once" specifications. These transfers and commands are attempted during the first cycle only. Even if errors occur, Autopoll does not attempt the transfers or commands again. For this reason, wildcards and remote commands must be used with caution. Autopoll uses standard BLAST Setup files (.su files) to specify site-dependent configuration information. You may run Autopoll with either one or multiple setup files. Please note, whether you use one or multiple setup files, you must always create an autopoll.su setup file.You may use one setup file (autopoll.su) if all of the following conditions exist.
Autopoll script files, transfer command files, and site files must be stored in the same directory, which must be your current working directory. Setup files must be stored in the directory specified by the SETUPDIR environment variable. ^ topConfiguration Example Suppose you have been asked to set up a polling network for a client who has a central UNIX system and two remote UNIX sites. The sites are configured as follows:
Because the logins are different, different BLAST setup files are created for each site ("sam" and "metro"). The site file, retail.dat, for the polling network then becomes: ....|....1....|....2....|....3....|....4....|....5....The first line of the file is treated as a comment since it begins
with a space. The last two lines are the site records. Actually, the site
records may be duplicating information already in the setups since BLAST
setups contain fields for the Phone Number and Description. If so, the
site records could be simplified:....|....1....|....2....|....3....|....4....|....5....The site file now has an additional comment line; otherwise it
is equivalent to the previous site list.According to the site list, a
command file called sams.tcf will be executed when Autopoll connects to
Sam's Discount Mart. The command file metro.tcf will be executed when
Autopoll connects to Metro Army Surplus (The rules for writing command
files are described in the User Manual). Suppose you needed to get two
files from Sam and send him one. The TCF sams.tcf might look like this:....|....1....|....2....|....3....|....4....|....5....The "+" sign in column 1 of the first two lines signifies
that BLAST will per form a GET. Thus, BLAST will get /usr/buz/acq12.txt
and /usr/buz/wk_82 from Sam. The files will be called /usr/client/sam1
and /usr/client/sam2 respectively on the local system. The last line of
the TCF signifies a SEND because it does not begin with "+".
Thus, BLAST will send /usr/tmp/read_me to the remote system. Since the
remote filename is not specified, BLAST will use the same name on the
remote side. The /OVW switch signifies that BLAST may overwrite an existing
file of the same name on the remote system.Luckily, metro.tcf is similar to sams.tcf: ....|....1....|....2....|....3....|....4....|....5....These files--retail.dat, sams.tcf, and metro.tcf--are created using a standard text editor (e.g., vi) and saved in the same directory as the Autopoll scripts.With the required files ready, the BLAST command line to start Autopoll could then be: blast autopoll 3 retail which specifies a maximum of three attempts to complete the polling session with retail.dat. ^ top Other Files That Use the Site Filename Stub Autopoll distinguishes several special files by appending different extensions to the site filename stub. The extensions are shown below.
^ top Long and Short Summaries The Autopoll status files summarize the activities of a polling session.
Two summary files are generated. Printed at the end of polling, the
short summary is most helpful when polling goes well since a quick glance
is all it takes to see the outcome of the polling session. The long
summary is helpful for troubleshooting.A typical short summary file
looks like this:
^ top Autopoll under cron cron is a UNIX-supplied scheduler. To run Autopoll under cron, you
will need to create a crontab file that launches BLAST. Usually, the
crontab specifies a shell procedure that starts BLAST after setting
some environment variables like BLASTDIR and SETUPDIR.A typical crontab
file could consist of a single entry: Tips and Tricks Keep it SimplePolling sessions can quickly become complicated if there are many remote sites and several file transfers that must be performed with each one. Create simple but sensible directory structures to support the polling network. As a rule of thumb, command files should contain lines no longer than 80 characters so that they can be easily viewed and edited on standard terminals.Problems Don't "Just Go Away"In a large polling network, it is not uncommon to have a few remote sites that consistently stumble. Especially frustrating are intermittent difficulties. Take some time to study problem sites carefully.
Exploiting BPRINTER The summary file is printed by the BLAST script LPRINT command, which is tied to the BPRINTER environment variable. You can alter the behavior of LPRINT by changing the definition of BPRINTER in the shell environment. For example, Autopoll can append summaries to an archive instead of printing them if BPRINTER performs a concatenation: BPRINTER="cat %s >> /usr/blast/summaries"BLAST substitutes %s for the name of the short summary when the
command is executed. For more information about BPRINTER, see the BLAST
User Manual.^ top Modifying Autopoll Because Autopoll is written in BLAST's scripting language, it is very easy to modify. The Autopoll scripts are thoroughly commented, and the BLAST User Manual contains a complete description of BLAST's scripting language with many examples. Feel free to customize Autopoll to your exact needs. The behavior of Autopoll can also be changed by writing one or more user-supplied scripts. Autopoll checks for the existence of these scripts at various points during execution. If it finds a user-supplied script, the script is CALLed. Autopoll tests the value of @STATUS when the script returns; polling continues normally if @STATUS equals 0; otherwise the site is marked as failed.User-supplied scripts reside in the same directory as the Autopoll scripts. They are CALLed at the following places during execution:
Because BLASTscript variables are global, a user-supplied script must be careful not to disturb the contents of any variables needed by Autopoll. The following variables may be changed freely by any user-supplied script:
You can also create new variables if you wish. To prevent confusion, it is suggested that new variables begin with "u", e.g., @uvar2. File I/O with User-Supplied Scripts Autopoll opens file handles 1-7 at various points during execution. The handles have the following functions:
Any of the handles reserved for utility I/O may be opened by user-supplied scripts as long as the handles are freed before the scripts return to Autopoll (i.e., each user script must close its own files). User scripts may also write to the status files, handle 5 and handle 7, if they wish. An example of this technique is shown below.Autopoll closes the log file before calling user-supplied scripts. If a user script opens a log of its own, the log must be closed before execution returns to Autopoll.NOTE: If TRACE is specified, a user-supplied script cannot use the TCAPTURE command because TRACE uses the capture buffer for its own use. The following script is an example of a user-supplied script creating
a. command file on a remote UNIX system consisting of all the files
in a given target directory. The file is retrieved for use by Autopoll
in the normal way. This script provides a way to GET an unspecified
number of files from the remote system without sacrificing Autopoll's
ability to recover from file transfer errors. Configuration Worksheets The following "worksheets" may help you organize the large
amount of information needed to set up a polling network successfully.A.
List the machines in your polling network. |