AOLserver Wiki - User contributions [en]

Ns respond

2009-05-06T12:22:24Z

Lemuelf: wiki-formatted the page

'''NAME'''
: ns_respond - Build a complete response

'''SYNOPSIS'''
: '''ns_respond''' ''?-status status? ?-type type? {?-string string? | ?-file file? | ?-fileid fileid? } ?-length length? ?-headers setId?''

'''DESCRIPTION'''

: ns_respond builds a complete response for the client with all of the specified information in the header.

'''EXAMPLE'''

: Using ns_respond, it's easy to do an HTTP redirect:

set headers [ns_set new myheaders]
ns_set put $headers location <nowiki>http://www.aolserver.com</nowiki>
ns_respond -status 302 -type text/plain \
-string "redirection" -headers $headers

Tcl API

2009-02-12T08:18:43Z

Lemuelf: /* Custom data structures and variable manipulation commands */ Removed "Network Shared Variables" in the NSV heading, since nothing is network-shared and I believe it stood for "NaviServer Variables"

Links to all of the Tcl commands provided by the AOLserver core "out of the box". To view a complete list of these commands in alphabetical order, try the [[:Category:Core Tcl API]] page.

Like what you see here? Want to try your hand at documenting a command, too? Here's [[how to document the core Tcl API]].

== ADP commands ==

: [[ns_adp_abort]], [[ns_adp_append]], [[ns_adp_argc]], [[ns_adp_argv]], [[ns_adp_bind_args]], [[ns_adp_break]], [[ns_adp_debug]], [[ns_adp_debuginit]], [[ns_adp_dir]], [[ns_adp_dump]], [[ns_adp_eval]], [[ns_adp_exception]], [[ns_adp_include]], [[ns_adp_mime]], [[ns_adp_mimetype]], [[ns_adp_parse]], [[ns_adp_puts]] ([[ns_puts]]), [[ns_adp_registeradp]], [[ns_adp_registerproc]], [[ns_adp_registertag]], [[ns_adp_return]], [[ns_adp_safeeval]], [[ns_adp_stats]], [[ns_adp_stream]], [[ns_adp_tell]], [[ns_adp_trunc]]

: [[ns_browsermatch]]

: [[ns_conn]], [[ns_conncptofp]], [[ns_connsendfp]]

: [[ns_getform]], [[ns_getformfile]]

: [[ns_queryexists]], [[ns_queryget]], [[ns_querygetall]]

: [[ns_return]], [[ns_returnadminnotice]], [[ns_returnbadrequest]], [[ns_returnerror]], [[ns_returnfile]], [[ns_returnforbidden]], [[ns_returnfp]], [[ns_returnnotfound]], [[ns_returnnotice]], [[ns_returnok]], [[ns_returnredirect]], [[ns_returnunauthorized]],

: [[ns_setexpires]], [[ns_setformencoding]]

: [[ns_startcontent]], [[ns_write]], [[ns_writecontent]], [[ns_writefp]]

== Cache commands ==

: [[ns_cache]], [[ns_cache_flush]], [[ns_cache_keys]], [[ns_cache_names]], [[ns_cache_size]], [[ns_cache_stats]]

== Concurrent programming commands ==

: [[ns_cond]], [[ns_critsec]], [[ns_event]], [[ns_job]], [[ns_kill]], [[ns_mutex]], [[ns_sema]], [[ns_thread]]

== Custom data structures and variable manipulation commands ==
* TclX keyed lists:

: [[keyldel]], [[keylget]], [[keylkeys]], [[keylset]]
* [[Thread-shared Variables]] (NSVs):

: [[nsv_get]], [[nsv_exists]], [[nsv_set]], [[nsv_incr]], [[nsv_append]], [[nsv_lappend]], [[nsv_array]], [[nsv_unset]], [[nsv_names]]
* Sets and multisets:

: [[ns_findset]], [[ns_set]]
* ???

: [[ns_share]], [[ns_var]]

== Database commands ==

: [[ns_buildsqldate]], [[ns_buildsqltime]], [[ns_buildsqltimestamp]], [[ns_db]], [[ns_dbquotename]], [[ns_dbquotevalue]], [[ns_localsqltimestamp]], [[ns_parsesqldate]], [[ns_parsesqltime]], [[ns_parsesqltimestamp]], [[ns_writecsv]]

