Quick Install of OpenACS

Created by Malte Sussdorff, last modified by Gustaf Neumann 29 Sep 2019, at 10:19 AM

Setup user

Especially for incoming e-mail, each webserver should run with it's own user. We are going to use the service name "service0" throughout this script to denote a couple of things needed to run your webserver "www.service0.com": 

• username to run the service
• username in the database
• database name in postgresql
• service name for aolserver
  

First add the unix user:

Now it is time to prepare the database for the OpenACS System:

PostgreSQL 

Make sure to have PostgreSQL installed 

Oracle

Make sure to have Oracle installed 

After the user is setup, login as this user and get the source files. Furthermore configure the config file.

 sudo su - $SERVICE0 

If you do this directly from OpenACS you can run:

cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -r oacs-5-3 openacs-4

mv openacs-4/* . 

If you want to use SVN you can run

svn co https://svn.cognovis.de/openacs/branches/oacs-5-3 .

If you are working within cognovis and start a new client project do the following

export REPOS=https://svn.cognovis.de/
svn mkdir $REPOS/$SERVICE0 $REPOS/$SERVICE0 $REPOS/$SERVICE0/branches $REPOS/$SERVICE0/tags -m "Creating clientname directory structure"
svn copy $REPOS/openacs/branches/oacs-5-3 $REPOS/$SERVICE0/trunk
svn co $REPOS/$SERVICE0/trunk .

cp etc/config.tcl etc/`whoami`.tcl     
perl -pi*.bak -e "s/service0/`whoami`/g" etc/`whoami`.tcl    
perl -pi*.bak -e "s/service0/`whoami`/g" etc/daemontools/run    
perl -pi*.bak -e "s/config/`whoami`/g" etc/daemontools/run 
    

This will get the latest openacs from the current release branch into your service name. If you need certain packages to come from HEAD you can still update them later.

As root make sure the system is under daemontools control:

# Logout to become root again 
exit   
sudo ln -s /var/lib/aolserver/$SERVICE0/etc/daemontools /service/$SERVICE0 
sudo svgroup web /service/* 

You are now configured to start your OpenACS installation on http://127.0.0.1:8000 unless some other server has been running there.

If you want to install .LRN issue the following command:

You can verify that your server is running by looking at /var/lib/aolserver/$SERVICE0/log/error.log

If you want to edit your config files, here is their location

• /var/lib/aolserver/SERVICE0/etc/SERVICE0.tcl
  This contains the configuration parameters and is usually referred to as "config" file.
  
• /var/lib/aolserver/SERVICE0/etc/daemontools/run
  If you made changes to the IP Address and the port you will need to edit this file:
  
• add the "-b" switch to match your ip address and port right after "nsd-postgres", before the "-it ..." part

Last but not least make sure incoming E-Mail will work (for a full installation overview look at incoming_email. First add your domain to the virtual_domains in /etc/postfix/main.cf then execute the following commands:

Now it is time to setup the backup and keepalive correctly. First edit /var/lib/aolserver/$SERVICE0/etc/keepalive/keepalive-config.tcl to include your server.

Then copy /var/lib/aolserver/$SERVICE0/etc/backup.sh to /var/lib/aolserver/$SERVICE0/etc/backup-$SERVICE0.sh and edit it to reflect your environment.

Last but not least login as $SERVICE0 and edit the crontab

File in the following data, replaceing service0 where occuring.

Webservices Support (TWiST)

To support webservices there exists the tool called "TWiST". To download and install it onto your server the following steps need to be taken:

cd /var/lib/aolserver/service0/tcl
svn checkout http://twsdl.googlecode.com/svn/tags/twist-0.9.9 twist-0.9.9
mv twist-0.9.9 twsdl

Then you need to edit your config file at /var/lib/aolserver/SERVICE0/etc/SERVICE0.tcl by adding the following in the modules section:

ns_section ns/server/${server}/modules
ns_param twsdl tcl

Basic String Operations

Created by Hal Abelson, Philip Greenspun, and Lydia Sandon, last modified by Gustaf Neumann 03 Mar 2017, at 08:42 AM

set whole_page "some stuff for the top of the page\n\n"
append whole_page "some stuff for the middle of the page\n\n"
append whole_page "some stuff for the bottom of the page\n\n"
# done composing the page, let's write it back to the user
ns_return 200 text/html $whole_page

# compare the first_names value to the empty string
if { [string compare $first_names ""] == 0 } {
    lappend exception_list "You forgot to type your first name"
}

# see if their email address has the form
#   something at-sign something
if { ![regexp {.+@.+} $email] } {
    lappend exception_list "Your email address doesn't look valid."
}

if { [string length $password] > 20 } {
    lappend exception_list "The password you selected is too long."
}

# remove whitespace from ends of input (if any)
set last_name_trimmed [string trim $last_name]

# escape any single quotes with an extra one (since the SQL
# string literal quoting system uses single quotes)
regsub -all ' $last_name_trimmed '' last_name_final

set sql_insert "insert into users (..., last_name, ...) 
values 
(..., '$last_name_final', ...)"

Looking for stuff in a string

The simplest way to look for a substring within a string is with the string first command. Some users of photo.net complained that they didn't like seeing classified ads that were simply pointers to the eBay auction site. Here's a simplified snippet from http://software.arsdigita.com/www/gc/place-ad-3.tcl:

if { [string first "ebay" [string tolower $full_ad]] != -1 } {
    # return an exception
    ...
}

if { [regexp -nocase {ebay} $full_ad] } {
    # return an exception
    ...
}

If you're just trying to find a substring, you can use either string first or regexp. If you're trying to do something more subtle, you'll need regexp (described more fully in the chapter "Pattern Matching"):

if { ![regexp {[a-z]} $full_ad] } {
    # no lowercase letters in the ad!
    append exception_text "
      
      
            
      
Your ad appears to be all uppercase.  
ON THE INTERNET THIS IS CONSIDERED SHOUTING.  IT IS ALSO MUCH 
HARDER TO READ THAN MIXED CASE TEXT.  So we don't allow it, 
out of decorum and consideration for people who may 
be visually impaired."
    incr exception_count
}

      
    

Using only part of a string 

In the ArsDigita Community System, we have a page that shows a user's complete history with a Web service, e.g., http://photo.net/shared/community-member.tcl?user_id=23069 shows all of the postings by Philip Greenspun. If a comment on a static page is short, we want to show the entire message. If not, we want to show just the first 1000 characters.

In http://software.arsdigita.com/www/shared/community-member.tcl, we find the following use of the string range command:

if { [string length $message] > 1000 } {
    set complete_message "[string range $message 0 1000]... "
} else {
    set complete_message $message
}

Fortran-style formatting and reading of numbers 

The Tcl commands format and scan resemble C's printf and scanf commands. That's pretty much all that any Tcl manual will tell you about these commands, which means that you're kind of S.O.L. if you don't know C. The basic idea of these commands comes from Fortran, a computer language developed by John Backus at IBM in 1954. The FORMAT command in Fortran would let you control the printed display of a number, including such aspects as spaces of padding to the left and digits of precision after the decimal point.

With Tcl format, the first argument is a pattern for how you'd like the final output to look. Inside the pattern are placeholders for values. The second through Nth arguments to format are the values themselves:

format pattern value1 value2 value3 .. valueN

% # format prices with two digits after the point
% format "Price:  %0.2f" 17
Price:  17.00
% # pad some stuff out to fill 20 spaces
% format "%20s" "a long thing"
        a long thing
% format "%20s" "23"
                  23
% # notice that the 20 spaces is a MINIMUM; use string range
% # if you might need to truncate
% format "%20s" "something way longer than 20 spaces"
something way longer than 20 spaces
% # turn a number into an ASCII character
% format "%c" 65
A

% # turn an ASCII character into a number
% scan "A" "%c" the_ascii_value
1
% set the_ascii_value
65
% 

Reference: String operations

A.) Commands that don't start with string

• append variable_name value1 value2 value3 ... valueN
  sets the variable defined by variable_name to the concatenation of the old value and all the remaining arguments (http://www.tcl.tk/man/tcl8.4/TclCmd/append.htm)
• regexp ?switches? expression string ?matchVar? ?subMatchVar subMatchVar ...?
  Returns 1 if expression matches string; 0 otherwise. If successful, regexp sets the match variables to the parts of string that matches the corresponding parts of expression.

  % set fraction "5/6"
  5/6
  % regexp {(.*)/(.*)} $fraction match num denom
  1
  % set match
  5/6
  % set num
  5
  % set denom
  6
  

  (more: the pattern matching chapter and http://www.tcl.tk/man/tcl8.4/TclCmd/regexp.htm)
• regsub ?switches? expression string substitution_spec result_variable_name
  Returns a count of the number of matching items that were found and replaced. Primarily called for its effect in setting result_variable_name.

  Here's an example where we ask a user to type in keywords, separated by commands. We then expect to feed this list to a full-text search indexer that will throw an error if handed two commas in a row. We use regsub to clean up what the user typed:

  # here we destructively modify the variable $query_string'
  # replacing every occurrence of one or more commas with a single
  # command 
  % set query_string "samoyed,, sledding, harness"
  samoyed,, sledding, harness
  % regsub -all {,+} $query_string "," query_string
  2
  % set query_string
  samoyed, sledding, harness
  

  (more: the pattern matching chapter and http://www.tcl.tk/man/tcl8.4/TclCmd/regsub.htm)
  

  were dramatically improved with the Tcl 8.1 release. For a Web developer the most important feature is the inclusion of non-greedy regular expressions. This makes it easy to match the contents of HTML tags. See http://www.scriptics.com/services/support/howto/regexp81.html for a full discussion of the differences.

  B.) Commands that start with string

  (all of which are documented at http://www.tcl.tk/man/tcl8.4/TclCmd/string.htm)

• string compare string1 string2
  returns 0 if the two strings are equal, -1 if string1 sorts lexicographically before string2, 1 if string2 sorts lexicographically before string1:

  string compare apple applesauce  ==> -1
  string compare apple Apple ==> 1
  

• string first string1 string2
  returns -1 if string1 is not within string2, else returns the index of the first occurrence. Indices start from zero, e.g.,

  string first tcl catclaw  ==> 2
  

• string last string1 string2
  -1 if string1 is not within string2, else index of last occurrence.

  string last abra abracadabra ==> 7
  

• string match pattern string
  1 if string matches pattern, 0 if not. See the chapter on pattern matching for an explanation of patterns.

• string range string i j
  range of characters in string from index i to j, inclusive.

  string range catclaw 2 4 ==> tcl
  

• string tolower string
  string in lower case.

  string compare weBmaster Webmaster => 1
  
  string compare [string tolower weBmaster] \
                 [string tolower Webmaster] => 0
  

• string toupper string
  string in upper case.

  set password "ferrari"
  string compare "FERRARI" [string toupper $password] ==> 0
  

• string trim string ?chars?
  trims chars from right and left side of string; defaults to whitespace.

  set password [string trim $form_password] ; # see above example
  

• string trimleft string ?chars?
  trims chars from left of string; defaults to whitespace.

  set password [string trimleft $form_password] 
  

• string trimright string ?chars?
  trims chars from right of string; defaults to whitespace.

  set password [string trimright $form_password] 
  

• string wordend string index
  index of the first character after the last character of the word containing index.

  string wordend "tcl is the greatest" 0 ==>3
  

• string wordstart string index
  index of the first char of the word containing index.

  string wordstart "tcl is the greatest" 5 ==> 4
  

Exercises ( see section V.3  List Operations )

---

based on Tcl for Web Nerds 

Install Oracle 8.1.7

Created by Gustaf Neumann, last modified by Gustaf Neumann 05 Dec 2016, at 08:09 AM

export ORACLE_BASE=/ora8/m01/app/oracle
export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
export PATH=$PATH:$ORACLE_HOME/bin
export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
export ORACLE_SID=ora8
export ORACLE_TERM=vt100
export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data

umask 022

open_cursors = 500

nls_date_format = "YYYY-MM-DD"

nls_date_format = "YYYY-MM-DD"

SQL> select sysdate from dual;

SQL> column sysdate format a15
SQL> select sysdate from dual;

[joeuser ~]$ svrmgrl
SVRMGR> connect internal
Connected.
SVRMGR> shutdown
Database closed.
Database dismounted.
ORACLE instance shut down.
SVRMGR> startup
ORACLE instance started.

export nls_lang = american

export nls_date_format = 'YYYY-MM-DD'

here

Created by Gustaf Neumann, last modified by Gustaf Neumann 06 Nov 2016, at 09:43 AM

-- acceptance-sql.txt by philg@mit.edu and jsc@arsdigita.com
--                      (Philip Greenspun and Jin Choi)

-- SQL commands to test an Oracle installation
-- for adequate privileges and capacity
-- run as the same user as the Web user

-- creating a table
create table foo (
	foo_key	integer primary key,
	random	varchar(1000)
);

-- creating an index
create index foo_on_random on foo ( random );

-- inserting some rows
insert into foo values (1, '1');
insert into foo values (2, '2');
insert into foo values (3, '3');
insert into foo values (4, '4');
insert into foo values (5, '5');
insert into foo values (6, '6');
insert into foo values (7, '7');
insert into foo values (8, '8');
insert into foo values (9, '9');
insert into foo values (10, '10');
insert into foo values (11, null);
insert into foo values (12, null);
insert into foo values (13, null);
insert into foo values (14, null);
insert into foo values (15, null);
insert into foo values (16, null);
insert into foo values (17, null);
insert into foo values (18, null);
insert into foo values (19, null);
insert into foo values (20, null);

-- create another table to work with
create table bar as select foo_key + 1 as bar_key, random from foo;

-- joins
select b.random from foo f, bar b where f.foo_key = b.bar_key and f.random like '3%';

-- update
update foo set foo_key = foo_key + 100 where random is null;

-- should return 10
select count(*) from foo where foo_key > 100;

-- create a sequence
create sequence foo_sequence start with 200;

-- test whether truncate works
truncate table bar;

drop table bar;


-- test 1) whether has privileges to create a procedure
--  and 2)  whether rollback segments are adequately sized

-- create a pl/sql procedure
create or replace procedure thrash_database(v_number_of_rows IN integer)
AS
  i	integer;
BEGIN
  FOR i IN 1..v_number_of_rows LOOP
    insert into foo (foo_key, random) values (foo_sequence.nextval, 'abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghij');
  END LOOP;
END thrash_database;
/
show errors

-- we think any Oracle installation ought to be able to handle
-- 100,000 rows of 500 bytes each

execute thrash_database(100000);

select count(*) from foo;

commit;

delete from foo;
commit;

drop table foo;
drop sequence foo_sequence;
drop procedure thrash_database;

-- make sure that NLS_DATE_FORMAT is correct by 
-- seeing that the following command returns
-- YYYY-MM-DD (e.g., 1999-05-22)

select sysdate from dual;

Escaping to the procedural world

Created by Anett Szabo, last modified by Gustaf Neumann 13 Feb 2009, at 09:37 AM

Declarative languages can be very powerful and reliable, but sometimes it is easier to think about things procedurally. One way to do this is by using a procedural language in the database client. For example, with AOLserver we generally program in Tcl, a procedural language, and read the results of SQL queries. For example, in the /news module of the ArsDigita Community System, we want to

• query for the current news
• loop through the rows that come back and display one line for each row (with a link to a page that will show the full story)
• for the first three rows, see if the news story is very short. If so, just display it on this page

Here's the AOLserver Tcl program. Note that depending on the contents of an item in the news table, the Tcl program may execute an SQL query (to figure out if there are user comments on a short news item).

set selection [ns_db select $db "select * 
from news
where sysdate between release_date and expiration_date
and approved_p = 't'
order by release_date desc, creation_date desc"]

while { [ns_db getrow $db $selection] } {
    set_variables_after_query
    # we use the luxury of Tcl to format the date nicely
    ns_write "<li>[util_AnsiDatetoPrettyDate $release_date]: "
    if { $counter <= 3 && [string length $body] < 300 } {
	# it is one of the top three items and it is rather short
	# so, let's consider displaying it right here
	# first, let's go back to Oracle to find out if there are any
	# comments on this item
	set n_comments [database_to_tcl_string $db_sub "select count(*) from general_comments where on_what_id = $news_id and on_which_table = 'news'"]
	if { $n_comments > 0 } {
	    # there are some comments; just show the title
	    ns_write "<a href=\"item.tcl?news_id=$news_id\">$title</a>\n"
	} else {
	    # let's show the whole news item
	    ns_write "$title\n<blockquote>\n[util_maybe_convert_to_html $body $html_p]\n"
	    if {[parameter::get -parameter SolicitCommentsP -default 1]} {
		ns_write "<br><br>\n<A HREF=\"comment-add.tcl?news_id=$news_id\">comment</a>\n"
	    }
	    ns_write "</blockquote>\n"
	}
    } else {
	ns_write "<a href=\"item.tcl?news_id=$news_id\">$title</a>\n"
    }
}

Suppose that you have a million rows in your news table, you want five, but you can only figure out which five with a bit of procedural logic. Does it really make sense to drag those million rows of data all the way across the network from the database server to your client application and then throw out 999,995 rows?

Or suppose that you're querying a million-row table and want the results back in a strange order. Does it make sense to build a million-row data structure in your client application, sort them in the client program, then return the sorted rows to the user?

Visit http://www.scorecard.org/chemical-profiles/ and search for "benzene". Note that there are 328 chemicals whose names contain the string "benzene":

select count(*) 
from chemical 
where upper(edf_chem_name) like upper('%benzene%');

  COUNT(*)
----------
       328

• exact matches on top
• line break
• chemicals that start with the query string
• line break
• chemicals that contain the query string

Can you do all of that with one query? And have them come back from the database in the desired order?

You could if you could make a procedure that would run inside the database. For each row, the procedure would compute a score reflecting goodness of match. To get the order correct, you need only ORDER BY this score. To get the line breaks right, you need only have your application program watch for changes in score. For the fine tuning of sorting equally scored matches alphabetically, just write another procedure that will return a chemical name stripped of leading special characters, then sort by the result. Here's how it looks:

select edf_chem_name, 
       edf_substance_id, 
       score_chem_name_match_score(upper(edf_chem_name),upper('%benzene%'))
          as match_score
from chemical
where upper(edf_chem_name) like upper('%benzene%');
order by score_chem_name_match_score(upper(edf_chem_name),upper('benzene')), 
         score_chem_name_for_sorting(edf_chem_name)

We specify the procedure score_chem_name_match_score to take two arguments: one the chemical name from the current row, and one the query string from the user. It returns 0 for an exact match, 1 for a chemical whose name begins with the query string, and 2 in all other cases (remember that this is only used in queries where a LIKE clause ensures that every chemical name at least contains the query string. Once we defined this procedure, we'd be able to call it from a SQL query, the same way that we can call built-in SQL functions such as upper.

So is this possible? Yes, in all "enterprise-class" relational database management systems. Historically, each DBMS has had a proprietary language for these stored procedures. Starting in 1997, DBMS companies began to put Java byte-code interpreters into the database server. Oracle added Java-in-the-server capability with its 8.1 release in February 1999. If you're looking at old systems such as Scorecard, though, you'll be looking at procedures in Oracle's venerable PL/SQL language:

create or replace function score_chem_name_match_score
 (chem_name IN varchar, query_string IN varchar)
return integer
AS
BEGIN
  IF chem_name = query_string THEN
     return 0;
  ELSIF instr(chem_name,query_string) = 1 THEN
     return 1;
  ELSE
     return 2;
  END IF;
END score_chem_name_match_score;

create or replace function score_chem_name_for_sorting (chem_name IN varchar)
return varchar
AS
  stripped_chem_name chem_hazid_ref.edf_chem_name%TYPE;
BEGIN
  stripped_chem_name := ltrim(chem_name,'1234567890-+()[],'' #');
  return stripped_chem_name;
END score_chem_name_for_sorting;

If you are using the Oracle application SQL*Plus to define PL/SQL functions, you have to terminate each definition with a line containing only the character "/". If SQL*Plus reports that there were errors in evaluating your definition, you then have to type "show errors" if you want more explanation. Unless you expect to write perfect code all the time, it can be convenient to leave these SQL*Plus incantations in your .sql files. Here's an example:

-- note that we prefix the incoming arg with v_ to keep it 
-- distinguishable from the database column of the same name
-- this is a common PL/SQL convention
create or replace function user_group_name_from_id (v_group_id IN integer)
return varchar
IS
  -- instead of worrying about how many characters to
  -- allocate for this local variable, we just tell
  -- Oracle "make it the same type as the group_name
  -- column in the user_groups table"
  v_group_name    user_groups.group_name%TYPE;
BEGIN
  if v_group_id is null
     then return '';
  end if;
  -- note the usage of INTO below, which pulls a column
  -- from the table into a local variable
  select group_name into v_group_name 
   from user_groups 
   where group_id = v_group_id;
  return v_group_name;
END;
/
show errors

Choosing between PL/SQL and Java

Reference

• Overview: Oracle8 Server Application Developer's Guide, "Using Procedures and Packages" at http://www.oradoc.com/keyword/using_procedures_and_packages
• PL/SQL User's Guide and Reference at http://www.oradoc.com/keyword/plsql
• Java Stored Procedures Developer's Guide at http://www.oradoc.com/keyword/java_stored_procedures

---

based on  SQL for Web Nerds

Control Structure

Created by Anett Szabo, last modified by Gustaf Neumann 13 Feb 2009, at 09:27 AM

• conditional
• looping (iteration)
• error-handling
• miscellaneous (non-local exit)

The Fundamental Conditional Command: if

The most basic Tcl control structure is the if command:

if boolean ?then? body1 ?else? ?body2?

if {condition} {
   body
}

if {condition} {
   body
} elseif {other_condition} {
   alternate_body
} else {
   another_body
}

if {condition} {
   body
} elseif {other_condition} {
   alternate_body
} else {
   another_body
}

Let's look at an example from http://software.arsdigita.com/www/register/user-login.tcl. At this point in the ArsDigita Community System flow, a user has already typed his or her email address.

# Get the user ID
set selection [ns_db 0or1row $db "select user_id, user_state, converted_p from users \
   where upper(email)=upper('$QQemail')"]

if {$selection == ""} {
    # Oracle didn't find a row; this email addres is not in the database
    # redirect this person to the new user registration page
    ns_returnredirect "user-new.tcl?[export_url_vars return_url email]"
    return
} 

if {[parameter::get -parameter AllowPersistentLoginP -default 1]} {
    # publisher has elected to provide an option to issue
    # a persistent cookie with user_id and crypted password
    if {[parameter::get -parameter PersistentLoginDefaultP -default 1]} {
        # persistent cookie shoudl be the default
	set checked_option "CHECKED" 
    } else {
	set checked_option "" 
    }
    ns_write "<input type=checkbox name=persistent_cookie_p value=t $checked_option> 
Remember this address and password?  
(<a href=\"explain-persistent-cookies.adp\">help</a>)"
}

set checked_option [if {[parameter::get ...]} {
    subst "CHECKED" 
} else {
    subst ""
}]

Another Conditional Command: switch

The switch dispatches on the value of its first argument: particular variable as follows:

switch flags value {
   pattern1 body1
   pattern2 body2
   ...
}

switch $user_state {
    "authorized" { # just move on } 
    "banned" { 
	ns_returnredirect "banned-user.tcl?user_id=$user_id" 
	return
    }
    "deleted" {  
	ns_returnredirect "deleted-user.tcl?user_id=$user_id" 
	return
    }
    "need_email_verification_and_admin_approv" {
	ns_returnredirect "awaiting-email-verification.tcl?user_id=$user_id"
	return
    }
    "need_admin_approv" { 
	ns_returnredirect "awaiting-approval.tcl?user_id=$user_id"
	return
    }
    "need_email_verification" {
	ns_returnredirect "awaiting-email-verification.tcl?user_id=$user_id"
	return
    }
    "rejected" {
	ns_returnredirect "awaiting-approval.tcl?user_id=$user_id"
	return
    }
    default {
	ns_log Warning "Problem with registration state machine on user-login.tcl"
	ad_return_error "Problem with login" "There was a problem authenticating the account: $user_id. Most likely, the database contains users with no user_state."
	return
    }
}

It is possible to use more sophisticated patterns in switch. Here's a fragment that sends different email depending on the pattern of the address:

switch -glob $email {
   {*mit.edu} { ns_sendmail $email $from $subject $body }
   {*cmu.edu} { ns_sendmail $email $from $subject "$body\n\nP.S. Consider applying to MIT.  Boston is much nicer than Pittsburgh"}
   {*harvard.edu} { ns_sendmail $email $from $subject "$body\n\nP.S. Please ask your parents to invest in our tech startup."}
}

The third behavior for switch is invoked using the "-regexp" flag. See the pattern matching chapter for more on how these patterns work.

More: http://www.tcl.tk/man/tcl8.4/TclCmd/switch.htm

Looping commands while, foreach, and for

The while command in Tcl operates as follows:

while { conditional_statement } {
   loop_body_statements
}

Here is a while statement used to display the last name, first name of each MIT nerd using a Web service. The conditional is the result of calling AOLserver's ns_db getrow API procedure. This procedure returns 1 if it can fetch the next row from the SQL cursor, 0 if there aren't any more rows to fetch.

set selection [ns_db select $db "select first_names, last_name from users \
   where lower(email) like '%mit.edu'"]

while { [ns_db getrow $db $selection] } { 
    # set local variables to the SQL column names
    set_variables_after_query
    ns_write "<LI>$last_name, $first_names"
}

More: http://www.tcl.tk/man/tcl8.4/TclCmd/while.htm

The Tcl foreach command loops through the elements of a list, setting a loop variable to each element in term:

foreach variable_name list {
   body
}

# ask AOLserver to return a list of lists, one for each current connection
set connections [ns_server active]

foreach connection $connections {
    # separate the sublist elements with "
        
        " tags
    ns_write $conn "
        
        
        
        [join $connection "
        
        "]"
}
      
      

proc check_file {f} {
    # alert the administrator that we're working on this file
    ns_write "<li>$f\n<ul>\n"
    # read the contents into $content
    set stream [open $f]
    set content [read $stream]
    close $stream
    # loop through each reference, relying on API call ns_hrefs
    # to parse the HTML and tell us where this file points
    foreach url [ns_hrefs $content] {
	# do all the hard work
        ...
    }
    ns_write "</ul>\n"
}

Notice how easy this procedure was to write thanks to the AOLserver developers thoughtfully providing us with ns_hrefs, which takes an HTML string and returns a list of every HREF target.

More: http://www.tcl.tk/man/tcl8.4/TclCmd/foreach.htm

The last looping command, for, is good for traditional "for i from 1 to 10" kind of iteration. Here's the syntax:

for start test next body

for {set i 1} {$i <= $n_winners} {incr i} {
    # we'll have winner_numbers between 0 and $n_contestants - 1
    # because randomRange returns a random integer between 0 
    # and its argument
    lappend winner_numbers [randomRange $n_contestants]
}

More: http://www.tcl.tk/man/tcl8.4/TclCmd/for.htm

Error-handling command: catch

If a Tcl command throws an error in a CGI script or an AOLserver API page, by default the user will be presented with an error page. If you don't want that to happen, fix your bugs! Sometimes it isn't possible to fix your bugs. For example, the ns_httpget API procedure fetches a Web page from the wider Internet. Under certain network-dependent conditions, it may throw an error. If you don't want your users to be exposed to that as an error, put in a catch:

catch script ?variable_name?

Our classic example always involves ns_httpget. Here's one from http://www.webho.com/WealthClock:

# define a procedure that computes the entire page
proc wealth_ReturnWholePage {} {
    # do a couple of ns_httpgets and some arithmetic
    # to produce the user-visible HTML 
    ...
}

# this is the procedure registered to http://www.webho.com/WealthClock
proc wealth_Top {ignore} {
    if [catch {set moby_string [Memoize wealth_ReturnWholePage]} errmsg] {
	# something went wrong with our sources 
        ... return an apology message to the users
    } else {
	# we computed the result (or Memoize got it from the cache)
	ns_return 200 text/html $moby_string
    }
}

Sending email is another time that a Web server has to go outside its carefully controlled world and might experience an error. Here is the entire http://software.arsdigita.com/tcl/ad-monitor.tcl, which implements a central facility for other sections in the ArsDigita Community System. The idea is that programmers can put in "email the administrator if broken" instructions on pages that won't result in a nightmare for the administrator if the page is getting hit every few seconds.

# the overall goal here is that the ad_host_administrator gets
# notified if something is horribly wrong, but not more than once
# every 15 minutes

# we store the last [ns_time] (seconds since 1970) notification time 
# in ad_host_administrator_last_notified

ns_share -init { set ad_host_administrator_last_notified 0 } ad_host_administrator_last_notified

proc ad_notify_host_administrator {subject body {log_p 0}} {
    ns_share ad_host_administrator_last_notified
    if $log_p {
	# usually the error will be in the error log anyway
	ns_log Notice "ad_notify_host_administrator: $subject\n\n$body\n\n"
    }
    if { [ns_time] > [expr $ad_host_administrator_last_notified + 900] } {
	# more than 15 minutes have elapsed since last note
	set ad_notify_host_administrator [ns_time]
	if [catch { ns_sendmail [ad_host_administrator] [ad_system_owner] $subject $body } errmsg] {
	    ns_log Error "failed sending email note to [ad_host_administrator]"
	}
    }
}

Make sure that you don't overuse catch. The last thing that you want is a page failing silently. Genuine errors should always be brought to a user's attention and ideally to the site administrator's. Users should not think that a server has done something on their behalf when in fact the task was not accomplished.

More: http://www.tcl.tk/man/tcl8.4/TclCmd/catch.htm

Miscellaneous commands: break, continue, return, and error

When inside a looping command, it is sometimes desirable to get the command to stop looping or to stop executing the current iteration but to continue on the next one. The break command is used to permanently escape the loop; the continue command is used to escape the current iteration of the loop but to start again at the next iteration. The syntax for each consists only of the appropriate word written on a line by itself within a loop.

We often use the break command when we want to limit the number of rows to display from the database. Here's an example from the photo.net neighbor-to-neighbor system. By default, we only want to show a "reasonable" number of postings on one page:

set selection [ns_db select $db ... big SQL query ... ]

set list_items ""
# see what the publisher thinks is a reasonable number (default to 100)
set n_reasonable [parameter::get -parameter NReasonablePostings -default 100]

# initialize a counter of the number of rows displayed so far
set counter 0
while {[ns_db getrow $db $selection]} {
    set_variables_after_query
    incr counter
    if { $counter > $n_reasonable) } {
	# append ellipses 
	append list_items "<p>\n..."
	# flush the database cursor (tell Oracle that we don't need the
	# rest of the rows)
	ns_db flush $db 
	# break out of the loop
	break
    }
    append list_items "<li><a href=\"view-one.tcl ..."

}

More: http://www.tcl.tk/man/tcl8.4/TclCmd/break.htm

The return command has been shown before. It quits the proc it's in and returns the supplied value. Remember that any procedure lines after return aren't executed. Too many times we've seen code of the following form:

proc a_new_programmers_proc {} {
    set db [ns_db gethandle]
    # do a bunch of stuff with the database
    return $result
    # release the database handle
    ns_db releasehandle $db 
}

proc ad_maybe_redirect_for_registration {} {
    if { [ad_verify_and_get_user_id] != 0 } {
	# user is in fact logged in, return happiness
	return
    } else {
	ns_returnredirect "/register/index.tcl?return_url=[ns_urlencode [ns_conn url]$url_args]"
	# blow out of 2 levels
	return -code return
    }
}

ad_maybe_redirect_for_registration 

# the code below will never get executed if the user isn't registered
# ... update the database or whatever ...

More: http://www.tcl.tk/man/tcl8.4/TclCmd/return.htm

The error command returns from a proc and and raises an error that, if not caught by a catch statement, will result in the user seeing a server error page. The first argument to error is displayed in the debugging backtrace:

proc divide {x y} {
   if {$y == 0} {
      error "Can't divide by zero."
   } else {
      return [expr {$x / $y}]
   }
}     

More: http://www.tcl.tk/man/tcl8.4/TclCmd/error.htm

---

based on Tcl for Web Nerds 

Basic infrastructure

Created by Anett Szabo, last modified by Anett Szabo 14 Aug 2007, at 05:12 PM

2.1. AOLserver

OpenACS is built atop the mighty AOLserver, the open source, multithreaded HTTP
server that powers http://www.aol.com. AOLserver provides a rich Tcl API, server-side
processing of custom tags via AOLserver Dynamic Pages (ADP), database connection
pooling and a cron-like service for running scheduled code in the background. For more
about AOLserver, please see the AOLserver home page (http://www.aolserver.com).

2.2. Templating system

 
OpenACS divides responsibility for serving most requests among two or three file types
having distinct purposes. The basic split is between a script file that sets up dynamic
variables and a markup file that renders them. The script file is a Tcl script having a .tcl
extension. The markup file has an .adp extension and looks much like standard HTML.
In fact, HTML is valid ADP, providing a gentle slope for programmers and designers
who are just getting started with the framework. Because they resemble HTML, ADP
files may be edited in standard tools such as Dreamweaver.
The OpenACS templating system supports the ability to work with page fragments via
the <include> tag. The same Tcl/ADP file pair idiom operates at this level. Hence if a
page contains a tag
<include src=”motd”>
the template system will search the current filesystem directory for motd.tcl to set up the
dynamic variables and motd.adp for the markup.
More interestingly, the OpenACS templating system supports a master/slave relationship
among page fragments. A page fragment that specifies a <master> will have its contents
embedded into the master template at a location designated by the <slave> tag in that
template. Master templates are typically used to standardize headers and footers across a
site. A nice property of the master/slave system is that the master template provides a
bird’s eye view of the entire page in a single file. And of course, the same Tcl/ADP file
pair idiom applies to master templates as well.
Before we get too far down the two-file path it’s worth pointing out a third type of file
that also participates in serving most requests: the query file. Query files have an .xql
extension and contain SQL that is specific to the template. The function of these files
will be explored further in the next section.

2.3. Database API

The OpenACS database API is designed to maximize Tcl integration with the database,
allowing data to pass back and forth as simply and naturally as possible. Let’s dive in
and consider a code example:

2.4. Declarative programming

Among other Web development frameworks, OpenACS is still unique, powerful and
simple, and that’s based on the programming advantages created within the OpenACS,
such as declarative programming, which is understood as the opposite of writing the
logic of the program using the normal procedural programming, instead use an special
declarative syntax to reflect how the program will act, based on a possible entry, but not
relied only on that. A positive effect of writing in a declarative syntax is that the
programs usually are more robust in its behavior and more readable by other developers,
since the declarative syntax is standard and always more ordered.

2.4.1. Form processing, ad_form

As an example, for web form management, OpenACS has ad_form. This procedure
implements a high-level, declarative syntax for the generation and handling of HTML
forms. It includes special syntax for the handling of forms tied to database entries,
including the automatic generation and handling of primary keys generated from
sequences. You can declare code blocks to be executed when the form is submitted, new
data is to be added, or existing data modified.

In this example, ad_form will first check to see if my_table_key was passed to the
script. If not, the database will be called to generate a new key value from
my_table_sequence. If defined, the query defined by -select_query will be
used to fill the form elements with existing data.
On submission, the validation block checks that the user has entered at least three
characters into the textarea. If the validation check fails the value element will be
tagged with the error message, which will be displayed in the form when it is rendered. If
the validation check returns true, one of the new_data or edit_data code blocks will
be executed depending on whether or not my_table_key was defined during the initial
request. my_table_key is passed as a hidden form variable and is signed and verified.
This example illustrates how to declare a form, define validation and define a set of
actions to be taken on standard events.
More information about ad_form can be found here: http://openacs.org/api-doc/procview?
proc=ad%5fform, from which part of this sub section has been taken.

2.4.2. List builder

The list-builder is used create sophisticated table-like reports with many popular
capabilities, here is an example.

For this example you see first the -name of the list-builder. Then the declaration of the
-multirow name used for populating the report with data, which is usually extracted
from the database. Then the -elements (columns) to be displayed in the report. Each
element is defined as a name of the variable that is set at the multirow in the case
that the variable will be used as data to be displayed in that column, like
instance_name. Also the element name can be an arbitrary name in the case that
is used the parameter display_template, which is used to include HTML tags or
ADP logic when displaying data passed by the multirow. For each element you always
define label which is the title of the column, and more special parameters such as:
link_url_col that expect a variable name which must be set at the multirow that
contains a link for automatically display the data of that column as a link.
The list builder has many more important features like order by column, filters, bulk
actions, pagination, etc.
And this is the result seen in the browser produce by the list-builder example:

2.4.3. Upgrades

Since OpenACS is a modular system consisting on independent packages, each package
has its own version and can require upgrade scripts when updating the package in a given
OpenACS installation. This is a simple example of a declarative upgrade syntax:

Configuring an OpenACS package

Created by Malte Sussdorff, last modified by Malte Sussdorff 07 Aug 2007, at 04:33 PM

Configure OpenACS look and feel with templates

Created by Malte Sussdorff, last modified by Malte Sussdorff 07 Aug 2007, at 04:28 PM

Configuring a new OpenACS Site

Created by Malte Sussdorff, last modified by Malte Sussdorff 07 Aug 2007, at 04:26 PM