Introduction to Emacs, Tcl, SQL, and OpenACS

Table of Contents:

Introduction

These problem sets are inspired by courses offered at MIT as a teaching tool and latter offered as bootcamps by Arsdigita Corporation as a recruiting tool. They are meant as an introduction to the Open Architecture Community System (OpenACS).

To get some momentum going from the start, it will help tremendously if you know a few things first. Specifically, if you have some real knowledge of the tools that you will be using. While there are some documents available for this purpose, nothing beats actual hands-on experience.

Before you start there are some basics that you need to cover to prevent yourself from getting frustrated. Imagine trying to write three long term papers very quickly without knowing how to touch-type. No fun. It would make sense to spend a few hours beforehand learning to type, right? Same idea here.

This "prequel" problem set will attempt to acquaint you with some of the basics that you will find invaluable while developing with OpenACS and may well help you later on if you continue programming. Specifically, this problem set will point you to the tools that you will need and give you some ideas what to do with them once you get them.

Pick your Editor

(For any non-programmer stow-aways--welcome aboard--an editor is basically a word processor used for writing programs)

Many people have philosphical or even religious reasons for using this or that editor. For others it is just a matter of familiarity. Listing to people argue over why this or that editor is the holy grail can be entertaining, but we are not going to get into that. If you have an editor that your love and have used for years and do not feel like switching, please skip ahead to the OpenACS orientation. If you are new to the area or are open to something new, you should consider Emacs.

Introducing Emacs

Introducing the kitchen-sink editor created by MacArthur Grant-winning free-software pioneer Richard Stallman. Emacs can do just about anything and what it can't do, it can be programmed to do. In fact, you could probably spend a three week intensive course just getting to know Emacs. But fear not--you only need to know how to do a few basic actions in order to be very productive with Emacs. However: it is very, very helpful to know these commands well, to the point that they are in your fingers and not just in your head. If you can get Emacs into your fingers, you will find that Emacs will be your friend, rather than a hindrance.

Now some of you may be thinking, "Oh, I've used Emacs before, this is a waste of my time". Listen up: Knowing *about* Emacs is not the same as *knowing* Emacs. As it happens, people "confuse the map for the territory" all the time. Don't let it happen to you.

Here's the acid test: if you cannot "touch-type" the basic commands in Emacs, you do not know Emacs very well. You might want to rectify this. Doing so is quite easy, especially since there really are only about 20 or so commands that you really need to know--some movement commands, cutting-and-pasting, saving files, splitting the screen, opening a Unix shell and a few more. So, don't just stand there--download Emacs for your machine (unless of course it is already installed on a unix machine you can log into with over a secure shell connection) and get to it!

The Emacs Cheat Sheet

The Emacs Cheat Sheet will help you quickly figure your way around Emacs. You might want to print out the GNU Emacs quick reference card and tape it to the wall.

The Emacs Workout

Emacs comes with its own built-in tutorial. To run it, when Emacs comes up, type: Ctrl-h t
(or, go to the Help menu if you have one and choose "Tutorial")

Although most of the things you need to know are listed below.

One important note before you start: in Emacs,

