Go to the first, previous, next, last section, table of contents.


2. Networking With @command{gawk}

The @command{awk} programming language was originally developed as a pattern-matching language for writing short programs to perform data manipulation tasks. @command{awk}'s strength is the manipulation of textual data that is stored in files. It was never meant to be used for networking purposes. To exploit its features in a networking context, it's necessary to use an access mode for network connections that resembles the access of files as closely as possible.

@command{awk} is also meant to be a prototyping language. It is used to demonstrate feasibility and to play with features and user interfaces. This can be done with file-like handling of network connections. @command{gawk} trades the lack of many of the advanced features of the TCP/IP family of protocols for the convenience of simple connection handling. The advanced features are available when programming in C or Perl. In fact, the network programming in this chapter is very similar to what is described in books like Internet Programming with Python, Advanced Perl Programming, or Web Client Programming with Perl. But it's done here without first having to learn object-oriented ideology, underlying languages such as Tcl/Tk, Perl, Python, or all of the libraries necessary to extend these languages before they are ready for the Internet.

This chapter demonstrates how to use the TCP protocol. The other protocols are much less important for most users (UDP) or even untractable (RAW).

2.1 @command{gawk} Networking Mechanisms

The `|&' operator introduced in @command{gawk} 3.1 for use in communicating with a co-process is described in section `Two-way Communications With Another Process' in GAWK: Effective AWK Programming. It shows how to do two-way I/O to a separate process, sending it data with print or printf and reading data with getline. If you haven't read it already, you should detour there to do so.

@command{gawk} transparently extends the two-way I/O mechanism to simple networking through the use of special file names. When a "co-process" is started that matches the special files we are about to describe, @command{gawk} creates the appropriate network connection, and then two-way I/O proceeds as usual.

At the C, C++ (and basic Perl) level, networking is accomplished via sockets, an Application Programming Interface (API) originally developed at the University of California at Berkeley that is now used almost universally for TCP/IP networking. Socket level programming, while fairly straightforward, requires paying attention to a number of details, as well as using binary data. It is not well-suited for use from a high-level language like @command{awk}. The special files provided in @command{gawk} hide the details from the programmer, making things much simpler and easier to use.

The special file name for network access is made up of several fields, all of them mandatory, none of them optional:

/inet/protocol/localport/hostname/remoteport

The `/inet/' field is, of course, constant when accessing the network. The localport and remoteport fields do not have a meaning when used with `/inet/raw' because "ports" only apply to TCP and UDP. So, when using `/inet/raw', the port fields always have to be `0'.

2.1.1 The Fields of the Special File Name

This section explains the meaning of all the other fields, as well as the range of values and the defaults. All of the fields are mandatory. To let the system pick a value, or if the field doesn't apply to the protocol, specify it as `0'.

