In this chapter, we look at a number of self-contained scripts, with an emphasis on concise networking. Along the way, we work towards creating building blocks that encapsulate often needed functions of the networking world, show new techniques that broaden the scope of problems that can be solved with @command{gawk}, and explore leading edge technology that may shape the future of networking.
We often refer to the site-independent core of the server that
we built in
section 2.10 A Simple Web Server.
When building new and non-trivial servers, we
always copy this building block and append new instances of the two
functions SetUpServer
and HandleGET
.
This makes a lot of sense, since this scheme of event-driven execution provides @command{gawk} with an interface to the most widely accepted standard for GUIs: the web browser. Now, @command{gawk} can even rival Tcl/Tk.
Tcl and @command{gawk} have much in common. Both are simple scripting languages that allow us to quickly solve problems with short programs. But Tcl has Tk on top of it and @command{gawk} had nothing comparable up to now. While Tcl needs a large and ever changing library (Tk, which was bound to the X Window System until recently), @command{gawk} needs just the networking interface and some kind of browser on the client's side. Besides better portability, the most important advantage of this approach (embracing well-established standards such HTTP and HTML) is that we do not need to change the language. We let others do the work of fighting over protocols and standards. We can use HTML, JavaScript, VRML, or whatever else comes along to do our work.
At first glance, the "Hello, world"
example in
section 2.8 A Primitive Web Service,
seems useless. By adding just a few lines, we can turn it into something useful.
The PANIC program tells everyone who connects that the local site is not working. When a web server breaks down, it makes a difference if customers get a strange "network unreachable" message, or a short message telling them that the server has a problem. In such an emergency, the hard disk and everything on it (including the regular web service) may be unavailable. Rebooting the web server off a diskette makes sense in this setting.
To use the PANIC program as an emergency web server, all you need are the @command{gawk} executable and the program below on a diskette. By default, it connects to port 8080. A different value may be supplied on the command line:
BEGIN { RS = ORS = "\r\n" if (MyPort == 0) MyPort = 8080 HttpService = "/inet/tcp/" MyPort "/0/0" Hello = "<HTML><HEAD><TITLE>Out Of Service</TITLE>" \ "</HEAD><BODY><H1>" \ "This site is temporarily out of service." \ "</H1></BODY></HTML>" Len = length(Hello) + length(ORS) while ("awk" != "complex") { print "HTTP/1.0 200 OK" |& HttpService print "Content-Length: " Len ORS |& HttpService print Hello |& HttpService while ((HttpService |& getline) > 0) continue; close(HttpService) } }
GETURL is a versatile building block for shell scripts that need to retrieve files from the Internet. It takes a web address as a command-line parameter and tries to retrieve the contents of this address. The contents are printed to standard output, while the header is printed to `/dev/stderr'. A surrounding shell script could analyze the contents and extract the text or the links. An ASCII browser could be written around GETURL. But more interestingly, web robots are straightforward to write on top of GETURL. On the Internet, you can find several programs of the same name that do the same job. They are usually much more complex internally and at least 10 times longer.
At first, GETURL checks if it was called with exactly one web address.
Then, it checks if the user chose to use a special proxy server whose name
is handed over in a variable. By default, it is assumed that the local
machine serves as proxy. GETURL uses the GET
method by default
to access the web page. By handing over the name of a different method
(such as HEAD
), it is possible to choose a different behavior. With
the HEAD
method, the user does not receive the body of the page
content, but does receive the header:
BEGIN { if (ARGC != 2) { print "GETURL - retrieve Web page via HTTP 1.0" print "IN:\n the URL as a command-line parameter" print "PARAM(S):\n -v Proxy=MyProxy" print "OUT:\n the page content on stdout" print " the page header on stderr" print "JK 16.05.1997" print "ADR 13.08.2000" exit } URL = ARGV[1]; ARGV[1] = "" if (Proxy == "") Proxy = "127.0.0.1" if (ProxyPort == 0) ProxyPort = 80 if (Method == "") Method = "GET" HttpService = "/inet/tcp/0/" Proxy "/" ProxyPort ORS = RS = "\r\n\r\n" print Method " " URL " HTTP/1.0" |& HttpService HttpService |& getline Header print Header > "/dev/stderr" while ((HttpService |& getline) > 0) printf "%s", $0 close(HttpService) }
This program can be changed as needed, but be careful with the last lines.
Make sure transmission of binary data is not corrupted by additional line
breaks. Even as it is now, the byte sequence "\r\n\r\n"
would
disappear if it were contained in binary data. Don't get caught in a
trap when trying a quick fix on this one.
Today, you often find powerful processors in embedded systems. Dedicated network routers and controllers for all kinds of machinery are examples of embedded systems. Processors like the Intel 80x86 or the AMD Elan are able to run multitasking operating systems, such as XINU or GNU/Linux in embedded PCs. These systems are small and usually do not have a keyboard or a display. Therefore it is difficult to set up their configuration. There are several widespread ways to set them up:
In this section, we look at a solution that uses HTTP connections
to control variables of an embedded system that are stored in a file.
Since embedded systems have tight limits on resources like memory,
it is difficult to employ advanced techniques such as SNMP and HTTP
servers. @command{gawk} fits in quite nicely with its single executable
which needs just a short script to start working.
The following program stores the variables in a file, and a concurrent
process in the embedded system may read the file. The program uses the
site-independent part of the simple web server that we developed in
section 2.9 A Web Service with Interaction.
As mentioned there, all we have to do is to write two new procedures
SetUpServer
and HandleGET
:
function SetUpServer() { TopHeader = "<HTML><title>Remote Configuration</title>" TopDoc = "<BODY>\ <h2>Please choose one of the following actions:</h2>\ <UL>\ <LI>About this server</LI>\ <LI>Read Configuration</LI>\ <LI>Check Configuration</LI>\ <LI>Change Configuration</LI>\ <LI>Save Configuration</LI>\ </UL>" TopFooter = "</BODY></HTML>" if (ConfigFile == "") ConfigFile = "config.asc" }
The function SetUpServer
initializes the top level HTML texts
as usual. It also initializes the name of the file that contains the
configuration parameters and their values. In case the user supplies
a name from the command line, that name is used. The file is expected to
contain one parameter per line, with the name of the parameter in
column one and the value in column two.
The function HandleGET
reflects the structure of the menu
tree as usual. The first menu choice tells the user what this is all
about. The second choice reads the configuration file line by line
and stores the parameters and their values. Notice that the record
separator for this file is "\n"
, in contrast to the record separator
for HTTP. The third menu choice builds an HTML table to show
the contents of the configuration file just read. The fourth choice
does the real work of changing parameters, and the last one just saves
the configuration into a file:
function HandleGET() { if(MENU[2] == "AboutServer") { Document = "This is a GUI for remote configuration of an\ embedded system. It is is implemented as one GAWK script." } else if (MENU[2] == "ReadConfig") { RS = "\n" while ((getline < ConfigFile) > 0) config[$1] = $2; close(ConfigFile) RS = "\r\n" Document = "Configuration has been read." } else if (MENU[2] == "CheckConfig") { Document = "<TABLE BORDER=1 CELLPADDING=5>" for (i in config) Document = Document "<TR><TD>" i "</TD>" \ "<TD>" config[i] "</TD></TR>" Document = Document "</TABLE>" } else if (MENU[2] == "ChangeConfig") { if ("Param" in GETARG) { # any parameter to set? if (GETARG["Param"] in config) { # is parameter valid? config[GETARG["Param"]] = GETARG["Value"] Document = (GETARG["Param"] " = " GETARG["Value"] ".") } else { Document = "Parameter <b>" GETARG["Param"] "</b> is invalid." } } else { Document = "<FORM method=GET><h4>Change one parameter</h4>\ <TABLE BORDER CELLPADDING=5>\ <TR><TD>Parameter</TD><TD>Value</TD></TR>\ <TR><TD><input type=text name=Param value=\"\" size=20></TD>\ <TD><input type=text name=Value value=\"\" size=40></TD>\ </TR></TABLE><input type=submit value=\"Set\"></FORM>" } } else if (MENU[2] == "SaveConfig") { for (i in config) printf("%s %s\n", i, config[i]) > ConfigFile close(ConfigFile) Document = "Configuration has been saved." } }
We could also view the configuration file as a database. From this point of view, the previous program acts like a primitive database server. Real SQL database systems also make a service available by providing a TCP port that clients can connect to. But the application level protocols they use are usually proprietary and also change from time to time. This is also true for the protocol that MiniSQL uses.
Most people who make heavy use of Internet resources have a large
bookmark file with pointers to interesting web sites. It is impossible
to regularly check by hand if any of these sites have changed. A program
is needed to automatically look at the headers of web pages and tell
which ones have changed. URLCHK does the comparison after using GETURL
with the HEAD
method to retrieve the header.
Like GETURL, this program first checks that it is called with exactly
one command-line parameter. URLCHK also takes the same command-line variables
Proxy
and ProxyPort
as GETURL,
because these variables are handed over to GETURL for each URL
that gets checked. The one and only parameter is the name of a file that
contains one line for each URL. In the first column, we find the URL, and
the second and third columns hold the length of the URL's body when checked
for the two last times. Now, we follow this plan:
It may seem a bit peculiar to read the URLs from a file together with their two most recent lengths, but this approach has several advantages. You can call the program again and again with the same file. After running the program, you can regenerate the changed URLs by extracting those lines that differ in their second and third columns:
BEGIN { if (ARGC != 2) { print "URLCHK - check if URLs have changed" print "IN:\n the file with URLs as a command-line parameter" print " file contains URL, old length, new length" print "PARAMS:\n -v Proxy=MyProxy -v ProxyPort=8080" print "OUT:\n same as file with URLs" print "JK 02.03.1998" exit } URLfile = ARGV[1]; ARGV[1] = "" if (Proxy != "") Proxy = " -v Proxy=" Proxy if (ProxyPort != "") ProxyPort = " -v ProxyPort=" ProxyPort while ((getline < URLfile) > 0) Length[$1] = $3 + 0 close(URLfile) # now, URLfile is read in and can be updated GetHeader = "gawk " Proxy ProxyPort " -v Method=\"HEAD\" -f geturl.awk " for (i in Length) { GetThisHeader = GetHeader i " 2>&1" while ((GetThisHeader | getline) > 0) if (toupper($0) ~ /CONTENT-LENGTH/) NewLength = $2 + 0 close(GetThisHeader) print i, Length[i], NewLength > URLfile if (Length[i] != NewLength) # report only changed URLs print i, Length[i], NewLength } close(URLfile) }
Another thing that may look strange is the way GETURL is called.
Before calling GETURL, we have to check if the proxy variables need
to be passed on. If so, we prepare strings that will become part
of the command line later. In GetHeader
, we store these strings
together with the longest part of the command line. Later, in the loop
over the URLs, GetHeader
is appended with the URL and a redirection
operator to form the command that reads the URL's header over the Internet.
GETURL always produces the headers over `/dev/stderr'. That is
the reason why we need the redirection operator to have the header
piped in.
This program is not perfect because it assumes that changing URLs results in changed lengths, which is not necessarily true. A more advanced approach is to look at some other header line that holds time information. But, as always when things get a bit more complicated, this is left as an exercise to the reader.
Sometimes it is necessary to extract links from web pages. Browsers do it, web robots do it, and sometimes even humans do it. Since we have a tool like GETURL at hand, we can solve this problem with some help from the Bourne shell:
BEGIN { RS = "http://[#%&\\+\\-\\./0-9\\:;\\?A-Z_a-z\\~]*" } RT != "" { command = ("gawk -v Proxy=MyProxy -f geturl.awk " RT \ " > doc" NR ".html") print command }
Notice that the regular expression for URLs is rather crude. A precise regular expression is much more complex. But this one works rather well. One problem is that it is unable to find internal links of an HTML document. Another problem is that `ftp', `telnet', `news', `mailto', and other kinds of links are missing in the regular expression. However, it is straightforward to add them, if doing so is necessary for other tasks.
This program reads an HTML file and prints all the HTTP links that it finds.
It relies on @command{gawk}'s ability to use regular expressions as record
separators. With RS
set to a regular expression that matches links,
the second action is executed each time a non-empty link is found.
We can find the matching link itself in RT
.
The action could use the system
function to let another GETURL
retrieve the page, but here we use a different approach.
This simple program prints shell commands that can be piped into @command{sh}
for execution. This way it is possible to first extract
the links, wrap shell commands around them, and pipe all the shell commands
into a file. After editing the file, execution of the file retrieves
exactly those files that we really need. In case we do not want to edit,
we can retrieve all the pages like this:
gawk -f geturl.awk http://www.suse.de | gawk -f webgrab.awk | sh
After this, you will find the contents of all referenced documents in files named `doc*.html' even if they do not contain HTML code. The most annoying thing is that we always have to pass the proxy to GETURL. If you do not like to see the headers of the web pages appear on the screen, you can redirect them to `/dev/null'. Watching the headers appear can be quite interesting, because it reveals interesting details such as which web server the companies use. Now, it is clear how the clever marketing people use web robots to determine the market shares of Microsoft and Netscape in the web server market.
Port 80 of any web server is like a small hole in a repellent firewall. After attaching a browser to port 80, we usually catch a glimpse of the bright side of the server (its home page). With a tool like GETURL at hand, we are able to discover some of the more concealed or even "indecent" services (i.e., lacking conformity to standards of quality). It can be exciting to see the fancy CGI scripts that lie there, revealing the inner workings of the server, ready to be called:
gawk -f geturl.awk http://any.host.on.the.net/cgi-bin/some servers give you a directory listing of the CGI files. Knowing the names, you can try to call some of them and watch for useful results. Sometimes there are executables in such directories (such as Perl interpreters) that you may call remotely. If there are subdirectories with configuration data of the web server, this can also be quite interesting to read.
gawk -f geturl.awk http://any.host.on.the.net/cgi-bin/test-cgi gawk -f geturl.awk http://any.host.on.the.net/cgi-bin/printenv
Caution: Although this may sound funny or simply irrelevant, we are talking about severe security holes. Try to explore your own system this way and make sure that none of the above reveals too much information about your system.
In the HTTP server examples we've shown thus far, we never present an image
to the browser and its user. Presenting images is one task. Generating
images that reflect some user input and presenting these dynamically
generated images is another. In this section, we use GNUPlot
for generating `.png', `.ps', or `.gif'
files.(8)
The program we develop takes the statistical parameters of two samples
and computes the t-test statistics. As a result, we get the probabilities
that the means and the variances of both samples are the same. In order to
let the user check plausibility, the program presents an image of the
distributions. The statistical computation follows
Numerical Recipes in C: The Art of Scientific Computing
by William H. Press, Saul A. Teukolsky, William T. Vetterling, and Brian P. Flannery.
Since @command{gawk} does not have a built-in function
for the computation of the beta function, we use the ibeta
function
of GNUPlot. As a side effect, we learn how to use GNUPlot as a
sophisticated calculator. The comparison of means is done as in tutest
,
paragraph 14.2, page 613, and the comparison of variances is done as in ftest
,
page 611 in Numerical Recipes.
As usual, we take the site-independent code for servers and append
our own functions SetUpServer
and HandleGET
:
function SetUpServer() { TopHeader = "<HTML><title>Statistics with GAWK</title>" TopDoc = "<BODY>\ <h2>Please choose one of the following actions:</h2>\ <UL>\ <LI>About this server</LI>\ <LI>Enter Parameters</LI>\ </UL>" TopFooter = "</BODY></HTML>" GnuPlot = "gnuplot 2>&1" m1=m2=0; v1=v2=1; n1=n2=10 }
Here, you see the menu structure that the user sees. Later, we
will see how the program structure of the HandleGET
function
reflects the menu structure. What is missing here is the link for the
image we generate. In an event-driven environment, request,
generation, and delivery of images are separated.
Notice the way we initialize the GnuPlot
command string for
the pipe. By default,
GNUPlot outputs the generated image via standard output, as well as
the results of print
(ed) calculations via standard error.
The redirection causes standard error to be mixed into standard
output, enabling us to read results of calculations with getline
.
By initializing the statistical parameters with some meaningful
defaults, we make sure the user gets an image the first time
he uses the program.
Following is the rather long function HandleGET
, which
implements the contents of this service by reacting to the different
kinds of requests from the browser. Before you start playing with
this script, make sure that your browser supports JavaScript and that it also
has this option switched on. The script uses a short snippet of
JavaScript code for delayed opening of a window with an image.
A more detailed explanation follows:
function HandleGET() { if(MENU[2] == "AboutServer") { Document = "This is a GUI for a statistical computation.\ It compares means and variances of two distributions.\ It is implemented as one GAWK script and uses GNUPLOT." } else if (MENU[2] == "EnterParameters") { Document = "" if ("m1" in GETARG) { # are there parameters to compare? Document = Document "<SCRIPT LANGUAGE=\"JavaScript\">\ setTimeout(\"window.open(\\\"" MyPrefix "/Image" systime()\ "\\\",\\\"dist\\\", \\\"status=no\\\");\", 1000); </SCRIPT>" m1 = GETARG["m1"]; v1 = GETARG["v1"]; n1 = GETARG["n1"] m2 = GETARG["m2"]; v2 = GETARG["v2"]; n2 = GETARG["n2"] t = (m1-m2)/sqrt(v1/n1+v2/n2) df = (v1/n1+v2/n2)*(v1/n1+v2/n2)/((v1/n1)*(v1/n1)/(n1-1) \ + (v2/n2)*(v2/n2) /(n2-1)) if (v1>v2) { f = v1/v2 df1 = n1 - 1 df2 = n2 - 1 } else { f = v2/v1 df1 = n2 - 1 df2 = n1 - 1 } print "pt=ibeta(" df/2 ",0.5," df/(df+t*t) ")" |& GnuPlot print "pF=2.0*ibeta(" df2/2 "," df1/2 "," \ df2/(df2+df1*f) ")" |& GnuPlot print "print pt, pF" |& GnuPlot RS="\n"; GnuPlot |& getline; RS="\r\n" # $1 is pt, $2 is pF print "invsqrt2pi=1.0/sqrt(2.0*pi)" |& GnuPlot print "nd(x)=invsqrt2pi/sd*exp(-0.5*((x-mu)/sd)**2)" |& GnuPlot print "set term png small color" |& GnuPlot #print "set term postscript color" |& GnuPlot #print "set term gif medium size 320,240" |& GnuPlot print "set yrange[-0.3:]" |& GnuPlot print "set label 'p(m1=m2) =" $1 "' at 0,-0.1 left" |& GnuPlot print "set label 'p(v1=v2) =" $2 "' at 0,-0.2 left" |& GnuPlot print "plot mu=" m1 ",sd=" sqrt(v1) ", nd(x) title 'sample 1',\ mu=" m2 ",sd=" sqrt(v2) ", nd(x) title 'sample 2'" |& GnuPlot print "quit" |& GnuPlot GnuPlot |& getline Image while ((GnuPlot |& getline) > 0) Image = Image RS $0 close(GnuPlot) } Document = Document "\ <h3>Do these samples have the same Gaussian distribution?</h3>\ <FORM METHOD=GET> <TABLE BORDER CELLPADDING=5>\ <TR>\ <TD>1. Mean </TD> <TD><input type=text name=m1 value=" m1 " size=8></TD>\ <TD>1. Variance</TD> <TD><input type=text name=v1 value=" v1 " size=8></TD>\ <TD>1. Count </TD> <TD><input type=text name=n1 value=" n1 " size=8></TD>\ </TR><TR>\ <TD>2. Mean </TD> <TD><input type=text name=m2 value=" m2 " size=8></TD>\ <TD>2. Variance</TD> <TD><input type=text name=v2 value=" v2 " size=8></TD>\ <TD>2. Count </TD> <TD><input type=text name=n2 value=" n2 " size=8></TD>\ </TR> <input type=submit value=\"Compute\">\ </TABLE></FORM><BR>" } else if (MENU[2] ~ "Image") { Reason = "OK" ORS "Content-type: image/png" #Reason = "OK" ORS "Content-type: application/x-postscript" #Reason = "OK" ORS "Content-type: image/gif" Header = Footer = "" Document = Image } }
As usual, we give a short description of the service in the first
menu choice. The third menu choice shows us that generation and
presentation of an image are two separate actions. While the latter
takes place quite instantly in the third menu choice, the former
takes place in the much longer second choice. Image data passes from the
generating action to the presenting action via the variable Image
that contains a complete `.png' image, which is otherwise stored
in a file. If you prefer `.ps' or `.gif' images over the
default `.png' images, you may select these options by uncommenting
the appropriate lines. But remember to do so in two places: when
telling GNUPlot which kind of images to generate, and when transmitting the
image at the end of the program.
Looking at the end of the program, the way we pass the `Content-type' to the browser is a bit unusual. It is appended to the `OK' of the first header line to make sure the type information becomes part of the header. The other variables that get transmitted across the network are made empty, because in this case we do not have an HTML document to transmit, but rather raw image data to contain in the body.
Most of the work is done in the second menu choice. It starts with a
strange JavaScript code snippet. When first implementing this server,
we used a short "
here. But then
browsers got smarter and tried to improve on speed by requesting the
image and the HTML code at the same time. When doing this, the browser
tries to build up a connection for the image request while the request for
the HTML text is not yet completed. The browser tries to connect
to the @command{gawk} server on port 8080 while port 8080 is still in use for
transmission of the HTML text. The connection for the image cannot be
built up, so the image appears as "broken" in the browser window.
We solved this problem by telling the browser to open a separate window
for the image, but only after a delay of 1000 milliseconds.
By this time, the server should be ready for serving the next request.
"
But there is one more subtlety in the JavaScript code.
Each time the JavaScript code opens a window for the image, the
name of the image is appended with a timestamp (systime
).
Why this constant change of name for the image? Initially, we always named
the image Image
, but then the Netscape browser noticed the name
had not changed since the previous request and displayed the
previous image (caching behavior). The server core
is implemented so that browsers are told not to cache anything.
Obviously HTTP requests do not always work as expected. One way to
circumvent the cache of such overly smart browsers is to change the
name of the image with each request. These three lines of JavaScript
caused us a lot of trouble.
The rest can be broken down into two phases. At first, we check if there are statistical parameters. When the program is first started, there usually are no parameters because it enters the page coming from the top menu. Then, we only have to present the user a form that he can use to change statistical parameters and submit them. Subsequently, the submission of the form causes the execution of the first phase because now there are parameters to handle.
Now that we have parameters, we know there will be an image available.
Therefore we insert the JavaScript code here to initiate the opening
of the image in a separate window. Then,
we prepare some variables that will be passed to GNUPlot for calculation
of the probabilities. Prior to reading the results, we must temporarily
change RS
because GNUPlot separates lines with newlines.
After instructing GNUPlot to generate a `.png' (or `.ps' or
`.gif') image, we initiate the insertion of some text,
explaining the resulting probabilities. The final `plot' command
actually generates the image data. This raw binary has to be read in carefully
without adding, changing, or deleting a single byte. Hence the unusual
initialization of Image
and completion with a while
loop.
When using this server, it soon becomes clear that it is far from being perfect. It mixes source code of six scripting languages or protocols:
After all this work, the GNUPlot image opens in the JavaScript window where it can be viewed by the user.
It is probably better not to mix up so many different languages. The result is not very readable. Furthermore, the statistical part of the server does not take care of invalid input. Among others, using negative variances will cause invalid results.
In the long run, every program becomes rococo, and then rubble.
Alan Perlis
By now, we know how to present arbitrary `Content-type's to a browser.
In this section, our server will present a 3D world to our browser.
The 3D world is described in a scene description language (VRML,
Virtual Reality Modeling Language) that allows us to travel through a
perspective view of a 2D maze with our browser. Browsers with a
VRML plugin enable exploration of this technology. We could do
one of those boring `Hello world' examples here, that are usually
presented when introducing novices to
VRML. If you have never written
any VRML code, have a look at
the VRML FAQ.
Presenting a static VRML scene is a bit trivial; in order to expose
@command{gawk}'s new capabilities, we will present a dynamically generated
VRML scene. The function SetUpServer
is very simple because it
only sets the default HTML page and initializes the random number
generator. As usual, the surrounding server lets you browse the maze.
function SetUpServer() { TopHeader = "<HTML><title>Walk through a maze</title>" TopDoc = "\ <h2>Please choose one of the following actions:</h2>\ <UL>\ <LI>About this server\ <LI>Watch a simple VRML scene\ </UL>" TopFooter = "</HTML>" srand() }
The function HandleGET
is a bit longer because it first computes
the maze and afterwards generates the VRML code that is sent across
the network. As shown in the STATIST example
(see section 3.6 STATIST: Graphing a Statistical Distribution),
we set the type of the
content to VRML and then store the VRML representation of the maze as the
page content. We assume that the maze is stored in a 2D array. Initially,
the maze consists of walls only. Then, we add an entry and an exit to the
maze and let the rest of the work be done by the function MakeMaze
.
Now, only the wall fields are left in the maze. By iterating over the these
fields, we generate one line of VRML code for each wall field.
function HandleGET() { if (MENU[2] == "AboutServer") { Document = "If your browser has a VRML 2 plugin,\ this server shows you a simple VRML scene." } else if (MENU[2] == "VRMLtest") { XSIZE = YSIZE = 11 # initially, everything is wall for (y = 0; y < YSIZE; y++) for (x = 0; x < XSIZE; x++) Maze[x, y] = "#" delete Maze[0, 1] # entry is not wall delete Maze[XSIZE-1, YSIZE-2] # exit is not wall MakeMaze(1, 1) Document = "\ #VRML V2.0 utf8\n\ Group {\n\ children [\n\ PointLight {\n\ ambientIntensity 0.2\n\ color 0.7 0.7 0.7\n\ location 0.0 8.0 10.0\n\ }\n\ DEF B1 Background {\n\ skyColor [0 0 0, 1.0 1.0 1.0 ]\n\ skyAngle 1.6\n\ groundColor [1 1 1, 0.8 0.8 0.8, 0.2 0.2 0.2 ]\n\ groundAngle [ 1.2 1.57 ]\n\ }\n\ DEF Wall Shape {\n\ geometry Box {size 1 1 1}\n\ appearance Appearance { material Material { diffuseColor 0 0 1 } }\n\ }\n\ DEF Entry Viewpoint {\n\ position 0.5 1.0 5.0\n\ orientation 0.0 0.0 -1.0 0.52\n\ }\n" for (i in Maze) { split(i, t, SUBSEP) Document = Document " Transform { translation " Document = Document t[1] " 0 -" t[2] " children USE Wall }\n" } Document = Document " ] # end of group for world\n}" Reason = "OK" ORS "Content-type: model/vrml" Header = Footer = "" } }
Finally, we have a look at MakeMaze
, the function that generates
the Maze
array. When entered, this function assumes that the array
has been initialized so that each element represents a wall element and
the maze is initially full of wall elements. Only the entrance and the exit
of the maze should have been left free. The parameters of the function tell
us which element must be marked as not being a wall. After this, we take
a look at the four neighbouring elements and remember which we have already
treated. Of all the neighbouring elements, we take one at random and
walk in that direction. Therefore, the wall element in that direction has
to be removed and then, we call the function recursively for that element.
The maze is only completed if we iterate the above procedure for
all neighbouring elements (in random order) and for our present
element by recursively calling the function for the present element. This
last iteration could have been done in a loop,
but it is done much simpler recursively.
Notice that elements with coordinates that are both odd are assumed to be
on our way through the maze and the generating process cannot terminate
as long as there is such an element not being delete
d. All other
elements are potentially part of the wall.
function MakeMaze(x, y) { delete Maze[x, y] # here we are, we have no wall here p = 0 # count unvisited fields in all directions if (x-2 SUBSEP y in Maze) d[p++] = "-x" if (x SUBSEP y-2 in Maze) d[p++] = "-y" if (x+2 SUBSEP y in Maze) d[p++] = "+x" if (x SUBSEP y+2 in Maze) d[p++] = "+y" if (p>0) { # if there are univisited fields, go there p = int(p*rand()) # choose one unvisited field at random if (d[p] == "-x") { delete Maze[x - 1, y]; MakeMaze(x - 2, y) } else if (d[p] == "-y") { delete Maze[x, y - 1]; MakeMaze(x, y - 2) } else if (d[p] == "+x") { delete Maze[x + 1, y]; MakeMaze(x + 2, y) } else if (d[p] == "+y") { delete Maze[x, y + 1]; MakeMaze(x, y + 2) } # we are back from recursion MakeMaze(x, y); # try again while there are unvisited fields } }
There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies.
C. A. R. Hoare
A mobile agent is a program that can be dispatched from a computer and transported to a remote server for execution. This is called migration, which means that a process on another system is started that is independent from its originator. Ideally, it wanders through a network while working for its creator or owner. In places like the UMBC Agent Web, people are quite confident that (mobile) agents are a software engineering paradigm that enables us to significantly increase the efficiency of our work. Mobile agents could become the mediators between users and the networking world. For an unbiased view at this technology, see the remarkable paper Mobile Agents: Are they a good idea?.(9)
When trying to migrate a process from one system to another, a server process is needed on the receiving side. Depending on the kind of server process, several ways of implementation come to mind. How the process is implemented depends upon the kind of server process:
POST
method to transfer
some data to a file on the web server. When a CGI script is called
remotely with the POST
method instead of the usual GET
method,
data is transmitted from the client process to the standard input
of the server's CGI script. So, to implement a mobile agent,
we must not only write the agent program to start on the client
side, but also the CGI script to receive the agent on the server side.
PUT
method can also be used for migration. HTTP does not
require a CGI script for migration via PUT
. However, with common web
servers there is no advantage to this solution, because web servers such as
Apache
require explicit activation of a special PUT
script.
Our agent example abuses a common web server as a migration tool. So, it needs a
universal CGI script on the receiving side (the web server). The receiving script is
activated with a POST
request when placed into a location like
`/httpd/cgi-bin/PostAgent.sh'. Make sure that the server system uses a
version of @command{gawk} that supports network access (Version 3.1 or later;
verify with `gawk --version').
#!/bin/sh MobAg=/tmp/MobileAgent.$$ # direct script to mobile agent file cat > $MobAg # execute agent concurrently gawk -f $MobAg $MobAg > /dev/null & # HTTP header, terminator and body gawk 'BEGIN { print "\r\nAgent started" }' rm $MobAg # delete script file of agent
By making its process id ($$
) part of the unique file name, the
script avoids conflicts between concurrent instances of the script.
First, all lines
from standard input (the mobile agent's source code) are copied into
this unique file. Then, the agent is started as a concurrent process
and a short message reporting this fact is sent to the submitting client.
Finally, the script file of the mobile agent is removed because it is
no longer needed. Although it is a short script, there are several noteworthy
points:
The originating agent itself is started just like any other command-line
script, and reports the results on standard output. By letting the name
of the original host migrate with the agent, the agent that migrates
to a host far away from its origin can report the result back home.
Having arrived at the end of the journey, the agent establishes
a connection and reports the results. This is the reason for
determining the name of the host with `uname -n' and storing it
in MyOrigin
for later use. We may also set variables with the
@option{-v} option from the command line. This interactivity is only
of importance in the context of starting a mobile agent; therefore this
BEGIN
pattern and its action do not take part in migration:
BEGIN { if (ARGC != 2) { print "MOBAG - a simple mobile agent" print "CALL:\n gawk -f mobag.awk mobag.awk" print "IN:\n the name of this script as a command-line parameter" print "PARAM:\n -v MyOrigin=myhost.com" print "OUT:\n the result on stdout" print "JK 29.03.1998 01.04.1998" exit } if (MyOrigin == "") { "uname -n" | getline MyOrigin close("uname -n") } }
Since @command{gawk} cannot manipulate and transmit parts of the program directly, the source code is read and stored in strings. Therefore, the program scans itself for the beginning and the ending of functions. Each line in between is appended to the code string until the end of the function has been reached. A special case is this part of the program itself. It is not a function. Placing a similar framework around it causes it to be treated like a function. Notice that this mechanism works for all the functions of the source code, but it cannot guarantee that the order of the functions is preserved during migration:
#ReadMySelf /^function / { FUNC = $2 } /^END/ || /^#ReadMySelf/ { FUNC = $1 } FUNC != "" { MOBFUN[FUNC] = MOBFUN[FUNC] RS $0 } (FUNC != "") && (/^}/ || /^#EndOfMySelf/) \ { FUNC = "" } #EndOfMySelf
The web server code in section 2.9 A Web Service with Interaction, was first developed as a site-independent core. Likewise, the @command{gawk}-based mobile agent starts with an agent-independent core, to which can be appended application-dependent functions. What follows is the only application-independent function needed for the mobile agent:
function migrate(Destination, MobCode, Label) { MOBVAR["Label"] = Label MOBVAR["Destination"] = Destination RS = ORS = "\r\n" HttpService = "/inet/tcp/0/" Destination for (i in MOBFUN) MobCode = (MobCode "\n" MOBFUN[i]) MobCode = MobCode "\n\nBEGIN {" for (i in MOBVAR) MobCode = (MobCode "\n MOBVAR[\"" i "\"] = \"" MOBVAR[i] "\"") MobCode = MobCode "\n}\n" print "POST /cgi-bin/PostAgent.sh HTTP/1.0" |& HttpService print "Content-length:", length(MobCode) ORS |& HttpService printf "%s", MobCode |& HttpService while ((HttpService |& getline) > 0) print $0 close(HttpService) }
The migrate
function prepares the
aforementioned strings containing the program code and transmits them to a
server. A consequence of this modular approach is that the migrate
function takes some parameters that aren't needed in this application,
but that will be in future ones. Its mandatory parameter Destination
holds the
name (or IP address) of the server that the agent wants as a host for its
code. The optional parameter MobCode
may contain some @command{gawk}
code that is inserted during migration in front of all other code.
The optional parameter Label
may contain
a string that tells the agent what to do in program execution after
arrival at its new home site. One of the serious obstacles in implementing
a framework for mobile agents is that it does not suffice to migrate the
code. It is also necessary to migrate the state of execution of the agent. In
contrast to Agent Tcl, this program does not try to migrate the complete set
of variables. The following conventions are used:
MOBFUN
shown above is an exception. It is handled
by the function migrate
and does migrate with the application.
MOBVAR
. Each variable that
takes part in migration has to be an element of this array.
migrate
also takes care of this.
Now it's clear what happens to the Label
parameter of the
function migrate
. It is copied into MOBVAR["Label"]
and
travels alongside the other data. Since travelling takes place via HTTP,
records must be separated with "\r\n"
in RS
and
ORS
as usual. The code assembly for migration takes place in
three steps:
MOBFUN
to collect all functions verbatim.
BEGIN
pattern and put assignments to mobile
variables into the action part.
Content-length
is followed by the body. In case there is
any reply over the network, it is read completely and echoed to
standard output to avoid irritating the server.
The application-independent framework is now almost complete. What follows
is the END
pattern that is executed when the mobile agent has
finished reading its own code. First, it checks whether it is already
running on a remote host or not. In case initialization has not yet taken
place, it starts MyInit
. Otherwise (later, on a remote host), it
starts MyJob
:
END { if (ARGC != 2) exit # stop when called with wrong parameters if (MyOrigin != "") # is this the originating host? MyInit() # if so, initialize the application else # we are on a host with migrated data MyJob() # so we do our job }
All that's left to extend the framework into a complete application
is to write two application-specific functions: MyInit
and
MyJob
. Keep in mind that the former is executed once on the
originating host, while the latter is executed after each migration:
function MyInit() { MOBVAR["MyOrigin"] = MyOrigin MOBVAR["Machines"] = "localhost/80 max/80 moritz/80 castor/80" split(MOBVAR["Machines"], Machines) # which host is the first? migrate(Machines[1], "", "") # go to the first host while (("/inet/tcp/8080/0/0" |& getline) > 0) # wait for result print $0 # print result close("/inet/tcp/8080/0/0") }
As mentioned earlier, this agent takes the name of its origin
(MyOrigin
) with it. Then, it takes the name of its first
destination and goes there for further work. Notice that this name has
the port number of the web server appended to the name of the server,
because the function migrate
needs it this way to create
the HttpService
variable. Finally, it waits for the result to arrive.
The MyJob
function runs on the remote host:
function MyJob() { # forget this host sub(MOBVAR["Destination"], "", MOBVAR["Machines"]) MOBVAR["Result"]=MOBVAR["Result"] SUBSEP SUBSEP MOBVAR["Destination"] ":" while (("who" | getline) > 0) # who is logged in? MOBVAR["Result"] = MOBVAR["Result"] SUBSEP $0 close("who") if (index(MOBVAR["Machines"], "/") > 0) { # any more machines to visit? split(MOBVAR["Machines"], Machines) # which host is next? migrate(Machines[1], "", "") # go there } else { # no more machines gsub(SUBSEP, "\n", MOBVAR["Result"]) # send result to origin print MOBVAR["Result"] |& "/inet/tcp/0/" MOBVAR["MyOrigin"] "/8080" close("/inet/tcp/0/" MOBVAR["MyOrigin"] "/8080") } }
After migrating, the first thing to do in MyJob
is to delete
the name of the current host from the list of hosts to visit. Now, it
is time to start the real work by appending the host's name to the
result string, and reading line by line who is logged in on this host.
A very annoying circumstance is the fact that the elements of
MOBVAR
cannot hold the newline character ("\n"
). If they
did, migration of this string did not work because the string didn't
obey the syntax rule for a string in @command{gawk}.
SUBSEP
is used as a temporary replacement.
If the list of hosts to visit holds
at least one more entry, the agent migrates to that place to go on
working there. Otherwise, we replace the SUBSEP
s
with a newline character in the resulting string, and report it to
the originating host, whose name is stored in MOBVAR["MyOrigin"]
.
Far out in the uncharted backwaters of the unfashionable end of the Western Spiral arm of the Galaxy lies a small unregarded yellow sun.
Orbiting this at a distance of roughly ninety-two million miles is an utterly insignificant little blue-green planet whose ape-descendent life forms are so amazingly primitive that they still think digital watches are a pretty neat idea.
This planet has -- or rather had -- a problem, which was this: most of the people living on it were unhappy for pretty much of the time. Many solutions were suggested for this problem, but most of these were largely concerned with the movements of small green pieces of paper, which is odd because it wasn't the small green pieces of paper that were unhappy.
Douglas Adams, The Hitch Hiker's Guide to the Galaxy
Valuable services on the Internet are usually not implemented as mobile agents. There are much simpler ways of implementing services. All Unix systems provide, for example, the @command{cron} service. Unix system users can write a list of tasks to be done each day, each week, twice a day, or just once. The list is entered into a file named `crontab'. For example, to distribute a newsletter on a daily basis this way, use @command{cron} for calling a script each day early in the morning.
# run at 8 am on weekdays, distribute the newsletter 0 8 * * 1-5 $HOME/bin/daily.job >> $HOME/log/newsletter 2>&1
The script first looks for interesting information on the Internet, assembles it in a nice form and sends the results via email to the customers.
The following is an example of a primitive newsletter on stock market prediction. It is a report which first tries to predict the change of each share in the Dow Jones Industrial Index for the particular day. Then it mentions some especially promising shares as well as some shares which look remarkably bad on that day. The report ends with the usual disclaimer which tells every child not to try this at home and hurt anybody.
Good morning Uncle Scrooge, This is your daily stock market report for Monday, October 16, 2000. Here are the predictions for today: AA neutral GE up JNJ down MSFT neutral ... UTX up DD down IBM up MO down WMT up DIS up INTC up MRK down XOM down EK down IP down The most promising shares for today are these: INTC http://biz.yahoo.com/n/i/intc.html The stock shares to avoid today are these: EK http://biz.yahoo.com/n/e/ek.html IP http://biz.yahoo.com/n/i/ip.html DD http://biz.yahoo.com/n/d/dd.html ...
The script as a whole is rather long. In order to ease the pain of studying other people's source code, we have broken the script up into meaningful parts which are invoked one after the other. The basic structure of the script is as follows:
BEGIN { Init() ReadQuotes() CleanUp() Prediction() Report() SendMail() }
The earlier parts store data into variables and arrays which are
subsequently used by later parts of the script. The Init
function
first checks if the script is invoked correctly (without any parameters).
If not, it informs the user of the correct usage. What follows are preparations
for the retrieval of the historical quote data. The names of the 30 stock
shares are stored in an array name
along with the current date
in day
, month
, and year
.
All users who are separated from the Internet by a firewall and have to direct their Internet accesses to a proxy must supply the name of the proxy to this script with the `-v Proxy=name' option. For most users, the default proxy and port number should suffice.
function Init() { if (ARGC != 1) { print "STOXPRED - daily stock share prediction" print "IN:\n no parameters, nothing on stdin" print "PARAM:\n -v Proxy=MyProxy -v ProxyPort=80" print "OUT:\n commented predictions as email" print "JK 09.10.2000" exit } # Remember ticker symbols from Dow Jones Industrial Index StockCount = split("AA GE JNJ MSFT AXP GM JPM PG BA HD KO \ SBC C HON MCD T CAT HWP MMM UTX DD IBM MO WMT DIS INTC \ MRK XOM EK IP", name); # Remember the current date as the end of the time series day = strftime("%d") month = strftime("%m") year = strftime("%Y") if (Proxy == "") Proxy = "chart.yahoo.com" if (ProxyPort == 0) ProxyPort = 80 YahooData = "/inet/tcp/0/" Proxy "/" ProxyPort }
There are two really interesting parts in the script. One is the function which reads the historical stock quotes from an Internet server. The other is the one that does the actual prediction. In the following function we see how the quotes are read from the Yahoo server. The data which comes from the server is in CSV format (comma-separated values):
Date,Open,High,Low,Close,Volume 9-Oct-00,22.75,22.75,21.375,22.375,7888500 6-Oct-00,23.8125,24.9375,21.5625,22,10701100 5-Oct-00,24.4375,24.625,23.125,23.50,5810300
Lines contain values of the same time instant, whereas columns are
separated by commas and contain the kind of data that is described
in the header (first) line. At first, @command{gawk} is instructed to
separate columns by commas (`FS = ","'). In the loop that follows,
a connection to the Yahoo server is first opened, then a download takes
place, and finally the connection is closed. All this happens once for
each ticker symbol. In the body of this loop, an Internet address is
built up as a string according to the rules of the Yahoo server. The
starting and ending date are chosen to be exactly the same, but one year
apart in the past. All the action is initiated within the printf
command which transmits the request for data to the Yahoo server.
In the inner loop, the server's data is first read and then scanned
line by line. Only lines which have six columns and the name of a month
in the first column contain relevant data. This data is stored
in the two-dimensional array quote
; one dimension
being time, the other being the ticker symbol. During retrieval of the
first stock's data, the calendar names of the time instances are stored
in the array day
because we need them later.
function ReadQuotes() { # Retrieve historical data for each ticker symbol FS = "," for (stock = 1; stock <= StockCount; stock++) { URL = "http://chart.yahoo.com/table.csv?s=" name[stock] \ "&a=" month "&b=" day "&c=" year-1 \ "&d=" month "&e=" day "&f=" year \ "g=d&q=q&y=0&z=" name[stock] "&x=.csv" printf("GET " URL " HTTP/1.0\r\n\r\n") |& YahooData while ((YahooData |& getline) > 0) { if (NF == 6 && $1 ~ /Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec/) { if (stock == 1) days[++daycount] = $1; quote[$1, stock] = $5 } } close(YahooData) } FS = " " }
Now that we have the data, it can be checked once again to make sure that no individual stock is missing or invalid, and that all the stock quotes are aligned correctly. Furthermore, we renumber the time instances. The most recent day gets day number 1 and all other days get consecutive numbers. All quotes are rounded toward the nearest whole number in US Dollars.
function CleanUp() { # clean up time series; eliminate incomplete data sets for (d = 1; d <= daycount; d++) { for (stock = 1; stock <= StockCount; stock++) if (! ((days[d], stock) in quote)) stock = StockCount + 10 if (stock > StockCount + 1) continue datacount++ for (stock = 1; stock <= StockCount; stock++) data[datacount, stock] = int(0.5 + quote[days[d], stock]) } delete quote delete days }
Now we have arrived at the second really interesting part of the whole affair.
What we present here is a very primitive prediction algorithm:
If a stock fell yesterday, assume it will also fall today; if
it rose yesterday, assume it will rise today. (Feel free to replace this
algorithm with a smarter one.) If a stock changed in the same direction
on two consecutive days, this is an indication which should be highlighted.
Two-day advances are stored in hot
and two-day declines in
avoid
.
The rest of the function is a sanity check. It counts the number of correct predictions in relation to the total number of predictions one could have made in the year before.
function Prediction() { # Predict each ticker symbol by prolonging yesterday's trend for (stock = 1; stock <= StockCount; stock++) { if (data[1, stock] > data[2, stock]) { predict[stock] = "up" } else if (data[1, stock] < data[2, stock]) { predict[stock] = "down" } else { predict[stock] = "neutral" } if ((data[1, stock] > data[2, stock]) && (data[2, stock] > data[3, stock])) hot[stock] = 1 if ((data[1, stock] < data[2, stock]) && (data[2, stock] < data[3, stock])) avoid[stock] = 1 } # Do a plausibility check: how many predictions proved correct? for (s = 1; s <= StockCount; s++) { for (d = 1; d <= datacount-2; d++) { if (data[d+1, s] > data[d+2, s]) { UpCount++ } else if (data[d+1, s] < data[d+2, s]) { DownCount++ } else { NeutralCount++ } if (((data[d, s] > data[d+1, s]) && (data[d+1, s] > data[d+2, s])) || ((data[d, s] < data[d+1, s]) && (data[d+1, s] < data[d+2, s])) || ((data[d, s] == data[d+1, s]) && (data[d+1, s] == data[d+2, s]))) CorrectCount++ } } }
At this point the hard work has been done: the array predict
contains the predictions for all the ticker symbols. It is up to the
function Report
to find some nice words to introduce the
desired information.
function Report() { # Generate report report = "\nThis is your daily " report = report "stock market report for "strftime("%A, %B %d, %Y")".\n" report = report "Here are the predictions for today:\n\n" for (stock = 1; stock <= StockCount; stock++) report = report "\t" name[stock] "\t" predict[stock] "\n" for (stock in hot) { if (HotCount++ == 0) report = report "\nThe most promising shares for today are these:\n\n" report = report "\t" name[stock] "\t\thttp://biz.yahoo.com/n/" \ tolower(substr(name[stock], 1, 1)) "/" tolower(name[stock]) ".html\n" } for (stock in avoid) { if (AvoidCount++ == 0) report = report "\nThe stock shares to avoid today are these:\n\n" report = report "\t" name[stock] "\t\thttp://biz.yahoo.com/n/" \ tolower(substr(name[stock], 1, 1)) "/" tolower(name[stock]) ".html\n" } report = report "\nThis sums up to " HotCount+0 " winners and " AvoidCount+0 report = report " losers. When using this kind\nof prediction scheme for" report = report " the 12 months which lie behind us,\nwe get " UpCount report = report " 'ups' and " DownCount " 'downs' and " NeutralCount report = report " 'neutrals'. Of all\nthese " UpCount+DownCount+NeutralCount report = report " predictions " CorrectCount " proved correct next day.\n" report = report "A success rate of "\ int(100*CorrectCount/(UpCount+DownCount+NeutralCount)) "%.\n" report = report "Random choice would have produced a 33% success rate.\n" report = report "Disclaimer: Like every other prediction of the stock\n" report = report "market, this report is, of course, complete nonsense.\n" report = report "If you are stupid enough to believe these predictions\n" report = report "you should visit a doctor who can treat your ailment." }
The function SendMail
goes through the list of customers and opens
a pipe to the mail
command for each of them. Each one receives an
email message with a proper subject heading and is addressed with his full name.
function SendMail() { # send report to customers customer["uncle.scrooge@ducktown.gov"] = "Uncle Scrooge" customer["more@utopia.org" ] = "Sir Thomas More" customer["spinoza@denhaag.nl" ] = "Baruch de Spinoza" customer["marx@highgate.uk" ] = "Karl Marx" customer["keynes@the.long.run" ] = "John Maynard Keynes" customer["bierce@devil.hell.org" ] = "Ambrose Bierce" customer["laplace@paris.fr" ] = "Pierre Simon de Laplace" for (c in customer) { MailPipe = "mail -s 'Daily Stock Prediction Newsletter'" c print "Good morning " customer[c] "," | MailPipe print report "\n.\n" | MailPipe close(MailPipe) } }
Be patient when running the script by hand.
Retrieving the data for all the ticker symbols and sending the emails
may take several minutes to complete, depending upon network traffic
and the speed of the available Internet link.
The quality of the prediction algorithm is likely to be disappointing.
Try to find a better one.
Should you find one with a success rate of more than 50%, please tell
us about it! It is only for the sake of curiosity, of course. :-)
Hoare's Law of Large Problems: Inside every large problem is a small problem struggling to get out.
Yahoo's database of stock market data is just one among the many large databases on the Internet. Another one is located at NCBI (National Center for Biotechnology Information). Established in 1988 as a national resource for molecular biology information, NCBI creates public databases, conducts research in computational biology, develops software tools for analyzing genome data, and disseminates biomedical information. In this section, we look at one of NCBI's public services, which is called BLAST (Basic Local Alignment Search Tool).
You probably know that the information necessary for reproducing living cells is encoded in the genetic material of the cells. The genetic material is a very long chain of four base nucleotides. It is the order of appearance (the sequence) of nucleotides which contains the information about the substance to be produced. Scientists in biotechnology often find a specific fragment, determine the nucleotide sequence, and need to know where the sequence at hand comes from. This is where the large databases enter the game. At NCBI, databases store the knowledge about which sequences have ever been found and where they have been found. When the scientist sends his sequence to the BLAST service, the server looks for regions of genetic material in its database which look the most similar to the delivered nucleotide sequence. After a search time of some seconds or minutes the server sends an answer to the scientist. In order to make access simple, NCBI chose to offer their database service through popular Internet protocols. There are four basic ways to use the so-called BLAST services:
Our starting point is the demonstration client mentioned in the first option. The `README' file that comes along with the client explains the whole process in a nutshell. In the rest of this section, we first show what such requests look like. Then we show how to use @command{gawk} to implement a client in about 10 lines of code. Finally, we show how to interpret the result returned from the service.
Sequences are expected to be represented in the standard IUB/IUPAC amino acid and nucleic acid codes, with these exceptions: lower-case letters are accepted and are mapped into upper-case; a single hyphen or dash can be used to represent a gap of indeterminate length; and in amino acid sequences, `U' and `*' are acceptable letters (see below). Before submitting a request, any numerical digits in the query sequence should either be removed or replaced by appropriate letter codes (e.g., `N' for unknown nucleic acid residue or `X' for unknown amino acid residue). The nucleic acid codes supported are:
A --> adenosine M --> A C (amino) C --> cytidine S --> G C (strong) G --> guanine W --> A T (weak) T --> thymidine B --> G T C U --> uridine D --> G A T R --> G A (purine) H --> A C T Y --> T C (pyrimidine) V --> G C A K --> G T (keto) N --> A G C T (any) - gap of indeterminate length
Now you know the alphabet of nucleotide sequences. The last two lines of the following example query show you such a sequence, which is obviously made up only of elements of the alphabet just described. Store this example query into a file named `protbase.request'. You are now ready to send it to the server with the demonstration client.
PROGRAM blastn DATALIB month EXPECT 0.75 BEGIN >GAWK310 the gawking gene GNU AWK tgcttggctgaggagccataggacgagagcttcctggtgaagtgtgtttcttgaaatcat caccaccatggacagcaaa
The actual search request begins with the mandatory parameter `PROGRAM' in the first column followed by the value `blastn' (the name of the program) for searching nucleic acids. The next line contains the mandatory search parameter `DATALIB' with the value `month' for the newest nucleic acid sequences. The third line contains an optional `EXPECT' parameter and the value desired for it. The fourth line contains the mandatory `BEGIN' directive, followed by the query sequence in FASTA/Pearson format. Each line of information must be less than 80 characters in length.
The "month" database contains all new or revised sequences released in the last 30 days and is useful for searching against new sequences. There are five different blast programs, @command{blastn} being the one that compares a nucleotide query sequence against a nucleotide sequence database.
The last server directive that must appear in every request is the `BEGIN' directive. The query sequence should immediately follow the `BEGIN' directive and must appear in FASTA/Pearson format. A sequence in FASTA/Pearson format begins with a single-line description. The description line, which is required, is distinguished from the lines of sequence data that follow it by having a greater-than (`>') symbol in the first column. For the purposes of the BLAST server, the text of the description is arbitrary.
If you prefer to use a client written in @command{gawk}, just store the following 10 lines of code into a file named `protbase.awk' and use this client instead. Invoke it with `gawk -f protbase.awk protbase.request'. Then wait a minute and watch the result coming in. In order to replicate the demonstration client's behaviour as closely as possible, this client does not use a proxy server. We could also have extended the client program in section 3.2 GETURL: Retrieving Web Pages, to implement the client request from `protbase.awk' as a special case.
{ request = request "\n" $0 } END { BLASTService = "/inet/tcp/0/www.ncbi.nlm.nih.gov/80" printf "POST /cgi-bin/BLAST/nph-blast_report HTTP/1.0\n" |& BLASTService printf "Content-Length: " length(request) "\n\n" |& BLASTService printf request |& BLASTService while ((BLASTService |& getline) > 0) print $0 close(BLASTService) }
The demonstration client from NCBI is 214 lines long (written in C) and it is not immediately obvious what it does. Our client is so short that it is obvious what it does. First it loops over all lines of the query and stores the whole query into a variable. Then the script establishes an Internet connection to the NCBI server and transmits the query by framing it with a proper HTTP request. Finally it receives and prints the complete result coming from the server.
Now, let us look at the result. It begins with an HTTP header, which you can ignore. Then there are some comments about the query having been filtered to avoid spuriously high scores. After this, there is a reference to the paper that describes the software being used for searching the data base. After a repitition of the original query's description we find the list of significant alignments:
Sequences producing significant alignments: (bits) Value gb|AC021182.14|AC021182 Homo sapiens chromosome 7 clone RP11-733... 38 0.20 gb|AC021056.12|AC021056 Homo sapiens chromosome 3 clone RP11-115... 38 0.20 emb|AL160278.10|AL160278 Homo sapiens chromosome 9 clone RP11-57... 38 0.20 emb|AL391139.11|AL391139 Homo sapiens chromosome X clone RP11-35... 38 0.20 emb|AL365192.6|AL365192 Homo sapiens chromosome 6 clone RP3-421H... 38 0.20 emb|AL138812.9|AL138812 Homo sapiens chromosome 11 clone RP1-276... 38 0.20 gb|AC073881.3|AC073881 Homo sapiens chromosome 15 clone CTD-2169... 38 0.20
This means that the query sequence was found in seven human chromosomes. But the value 0.20 (20%) means that the probability of an accidental match is rather high (20%) in all cases and should be taken into account. You may wonder what the first column means. It is a key to the specific database in which this occurence was found. The unique sequence identifiers reported in the search results can be used as sequence retrieval keys via the NCBI server. The syntax of sequence header lines used by the NCBI BLAST server depends on the database from which each sequence was obtained. The table below lists the identifiers for the databases from which the sequences were derived.
@ifnotinfo
gb|accession|locus
emb|accession|locus
dbj|accession|locus
pir||entry
prf||name
sp|accession|entry name
pdb|entry|chain
gnl|kabat|identifier
pat|country|number
bbs|number
For example, an identifier might be `gb|AC021182.14|AC021182', where the
`gb' tag indicates that the identifier refers to a GenBank sequence,
`AC021182.14' is its GenBank ACCESSION, and `AC021182' is the GenBank LOCUS.
The identifier contains no spaces, so that a space indicates the end of the
identifier.
Let us continue in the result listing. Each of the seven alignments mentioned
above is subsequently described in detail. We will have a closer look at
the first of them.
>gb|AC021182.14|AC021182 Homo sapiens chromosome 7 clone RP11-733N23, WORKING DRAFT SEQUENCE, 4 unordered pieces Length = 176383 Score = 38.2 bits (19), Expect = 0.20 Identities = 19/19 (100%) Strand = Plus / Plus Query: 35 tggtgaagtgtgtttcttg 53 ||||||||||||||||||| Sbjct: 69786 tggtgaagtgtgtttcttg 69804This alignment was located on the human chromosome 7. The fragment on which part of the query was found had a total length of 176383. Only 19 of the nucleotides matched and the matching sequence ran from character 35 to 53 in the query sequence and from 69786 to 69804 in the fragment on chromosome 7. If you are still reading at this point, you are probably interested in finding out more about Computational Biology and you might appreciate the following hints.
gawk
to prevail over other scripting languages such as perl
,
tcl
, or python
which are not even proper sequences. (:-)
Go to the first, previous, next, last section, table of contents.