== DNS lookup commands ==

: [[ns_addrbyhost]], [[ns_hostbyaddr]]

== File manipulation commands ==

: [[ns_chmod]], [[ns_cp]], [[ns_ftruncate]], [[ns_link]], [[ns_mkdir]], [[ns_mktemp]], [[ns_normalizepath]], [[ns_openexcl]], [[ns_purgefiles]], [[ns_rename]], [[ns_rmdir]], [[ns_rollfile]], [[ns_symlink]], [[ns_tmpnam]], [[ns_truncate]], [[ns_unlink]]

== HTML manipulation commands ==

: [[ns_formvalueput]], [[ns_hrefs]], [[ns_htmlselect]], [[ns_quotehtml]], [[ns_striphtml]], [[ns_tagelement]], [[ns_tagelementset]]

== HTTP commands ==

: [[ns_http]], [[ns_httpget]], [[ns_httpopen]], [[ns_httppost]]

== Image manipulation commands ==

: [[ns_gifsize]], [[ns_jpegsize]]

== Internationalization (I18N) support commands ==

: [[ns_charsets]], [[ns_choosecharset]], [[ns_cookiecharset]], [[ns_encodingforcharset]], [[ns_encodingfortype]], [[ns_formfieldcharset]], [[ns_urlcharset]]

== Logging commands ==

: [[ns_accesslog]], [[ns_log]], [[ns_logctl]], [[ns_logroll]]

== Request authorization commands ==

: [[ns_checkurl]], [[ns_requestauthorize]]

== Request processing commands ==

: [[ns_register_proc]], [[ns_unregister_proc]]

== Scheduling commands ==

: [[ns_after]], [[ns_atclose]], [[ns_atexit]], [[ns_atshutdown]], [[ns_atsignal]], [[ns_cancel]], [[ns_pause]], [[ns_resume]], [[ns_schedule_proc]], [[ns_schedule_daily]], [[ns_schedule_weekly]], [[ns_shutdown]], [[ns_unschedule_proc]]

== Server configuration commands ==

: [[ns_config]], [[ns_configsection]], [[ns_configsections]], [[ns_library]], [[ns_limits]], [[ns_modulepath]], [[ns_param]], [[ns_pools]], [[ns_section]]

== Server introspection commands ==

: [[ns_env]], [[ns_info]], [[ns_server]], [[ns_stats]]

== Socket I/O commands ==

: [[ns_sock]], [[ns_sockaccept]], [[ns_sockblocking]], [[ns_sockcallback]], [[ns_sockcheck]], [[ns_sockclose]], [[ns_sockdup]], [[ns_sockerrno]], [[ns_socketpair]], [[ns_sockioctl]], [[ns_socklisten]], [[ns_socklistencallback]], [[ns_socknbclose]], [[ns_socknonblocking]], [[ns_socknread]], [[ns_sockopen]], [[ns_sockpair]], [[ns_sockreadwait]], [[ns_sockselect]], [[ns_socksend]], [[ns_sockstrerror]]

== Tcl channel management commands ==

: [[ns_chan]], [[ns_cleanupchans]], [[ns_getchannels]]

== Tcl interpreter management commands ==

: [[ns_cleanup]], [[ns_eval]], [[ns_ictl]], [[ns_init]], [[ns_markfordelete]], [[ns_reinit]]

== Time commands ==

: [[ns_fmttime]], [[ns_gmtime]], [[ns_httptime]], [[ns_localtime]], [[ns_parsehttptime]], [[ns_parsetime]], [[ns_time]]

== Uncategorized ==

: [[ns_cpfp]], [[ns_crypt]], [[ns_geturl]], [[ns_guesstype]], [[ns_headers]], [[ns_isformcached]], [[ns_issmallint]], [[ns_paren]], [[ns_parseheader]], [[ns_parsequery]], [[ns_rand]], [[ns_register_adptag]], [[ns_register_adp]], [[ns_register_filter]], [[ns_register_trace]], [[ns_resetcachedform]], [[ns_sendmail]], [[ns_sleep]], [[ns_sourceproc]], [[ns_unregister_adp]], [[ns_updateheader]], [[ns_url2file]], [[ns_urldecode]], [[ns_urlencode]], [[ns_uudecode]], [[ns_uuencode]]

