$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/api/general.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
env get returns the value of the specified environment variable.
env names returns a list of the names of all environment variables. (Only the names are returned, not the values.)
env set sets the specified environment variable to the specified value.
env unset unsets the specified environment variable.
1. Environment variables are not case-sensitive on certain platforms. The env variable code always copied the variables and preserved case into a Tcl array so you may think $env(PATH) wasn't set when in fact $env(Path) was set. This could cause problems when, for example, preparing for an exec. The env command does the right thing and returns the same value with: env get Path or: env get PATH 2. The implementation of env as a variable was not thread safe. 3. The implementation of env as a command always fetches, in a thread safe way, the actual environment variables. In the implementation of env as a variable, on the other hand, the environment variables are copied to the env global array at Tcl interp startup. Therefore, if C code changes the environment, with putenv("foo=bar") for example, the env array wouldn't see the change.
The time argument must specify the date and time as the number of seconds since 00:00:00 UTC, January 1, 1970. You can use the ns_time function to get the current time in this format.
You can use the following elements in the formatstring argument to specify how the returned string will be formatted. The default formatstring is "%a %b %d %T %Y". %% same as %
%a locale's abbreviated weekday name
%A locale's full weekday name
%b locale's abbreviated month name
%B locale's full month name
%c locale's appropriate date and time representation
%C locale's century number (the year divided by 100 and truncated)
%d day of month ( 01 - 31 )
%D date as %m/%d/%y
%e day of month (1-31; single digits are preceded by a blank)
%h locale's abbreviated month name
%H hour ( 00 - 23 )
%I hour ( 01 - 12 )
%j day number of year ( 001 - 366 )
%m month number ( 01 - 12 )
%M minute ( 00 - 59 )
%n same as new-line
%p locale's equivalent of either AM or PM
%r time as %I:%M:%S [AM|PM]
%R time as %H:%M
%S seconds ( 00 - 61 ), allows for leap seconds
%t same as a tab
%T time as %H:%M:%S
%U week number of year ( 00 - 53 ), Sunday is the first day of week1
%w weekday number ( 0 - 6 ), Sunday = 0
%W week number of year ( 00 - 53 ), Monday is the first day of week 1
%x locale's appropriate date representation
%X locale's appropriate time representation
%y year within century ( 00 - 99 )
%Y year as ccyy ( e.g. 1986)
%Z time zone name or no characters if no time zone exists
ns_fmttime [ns_time]Returns the date and time formatted like this:
Wed Oct 29 15:42:11 19972. Calling ns_fmttime as follows:
ns_fmttime [ns_time] "%D %T"Returns the date and time formatted like this:
10/29/97 15:50:26
.ai=application/postscript
.aif=audio/aiff
.aiff=audio/aiff
.ani=application/x-navi-animation
.au=audio/basic
.avi=video/x-msvideo
.bin=application/x-macbinary
.bmp=image/bmp
.dp=application/commonground
.exe=application/octet-stream
.gif=image/gif
.gz=application/x-compressed
.hqx=application/mac-binhex40
.htm=text/html
.html=text/html
.jfif=image/jpeg
.jpe=image/jpeg
.jpg=image/jpeg
.jpeg=image/jpeg
.map=application/x-navimap
.mov=video/quicktime
.mpe=video/mpeg
.mpeg=video/mpeg
.mpg=video/mpeg
.nvd=application/x-navidoc
.nvm=application/x-navimap
.pbm=image/x-portable-bitmap
.pdf=application/pdf
.pgm=image/x-portable-graymap
.pic=image/pict
.pict=image/pict
.pnm=image/x-portable-anymap
.ps=application/postscript
.qt=video/quicktime
.ras=image/x-cmu-raster
.rgb=image/x-rgb
.rtf=application/rtf
.sit=application/x-stuffit
.snd=audio/basic
.stl=application/x-navistyle
.tar=appliation/x-tar
.text=text/plain
.tgz=application/x-compressed
.tif=image/tiff
.tiff=image/tiff
.txt=text/plain
.xbm=image/x-xbitmap
.xpm=image/x-xpixmap
.wav=audio/x-wav
.z=application/x-compressed
.zip=application/x-compressed
The result of the above command might be:
1996-05-22 00:15:58
seconds (0-59) minutes (0-59) hours (0-23) dayofmonth (1-31) monthofyear (0-11) year (year-1900)* dayofweek (Sunday=0) dayofyear (0-365) 1 if Daylight Savings Time is in effectAll values are numeric. Note that the year value can be longer than two digits, which allows for years past 1999. This is sometimes incorrectly assumed to be a "Y2K bug" but it is not.
ns_rand is implemented with the drand48(3) and lrand48(3) standard library functions. An internal random seed is generated the first time ns_rand is called after the server is started.
ns_register_filter when method URLpattern myScript ?args? proc myScript {?conn? args why} { # Do stuff... }
This function will be called at the specified stage of a connection, if the method/URL combination for the filter matches the method/URL combination for the connection using glob style matching.
The URLpattern can contain standard string-matching characters. For example, these are valid URLpatterns:
/employees/*.tcl /accounts/*/outValid values for the "when" argument are: preauth, postauth, and trace.
Using pre-authorization, the procedure will be called (assuming that the method/URL combination matches) just before authorization. If the procedure returns with a code of:
* TCL_OK (using: return "filter_ok"): The server will continue to the next pre-authorization filter for this connection, or, if there are no more pre-authorization filters, it will continue on with authorization. * TCL_BREAK (using: return "filter_break"): The server will not process any more pre-authorization filters for this connection, and it will continue on with authorization. * TCL_RETURN (using: return "filter_return"): The server will close the connection and will not run any more pre-authorization filters. It will not authorize the request, and it will not run the function registered for this METHOD/URL. It WILL run any trace functions registered for this METHOD/URL, usually including logging. It is assumed that the filter has sent a proper response (e.g., using ns_return) to the client before returning TCL_RETURN.Using post-authorization, the procedure will be called (assuming that the method/URL combination matches) just after successful authorization. If the procedure returns:
* TCL_OK (using: return "filter_ok"): The server will continue to the next post-authorization filter for this connection, or, if there are no more post-authorization filters, it will run the function registered to handle this request. * TCL_BREAK (using: return "filter_break"): The server will not process any more post-authorization filters for this connection, and it will run the function registered to handle this request. * TCL_RETURN (using: return "filter_return"): The server will close the connection and will not run any more post-authorization filters and it will not run the function registered for this METHOD/URL. It WILL run any trace functions registered for this METHOD/URL, usually including logging. It is assumed that the filter has returned a proper response (e.g., using ns_return) to the client before returning TCL_RETURN.Using trace, the procedure will be called (assuming that the method/URL combination match) after the connection has been totally processed and closed. If the procedure returns:
* TCL_OK (using: return "filter_ok"): The server will continue to the next trace filter. * TCL_BREAK, TCL_RETURN (using: return "filter_break" or return "filter_return"): The rest of the trace filters are ignored.
ns_register_filter trace GET /noargs filter_noargs ns_register_filter trace GET /context filter_context fnord ns_register_filter trace GET /conncontext filter_conncontext proc filter_noargs { why } { ns_log Notice "filter noargs" return filter_ok } ;# filter_noargs proc filter_context { arg why } { ns_log Notice "filter context. Arg: $arg" return filter_ok } ;# filter_noargs proc filter_conncontext { conn arg why } { ns_log Notice "filter conn context" return filter_ok } ;# filter_noargsThe conn (connection) argument is required for procedures registered by ns_register_filter if the procedure has 3 or more arguments (including why but not including conn). The conn argument is automatically filled with the connection information. The first argument following conn will always take the value supplied by ns_register_filter, if there is one, or an empty value. The why argument at the end is automatically filled with the type of filter requested. All other arguments must supply a default value. The following examples show the variations that can be used in this case:
ns_register_filter postauth GET /threeargs threeargs aaa ns_register_filter postauth GET /fourargs fourargs aaa bbb ccc proc threeargs { conn context { greeble bork } why } { ... } ; proc fourargs { conn context { greeble bork } {hoover quark} why } { ... } ;When a GET of /threeargs is requested, the conn and why arguments will be filled automatically, the context argument will be assigned "aaa" and the greeble argument will be assigned the default value "bork".
When a GET of /fourargs is requested, the conn and why arguments will be filled automatically, the context argument will be assigned "aaa", the greeble argument will be assigned "bbb", and the hoover argument will be assigned the default value "quark".
Be aware that executing the same ns_register_filter statement more than once (as you might do when re-initializing Tcl) will add the filter more than once! You may want to have a shared variable set so that you don't do this.
ns_share -init {set filters_installed 0} filters_installed if {!$filters_installed} { set filters_installed 1 ns_register_filter postauth GET /*.html ExpireSoon 3600 } proc ExpireSoon {seconds why} { ns_set update [ns_conn outputheaders] Expires \ [ns_httptime [expr $seconds + [ns_time]]] }
ns_register_proc ?-noinherit? method URL myProc ?args? proc myProc {?conn? args} { # Do stuff... }
If -noinherit is specified, the requested URL must match the specified URL exactly. For example, if the URL specified with ns_register_proc is /foo/bar, procname will not be called unless the requested URL is exactly /foo/bar.
If -noinherit is not specified, the requested URL can match the specified URL or any URL below it. For example, if the URL specified with ns_register_proc is /foo/bar, procname will be called for /foo/bar, /foo/bar/hmm, and any other URL below /foo/bar, provided there is not already another procedure registered for that exact URL or for an URL with a closer match.
Note that you must use a glob-style matching character if you want inheritance for file names. For example, if you want /foo/bar to match /foo/bar.html, you must use: ns_register_proc /foo/bar*
You can register two procedures for any given method/URL combination by calling ns_register_proc once with the -noinherit flag set and once without it. Only one of the procedures will be called for any given request, depending on whether the URL was an exact match or not. For example:
ns_register_proc -noinherit GET /foo/bar Aproc ns_register_proc GET /foo/bar Bproc ns_register_proc GET /foo/bar/hmm Cproc
Aproc will be called when the requested URL is exactly /foo/bar. Bproc will be called when the requested URL is below /foo/bar, provided there is not already another procedure registered to be called for that exact URL or for an URL with a closer match. Cproc (not Bproc) will be called when the requested URL is equal to or below /foo/bar/hmm.
ns_register_proc GET /noargs noargs ns_register_proc GET /context context fnord ns_register_proc GET /conncontext conncontext greeble proc noargs { } { ns_returnnotice 200 "noargs" } ;# noargs proc context { context } { ns_returnnotice 200 "context is $context" } ;# context proc conncontext { conn context } { ns_returnnotice 200 "conncontext is $context" } ;# conncontextThe conn (connection) argument is required for procedures registered by ns_register_proc if the procedure has 2 or more arguments (not including conn). The conn argument will be filled automatically with the connection information. The first argument following conn will always take the value supplied by ns_register_proc, if there is one, or an empty value. All other arguments must supply a default value. The following examples show the variations that can be used in this case:
ns_register_proc GET /twoargs twoargs fnord ns_register_proc GET /threeargs threeargs fnord fjord proc twoargs { conn context { greeble bork } } { # Do stuff... } proc threeargs { conn context {greeble bork } { hoover quark } { # Do stuff... }When a GET of /twoargs is requested, the conn argument will be filled automatically, the context argument will be assigned "fnord" and the greeble argument will be assigned the default value "bork".
When a GET of /threeargs is requested, the conn argument will be filled automatically, the context argument will be assigned "fnord" and the greeble argument will be assigned "fjord", and the hoover argument will be assigned the default value "quark".
(Note: This function is obsolete. Use ns_register_filter instead.)
The URLpattern can contain standard string-matching characters. For example, these are valid URLpatterns:
/employees/*.tcl /accounts/*/out
ns_register_proc results in a single match, whereas multiple ns_register_trace's can be matched and will be called.
You can add additional headers (such as an Errors-To header) by specifying the set ID of an ns_set that contains header name and content pairs in the extraheaders argument. On error, a Tcl error is signaled.
Specify BCC recipients in the bcc argument. Separate multiple BCC recipients by commas. If you want to specify BCC recipients, you'll need to specify the extraheaders argument, too, but the extraheaders argument can be empty.
ns_sendmail uses the SMTP server specified by the MailHost parameter in the configuration file. If MailHost is not specified in the configuration file, localhost is used. You can also specify an SMTP smarterhost in the SmtpPort parameter in the configuration file.
ns_sendmail is RFC #822 compliant.
ns_set copy -persist setId
ns_set cput setId key value
ns_set create -persist name
ns_set delete setId fieldNumber
ns_set delkey setId key
ns_set find setId key
ns_set free setId
ns_set get setId key
ns_set icput setId key value
ns_set idelkey setId key
ns_set ifind setId key
ns_set iget setId key
ns_set isnull setId fieldNumber
ns_set iunique setId key
ns_set key setId fieldNumber
ns_set merge high low
ns_set move to from
ns_set name setId
ns_set new -persist name
ns_set print setId
ns_set put setId key value
ns_set size setId
ns_set split -persist setId ?splitChar?
ns_set truncate setId size
ns_set unique setId key
ns_set update setId key value
ns_set value setId fieldNumber
ns_set cput appends a new field to the set with key key and value value if the field does not already exist in the set. The field number of the new field is returned.
ns_set create (which is the same as ns_set new) allocates memory for a new set and returns the ID for the new set. If -persist is specified, the new set will persist even after the current transaction ends, and you can free it later with ns_set free. If -persist is not specified, the new set is automatically freed when the transaction ends.
ns_set delete deletes the field in the set at field number fieldNumber.
ns_set delkey removes the first field in the set whose key is key. Note that there could be multiple fields in the set with this key; this command only removes the first occurrence.
ns_set find returns the index of the first field in the specified set whose key name matches the specified key. Zero (0) is the index of the first field. If no matching fields are found, ns_set find returns -1.
ns_set free frees the specified set. Sets must be explicitly freed with ns_set free if the -persist option was used when creating the set. Otherwise, sets are automatically freed when the transaction ends.
ns_set get returns the first value associated with the passed-in key. If the key is invalid, an empty string is returned.
ns_set icput is the case-insensitive counterpart of ns_set cput.
ns_set idelkey is the case-insensitive counterpart of ns_set delkey.
ns_set ifind is the case-insensitive counterpart of ns_set find.
ns_set iget is the case-insensitive counterpart of ns_set get.
ns_set isnull returns 1 if the value of the field specified by fieldNumber is null and 0 if it is not. Note that an empty string is not the same as a null. ns_set isnull will return 0 for an empty string.
ns_set iunique returns 1 if the specified key is unique in the specified set and 0 if it is not. The test for uniqueness is performed case-insensitively. ns_set unique is the case-sensitive version of this function.
For example, a client could send multiple "Accept:" headers which would end up in the header set for the connection. ns_set iunique would return 0 for the "Accept:" key, because there are multiple fields with the key "Accept:".
ns_set key extracts the key of the set at field number fieldNumber. This command is useful when looping through all the key-value pairs in the set.
ns_set merge merges two sets. Any fields in the low set are appended to the high set if a field with the same key name does not already exist in the high set.
ns_set move moves all fields from the from set to the end of the to set, leaving the from set a valid, empty set.
ns_set name returns the name of the set.
ns_set new (which is the same as ns_set create) allocates memory for a new set and returns the ID for the new set. If -persist is specified, the new set will persist even after the current transaction ends, and you can free it later with ns_set free. If -persist is not specified, the new set is automatically freed when the transaction ends.
ns_set print prints the specified set to stderr.
ns_set put appends a new field to the set with key key and value value. Note that the field is appended so if a previous field has the same key as the new field, the previous field is returned by ns_set get command. The field number of the new field is returned.
ns_set size returns the number of key-value pairs in the set.
ns_set split splits one set into multiple sets based on the splitChar as described below and returns a Tcl list of the newly-allocated sets. It assumes that the keys in the specified set (setId) contain a specific character (splitChar) that can be used to separate the name of a new set and the key in the new set. The default splitChar is a period (.).
For example, if two fields in the original set have "dog.food" and "cat.food" as their key names and "Yummy dog food!" and "Yummy cat food!" as their values, ns_set split would return two new sets named "dog" and "cat". The dog set would have a single field whose key is "food" and whose value is "Yummy dog food!". The cat set would have a single field whose key is "food" and whose value is "Yummy cat food!".
ns_set truncate reduces the set to the first size key-value pairs and frees the memory for the rest of the key-value pairs that may have been in the set.
ns_set unique returns 1 if the specified key is unique in the specified set and 0 if it is not. The test for uniqueness is performed case-sensitively. ns_set iunique is the case-insensitive version of this function.
ns_set update updates the first field in the specified set whose key is key and replaces its value with value. ns_set update is equivalent to ns_set delkey followed by ns_set put.
ns_set value extracts the value of the set at field number fieldNumber. This command is useful when looping through all the key-value pairs in the set.
Share variable among all Tcl interpreters.
ns_share should be called in a script designed to be run only once, such as in the init.tcl script for private or shared libraries. Due to the way ns_share handles thread concurrency, execessive use of ns_share can have severe performance penalties.
Multiple variables can be specified by separating the variable names with spaces:
ns_share count length widthYou can optionally specify an init script when you share a single variable (not when sharing multiple variables) to initialize the variable at the same time. The following example sets the variable count to 0 immediately after sharing it, and the next line increments it to 1:
ns_share -init {set count 0} count incr count
You can initialize shared arrays like this:
ns_share -init { set itemlist(a) "Value 1" set itemlist(b) "Value 2" }Unlike global variables, shared variables are not available by default at the global level. You must share a variable at the top level also and not just in procedures that want to reference the variable. For example:
ns_share pagelength set pagelength "50" proc page { conn i } { ns_share pagelength # ... }
nevsky:/gteiXVtAXVqQ:28:1:Musician:/:/bin/shThe first two characters of the encrypted password are the SALT. Since calling the function like:
ns_crypt /g alexander
returns "/gte...Q", then "alexander" is the correct password.
`<` becomes `<'
`>` becomes `>'
`&' becomes `&'.
This encoding is defined in RFC #1738, Uniform Resource Locators (URL).
This encoding is defined in RFC #1738, Uniform Resource Locators (URL).
Note: This is HTTP-style uuencoding per RFC #1113--sometimes called "htuu"--and is not compatible with the format used by the Unix uuencode/uudecode commands, nor is it base-64 encoding.
Note: This is HTTP-style uuencoding per RFC #1113--sometimes called "htuu"--and is not compatible with the format used by the Unix uuencode/uudecode commands, nor is it base-64 encoding.