MBA 683 E-Business Technology --

Home    Site Map    Search    EhrlichOrg.com

Syllabus    Classes    References  Examples  Student Info    Guest Info

TCL old References

The TCL Applications Programming Interface (API) for AOL server applications and .adp pages changed between the Spring and Fall 2000 semesters. These changes correspond to new versions of AOLS Server (3.0) and the ACS (3.4).

This page documents the older style API. You should only need this information if your are looking at older TCL scripts, Greenspun's book, or have learned the old style API.

Summary of API changes

TCL Library Routines and AOL Server API Calls

ns_db gethandle 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.

© 2001 by Chuck Ehrlich, all rights reserved.  Comments to webmaster.  Updated on September 26, 2000.