[[Category:Documentation]]

Thread-shared Variables

2009-02-09T07:38:18Z

Lemuelf: removed "aka Network Shared Variables or NSVs" because nothing is shared in the network and it just confuses people how nsvs work

The nsv commands provide a high performance data sharing mechanism. This facility is a more flexible alternative to the obsolete [[ns_share]] command. The model uses an array syntax and includes more features. In addition, lock contention is managed in a much more scalable way--something that is not possible with the obsolete [[ns_share]] facility.
* [[nsv_get]] - get key value
* [[nsv_exists]] - check key existence
* [[nsv_set]] - set key value
* [[nsv_append]] - append value
* [[nsv_lappend]] - append value as list element
* [[nsv_incr]] - increment and return value
* [[nsv_unset]] - unset a value
* [[nsv_array]] - manage nsv arrays
* [[nsv_names]] - list the nsvs in use

Commands for the most part mirror the corresponding Tcl command for ordinary variables. Basically, to set a value, simply use the nsv_set command:

nsv_set myarray foo $value

and to get a value, simply use the nsv_get command:

set value [nsv_get myarray foo]

What is the difference between nsv_set and nsv_array set? Is it exactly the same as the difference between set and array set?

'''Multithreading Features'''

One advantages of nsv is built in interlocking for thread safety. For example, consider a case of a "increment-by-one" unique id system. Here's the [[ns_share]] solution:

ns_share ids
set ids(lock) [ns_mutex create]
set ids(next) 0

proc nextid {} {
ns_share ids
ns_mutex lock $ids(lock)
set next [incr ids(next)]
ns_mutex unlock $ids(lock)
return $next
}

and here's an nsv solution:

nsv_set ids next 0

proc nextid {} {
return [nsv_incr ids next]
}

Note that the nsv solution does not need a mutex as the [[nsv_incr]] command is internally interlocked.

'''Compatibility with Tcl Arrays'''

Another useful feature of nsv is the [[nsv_array]] command which works much like the Tcl array command. This can be used to import and export values from ordinary Tcl arrays. For example, to copy from Tcl use:

nsv_array set meta [array get tmpmeta]

and to copy to Tcl use:

array set metacopy [nsv_array get meta]

As with all other nsv command, [[nsv_array]] is atomic and no explicit locking is required. This feature can be used to contruct a new nsv array by first filling up an ordinary temporary Tcl array via some time consuming process and then swapping it into place as above. While the new temporary array is being constructed, other threads can access the old array without delay or inconsistant data. You can even reset a complete nsv array in one step with "reset". For example, instead of:

ns_share lock meta
set lock [ns_mutex create]

ns_mutex lock $lock
unset meta
array set meta [array get tmpmeta]
ns_mutex unlock $lock

you can simply use:

nsv_array reset meta [array get tmpmeta]

The reset option will flush and then reset all values atomically, eliminating the need for the explicit lock.

Other options for the nsv_array command include:
* [[nsv_array]] exists ''array'' - test existance of array
* [[nsv_array]] size ''array'' - return # of elements in array
* [[nsv_array]] names ''array'' ''?pattern?'' - return keys of array

'''Configuration'''

The nsv system uses a common multithreading technique to reduce the potential for lock contention which is to split the locks to acheive finer grained locking. This technique groups arrays randomly into buckets and only the arrays within a particular bucket share a lock. The number of buckets to be used can be configured by setting the "nsvbuckets" tcl parameters, e.g.:

[[ns/server/server1/tcl]]
nsvbuckets=20

The default is 8 which should be reasonable. Note that you can monitor the lock contention, if any, by enabling mutex metering:

[[ns/threads]]
mutexmetering=on

and then viewing the results of "[[ns_info]] locks" command after the server has been running for some time. The nsv locks all have names of the form "nsv:##". If you find many lock attempts which did not successed immediately, try increasing nsvbuckets.

'''Migrating From ns_share'''

Migrating from [[ns_share]] is straightforward. If your init.tcl included commands such as:

ns_share myshare
set myshare(lock) [ns_mutex create]

use instead:

nsv_set myshare lock [ns_mutex create]

In your procedures, instead of:

