MBA 669 E-Business Technology --

Home    Site Map    Search    EhrlichOrg.com

Syllabus    Classes    References    Student Info    Guest Info

TCL References

The TCL (pronounced 'tickle') programming language is supported by the AOL server environment that we are using for this course.  TCL programs can be embedded into Web pages and will be executed automatically when the page is accessed.  This is an extremely convenient way to develop programs that avoids all the software tools and compiling steps required for other programming languages.

This page provides a short guide to the subset of TCL you will need for this course.  See also additional references.

TCL code can be executed four ways, we primarily use the first alternative:

1. Files with the .adp extension may contain embedded TCL scripts enclosed between <% and %> tags, these scripts should use ns_adp_puts to write to the browser.  
2. ADP files may contain TCL code enclosed in <%= and %>, the result of this code is written automatically.  However, we will use only the <% %> form because its easier to test.
3. Files with the .tcl extension contain TCL code that is executed when the page is referenced.  The code may create Web pages or do other things.
4. Run TCL under Linux by typing tclsh.  

TCL variables:

TCL Syntax

Commands are terminated by the end of a line (called a newline) or a semicolon.

Whitespace (space or tab) is used to separate commands and arguments.

# indicated that rest of the line is a comment.  A backslash continues a comment to another line.  Use ;# to put a comment on the same line as a command.  Note that comments should only appear between TCL commands.  Comments embedded inside TCL commands may cause problems.

$ dollar sign returns the value of a variable.

[ ] brackets are used to nest commands.

Double quotes " " or curly braces { }  are used to group words together into one argument.  Quotes allow substitution (evaluation) of the contents, curly braces prevent substitution.

\ backslash is used to allow substituting characters that would otherwise have special meaning to TCL such as newline (\n).  Use \ to quote TCL special characters:

TCL Commands

set variable [exp].  For example the TCL equivalent of a=b is 

set a $b

expr evaluate an arithmetic expression (see Arithmetic Operators below).  The TCL equivalent of a=b+2 is:

set a [expr $b +2 ]

incr var, increment command adds one to a variable.  The equivalent of c=c+1 or c++ in C or Java is:

incr c

ns_adp_puts writes a string to the client.  In ADP pages, use ns_adp_puts instead puts or ns_write.  

ns_adp_puts "the value of a is $a."

format forms values according to a formatting specification and value like this:

format "%2.2f" $pure

Format may be used inside the string for ns_adp_puts like this:

ns_adp_puts "value is [format "%2.2f" $pure]% pure"

If $pure equals 99.98765 the result will be:

value is 99.99% pure

Format specifications are enclosed in quotes, begin with % followed by the formatting flags and ends with the format type.  Format flags include the number of characters as well as the following values:

Format types include:

If then, if then else conditional commands (comparison operators are defined below) are shown below.  The then command is optional.  

If {$x==0} {
    incr zero_count
} else {
    incr non_zero_count
}

Compound conditional statements may be created using elseif. 

If {$x==0} {
    incr zero_count
} elseif {$x<0} {
    incr neg_count
} else {
    incr pos_count
}

While loop with test clause and body.  Note that the condition ($x<=10) must be enclosed in braces ({$x<=10}) or an infinite loop will result.

Set x 1
While {$x<=10} {
    ns_adp_puts ‘line $x<br>’
    incr x
}

Info exists, test if a TCL variable has been defined.  Note that HTML Form variables will not be defined if the field is omitted.  Use info exists to check and provide an error message or a default value.

if {![info exists foo]||[$foo==""] } {
    ns_adp_puts "You must enter a value!"
    }

TCL String Operations

TCL Operators 

! is logical Not

* Multiply, / Divide, % Remainder

+ Add, - Subtract

< Less Than, <= Less Than or Equal

> Greater Than, >= Greater Than or Equal 

== test for Equal

!= test for Not Equal

&& is logical And

|| is logical Or

Note: logical operators treat 1 as true and 0 as false.

TCL Library Routines and AOL Server API Calls

ns_db get handle gets a database connection, required before any other database operation.

set db [ns_db gethandle]

ns_db select executes a SQL Select statement and copies the results into TCL variables for processing with ns_db_getrow (below).  Substitute your own Select statement, table name, and column names.  Select statements may not be nested, that is you can't issue a second select using the results of the first.  Note the qualified table name (chuck.s) and no semi-colon (;) at the end of the SQL statement.  

set selection [ns_db select $db "select * from chuck.s order by sid" ] 

The select statement may include values of TCL variables, for example if the lookup name is in variable foo.

set selection [ns_db select $db "select * from chuck.s where sname='$foo'" ] 

ns_db getrow returns one database row from the result of a ns_db select.  Use within a while loop with set_variables_after_query to make TCL variables based on SQL Select results for each column and row.  

while { [ns_db getrow $db $selection] } {
    set_variables_after_query
    # sets sid and sname
    set sname [ns_set get $selection sname]
    ns_adp_puts "$sid: $sname<br>"
}

ns_db dml execute a SQL Data Manipulation Language command such as Insert, Update or Delete.

ns_dbquotevalue prepares a string value for inclusion in an SQL statement by adding quotes and doubling any single quotes included in the string.  Empty strings ("") are translated to NULL.

set value "Wonka's Wonder"
ns_db dml $db \
"insert into s(sname) values ([ns_dbquotevalue $value])"

ns_time returns the current system time, use with ns_fmttime (below) to format the results.

ns_fmttime formats server time (ns_time) values.  For example: 

ns_fmttime [ns_time] "%A, %B %e, %Y at %r"

Options include: Weekday short (%a) or long (%A), Month name short (%b) or long (%B), Day of month (%e), Year short (%y) or long (%Y), Time hh:mm:ss xM (%r), 24 hour time hh:mm:ss (%T), or hh:mm (%R),  etc.

ns_returnredirect switches the user to a different page by doing a HTTP redirect.  Can be used on helper page if there no messages the user needs to see.  For example:

ns_returnredirect "helper-2.adp"

set_form_variables creates TCL variables with the same names as form fields.  Use set_the_usual_form_variables (below) instead so you have the QQ versions.    

set_the_usual_form_variables like set_form_variables but also makes QQ versions of names for handling quoted strings correctly.  Include a comment listing the variables you expect this routine to set.

set_the_usual_form_variables
# sets sid, QQsid, sname, QQsname

Note that fields that are not filled in, checked or selected do not pass their values, consequently variables will not be created.  Use the function export_var to access values of these variable.  export_var will return an empty string ("") if the variable is not defined.  See also info exists.

TCL Examples

Greenspun 378, 442, 467, 510, 515

Additional References

For more information on TCL see:

Note: we are not using Tk, a toolkit for building graphical user interfaces. 

© 2000 by Chuck Ehrlich, all rights reserved.  Comments to webmaster.  Updated on April 17, 2000.