Function Categories

The AOLserver Tcl functions are divided into four categories. The tables below list the functions in each category. Detailed descriptions of the functions are provided in alphabetical order in the remainder of this chapter.

Core functions

Core functions are available regardless of which modules are or are not loaded.

Function	Description
env	Manipulate environment variables
ns_adminlink	Add a link to /NS/Admin page
ns_atclose	Register a script to be executed when the current connection closes
ns_atshutdown	Register a script to be run at shutdown
ns_atsignal	Register a script to be run in response to a SIGHUP signal
ns_browsermatch	Perform comparison on User-Agent header
ns_cache	Work with Tcl cache
ns_chmod	Change a file's access permissions
ns_config	Extract information from the configuration file
ns_conn	Find information about the HTTP connection
ns_cp	Copy one file to another
ns_cpfp	Copy a specified number of bytes from one file to another
ns_crypt	Encrypt password
ns_eval	Evaluate Tcl (obsolete)
ns_fmttime	Return a formatted date and time
ns_formvalueput	Set the default value for a key in an HTML form
ns_ftruncate	Truncate an open file to a specified length
ns_getcsv	Read CSV data from a file
ns_getform	Return an ns_set that contains all of the query data that was part of the HTTP request
ns_get_multipart_formdata	Handle the POST action of a form containing one file widget
ns_geturl	Fetch a URL
ns_gifsize	Determine the width and height of a GIF87 or GIF89 image
ns_guesstype	Lookup MIME type
ns_hrefs	Return list of HTML <A> links
ns_htmlselect	Build an HTML SELECT form widget using specified data
ns_httpget	Open an HTTP connection and fetch a page
ns_httpopen	Open an HTTP connection
ns_httptime	Convert time in seconds to HTTP header format
ns_info	Find information about AOLserver
ns_library	Return directory for private or shared Tcl library
ns_link	Create a link
ns_localtime	Return local time
ns_log	Write messages to the error log
ns_mkdir	Create a directory
ns_mktemp	Return a unique file name based on a template
ns_normalizepath	Normalize a path
ns_parsehttptime	Return number of seconds from HTTP time
ns_parsetime	Return specified time element from a 10-element formatted time
ns_queryexists	Check for a key in the query data that was part of the HTTP request
ns_queryget	Get a value from the query data that was part of the HTTP request
ns_queryresolve	Query a name server
ns_quota	Check pageroot quota statistics
ns_quotehtml	Escape <, >, and & characters
ns_register_filter	Register a filter function for a method/URL combination
ns_register_proc	Register a procedure for a URL
ns_register_trace	Register a Tcl trace script to a method and matching URL (obsolete)
ns_rename	Rename a file
ns_requestauthorize	Check permissions
ns_respond	Build a complete response
ns_return	Return information to client
ns_rmdir	Remove a directory
ns_rwlock	Create, destroy, and manipulate read/write locks
ns_sendmail	Send a mail message
ns_server	Get information about a virtual server
ns_set	Manipulate sets of key-value pairs
ns_setexpires	Set Expires header
ns_set_precision	Set precision for floating-point to string conversions
ns_share	Share variable among all Tcl interpreters
ns_shutdown	Shut down the server and optionally restart it
ns_sleep	Sleep for a specified number of seconds
ns_socketpair	Create a pair of connected sockets
ns_state_delete	Remove HTML tags from a string
ns_symlink	Create a symbolic link
ns_time	Return current time in seconds
ns_tmpnam	Generate a temporary file name
ns_truncate	Truncate a file to a specified length
ns_unlink	Remove a file
ns_unregister_proc	Unregister a procedure for a URL
ns_updateheader	Change an entry in the output headers
ns_url2file	Return file corresponding to URL
ns_urldecode	Decode characters
ns_urlencode	Encode characters in a URL
ns_write	Write raw content back to the client
ns_writecontent	Write content to a file
ns_writefp	Write file contents to the connection

ADP functions

These functions are for use within AOLserver Dynamic Pages (ADPs):

Function	Description
ns_adp_abort	Stop processing of ADP and throw away all output
ns_adp_argc	Return number of ADP arguments
ns_adp_argv	Return ADP argument values
ns_adp_bind_args	Bind ADP arguments to names
ns_adp_break	Stop processing of ADP and flush all output
ns_adp_dir	Return directory where ADP resides
ns_adp_include	Write contents of file to page
ns_adp_parse	Process an ADP file and return the result as a string
ns_puts	Write string or Tcl command output to page
ns_register_adptag	Register a tag for use within an ADP

Scheduled procedures

These functions allow you to specify a Tcl script to be run daily, weekly, or at specified intervals.