proc myproc {} {
ns_share myshare
ns_mutex lock $myshare(lock) ...

use:

proc myproc {} {
ns_mutex lock [nsv_get myshare lock]
...

and within an ADP page, instead of:

<%
ns_share myshare
ns_puts $myshare(key1)
%>

<%=$myshare(key2)%>

use:

<%
ns_puts [nsv_get myshare key1]
%>

<%=[nsv_get myshare key2]%>

Notice that, unlike [[ns_share]], no command is required to define the shared array. The first attempt at setting the variable through any means will automaticaly create the array. Also notice that only arrays are supported. However, to migrate from [[ns_share]] you can simply package up all existing [[ns_share]] scalars into a single array with a short name, perhaps just ".". For example, if you had:

ns_share mylock myfile
set myfile /tmp/some.file
set mylock [ns_mutex create]

you can use:

nsv_set . myfile /tmp/some.file
nsv_set . mylock [ns_mutex create]

----

[[Category Documentation]] - [[Category Core Tcl API]]

Talk:Thread-shared Variables

2009-02-09T07:35:36Z

Lemuelf: Network Shared or NaviServer?

== Network Shared or NaviServer? ==

Was it really referred to as "network shared variables"? Or nsv stood for Naviserver Variables? Nothing is shared in the network so I guess we shouldn't refer to it as "network shared variables" and so we avoid confusing people how nsvs work. --[[User:Lemuelf|Lemuelf]] 02:35, 9 February 2009 (EST)

Ns parsequery

2009-01-28T08:30:07Z

Lemuelf: fixed markup of sample code

Man page: http://aolserver.com/docs/tcl/ns_parsequery.html

----

'''NAME'''

: ns_parsequery - Parse a URL query string into an ns_set.

'''SYNOPSIS'''

: '''ns_parsequery''' ''querystring''

'''DESCRIPTION'''

: This command parses the specified ''querystring'' into an [[ns_set]], which is returned. The keys and values will be decoded.

'''EXAMPLES'''

% set s [ns_parsequery "msg=Hello+World%21&a=b&a=b&c=d"]
d0

% ns_set array $s
msg {Hello World!} a b a b c d

----

[[Category Documentation]] - [[Category Core Tcl API]]

AOLserver Wishlist

2008-09-17T08:00:56Z

Lemuelf: unwikified proc code

'''You might also want to post your wishes to the AOLserver projects Feature Request[http://sourceforge.net/tracker/?atid=353152&group_id=3152&func=browse] page at Source Forge.'''

----

'''Dossy, 2000-08-14:''' Let this page serve as a place for people to list features and enhancements they would like to see for AOLserver.

----
'''2005-04-12:''' Idea for a simple aolserver installation maker - [[SAIM Proposal]]
----

'''2004-09-17:''' Please add an option to ns_quotehtml to write javascript (ECMAscript) output. Currently I use:

proc ns_quotejs {value} {
for {set i 0} {$i < 256} {incr i} {
if {$i < 32 || $i > 126 || $i == 34 || $i == 39} {
set jsmap([format {%c} $i]) "\\x[format {%02x} $i]"
}
}
set NS_QUOTEJS [array get jsmap]
return [string map $NS_QUOTEJS $value]
}

Which takes about 20 times as long as ns_quotehtml. Perhaps the map from ns_urlencode could be reused.

----

'''2003-06-02:''' Looking forward to full HTTP/1.1 compliance.

----

'''2003-06-02:''' Ultimatley it would be nice to factor out AOLserver functionality into standard Tcl packages which could then be scripted together to make the AOLserver. Historicaly AOLserver functionality has found its way back into the Tcl core (all be it sporadically), and there is also now a fairly full feature Tcl Threads package.

Low hanging fruit to get this started might be a Log module, the Ns_Set data structure.

----

'''2003-06-02:''' The [[ns_db]] interface is showing it's age. It's high performance and built in pooling was great back in the day, but the [[ACS]] db_* interface is far superior, and if implemented natively could skip the costly [[ns_set]] structure.

Might also be nice to link directly to the UnixODBC (see also: [[nsodbc]]) package as a back end to piggy back on all the work other people are doing on those drivers.

----

'''Jerry, 2001-01-15:''' I'd like to see the startup tcls moved into a database, and I'd like to see a system that let one update those initial parameters at run time and have them take effect as soon as possible. ([[maxthreads]], [[maxpost]], [[maxidle]], db pools, [[nsvhr]] hosts, nsvhr mapping, etc.)

----

'''Ian, 2001-06-21:''' An easy way (perhaps with a new flavor of filter) to easily prepend and append output with header and footer html.

And a new bike.

----

I'd like to see a webtrends-style reporting tool to quickly make pretty graphs and charts, thus keeping management gurgling happily in their offices.

''It's not quite Webtrends, but you'' ''can't beat it for the price (free!): webalizer.'' ''And, it works with AOLserver's logfiles! Check it out:'' http://www.webalizer.com/ -- [[Dossy]]

----

'''[[James Newton]], 2001-10-25:''' I'd like to see an HTML editor / publisher like AOLPress tightly integrated to AOLServer so that all the features of server could be easily incorporated in to the pages.

----

It sure would be nice to have the capacity to control how [[nslog]] writes access.log... I would like to add in the optional virtualserver info at the beginning of the line so that I can easily parse that information out when using my log graph generator (webalizer, such a fun toy)...

---

'''Kartic, 2003-03-17:''' How about a web-based configuration tool? Xitami Web server (not as widely used as Apache or AOLserver, free) has one such interface, built-in as a server extension and it is really cool. Such a facility in AOLserver will make life easier for newbies.

----

Standard authorization, authentication, identity, session, and cookie library and model, or at least a bare pluggable framework for authorization, or at the very least a real best practices framework using pre_auth filters or similar.

----

phpinfo() style auto-formatted html output function (see http://us3.php.net/phpinfo) to display aolserver information. raw start at [http://caveman.org/info/] --[[User:Caveman|Caveman]] 09:07, 8 December 2005 (EST)

Ns config

2007-11-21T12:05:46Z

Lemuelf: removed doubling of brackets in a tcl command in the example code so it doesn't appear as a wiki link

Man page: http://aolserver.com/docs/tcl/ns_config.html

----

'''NAME'''

ns_config - Extract configuration information from the server

'''SYNOPSIS'''

'''ns_config''' ''?-exact | -bool | -int? section key ?default?''

'''DESCRIPTION'''

This command returns the value associated with the ''key'' in the specified ''section'' of the current server's configuration. If ''default'' is specified, and the ''section'' and ''key'' are not defined, then ''default'' is returned. If ''default'' is not specified in this situation, an empty string is returned.

If ''-exact'' is specified, matching on ''key'' is case-sensitive. By default, matching is case-insensitive.

If ''-bool'' is specified, '''ns_config''' will perform the conversion of a boolean value from "on", "1", "y", "yes", "t", and "true" to "1", and it will convert a boolean value of "off", "0", "n", "no", "f", and "false" to "0". If a boolean contains any other value, a warning is written to the server log and an empty string is returned. If the configuration value is not defined, an empty string is returned.

If ''-int'' is specified, '''ns_config''' will return the integer value of the specified key. If there is a non-integer value in the configuration, a warning is written to the log file and an empty string is returned.

'''EXAMPLES'''

% ns_config ns/parameters debug
off

% string length [ns_config dummy dummy]
0

% ns_config dummy dummy default
default

'''SEE ALSO'''

[[ns_configsection]], [[ns_configsections]]

----

[[Category Documentation]] - [[Category Core Tcl API]]

Ns findset

2007-05-24T13:30:53Z

Lemuelf: removed double bracket so it will show up as a bracketed tcl command and not as a wiki link

Man page: http://aolserver.com/docs/tcl/ns_findset.html

----

'''NAME'''

: ns_findset - Find a set by its name from a list of sets

'''SYNOPSIS'''

: '''ns_findset''' ''sets name''

'''DESCRIPTION'''

: This command is used to find a set by its ''name'' from a list of ''sets'' and returns the setId of the first set whose name matches ''name'', or returns an empty string if no set matches.

'''EXAMPLES'''

% set sets [list]

% lappend sets [ns_set create foo]
d0

% lappend sets [ns_set create bar]
d0 d1

% lappend sets [ns_set create baz]
d0 d1 d2

% ns_findset $sets bar
d1

% llength [ns_findset $sets quux]
0

% ns_set cleanup

'''SEE ALSO'''

: [[ns_set]]

----

[[Category Documentation]] - [[Category Core Tcl API]]