ADP Functions

$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/api/adp.html,v 1.2 2004/07/20 23:44:26 dossy Exp $


Note! Updated Tcl API documentation in progress is now available on the wiki.


ns_adp_abort

Stop processing of ADP and throw away all output.

Syntax

ns_adp_abort ?return_value?

Description

This function aborts processing of the ADP file and any pending output up to that point is deleted. However, if a streaming script was processed before ns_adp_abort was called, the data will already have been output. Also, if any functions that cause output (such as ns_return or ns_write) were called before ns_adp_abort, their output will already have been output also.

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.



ns_adp_argc

Return number of ADP arguments.

Syntax

ns_adp_argc

Description

This function returns an integer value, which is the number of arguments passed to the ADP. The number of arguments includes the name of the ADP itself, which can be fetched with [ns_adp_argv 0].



ns_adp_argv

Return the value of an ADP argument.

Syntax

ns_adp_argv index

Description

This function returns the value of the argument corresponding to the argument number specified in index. If index is 0, the filename of the ADP is returned. Only the values 0 through the number of arguments minus one (obtained with ns_adp_argc) are valid for index.



ns_adp_bind_args

Bind ADP arguments to names.

Syntax

ns_adp_bind_args var1 ?var2? ?...?

Description

This function copies the arguments from the current ADP frame to the local variable names specified in var1, var2, etc. You must bind the same number of arguments in the ns_adp_bind_args function that were passed into the ADP. Attempting to bind any other number of arguments results in an error.

Example

This function invokes the ADP in foo.adp with two arguments, bar and baz:
ns_adp_include foo.adp bar baz

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.



ns_adp_break

Stop processing of ADP and flush all output.

Syntax

ns_adp_break ?return_value?

Description

This function aborts processing of the ADP file and sends any pending output (from ns_adp_puts or static HTML) up to the point where it was called to the browser. Nothing is output or executed after it is called.

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.



ns_adp_debug

Connect to TclPro debugger.

Syntax

ns_adp_debug ?procs? ?host? ?port?

Description

This function connects to the TclPro debugger, if it is not already connected. It essentially runs the TclPro command:
debuginit "procs" "host" "port"



ns_adp_dir

Return directory where ADP resides.

Syntax

ns_adp_dir

Description

This function returns the directory in which the ADP currently being processed resides. It is an error to call this function outside of ADP processing.



ns_adp_dump

Return ADP output buffer.

Syntax

ns_adp_dump

Description

This function returns the text of the ADP output buffer as its result.



ns_adp_eval

Evaluate an ADP.

Syntax

ns_adp_eval ?-parser parser? page ?arg ... ?

Description

This function evaluates the ADP specified by page and returns the output as the result. If any arguments are specified, they will be passed to the ADP.

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.



ns_adp_exception

Return ADP exception state.

Syntax

ns_adp_exception state

Description

This function returns the current ADP exception state. Possible values are: ok: ADP was evaluated successfully
overflow: Stack overflow occurred. This might happen, for example, if there was a recursive call to ns_adp_include.
abort: An attempt to debug failed or ns_adp_abort was called.
break: ns_adp_break was called
unknown: Unrecognized exception status. This should not occur.

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.



ns_adp_include

Parse an ADP file and include in page.

Syntax

ns_adp_include filename ?arg1? ?arg2? ?...?

Description

This functions parses the specified file as an ADP and inserts it into the page as if it were an argument to ns_adp_puts. Note that the ADP streaming cannot be turned on from within an ADP executed with the ns_adp_include command. Tcl commands in the ADP will be evaluated locally.

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.



ns_adp_parse

Process an ADP file or string and return the result as a string.

Syntax

ns_adp_parse [-file | -string] adp ?arg1? ?arg2? ?...?

Description

This function processes the specified ADP file or string and returns the result as a string. If you need to process a second ADP from inside an ADP, it is usually better to use ns_adp_include, because that function resolves relative pathnames passed to it. Also note that ns_adp_parse will ignore any directives to turn on streaming. Tcl_Eval is used to evaluate the Tcl commands in the 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

Write string or Tcl command output to page.

Syntax

ns_adp_puts string

Description

Writes the specified string out to the page from an embedded script. The string may be a quoted string or it may be another Tcl command.

Example

ns_adp_puts can be used to output strings and Tcl commands.
ns_adp_puts "Here is the current time:"
ns_adp_puts [ns_httptime [ns_time]]



ns_adp_registertag

Register an XML-like tag that executes an ADP script.

Syntax

ns_adp_registertag tag ?endtag? adpstring

Description

ns_adp_registertag registers an ADP script to be called when the specified beginning and ending tags are used in an ADP. The tag is the beginning tag to look for, and the endtag is the ending tag to look for. The adpstring is an ADP that will be called when AOLserver encounters the specified tags when processing an ADP.

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.

Example

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.



ns_adp_return

Stop processing of ADP and flush all output.

Syntax

ns_adp_return ?return_value?

Description

This function aborts processing of the ADP file and sends any pending output (from ns_adp_puts or static HTML) up to the point where it was called to the browser. Nothing is output or executed after it is called.

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.



ns_adp_stream

Begin ADP streaming.

Syntax

ns_adp_stream

Description

This function begins streaming mode for the ADP. All data currently in the ADP output buffer is flushed and any subsequent data will be output directly to the conn.

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.



ns_adp_tell

Returns the number of bytes currently in the ADP output buffer.

Syntax

ns_adp_tell

Description

This function returns the total number of bytes already built by your script. This is helpful if you want to guess the Content-Length of the page your script is putting together.

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.



ns_adp_trunc

Clear ADP output buffer.

Syntax

ns_adp_trunc

Description

This function clears the ADP output buffer. To have the contents of the ADP output buffer sent to the conn, use ns_adp_stream instead.

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".



ns_register_adptag

Register an XML-like tag for use within an ADP.

Syntax

ns_register_adptag command ?endcommand? proc

Description

ns_register_adptag registers a procedure to be called when the specified beginning and ending tags are used in an ADP. The command is the beginning tag to look for, and the endcommand is the ending tag to look for. The proc is the procedure that will be called when AOLserver encounters those tags when processing an ADP.

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.

Example

Suppose you want to register a tag that displays the enclosed text only if it is Christmas. You could register the tag as follows:
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.