Function	Description
ns_schedule_daily	Schedule a procedure to run once a day
ns_schedule_proc	Schedule a procedure to run at specified intervals
ns_schedule_weekly	Schedule a procedure to run once a week
ns_unschedule_proc	Stop a scheduled procedure

Server statistics

The following Tcl functions allow you to get statistics on the server:

Function	Description
ns_intervalstats	Get server statistics for current interval
ns_resetintervalstats	Reset interval statistics
ns_totalstats	Get server statistics since server startup

Sockets interface

The following functions are available for managing sockets:

Function	Description
ns_hostbyaddr	Resolve an IP address to a hostname
ns_sockaccept	Accept a new socket connection
ns_sockcallback	Register a socket callback script
ns_sockcheck	Check if a socket is connected
ns_socklisten	Create a socket listening for connections
ns_sockopen	Connect to a remote host on the specified port
ns_sockselect	Determine readable file id's

State functions

The following functions are available for maintaining state across connections and server reboots:

Function	Description
ns_state_delete	Remove state data for specified id
ns_state_restore	Return state data for specified id and then remove it
ns_state_save	Save state data to disk and return an id
ns_state_view	Return state data for specified id

Threads interface

The following functions are available for managing threads and thread synchronozation objects:

Function	Description
ns_critsec	Manage critical sections
ns_event	Manage events
ns_mutex	Manage mutexes
ns_sema	Manage semaphores
ns_thread	Manage threads

Access Log Functions

These functions are available only if the nslog module is loaded.

Function	Description
ns_accesslog	Roll the access log on demand and get access log information

Permissions functions

Permissions functions are available only when the nsperm module is loaded. See Chapter 4 for information on the access control system. Note that the entire user interface for the access control system is implemented in Tcl. Follow the nsperm link on the Tcl Script Maintenance page to see the scripts..

Function	Description
ns_group	Add, delete, update, or get information about AOLserver groups
ns_method	Add, delete, or get information about method aliases
ns_passwordcheck	Verify a user/password combination
ns_perm	Add, delete, update, or get information on permissions records
ns_user	Add, delete, update, or get information about AOLserver users

Database Services functions

Database services functions are available only when the nsdb module is loaded.

Function	Description
ns_buildsqldate	Build an SQL date value from specified month, day, and year
ns_buildsqltime	Build an SQL time value from specified time and AM/PM designation
ns_buildsqltimestamp	Build an SQL timestamp from specified month, day, year, time, and AM/PM designation
ns_column	Find information about columns of tables in the database
ns_db	Access the AOLserver database
ns_dbconfigpath	Get nsdb section name
ns_dberror	Return SQL error information
ns_dbformvalue	Retrieve the value of a column specified by form data
ns_dbformvalueput	Set default values in an HTML form for accessing the database
ns_dbquotename	Surround a name by double quotes if it contains a space
ns_dbquotevalue	Prepare a value string for inclusion in an SQL statement
ns_deleterow	Delete row in specified table corresponding to form data
ns_entryform	Return HTML of an entry form for the specified table
ns_entrywidget	Return HTML form elements for entering data into specified table and column
ns_entrywidgetbytype	Return HTML form elements for entering data into specified column and type
ns_ext	Send information to the database proxy daemon
ns_findrowbyid	Return row corresponding to specified key/value pairs
ns_ill	Return Illustra connection information
ns_intervalstats	Insert form data into specified table as a new row
ns_localsqltimestamp	Return a SQL timestamp containing the local time
ns_parsesqldate	Return year, month, or day of specified SQL date value
ns_parsesqltime	Return clock time or AM/PM designation of specified SQL time value
ns_parsesqltimestamp	Return time, AM/PM designation, year, month, or day of specified SQL timestamp
ns_pooldescription	Get database pool description
ns_searchform	Return HTML of a search form for the specified table
ns_searchopwidget	Return HTML form element for searching data by the specified column and type
ns_searchqbf	Return HTML table containing search results corresponding to search form data
ns_table	Find information about tables in the database
ns_updateform	Return HTML of an update form for the specified table and row
ns_updaterow	Update row in specified table using form data
ns_updaterowbyid	Update row corresponding to specified key/value pairs with specified column values

Full Text functions

Full text functions are available only when the nstext module is loaded.

Function	Description
ns_archivetable	Get table name for archiving
ns_hiliteurl	Return a highlight URL
ns_htmltoquery	Get query string from HTML
ns_textarchive	Add or delete URLs from archive
ns_textconfigpath	Get config section for text module
ns_texthandlepool	Get pool used by text module
ns_textindex	Add or delete URLs from index
ns_texttable	Get table name for indexing