$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/api/adp.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
ns_adp_abort closes the connection without returning an empty HTML page. Every ns_returnxxx call in an ADP should be followed with a call to ns_adp_abort.
The return_value, if specified, becomes the return value of the ADP.
Note that this function returns all the way up the call stack. For example, suppose a.adp includes b.adp which includes c.adp, and c.adp calls ns_adp_abort. No code in b.adp or a.adp after the includes will be executed. You can get around this in one of two ways:
* You can execute these calls in a.adp and b.adp, respectively: catch {ns_adp_include b.adp} retval catch {ns_adp_include c.adp} retval * Or, you can execute this call in c.adp: ns_adp_return ?retval?
The ns_adp_return function returns up only one level.
In foo.adp, the two arguments are bound as follows:
ns_adp_bind_args x y
The value "bar" is assigned to the variable x, and the value "baz" is assigned to the variable y.
The return_value, if specified, becomes the return value of the ADP.
Note that this function returns all the way up the call stack. For example, suppose a.adp includes b.adp which includes c.adp, and c.adp calls ns_adp_break. No code in b.adp or a.adp after the includes will be executed. You can get around this in one of two ways:
* You can execute these calls in a.adp and b.adp, respectively: catch {ns_adp_include b.adp} retval catch {ns_adp_include c.adp} retval * Or, you can execute this call in c.adp: ns_adp_return ?retval?
The ns_adp_return function returns up only one level.
debuginit "procs" "host" "port"
If the -parser switch is specified, the ADP is evaluated using the specified parser. You can specify one of the pre-defined parsers, "adp" or "fancy", or an alternate parser that you have registered with the Ns_AdpRegisterParser C API function. By default, the parser specified by the DefaultParser parameter is used. If no DefaultParser is specified, the "adp" parser is used.
This function returns 1 if the status is "ok" and 0 otherwise. If the optional state argument is passed, it will be set with the actual state.
The filename is the file containing the ADP to be parsed. This function uses the directory where the ADP resides to resolve any relative file names.
You can pass optional arguments (arg1, arg2, etc.) to the ADP. The arguments can be accessed within the ADP using the ns_adp_argc, ns_adp_argv, and ns_adp_bind_args functions.
If this call is a nested ADP evaluation (where one ADP calls another), an error will be returned if the maximum number of nested ADP evaluations, 256, has been exceeded.
This call can only be used from an ADP. Use "ns_adp_parse" to parse ADPs from outside the context of an ADP.
If you use the -string syntax, the adp is a string containing ADP syntax to be parsed. Note that when you call ns_adp_parse with the -string syntax from inside an ADP, the string cannot contain the <% ... %> syntax. The -string syntax is the default.
If you use the -file syntax, the adp is the absolute filename of the file containing the ADP to be parsed. The -string syntax is the default.
You can pass optional arguments (arg1, arg2, etc.) to the ADP. The arguments can be accessed within the ADP using the ns_adp_argc, ns_adp_argv, and ns_adp_bind_args functions.
If this call is a nested ADP evaluation (where one ADP calls another), an error will be returned if the maximum number of nested ADP evaluations, 256, has been exceeded.
ns_adp_puts "Here is the current time:" ns_adp_puts [ns_httptime [ns_time]]
Try not to confuse ns_adp_registertag with ns__register_adptag. This one registers an ADP script that is run by the tag. The other one registers a Tcl proc that is run by the tag.
Note: This function cannot be called after the server has started. It must be called in a Tcl script in a virtual server's Tcl directory so that it can be initialized at server startup time.
There are two ways to use ns_adp_registertag, with and without the endtag parameter:
* If the endtag parameter is specified, the string of characters between the beginning tag (tag) and the ending tag (endtag) is passed to the adpstring. The return value of the ADP will be sent to the browser in place of the string of text that was specified between the beginning and ending tags. The string is not parsed, which means that you cannot include ADP tags in the string unless you execute ns_adp_parse on the string inside the ADP that processes the registered ADP tag. * If endtag is not specified, then no closing tag is required. The ADP will be called every time the specified tag is encountered.Note: This function is best used in a .tcl file rather than an .adp file, because the parser will be confused by the <% ... %> syntax even though they are in braces.
ns_adp_registertag printdate { The current date is: <% ns_adp_puts [ns_httptime [ns_time]] %> }In your HTML, you simply include a tag called "<PRINTDATE>". This can be extended to provide XML-like template pages for content.
The return_value, if specified, becomes the return value of the ADP.
Note that this function returns only one level up the call stack. To return all the way up the call stack, use ns_adp_break.
Unlike the ns_return* functions the ADP is really aborted and no further work can be done by your script. However, the function it returns to in the call stack can continue working.
Streaming is only available using the "Fancy" ADP parser. See the Administration Guide for more information on how to enable and use the "Fancy" parser.
Streaming does not work through proxies. The user will be forced to wait on a blank screen until your script finishes its work and closes the connection. In general, streaming is a very bad user interface concept and should never be used.
This function is a wonderful way to throttle pages that can get too large for the client to handle due to modem speeds and other factors.
This function is useful to return errors to the client without making the user experience a half-built and broken page, a phenomenon that testers will sometime call "blank pages" or "white pages".
Try not to confuse ns_register_adptag with ns_adp_registertag. This one registers a Tcl proc that is run by the tag. The other one registers an ADP script that is run by the tag.
There are two ways to use ns_register_adptag, with and without the endcommand parameter:
* If the endcommand parameter is specified, the procedure you specify with proc must be of the form: proc myadpproc { string tagset }The string is the string of characters between the beginning tag and the ending tag. The tagset is an ns_set of parameters that were specified with the beginning tag. The return value of the procedure will be sent to the browser in place of the string of text that was specified between the beginning and ending tags.
The string is not parsed, which means that you cannot include ADP tags in the string unless you execute ns_adp_parse on the string inside the procedure that processes the registered ADP tag.
* If endcommand is not specified, then no closing tag is required. The procedure (proc) will be called every time the specified command is encountered. The procedure should take one parameter, an ns_set containing the parameters to the tag: proc myadpproc { tagset }Note: This function cannot be called after the server has started. It must be called in a Tcl script in a virtual server's Tcl directory so that it can be initialized at server startup time.
ns_register_adptag "christmas" "/christmas" xmas # Note: We are registering a Tcl proc. proc xmas {string tagset} { if {[ns_fmttime [ns_time] "%m/%d"] == "12/25"} then { return $string } }Then, in an ADP, you use these tags:
<christmas>Merry Christmas to all, and to all a good night!</christmas>In another example we show how to use a registered tag without an endcommand. The tag is registered as follows:
ns_register_adptag hello helloproc # Note: We are registering a Tcl proc. proc helloproc { tags } { return "Hello, [ns_set get $tags name]." }In an ADP, you use this tag:
<hello name=Bob>This can be extended to provide XML-like template pages for content.