--- name: "ns_adp" section: "3" platform: "linux" package: "aolserver4" version: "4.0.10-7" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/ns_adp" --- # ns\_adp(3) AOLserver Dynamic Page (ADP) commands ``` ``` ## NAME 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 ## SYNOPSIS **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* ``` ``` ## DESCRIPTION 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\_return***xxx* 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 "\". 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 %>
<%=$column%>
No rows in result. <% if {[llength $rows] > 0} { recall "hasrows_header" foreach row $rows { set column $row recall "hasrows_rows" } recall "hasrows_footer" } else { recall "norows" } %> ``` ## SEE ALSO nsd(1), [info(n)](/info/n.md) ## KEYWORDS