UNDO = Ctrl-_  (that's an underscore)

Emacs has an infinite undo capability--you just keep doing it and it'll keep rolling back your changes.

"Ctrl-x" means press down the "Ctrl" key and the "x" key together "Meta-x" means press the "Alt" key and the "x" key together
(The "Esc" key also maps to "Meta" and note that on some systems, only one of the "Alt" keys maps to "Meta".

Action Key Commands
Open/Create a new file Ctrl-x  f
Save the File Ctrl-x  s
Exit Emacs Ctrl-x  c
Move up and down the page Pagedown/Pageup or
Ctrl-v (down)
Meta-v (up)
Go to Top/Bottom of Page Meta-< (to bottom)
Meta-> (to top)
Move to end/beginning of the line Ctrl-e to end
Ctrl-a to beginning
Cut-and-paste Ctrl-Spacebar to mark beginning of text

Ctrl-w to cut when you get to the end of text

Ctrl-y to paste
Copy-and-paste Ctrl-spacebar to mark text beginning

Meta-w to copy when you get to the end of text

Ctrl-y to paste
Forward Search Ctrl-s
Backward Search Ctrl-r
Search-and-replace Meta-x query-replace
(you actually type the words "query-replace")
Make more than one window Ctrl-x 2 (for 2)
Ctrl-x 3 (for 3)
Make only one window Ctrl-x 1
Bounce between windows Ctrl-x o
(that's the letter)
Get a working command prompt in Emacs Meta-x shell
(you actually type the word "shell")

Another important note: to get Emacs to format your code nicely, you really should have the following in place:
in your home directory on the machine from which you will be running emacs, create a file called: .emacs
Note the period--this is your "dot emacs" file. In there put the following statement, with parentheses:

(global-font-lock-mode 1)

Now, your Tcl and SQL statements will be highlighted, comments will appear in a different color, etc.

If you don't have a .emacs file, you can have this functionality from within emacs by typing:

M-x global-font-lock-mode

Go into emacs, create a file, type several paragraphs of text. Then move up and down the page, go from one end of a line to another and back. Try splitting the windows and bouncing between them and then going back to only one window. Try searching. And then, try copying and pasting and cutting and pasting.
Try to get good at the copy/paste and cut/paste so you can do them quickly without thinking about it.
Try to drill yourself by repeating these commands till you have them in your fingers. If you can make this investment early on, you will be in good shape.

The idea of being able to open a shell in emacs is important, though you might not be able to really get a sense of what this can do if you are not using Unix. Picture this. You are editing some code and you run it every time you save it. The running code generates error messages into a log file. Wouldn't it be great if you could have the log file show you the errors as you are editing it?

Well, with emacs you can: you can split the screen into two windows, put your file in one and then in the other you can open a shell that you can type commands into. In Unix, you can use the "tail -f" command to get you the end of a file (that is, its tail) whenever lines are added into the file. So, if you ran "tail -f error.log" (or whatever the error log's name is, with its complete path of course), you'd see the error messages as soon as you ran your code, so you could then edit it, save it again and run it, resulting in other errors, or, if you are lucky, no more errors. You see how emacs can make you more productive than other editors?

This only scratches the surface--you can open a Unix shell in emacs and then, typing "tclsh" (without the quotes) open a Tcl shell, so you can type in Tcl expressions and see them get evaluated in one half of a split-screen emacs while you are writing Tcl in the other half of the screen. Neat, eh?

You can also run SQL, that is, you can have a shell with a database promt so you can test queries before you put them into your code and so on.

In fact, Problem Set 1 has been revised to mention this:

Getting started with SQL*Plus

Start up again with Emacs (you took a break, right?) and start a Tcl shell as before ("M-x shell" then "tclsh"). Type "M-x rename-buffer" to rename the shell to "tcl-shell". Type "M-x shell" to then get a new Unix shell. Rename this buffer "sql-shell". In the SQL shell, type "sqlplus" to start SQL*Plus, the Oracle shell client. It's convenient to work like this using two shells, one for Tcl and one for SQL.

While you may not get to do all this stuff, you should be able to get somewhere if you play around with it. Even the commands listed above require a bit of playing around with in order to really get a sense of how Emacs works. Well worth whatever time you can put into it, though.

OpenACS Orientation

In order to understand OpenACS you need to have a general picture of what it is made up of: a powerful scripting language (Tcl), an industrial strength web/application server with the built in Tcl interpreter (AOLServer), a database with the OpenACS data model and logic loaded and ready (in Oracle or PostgreSQL), and a bunch of Tcl glue that is a result of years of work by a whole bunch of REALLY smart people (OpenACS).

Think of these three layers as your toolbox. Each one has functions and

Introducing Tcl


Tcl ("tool command language", pronounced "tickle") is a free open source scripting language originally written by John Ousterhout at the University of California at Berkeley in 1988. It is probably the second most popular Unix scripting language after Perl, yet it is easier to learn and its simplicity makes it easier to read and maintain. Check out the Tcl Advocacy Page for more information.

An important note: Tcl has all the usual file and I/O commands that you'd expect but when you are working with the OpenACS toolkit, you are not likely to be using those kinds of commands--AOLServer, the web server that you will be using to serve up web pages, will handle all that stuff for you with its own set of commands that you call from Tcl--check out the AOLServer section further down for more information.

  • Tcl for Web Nerds

    • Introducing AOLServer

    3a.) "Introduction to AOLServer" 
        by Philip "I-am-so-sick-of-being-the-poster-child-for-AOLServer" Greenspun

    • Part 1 History, why AOLServer, AOLServer vs. Apache, AOLServer open sourced, Programming Intro
    • Part 2 Using Tcl to program AOLServer for database-backed services, material on relational databases

    AOLServer Tcl Commands


    First, all AOLServer Tcl commands are prefixed with "ns" which stands for NaviSoft, the name of the company that wrote AOLServer before AOL bought them. (So you know, AOL has allowed AOLServer to be distributed free and as of version 3, it is an open source product in addition to being free).

    There are a few of these commands that will be of particular interest.

    ns_write

    The first one has to be "ns_write". ns_write is used to spit out HTML, the way that you'd use "print" in Perl to spit out HTML. You can say stuff like:

    ns_write "<HTML><HEAD></HEAD><BODY>Here is some text</BODY></HTML>"

    to put out a page of HTML.

    Or, you can do things like this:

    set variable1  100
    set variable2   200

    ns_write "<HTML><HEAD></HEAD><BODY>"
    ns_write "The result of the calculation is [expr $variable1 + $variable2]"
    ns_write "</BODY></HTML>

     

    And it will print out a page of HTML that looks like this:
     

    The result of the calculation is 300

    That is, Tcl expressions can be embedded in an ns_write command and the Tcl expressions get evaluated and the result gets put into the HTML that AOLServer spits out.

    So, you can imagine that you could have a "proc" (Tcl's name for procedures) that goes out to the Oracle database to get some values to print out on the fly. Perhaps you type your name in and it'll tell you what your address is or whatever. So using ns_write is neat for putting out HTML pages that can be very dynamic.

    One thing about ns_write: every time you use it, you generate network traffic, so, rather than having several ns_writes at the end of a page of Tcl, you want to have just one. How do you deal with having lots of stuff to output? You use the "append" command to build one long string of HTML and all and when you are done building it, you give it in a variable to ns_write.

    So, imagine you've built some long string in a variable called long_string, you could do it like so in your Tcl file:

    set long_string "<HTML><HEAD></HEAD><BODY>"
    ....
    append long_string "BLAH BLAH BLAH"
    ....
    append long_string [get_address_from_the_database firstname lastname]
    ...
    append  long_string "</BODY></HTML>"
     

    ns_write "$long_string"

    So, instead of outputting piecemeal, build the string from HTML, text, calls to procedures (like the call to get_address_from_the_database, an imaginary procedure that we'll imagine is defined somewhere) and then put it out at once.

    Now there are times when you might be doing a lot of database lookups that are slow. In those cases, you might want to have multiple ns_writes so the user sees something happening every so often instead of having to wait for everything to be done before you output anything.

    ns_log

    ns_log lets you write messages out to the error log, so, you can essentially do "write-statement debugging". If you want to make sure that certain things have happened, you can just do:
    set x "Hi"
    ns_log Notice "The value of variable x is: $x"
    set x "Bye"
    ns_log Notice "Now the value of variable x is: $x"

    Make sure that word "Notice" is in there and that you put quotes around the string you are outputting.

    Oh, and if memory serves, by default, all SQL statements output to ns_log.
     

    ns_db

    NEWSFLASH: In ACS 3.3 there is no longer any need to use "ns_db" directly, even to get a database handle!
    There is a spiffy new set of database calls that are much nicer to use than the old stuff.
    Read all about it right here. In other words, you can ignore the rest of this section if you are using ACS 3.3 or greater.

    This command is what you use to connect to the database to do queries, inserts, updates, etc.
    Here are a few links that will help you get a quick feel for this:

    • How to query using ns_db (the basic way--later look at the "Five ways of doing SQL 'Selects'" below)
    • How to insert using ns_db (the begin and end transactions should be uncommented if you are doing several related things (i.e. multiple inserts that are all closely tied together) so that either they all go through or they all are "rolled back")
    • Five ways of doing SQL "Selects" using ns_db (you can get a whole set of rows at once, exactly one row, exactly zero or one row, etc. depending on what your query is supposed to do)
    Full documentation for AOLServer can be found at http://www.aolserver.com/server/documentation.html What you want to read is the Tcl Developer's Guide. The Administrator's Guide is not worth reading and neither is most of the other stuff. The CGI thing wouldn't be bad, but a lot of it is superseded by the OpenACS toolkit, so read it primarily for CGI concepts, which you may already know anyway.
    Installation Help

    I have noticed that this page comes up in google.com when people search for installation information for the Ars Digita software and AOLServer. So, to keep disappointment to a minimum, here are some links in case you are trying to install the Ars Digita stuff at home.

    The following pages are more or less in order that you should look at them I think:


    Original Document by David Cohen. Last Revised: 25.05.04 by Carl Blesius