protocol
Determines which member of the TCP/IP family of protocols is selected to transport the data across the network. There are three possible values (always written in lowercase): `tcp', `udp', and `raw'. The exact meaning of each is explained later in this section.
localport
Determines which port on the local machine is used to communicate across the network. It has no meaning with `/inet/raw' and must therefore be `0'. Application level clients usually use `0' to indicate they do not care which local port is used--instead they specify a remote port to connect to. It is vital for application level servers to use a number different from `0' here because their service has to be available at a specific publicly-known port number. It is possible to use a name from `/etc/services' here.
hostname
Determines which remote host is to be at the other end of the connection. Application level servers must fill this field with a `0' to indicate their being open for all other hosts to connect to them and enforce connection level server behavior this way. It is not possible for an application level server to restrict its availability to one remote host by entering a host name here. Application level clients must enter a name different from `0'. The name can be either symbolic (e.g., `jpl-devvax.jpl.nasa.gov') or numeric (e.g., `128.149.1.143').
remoteport
Determines which port on the remote machine is used to communicate across the network. It has no meaning with `/inet/raw' and must therefore be 0. For `/inet/tcp' and `/inet/udp', application level clients must use a number other than `0' to indicate which port on the remote machine they want to connect to. Application level servers must not fill this field with a `0'. Instead they specify a local port for clients to connect to. It is possible to use a name from `/etc/services' here.

Experts in network programming will notice that the usual client/server asymmetry found at the level of the socket API is not visible here. This is for the sake of simplicity of the high-level concept. If this asymmetry is necessary for your application, use another language. For @command{gawk}, it is more important to enable users to write a client program with a minimum of code. What happens when first accessing a network connection is seen in the following pseudo-code:

if ((name of remote host given) && (other side accepts connection)) {
  rendez-vous successful; transmit with getline or print
} else {
  if ((other side did not accept) && (localport == 0))
    exit unsuccessful
  if (TCP) {
    set up a server accepting connections
    this means waiting for the client on the other side to connect
  } else
    ready
}

The exact behavior of this algorithm depends on the values of the fields of the special file name. When in doubt, the following table gives you the combinations of values and their meaning. If this table is too complicated, focus on the three lines printed in bold. All the examples in @ref{Using Networking, ,Networking With @command{gawk}}, use only the patterns printed in bold letters.

  • PROTOCOL LOCAL PORT HOST NAME REMOTE PORT RESULTING CONNECTION LEVEL BEHAVIOR
  • tcp 0 x x Dedicated client, fails if immediately connecting to a server on the other side fails
  • udp 0 x x Dedicated client
  • raw 0 x 0 Dedicated client, works only as root
  • tcp, udp x x x Client, switches to dedicated server if necessary
  • tcp, udp x 0 0 Dedicated server
  • raw 0 0 0 Dedicated server, works only as root
  • tcp, udp, raw x x 0 Invalid
  • tcp, udp, raw 0 0 x Invalid
  • tcp, udp, raw x 0 x Invalid
  • tcp, udp 0 0 0 Invalid
  • tcp, udp 0 x 0 Invalid
  • raw x 0 0 Invalid
  • raw 0 x x Invalid
  • raw x x x Invalid In general, TCP is the preferred mechanism to use. It is the simplest protocol to understand and to use. Use the others only if circumstances demand low-overhead.

    2.1.2 Comparing Protocols

    This section develops a pair of programs (sender and receiver) that do nothing but send a timestamp from one machine to another. The sender and the receiver are implemented with each of the three protocols available and demonstrate the differences between them.

    2.1.2.1 `/inet/tcp'

    Once again, always use TCP. (Use UDP when low-overhead is a necessity, and use RAW for network experimentation.) The first example is the sender program:

    # Server
    BEGIN {
      print strftime() |& "/inet/tcp/8888/0/0"
      close("/inet/tcp/8888/0/0")
    }
    

    The receiver is very simple:

    # Client
    BEGIN {
      "/inet/tcp/0/localhost/8888" |& getline
      print $0
      close("/inet/tcp/0/localhost/8888")
    }
    

    TCP guarantees that the bytes arrive at the receiving end in exactly the same order that they were sent. No byte is lost (except for broken connections), doubled, or out of order. Some overhead is necessary to accomplish this, but this is the price to pay for a reliable service. It does matter which side starts first. The sender/server has to be started first, and it waits for the receiver to read a line.

    2.1.2.2 `/inet/udp'

    The server and client programs that use UDP are almost identical to their TCP counterparts; only the protocol has changed. As before, it does matter which side starts first. The receiving side blocks and waits for the sender. In this case, the receiver/client has to be started first:

    # Server
    BEGIN {
      print strftime() |& "/inet/udp/8888/0/0"
      close("/inet/udp/8888/0/0")
    }
    

    The receiver is almost identical to the TCP receiver:

    # Client
    BEGIN {
      "/inet/udp/0/localhost/8888" |& getline
      print $0
      close("/inet/udp/0/localhost/8888")
    }
    

    UDP cannot guarantee that the datagrams at the receiving end will arrive in exactly the same order they were sent. Some datagrams could be lost, some doubled, and some out of order. But no overhead is necessary to accomplish this. This unreliable behavior is good enough for tasks such as data acquisition, logging, and even stateless services like NFS.

    2.1.2.3 `/inet/raw'

    This is an IP-level protocol. Only root is allowed to access this special file. It is meant to be the basis for implementing and experimenting with transport level protocols.(3) In the most general case, the sender has to supply the encapsulating header bytes in front of the packet and the receiver has to strip the additional bytes from the message.

    RAW receivers cannot receive packets sent with TCP or UDP because the operating system does not deliver the packets to a RAW receiver. The operating system knows about some of the protocols on top of IP and decides on its own which packet to deliver to which process. @inmargin{@image{lflashlight,1cm}, @image{rflashlight,1cm}} Therefore, the UDP receiver must be used for receiving UDP datagrams sent with the RAW sender. This is a dark corner, not only of @command{gawk}, but also of TCP/IP.

    For extended experimentation with protocols, look into the approach implemented in a tool called SPAK. This tool reflects the hierarchical layering of protocols (encapsulation) in the way data streams are piped out of one program into the next one. It shows which protocol is based on which other (lower-level) protocol by looking at the command-line ordering of the program calls. Cleverly thought out, SPAK is much better than @command{gawk}'s `/inet' for learning the meaning of each and every bit in the protocol headers.

    The next example uses the RAW protocol to emulate the behavior of UDP. The sender program is the same as above, but with some additional bytes that fill the places of the UDP fields:

    BEGIN {
      Message = "Hello world\n"
      SourcePort = 0
      DestinationPort = 8888
      MessageLength = length(Message)+8
      RawService = "/inet/raw/0/localhost/0"
      printf("%c%c%c%c%c%c%c%c%s",
          SourcePort/256, SourcePort%256,
          DestinationPort/256, DestinationPort%256,
          MessageLength/256, MessageLength%256,
          0, 0, Message) |& RawService
      fflush(RawService)
      close(RawService)
    }
    

    Since this program tries to emulate the behavior of UDP, it checks if the RAW sender is understood by the UDP receiver but not if the RAW receiver can understand the UDP sender. In a real network, the RAW receiver is hardly of any use because it gets every IP packet that comes across the network. There are usually so many packets that @command{gawk} would be too slow for processing them. Only on a network with little traffic can the IP-level receiver program be tested. Programs for analyzing IP traffic on modem or ISDN channels should be possible.

    Port numbers do not have a meaning when using `/inet/raw'. Their fields have to be `0'. Only TCP and UDP use ports. Receiving data from `/inet/raw' is difficult, not only because of processing speed but also because data is usually binary and not restricted to ASCII. This implies that line separation with RS does not work as usual.

    2.2 Establishing a TCP Connection

    Let's observe a network connection at work. Type in the following program and watch the output. Within a second, it connects via TCP (`/inet/tcp') to the machine it is running on (`localhost'), and asks the service `daytime' on the machine what time it is:

    BEGIN {
      "/inet/tcp/0/localhost/daytime" |& getline
      print $0
      close("/inet/tcp/0/localhost/daytime")
    }
    

    Even experienced @command{awk} users will find the second line strange in two respects:

    The `|&' operator was introduced in @command{gawk} 3.1 in order to overcome the crucial restriction that access to files and pipes in @command{awk} is always unidirectional. It was formerly impossible to use both access modes on the same file or pipe. Instead of changing the whole concept of file access, the `|&' operator behaves exactly like the usual pipe operator except for two additions:

    In the earlier example, the `|&' operator tells getline to read a line from the special file `/inet/tcp/0/localhost/daytime'. We could also have printed a line into the special file. But instead we just read a line with the time, printed it, and closed the connection. (While we could just let @command{gawk} close the connection by finishing the program, in this book we are pedantic, and always explicitly close the connections.)

    2.3 Troubleshooting Connection Problems

    It may well be that for some reason the above program does not run on your machine. When looking at possible reasons for this, you will learn much about typical problems that arise in network programming. First of all, your implementation of @command{gawk} may not support network access because it is a pre-3.1 version or you do not have a network interface in your machine. Perhaps your machine uses some other protocol like DECnet or Novell's IPX. For the rest of this chapter, we will assume you work on a Unix machine that supports TCP/IP. If the above program does not run on such a machine, it may help to replace the name `localhost' with the name of your machine or its IP address. If it does, you could replace `localhost' with the name of another machine in your vicinity. This way, the program connects to another machine. Now you should see the date and time being printed by the program. Otherwise your machine may not support the `daytime' service. Try changing the service to `chargen' or `ftp'. This way, the program connects to other services that should give you some response. If you are curious, you should have a look at your file `/etc/services'. It could look like this:

    # /etc/services:
    #
    # Network services, Internet style
    #
    # Name     Number/Protcol  Alternate name # Comments
    
    echo        7/tcp
    echo        7/udp
    discard     9/tcp         sink null
    discard     9/udp         sink null
    daytime     13/tcp
    daytime     13/udp
    chargen     19/tcp        ttytst source
    chargen     19/udp        ttytst source
    ftp         21/tcp
    telnet      23/tcp
    smtp        25/tcp        mail
    finger      79/tcp
    www         80/tcp        http      # WorldWideWeb HTTP
    www         80/udp        # HyperText Transfer Protocol
    pop-2       109/tcp       postoffice    # POP version 2
    pop-2       109/udp
    pop-3       110/tcp       # POP version 3
    pop-3       110/udp
    nntp        119/tcp       readnews untp  # USENET News
    irc         194/tcp       # Internet Relay Chat
    irc         194/udp
    ...
    

    Here, you find a list of services that traditional Unix machines usually support. If your GNU/Linux machine does not do so, it may be that these services are switched off in some startup script. Systems running some flavor of Microsoft Windows usually do not support such services. Nevertheless, it is possible to do networking with @command{gawk} on Microsoft Windows.(4) The first column of the file gives the name of the service, the second a unique number, and the protocol that one can use to connect to this service. The rest of the line is treated as a comment. You see that some services (`echo') support TCP as well as UDP.

    2.4 Interacting with a Network Service

    The next program makes use of the possibility to really interact with a network service by printing something into the special file. It asks the so-called @command{finger} service if a user of the machine is logged in. When testing this program, try to change `localhost' to some other machine name in your local network:

    BEGIN {
      NetService = "/inet/tcp/0/localhost/finger"
      print "name" |& NetService
      while ((NetService |& getline) > 0)
        print $0
      close(NetService)
    }
    

    After telling the service on the machine which user to look for, the program repeatedly reads lines that come as a reply. When no more lines are coming (because the service has closed the connection), the program also closes the connection. Try replacing "name" with your login name (or the name of someone else logged in). For a list of all users currently logged in, replace name with an empty string "".

    The final close command could be safely deleted from the above script, because the operating system closes any open connection by default when a script reaches the end of execution. In order to avoid portability problems, it is best to always close connections explicitly. With the Linux kernel, for example, proper closing results in flushing of buffers. Letting the close happen by default may result in discarding buffers.

    When looking at `/etc/services' you may have noticed that the `daytime' service is also available with `udp'. In the earlier example, change `tcp' to `udp', and change `finger' to `daytime'. After starting the modified program, you see the expected day and time message. The program then hangs, because it waits for more lines coming from the service. However, they never come. This behavior is a consequence of the differences between TCP and UDP. When using UDP, neither party is automatically informed about the other closing the connection. Continuing to experiment this way reveals many other subtle differences between TCP and UDP. To avoid such trouble, one should always remember the advice Douglas E. Comer and David Stevens give in Volume III of their series Internetworking With TCP (page 14):

    When designing client-server applications, beginners are strongly advised to use TCP because it provides reliable, connection-oriented communication. Programs only use UDP if the application protocol handles reliability, the application requires hardware broadcast or multicast, or the application cannot tolerate virtual circuit overhead.

    2.5 Setting Up a Service

    The preceding programs behaved as clients that connect to a server somewhere on the Internet and request a particular service. Now we set up such a service to mimic the behavior of the `daytime' service. Such a server does not know in advance who is going to connect to it over the network. Therefore we cannot insert a name for the host to connect to in our special file name.

    Start the following program in one window. Notice that the service does not have the name `daytime', but the number `8888'. From looking at `/etc/services', you know that names like `daytime' are just mnemonics for predetermined 16-bit integers. Only the system administrator (root) could enter our new service into `/etc/services' with an appropriate name. Also notice that the service name has to be entered into a different field of the special file name because we are setting up a server, not a client:

    BEGIN {
      print strftime() |& "/inet/tcp/8888/0/0"
      close("/inet/tcp/8888/0/0")
    }
    

    Now open another window on the same machine. Copy the client program given as the first example (see section 2.2 Establishing a TCP Connection) to a new file and edit it, changing the name `daytime' to `8888'. Then start the modified client. You should get a reply like this:

    Sat Sep 27 19:08:16 CEST 1997
    

    Both programs explicitly close the connection.

    Now we will intentionally make a mistake to see what happens when the name `8888' (the so-called port) is already used by another service. Start the server program in both windows. The first one works, but the second one complains that it could not open the connection. Each port on a single machine can only be used by one server program at a time. Now terminate the server program and change the name `8888' to `echo'. After restarting it, the server program does not run any more and you know why: there already is an `echo' service running on your machine. But even if this isn't true, you would not get your own `echo' server running on a Unix machine, because the ports with numbers smaller than 1024 (`echo' is at port 7) are reserved for root. On machines running some flavor of Microsoft Windows, there is no restriction that reserves ports 1 to 1024 for a privileged user; hence you can start an `echo' server there.

    Turning this short server program into something really useful is simple. Imagine a server that first reads a file name from the client through the network connection, then does something with the file and sends a result back to the client. The server-side processing could be:

    BEGIN {
      NetService = "/inet/tcp/8888/0/0"
      NetService |& getline
      CatPipe    = ("cat " $1)    # sets $0 and the fields
      while ((CatPipe | getline) > 0)
        print $0 |& NetService
      close(NetService)
    }
    

    and we would have a remote copying facility. Such a server reads the name of a file from any client that connects to it and transmits the contents of the named file across the net. The server-side processing could also be the execution of a command that is transmitted across the network. From this example, you can see how simple it is to open up a security hole on your machine. If you allow clients to connect to your machine and execute arbitrary commands, anyone would be free to do `rm -rf *'.

    2.6 Reading Email

    The distribution of email is usually done by dedicated email servers that communicate with your machine using special protocols. To receive email, we will use the Post Office Protocol (POP). Sending can be done with the much older Simple Mail Transfer Protocol (SMTP).

    When you type in the following program, replace the emailhost by the name of your local email server. Ask your administrator if the server has a POP service, and then use its name or number in the program below. Now the program is ready to connect to your email server, but it will not succeed in retrieving your mail because it does not yet know your login name or password. Replace them in the program and it shows you the first email the server has in store:

    BEGIN {
      POPService  = "/inet/tcp/0/emailhost/pop3"
      RS = ORS = "\r\n"
      print "user name"            |& POPService
      POPService                    |& getline
      print "pass password"         |& POPService
      POPService                    |& getline
      print "retr 1"                |& POPService
      POPService                    |& getline
      if ($1 != "+OK") exit
      print "quit"                  |& POPService
      RS = "\r\n\\.\r\n"
      POPService |& getline
      print $0
      close(POPService)
    }
    

    The record separators RS and ORS are redefined because the protocol (POP) requires CR-LF to separate lines. After identifying yourself to the email service, the command `retr 1' instructs the service to send the first of all your email messages in line. If the service replies with something other than `+OK', the program exits; maybe there is no email. Otherwise, the program first announces that it intends to finish reading email, and then redefines RS in order to read the entire email as multiline input in one record. From the POP RFC, we know that the body of the email always ends with a single line containing a single dot. The program looks for this using `RS = "\r\n\\.\r\n"'. When it finds this sequence in the mail message, it quits. You can invoke this program as often as you like; it does not delete the message it reads, but instead leaves it on the server.

    2.7 Reading a Web Page

    Retrieving a web page from a web server is as simple as retrieving email from an email server. We only have to use a similar, but not identical, protocol and a different port. The name of the protocol is HyperText Transfer Protocol (HTTP) and the port number is usually 80. As in the preceding section, ask your administrator about the name of your local web server or proxy web server and its port number for HTTP requests.

    The following program employs a rather crude approach toward retrieving a web page. It uses the prehistoric syntax of HTTP 0.9, which almost all web servers still support. The most noticeable thing about it is that the program directs the request to the local proxy server whose name you insert in the special file name (which in turn calls `www.yahoo.com'):

    BEGIN {
      RS = ORS = "\r\n"
      HttpService = "/inet/tcp/0/proxy/80"
      print "GET http://www.yahoo.com"     |& HttpService
      while ((HttpService |& getline) > 0)
         print $0
      close(HttpService)
    }
    

    Again, lines are separated by a redefined RS and ORS. The GET request that we send to the server is the only kind of HTTP request that existed when the web was created in the early 1990s. HTTP calls this GET request a "method," which tells the service to transmit a web page (here the home page of the Yahoo! search engine). Version 1.0 added the request methods HEAD and POST. The current version of HTTP is 1.1,(5) and knows the additional request methods OPTIONS, PUT, DELETE, and TRACE. You can fill in any valid web address, and the program prints the HTML code of that page to your screen.

    Notice the similarity between the responses of the POP and HTTP services. First, you get a header that is terminated by an empty line, and then you get the body of the page in HTML. The lines of the headers also have the same form as in POP. There is the name of a parameter, then a colon, and finally the value of that parameter.

    Images (`.png' or `.gif' files) can also be retrieved this way, but then you get binary data that should be redirected into a file. Another application is calling a CGI (Common Gateway Interface) script on some server. CGI scripts are used when the contents of a web page are not constant, but generated instantly at the moment you send a request for the page. For example, to get a detailed report about the current quotes of Motorola stock shares, call a CGI script at Yahoo! with the following:

    get = "GET http://quote.yahoo.com/q?s=MOT&d=t"
    print get |& HttpService
    

    You can also request weather reports this way.

    2.8 A Primitive Web Service

    Now we know enough about HTTP to set up a primitive web service that just says "Hello, world" when someone connects to it with a browser. Compared to the situation in the preceding section, our program changes the role. It tries to behave just like the server we have observed. Since we are setting up a server here, we have to insert the port number in the `localport' field of the special file name. The other two fields (hostname and remoteport) have to contain a `0' because we do not know in advance which host will connect to our service.

    In the early 1990s, all a server had to do was send an HTML document and close the connection. Here, we adhere to the modern syntax of HTTP. The steps are as follows:

    1. Send a status line telling the web browser that everything is OK.
    2. Send a line to tell the browser how many bytes follow in the body of the message. This was not necessary earlier because both parties knew that the document ended when the connection closed. Nowadays it is possible to stay connected after the transmission of one web page. This is to avoid the network traffic necessary for repeatedly establishing TCP connections for requesting several images. Thus, there is the need to tell the receiving party how many bytes will be sent. The header is terminated as usual with an empty line.
    3. Send the "Hello, world" body in HTML. The useless while loop swallows the request of the browser. We could actually omit the loop, and on most machines the program would still work. First, start the following program:
    BEGIN {
      RS = ORS = "\r\n"
      HttpService = "/inet/tcp/8080/0/0"
      Hello = "<HTML><HEAD>" \
              "<TITLE>A Famous Greeting</TITLE></HEAD>" \
              "<BODY><H1>Hello, world</H1></BODY></HTML>"
      Len = length(Hello) + length(ORS)
      print "HTTP/1.0 200 OK"          |& HttpService
      print "Content-Length: " Len ORS |& HttpService
      print Hello                      |& HttpService
      while ((HttpService |& getline) > 0)
         continue;
      close(HttpService)
    }
    

    Now, on the same machine, start your favorite browser and let it point to http://localhost:8080 (the browser needs to know on which port our server is listening for requests). If this does not work, the browser probably tries to connect to a proxy server that does not know your machine. If so, change the browser's configuration so that the browser does not try to use a proxy to connect to your machine.

    2.9 A Web Service with Interaction

    Setting up a web service that allows user interaction is more difficult and shows us the limits of network access in @command{gawk}. In this section, we develop a main program (a BEGIN pattern and its action) that will become the core of event-driven execution controlled by a graphical user interface (GUI). Each HTTP event that the user triggers by some action within the browser is received in this central procedure. Parameters and menu choices are extracted from this request and an appropriate measure is taken according to the user's choice. For example:

    BEGIN {
      if (MyHost == "") {
         "uname -n" | getline MyHost
         close("uname -n")
      }
      if (MyPort ==  0) MyPort = 8080
      HttpService = "/inet/tcp/" MyPort "/0/0"
      MyPrefix    = "http://" MyHost ":" MyPort
      SetUpServer()
      while ("awk" != "complex") {
        # header lines are terminated this way
        RS = ORS = "\r\n"
        Status   = 200          # this means OK
        Reason   = "OK"
        Header   = TopHeader
        Document = TopDoc
        Footer   = TopFooter
        if        (GETARG["Method"] == "GET") {
            HandleGET()
        } else if (GETARG["Method"] == "HEAD") {
            # not yet implemented
        } else if (GETARG["Method"] != "") {
            print "bad method", GETARG["Method"]
        }
        Prompt = Header Document Footer
        print "HTTP/1.0", Status, Reason       |& HttpService
        print "Connection: Close"              |& HttpService
        print "Pragma: no-cache"               |& HttpService
        len = length(Prompt) + length(ORS)
        print "Content-length:", len           |& HttpService
        print ORS Prompt                       |& HttpService
        # ignore all the header lines
        while ((HttpService |& getline) > 0)
            ;
        # stop talking to this client
        close(HttpService)
        # wait for new client request
        HttpService |& getline          
        # do some logging
        print systime(), strftime(), $0
        # read request parameters
        CGI_setup($1, $2, $3)
      }
    }
    

    This web server presents menu choices in the form of HTML links. Therefore, it has to tell the browser the name of the host it is residing on. When starting the server, the user may supply the name of the host from the command line with `gawk -v MyHost="Rumpelstilzchen"'. If the user does not do this, the server looks up the name of the host it is running on for later use as a web address in HTML documents. The same applies to the port number. These values are inserted later into the HTML content of the web pages to refer to the home system.

    Each server that is built around this core has to initialize some application-dependent variables (such as the default home page) in a procedure SetUpServer, which is called immediately before entering the infinite loop of the server. For now, we will write an instance that initiates a trivial interaction. With this home page, the client user can click on two possible choices, and receive the current date either in human-readable format or in seconds since 1970:

    function SetUpServer() {
      TopHeader = "<HTML><HEAD>"
      TopHeader = TopHeader \
         "<title>My name is GAWK, GNU AWK</title></HEAD>"
      TopDoc    = "<BODY><h2>\
        Do you prefer your date <A HREF=" MyPrefix \
        "/human>human or \
        POSIXed?</h2>" ORS ORS
      TopFooter = "</BODY></HTML>"
    }
    

    On the first run through the main loop, the default line terminators are set and the default home page is copied to the actual home page. Since this is the first run, GETARG["Method"] is not initialized yet, hence the case selection over the method does nothing. Now that the home page is initialized, the server can start communicating to a client browser.

    It does so by printing the HTTP header into the network connection (`print ... |& HttpService'). This command blocks execution of the server script until a client connects. If this server script is compared with the primitive one we wrote before, you will notice two additional lines in the header. The first instructs the browser to close the connection after each request. The second tells the browser that it should never try to remember earlier requests that had identical web addresses (no caching). Otherwise, it could happen that the browser retrieves the time of day in the previous example just once, and later it takes the web page from the cache, always displaying the same time of day although time advances each second.

    Having supplied the initial home page to the browser with a valid document stored in the parameter Prompt, it closes the connection and waits for the next request. When the request comes, a log line is printed that allows us to see which request the server receives. The final step in the loop is to call the function CGI_setup, which reads all the lines of the request (coming from the browser), processes them, and stores the transmitted parameters in the array PARAM. The complete text of these application-independent functions can be found in section 2.9.1 A Simple CGI Library. For now, we use a simplified version of CGI_setup:

    function CGI_setup(   method, uri, version, i) {
      delete GETARG;         delete MENU;        delete PARAM
      GETARG["Method"] = $1
      GETARG["URI"] = $2
      GETARG["Version"] = $3
      i = index($2, "?")
      # is there a "?" indicating a CGI request?
      if (i > 0) {
        split(substr($2, 1, i-1), MENU, "[/:]")
        split(substr($2, i+1), PARAM, "&") 
        for (i in PARAM) { 
          j = index(PARAM[i], "=")
          GETARG[substr(PARAM[i], 1, j-1)] = \
                                      substr(PARAM[i], j+1)
        }
      } else {    # there is no "?", no need for splitting PARAMs
        split($2, MENU, "[/:]")
      }
    }
    

    At first, the function clears all variables used for global storage of request parameters. The rest of the function serves the purpose of filling the global parameters with the extracted new values. To accomplish this, the name of the requested resource is split into parts and stored for later evaluation. If the request contains a `?', then the request has CGI variables seamlessly appended to the web address. Everything in front of the `?' is split up into menu items, and everything behind the `?' is a list of `variable=value' pairs (separated by `&') that also need splitting. This way, CGI variables are isolated and stored. This procedure lacks recognition of special characters that are transmitted in coded form(6). Here, any optional request header and body parts are ignored. We do not need header parameters and the request body. However, when refining our approach or working with the POST and PUT methods, reading the header and body becomes inevitable. Header parameters should then be stored in a global array as well as the body.

    On each subsequent run through the main loop, one request from a browser is received, evaluated, and answered according to the user's choice. This can be done by letting the value of the HTTP method guide the main loop into execution of the procedure HandleGET, which evaluates the user's choice. In this case, we have only one hierarchical level of menus, but in the general case, menus are nested. The menu choices at each level are separated by `/', just as in file names. Notice how simple it is to construct menus of arbitrary depth:

    function HandleGET() {
      if (       MENU[2] == "human") {
        Footer = strftime() TopFooter
      } else if (MENU[2] == "POSIX") {
        Footer = systime()  TopFooter
      }
    }
    

    The disadvantage of this approach is that our server is slow and can handle only one request at a time. Its main advantage, however, is that the server consists of just one @command{gawk} program. No need for installing an @command{httpd}, and no need for static separate HTML files, CGI scripts, or root privileges. This is rapid prototyping. This program can be started on the same host that runs your browser. Then let your browser point to http://localhost:8080.

    It is also possible to include images into the HTML pages. Most browsers support the not very well-known `.xbm' format, which may contain only monochrome pictures but is an ASCII format. Binary images are possible but not so easy to handle. Another way of including images is to generate them with a tool such as GNUPlot, by calling the tool with the system function or through a pipe.

    2.9.1 A Simple CGI Library

    HTTP is like being married: you have to be able to handle whatever you're given, while being very careful what you send back.
    Phil Smith III,
    http://www.netfunny.com/rhf/jokes/99/Mar/http.html

    In section 2.9 A Web Service with Interaction, we saw the function CGI_setup as part of the web server "core logic" framework. The code presented there handles almost everything necessary for CGI requests. One thing it doesn't do is handle encoded characters in the requests. For example, an `&' is encoded as a percent sign followed by the hexadecimal value---`%26'. These encoded values should be decoded. Following is a simple library to perform these tasks. This code is used for all web server examples used throughout the rest of this book. If you want to use it for your own web server, store the source code into a file named `inetlib.awk'. Then you can include these functions into your code by placing the following statement into your program:

    @include inetlib.awk
    

    on the first line of your script. But beware, this mechanism is only possible if you invoke your web server script with @command{igawk} instead of the usual @command{awk} or @command{gawk}. Here is the code:

    # CGI Library and core of a web server
    # Global arrays
    #   GETARG --- arguments to CGI GET command
    #   MENU   --- menu items (path names)
    #   PARAM  --- parameters of form x=y
    
    # Optional variable MyHost contains host address
    # Optional variable MyPort contains port number
    # Needs TopHeader, TopDoc, TopFooter
    # Sets MyPrefix, HttpService, Status, Reason
    
    BEGIN {
      if (MyHost == "") {
         "uname -n" | getline MyHost
         close("uname -n")
      }
      if (MyPort ==  0) MyPort = 8080
      HttpService = "/inet/tcp/" MyPort "/0/0"
      MyPrefix    = "http://" MyHost ":" MyPort
      SetUpServer()
      while ("awk" != "complex") {
        # header lines are terminated this way
        RS = ORS    = "\r\n"
        Status      = 200             # this means OK
        Reason      = "OK"
        Header      = TopHeader
        Document    = TopDoc
        Footer      = TopFooter
        if        (GETARG["Method"] == "GET") {
            HandleGET()
        } else if (GETARG["Method"] == "HEAD") {
            # not yet implemented
        } else if (GETARG["Method"] != "") {
            print "bad method", GETARG["Method"]
        }
        Prompt = Header Document Footer
        print "HTTP/1.0", Status, Reason     |& HttpService
        print "Connection: Close"            |& HttpService
        print "Pragma: no-cache"             |& HttpService
        len = length(Prompt) + length(ORS)
        print "Content-length:", len         |& HttpService
        print ORS Prompt                     |& HttpService
        # ignore all the header lines
        while ((HttpService |& getline) > 0) 
            continue
        # stop talking to this client
        close(HttpService)
        # wait for new client request
        HttpService |& getline
        # do some logging
        print systime(), strftime(), $0
        CGI_setup($1, $2, $3)
      }
    }
    
    function CGI_setup(   method, uri, version, i)
    {
        delete GETARG
        delete MENU
        delete PARAM
        GETARG["Method"] = method
        GETARG["URI"] = uri
        GETARG["Version"] = version
    
        i = index(uri, "?")
        if (i > 0) {  # is there a "?" indicating a CGI request?
            split(substr(uri, 1, i-1), MENU, "[/:]")
            split(substr(uri, i+1), PARAM, "&")
            for (i in PARAM) {
                PARAM[i] = _CGI_decode(PARAM[i])
                j = index(PARAM[i], "=")
                GETARG[substr(PARAM[i], 1, j-1)] = \
    	                                 substr(PARAM[i], j+1)
            }
        } else { # there is no "?", no need for splitting PARAMs
            split(uri, MENU, "[/:]")
        }
        for (i in MENU)     # decode characters in path
            if (i > 4)      # but not those in host name
                MENU[i] = _CGI_decode(MENU[i])
    }
    

    This isolates details in a single function, CGI_setup. Decoding of encoded characters is pushed off to a helper function, _CGI_decode. The use of the leading underscore (`_') in the function name is intended to indicate that it is an "internal" function, although there is nothing to enforce this:

    function _CGI_decode(str,   hexdigs, i, pre, code1, code2,
                                val, result)
    {
       hexdigs = "123456789abcdef"
    
       i = index(str, "%")
       if (i == 0) # no work to do
          return str
    
       do {
          pre = substr(str, 1, i-1)   # part before %xx
          code1 = substr(str, i+1, 1) # first hex digit
          code2 = substr(str, i+2, 1) # second hex digit
          str = substr(str, i+3)      # rest of string
    
          code1 = tolower(code1)
          code2 = tolower(code2)
          val = index(hexdigs, code1) * 16 \
                + index(hexdigs, code2)
    
          result = result pre sprintf("%c", val)
          i = index(str, "%")
       } while (i != 0)
       if (length(str) > 0)
          result = result str
       return result
    }
    

    This works by splitting the string apart around an encoded character. The two digits are converted to lowercase and looked up in a string of hex digits. Note that 0 is not in the string on purpose; index returns zero when it's not found, automatically giving the correct value! Once the hexadecimal value is converted from characters in a string into a numerical value, sprintf converts the value back into a real character. The following is a simple test harness for the above functions:

    BEGIN {
      CGI_setup("GET",
      "http://www.gnu.org/cgi-bin/foo?p1=stuff&p2=stuff%26junk" \
           "&percent=a %25 sign",
      "1.0")
      for (i in MENU)
          printf "MENU[\"%s\"] = %s\n", i, MENU[i]
      for (i in PARAM)
          printf "PARAM[\"%s\"] = %s\n", i, PARAM[i]
      for (i in GETARG)
          printf "GETARG[\"%s\"] = %s\n", i, GETARG[i]
    }
    

    And this is the result when we run it:

    $ gawk -f testserv.awk 
    -| MENU["4"] = www.gnu.org
    -| MENU["5"] = cgi-bin
    -| MENU["6"] = foo
    -| MENU["1"] = http
    -| MENU["2"] = 
    -| MENU["3"] = 
    -| PARAM["1"] = p1=stuff
    -| PARAM["2"] = p2=stuff&junk
    -| PARAM["3"] = percent=a % sign
    -| GETARG["p1"] = stuff
    -| GETARG["percent"] = a % sign
    -| GETARG["p2"] = stuff&junk
    -| GETARG["Method"] = GET
    -| GETARG["Version"] = 1.0
    -| GETARG["URI"] = http://www.gnu.org/cgi-bin/foo?p1=stuff&
    p2=stuff%26junk&percent=a %25 sign
    

    2.10 A Simple Web Server

    In the preceding section, we built the core logic for event driven GUIs. In this section, we finally extend the core to a real application. No one would actually write a commercial web server in @command{gawk}, but it is instructive to see that it is feasible in principle.

    uf002331

    The application is ELIZA, the famous program by Joseph Weizenbaum that mimics the behavior of a professional psychotherapist when talking to you. Weizenbaum would certainly object to this description, but this is part of the legend around ELIZA. Take the site-independent core logic and append the following code:

    function SetUpServer() {
      SetUpEliza()
      TopHeader = \
        "<HTML><title>An HTTP-based System with GAWK</title>\
        <HEAD><META HTTP-EQUIV=\"Content-Type\"\
        CONTENT=\"text/html; charset=iso-8859-1\"></HEAD>\
        <BODY BGCOLOR=\"#ffffff\" TEXT=\"#000000\"\
        LINK=\"#0000ff\" VLINK=\"#0000ff\"\
        ALINK=\"#0000ff\"> "
      TopDoc    = "\
       <h2>Please choose one of the following actions:</h2>\
       <UL>\
       <LI>\
       About this server\
       </LI><LI>\
       About Eliza</LI>\
       <LI>\
       <A HREF=" MyPrefix \
          "/StartELIZA>Start talking to Eliza</LI></UL>"
      TopFooter = "</BODY></HTML>"
    }
    

    SetUpServer is similar to the previous example, except for calling another function, SetUpEliza. This approach can be used to implement other kinds of servers. The only changes needed to do so are hidden in the functions SetUpServer and HandleGET. Perhaps it might be necessary to implement other HTTP methods. The @command{igawk} program that comes with @command{gawk} may be useful for this process.

    When extending this example to a complete application, the first thing to do is to implement the function SetUpServer to initialize the HTML pages and some variables. These initializations determine the way your HTML pages look (colors, titles, menu items, etc.).

    The function HandleGET is a nested case selection that decides which page the user wants to see next. Each nesting level refers to a menu level of the GUI. Each case implements a certain action of the menu. On the deepest level of case selection, the handler essentially knows what the user wants and stores the answer into the variable that holds the HTML page contents:

    function HandleGET() {
      # A real HTTP server would treat some parts of the URI as a file name.
      # We take parts of the URI as menu choices and go on accordingly.
      if(MENU[2] == "AboutServer") {
        Document    = "This is not a CGI script.\
          This is an httpd, an HTML file, and a CGI script all \
          in one GAWK script. It needs no separate www-server, \
          no installation, and no root privileges.\
          <p>To run it, do this:</p><ul>\
          <li> start this script with \"gawk -f httpserver.awk\",</li>\
          <li> and on the same host let your www browser open location\
               \"http://localhost:8080\"</li>\
          </ul>\<p>\ Details of HTTP come from:</p><ul>\
                <li>Hethmon:  Illustrated Guide to HTTP</p>\
                <li>RFC 2068</li></ul><p>JK 14.9.1997</p>"
      } else if (MENU[2] == "AboutELIZA") {
        Document    = "This is an implementation of the famous ELIZA\
            program by Joseph Weizenbaum. It is written in GAWK and\
    /bin/sh: expad: command not found
      } else if (MENU[2] == "StartELIZA") {
        gsub(/\+/, " ", GETARG["YouSay"])
        # Here we also have to substitute coded special characters
        Document    = "<form method=GET>" \
          "<h3>" ElizaSays(GETARG["YouSay"]) "</h3>\
          <p><input type=text name=YouSay value=\"\" size=60>\
          <br><input type=submit value=\"Tell her about it\"></p></form>"
      }
    }
    

    Now we are down to the heart of ELIZA, so you can see how it works. Initially the user does not say anything; then ELIZA resets its money counter and asks the user to tell what comes to mind open heartedly. The subsequent answers are converted to uppercase and stored for later comparison. ELIZA presents the bill when being confronted with a sentence that contains the phrase "shut up." Otherwise, it looks for keywords in the sentence, conjugates the rest of the sentence, remembers the keyword for later use, and finally selects an answer from the set of possible answers:

    function ElizaSays(YouSay) {
      if (YouSay == "") {
        cost = 0
        answer = "HI, IM ELIZA, TELL ME YOUR PROBLEM"
      } else {
        q = toupper(YouSay)
        gsub("'", "", q)
        if(q == qold) {
          answer = "PLEASE DONT REPEAT YOURSELF !"
        } else {
          if (index(q, "SHUT UP") > 0) {
            answer = "WELL, PLEASE PAY YOUR BILL. ITS EXACTLY ... $"\
                     int(100*rand()+30+cost/100)
          } else {
            qold = q
            w = "-"                 # no keyword recognized yet
            for (i in k) {          # search for keywords
              if (index(q, i) > 0) {
                w = i
                break
              }
            }
            if (w == "-") {         # no keyword, take old subject
              w    = wold
              subj = subjold
            } else {                # find subject 
              subj = substr(q, index(q, w) + length(w)+1)
              wold = w
              subjold = subj        #  remember keyword and subject
            }
            for (i in conj)
               gsub(i, conj[i], q)   # conjugation
            # from all answers to this keyword, select one randomly
            answer = r[indices[int(split(k[w], indices) * rand()) + 1]]
            # insert subject into answer
            gsub("_", subj, answer)
          }
        }
      }
      cost += length(answer) # for later payment : 1 cent per character
      return answer
    }
    

    In the long but simple function SetUpEliza, you can see tables for conjugation, keywords, and answers.(7) distribution.} The associative array k contains indices into the array of answers r. To choose an answer, ELIZA just picks an index randomly:

    function SetUpEliza() {
      srand()
      wold = "-"
      subjold = " "
    
      # table for conjugation
      conj[" ARE "     ] = " AM "
      conj["WERE "     ] = "WAS "
      conj[" YOU "     ] = " I "
      conj["YOUR "     ] = "MY "
      conj[" IVE "     ] =\
      conj[" I HAVE "  ] = " YOU HAVE "
      conj[" YOUVE "   ] =\
      conj[" YOU HAVE "] = " I HAVE "
      conj[" IM "      ] =\
      conj[" I AM "    ] = " YOU ARE "
      conj[" YOURE "   ] =\
      conj[" YOU ARE " ] = " I AM "
    
      # table of all answers
      r[1]   = "DONT YOU BELIEVE THAT I CAN  _"
      r[2]   = "PERHAPS YOU WOULD LIKE TO BE ABLE TO _ ?"
      ...
    
      # table for looking up answers that
      # fit to a certain keyword 
      k["CAN YOU"]      = "1 2 3"
      k["CAN I"]        = "4 5"
      k["YOU ARE"]      =\
      k["YOURE"]        = "6 7 8 9"
      ...
    
    }
    

    Some interesting remarks and details (including the original source code of ELIZA) are found on Mark Humphrys' home page. Yahoo! also has a page with a collection of ELIZA-like programs. Many of them are written in Java, some of them disclosing the Java source code, and a few even explain how to modify the Java source code.

    2.11 Network Programming Caveats

    By now it should be clear that debugging a networked application is more complicated than debugging a single-process single-hosted application. The behavior of a networked application sometimes looks non-causal because it is not reproducible in a strong sense. Whether a network application works or not sometimes depends on the following:

    The most difficult problems for a beginner arise from the hidden states of the underlying network. After closing a TCP connection, it's often necessary to wait a short while before reopening the connection. Even more difficult is the establishment of a connection that previously ended with a "broken pipe." Those connections have to "time out" for a minute or so before they can reopen. Check this with the command `netstat -a', which provides a list of still "active" connections.

    2.12 Where To Go From Here

    Now, you have learned enough to build your own application. You could, for example, take part in the Loebner Contest to win $100,000. The Loebner Prize is the first formal instantiation of a Turing Test. Hugh Loebner agreed with The Cambridge Center for Behavioral Studies to underwrite a contest designed to implement the Turing Test. Dr. Loebner pledged a Grand Prize of $100,000 for the first computer whose responses were indistinguishable from a human's. Each year an annual prize of $2000 and a bronze medal is awarded to the most human computer. The winner of the annual contest is the best entry relative to other entries that year, irrespective of how good it is in an absolute sense. Here is an example of a conversation with the winning program of 1997:

    (c)1997 Cambridge Center For Behavioral Studies all rights reserved [CONVERSE]
    [Intelligent Research Ltd.] Start at: [1997/04/29 08:59:40]
    PROGRAM[10:39:20]Hi, my name is Catherine, what's yours?
    JUDGE02[10:39:36]My name is Nathan.
    PROGRAM[10:39:37]Well, it's nice to meet you, Nathan.
    PROGRAM[10:39:45]Did you see that story on CNN last night about the lesbian
    PROGRAM[10:40:03]couple who came out at a White House party on Sunday?
    JUDGE02[10:40:45]No.  I'm sorry I missed that.  How did the Prez take it?
    PROGRAM[10:40:47]Ellen Degeneres was one of them - she was kissing her lover
    PROGRAM[10:41:08]in front of Bill Clinton. Do you think he was very
    PROGRAM[10:41:21]embarrassed?
    JUDGE02[10:41:37]You tell me.  I didn't see it.
    PROGRAM[10:41:38]Are you still a Friend of Bill Clinton?
    JUDGE02[10:42:22]Yes.  I would like to talk about something else.  Do you know anything about sculpture.
    PROGRAM[10:42:24]Well, I suppose he's doing his best like most of us, but he
    PROGRAM[10:42:35]does seem to attract an UNUSUAL amount of bad publicity,
    PROGRAM[10:42:51]wouldnt you say--can it all be bad luck?
    JUDGE02[10:43:20]I asked you if you knew anything about sculpture.
    PROGRAM[10:43:21]OK, but what happens now--does it all drift on, with
    PROGRAM[10:43:36]everyone waiting to see how much his friends have said about
    PROGRAM[10:43:47]him under threat of lots and lots of jail-or will something
    PROGRAM[10:44:01]dramatic actually happen?
    JUDGE02[10:44:19]Do you know what sculpture is?
    PROGRAM[10:44:20]Well, youre more a fan of his than I am I guess---though I
    PROGRAM[10:44:34]cant SWEAR what Id have done in that locked hotel room, I
    PROGRAM[10:44:51]must say.
    JUDGE02[10:45:26]Have you ever been to the Salmagundi Club?
    PROGRAM[10:45:29]Never. to go back to the original discussion Time to get
    PROGRAM[10:45:43]off this one I think and onto something more down to earth!
    JUDGE02[10:46:20]What is more down to earth than art?
    PROGRAM[10:46:21]I don't know what -- to be honest. -
    PROGRAM[10:46:30]I suppose it depends on where you're coming from, but as the
    PROGRAM[10:46:46]song goes in My Fair Lady, "Why can't a woman be more like a
    PROGRAM[10:47:03]man? "
    JUDGE02[10:47:52]I liked that song but I prefer "Why can't children be more like we are"
    JUDGE02[10:48:10]from another play the name of which I cannot remember.
    PROGRAM[10:48:12]What, if anything, do you enjoy about being a man?
    JUDGE02[10:49:01]I would enjoy all aspects of life no matter what my gender.
    PROGRAM[10:49:02]Do you think of yourself as being attractive?
    

    This program insists on always speaking about the same story around Bill Clinton. You see, even a program with a rather narrow mind can behave so much like a human being that it can win this prize. It is quite common to let these programs talk to each other via network connections. But during the competition itself, the program and its computer have to be present at the place the competition is held. We all would love to see a @command{gawk} program win in such an event. Maybe it is up to you to accomplish this?

    Some other ideas for useful networked applications:


    Go to the first, previous, next, last section, table of contents.