ns_adp_abort, ns_adp_argc, ns_adp_argv, ns_adp_bind_args, ns_adp_break, ns_adp_debug, ns_adp_dir, ns_adp_dump, ns_adp_eval, ns_adp_exception, ns_adp_mimetype, ns_adp_parse, ns_adp_puts, ns_adp_registeradp, ns_adp_registertag, ns_adp_return, ns_adp_stream, ns_adp_tell, ns_adp_trunc, ns_puts, ns_register_adptag - AOLserver Dynamic Page (ADP) commands

ns_adp_abort ?return_value? ns_adp_argc ns_adp_argv ?index? ns_adp_bind_args var1 ?var2...? ns_adp_break ?return_value? ns_adp_debug ?procs? ?host? ?port? ns_adp_dir ns_adp_dump ns_adp_eval ?-parser parser? page ?arg ...? ns_adp_exception ?state? ns_adp_include filename ?arg...? ns_adp_mimetype ?mimetype? ns_adp_parse ?source-option? ?scope-option? adp ?arg ...? ns_adp_puts ?-nonewline? string ns_adp_registeradp tag ?endtag? adpstring ns_adp_registertag tag ?endtag? adpstring ns_adp_return ?return_value? ns_adp_stream ns_adp_tell ns_adp_trunc ns_puts ?-nonewline? string ns_register_adptag tag ?endtag? proc

AOLserver Dynamic Pages, or ADPs, are a server-side environment for generating and delivering dynamic content by combining HTML and Tcl scripts.

An AOLserver is configured to recognize certain filenames as indicating an ADP using the mapping parameter of the server's adp configuration section. When the AOLserver receives a request for a file indicated by the mapping, it reads, parses and executes the file, resulting in output consisting of the static content from the file combined with the scripted content of the file. A programmer can use a number of functions to interact with the ADP execution environment, and to obtain information about the environment:

ns_adp_abort ?return_value?

This function aborts processing of the ADP file and any pending output up to that point is deleted. (By contrast, ns_adp_break will send pending output.) 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, assuming a page setup like the following: a.adp includes b.adp includes c.adp calls ns_adp_abort other code in b.adp other code in a.adp Then 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, while both ns_adp_return and ns_adp_abort return all the way up the call stack.

ns_adp_abort has no return value.

ns_adp_argc

Returns as an integer value 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 index

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 var1 ?var2...?

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.

ns_adp_bind_args has no return value.

ns_adp_break ?return_value?

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. (By contrast, ns_adp_abort deletes pending output.) 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, assuming a page setup like the following: a.adp includes b.adp includes c.adp calls ns_adp_break other code in b.adp other code in a.adp Then 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, while both ns_adp_return and ns_adp_abort return all the way up the call stack.

ns_adp_break has no return value.

ns_adp_debug ?procs? ?host? ?port?

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

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

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

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

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 ?state?

This function is used to examine the current ADP exception state. The function returns 0 if the exception state is ok and 1 otherwise.

If the optional state argument is passed, a variable with that name will be set for the caller, and will contain the exception state with one of the following possible values:

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.

ns_adp_include filename ?arg...?

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 (arg...) 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_mimetype ?mimetype?

Sets or fetches the ADP mime type. With no arguments, ns_adp_mimetype returns the MIME type for the ADP context. The MIME type is used in the HTTP response when AOLserver returns a normal ADP request, and defaults to text/html. If the optional mimetype argument is supplied, the context's MIME type is set to that value.

ns_adp_parse ?source-option? ?scope-option? adp ?arg ...?

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.

The source-option can be one of the following values:

-string

The adp argument must be a string containing ADP syntax to be parsed. Although the <% ... %> syntax is allowed in the string, if you have this embedded in an ADP, you have to be careful in constructing the string that you do not prematurely terminate an enclosing script.

-file

The adp argument must be the absolute name of a file containing an ADP. The source-option defaults to -string if none is specified.

The scope-option can be one of the following values:

-global

This option is deprecated, and will cause an error to be thrown.

-local

This option is deprecated, and will be ignored.

You can pass optional arguments (arg ...) 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 ?-nonewline? string

This function outputs the specified string to the page. Unless the optional -nonewline argument is used, a newline will be appended to the page after the string. Note that the argument to ns_adp_puts is a single string; the following will work: ns_adp_puts "Hello, there" but the following will throw an error: ns_adp_puts Hello, there.

ns_adp_registeradp tag ?endtag? adpstring

This function registers an ADP fragment that will be invoked when the specified tag is encountered while parsing an ADP. The tag argument specifies the tag that will trigger invocation of the ADP fragment, which is specified by the adpstring argument.

If the optional endtag argument is specified, then invocation of the fragment will be delayed until the endtag tag is encountered, and the fragment will be invoked with the content enclosed by the tag and endtag passed as an argument. Note that the enclosed content is not parsed by the ADP parser; if necessary, the ADP fragment may need to call ns_adp_parse on the content.

If the endtag argument is specified, then the ADP fragment will be invoked with two arguments: the first will be the enclosed content, and the second will be the name of an ns_set with any tag attributes specified in the content. If no endtag argument is specified, the ADP fragment will only be passed the name of the ns_set. The arguments may be retrieved using ns_adp_bindargs or ns_adp_argc and ns_adp_argv.

When the ADP fragment is invoked, its result is inserted in the output instead of the tag (or, if the endtag was specified, in place of the tag, end tag, and the enclosed content).

This function, ns_adp_registeradp, differs from ns_register_adptag in that this function registers an ADP fragment to be invoked upon encountering the tags during parsing, while ns_register_adptag registers a Tcl procedure.

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_adp_registeradp does not have a return value.

Note: Care must be taken when using this function from inside an ADP, because the adpstring is likely to contain script delimiters (<% ... %>) which will prematurely terminate script fragments. It is probably easier to restrict use of this function to .tcl files.

Example:

ns_adp_registertag printdate { The current date is: <%=[ns_httptime [ns_time]]%> } In your HTML, you simply include a tag called "<printdate>".

One use of ns_adp_registeradp is in handling XML documents.

ns_adp_registertag tag ?endtag? adpstring

This function is a deprecated synonym for ns_adp_registeradp.

ns_adp_return ?return_value?

This function halts processing of the current ADP and sends any pending output (from ns_adp_puts or static HTML) up to the point where it was called to the browser. Nothing in the current ADP 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. By contrast, ns_adp_abort and ns_adp_break will return all the way up the call stack. ns_adp_return is typically used from an ADP included by another ADP, to stop processing of the inner ADP while allowing the calling ADP to continue.

ns_adp_stream

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

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

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_puts ?-nonewline? string

This function is a deprecated synonym for ns_adp_puts.

ns_register_adptag tag ?endtag? proc

This function registers a Tcl procedure that will be invoked when the specified tag is encountered while parsing an ADP. The tag argument specifies the tag that will trigger invocation of the Tcl procedure, which is specified by the procfR argument.

If the optional endtag argument is specified, then invocation of the procedure will be delayed until the endtag tag is encountered, and the procedure will be invoked with the content enclosed by the tag and endtag passed as an argument. Note that the enclosed content is not parsed by the ADP parser; if necessary, the Tcl procedure may need to call ns_adp_parse on the content.

If the endtag argument is specified, then the Tcl procedure will be invoked with two arguments: the first will be the enclosed content, and the second will be the name of an ns_set with any tag attributes specified in the content. If no endtag argument is specified, the Tcl procedure will only be passed the name of the ns_set.

When the Tcl procedure is invoked, its result is inserted in the output instead of the tag (or, if the endtag was specified, in place of the tag, end tag, and the enclosed content).

This function, ns_register_adptag, differs from ns_adp_registeradp in that this function registers Tcl procedure to be invoked upon encountering the tags during parsing, while ns_adp_registeradp registers an ADP fragment.

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 does not have a return value.

The following is a simple way of handling conditional content in ADPs:

proc remember {input tagset} { global _adp_memory set tagname [ns_set iget $tagset name] if {[string match "" $tagname]} { set _adp_memory($tagname) $input return "" } else { return $input } } proc recall {name} { global _adp_memory if {[info exists _adp_memory($name)]} { set parsecommand [list ns_adp_parse -string] lappend parsecommand $_adp_memory($name) ns_puts -nonewline [uplevel $parsecommand] } else { ns_log Error "[ns_adp_argv 0]: Unable to recall } }

If the preceding Tcl has been executed (perhaps during server startup), then the following ADP fragment displays the results of a database query in a table, or shows "No rows in result." if there are no rows:

<% set rows {} set db [ns_db gethandle] ns_db exec "select somecolumn from sometable" set row [ns_db bindargs $db] while {[ns_db getrow $db $row] > 0} { lappend rows [ns_set get $row "somecolumn"] } ns_db releasehandle $db %> <remember name="hasrows_header"> <table> </remember> <remember name="hasrows_rows"> <tr> <td><%=$column%></td> </tr> </remember> <remember name="hasrows_footer"> </table> </remember> No rows in result. <remember name="norows"> <% if {[llength $rows] > 0} { recall "hasrows_header" foreach row $rows { set column $row recall "hasrows_rows" } recall "hasrows_footer" } else { recall "norows" } %>

nsd(1), info(n)