File: adp.html

package info (click to toggle)
aolserver4 4.5.1-15.1
links: PTS, VCS
area: main
in suites: wheezy
size: 11,772 kB
sloc: ansic: 45,120; tcl: 5,532; sh: 1,021; makefile: 380; pascal: 219; php: 13
file content (844 lines) | stat: -rw-r--r-- 17,204 bytes
parent folder | download | duplicates (8)
<html>
<head>
<title>AOLserver</title>
</head>
<body>

<a name=top><h1>ADP Functions</h1></a>


<p>
<small>
$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/api/adp.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
</small>
<p>


<h2><a href=./ name=ns_adp_abort>ns_adp_abort</a></h2>

Stop processing of ADP and throw away all output.

<h3>Syntax</h3>

ns_adp_abort ?return_value?


<h3>Description</h3>

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.

<p>

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.

<p>

The return_value, if specified, becomes the return value of the ADP.

<p>

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:

<pre>
  * 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?
</pre>

<p>

The ns_adp_return function returns up only one level.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_argc>ns_adp_argc</a></h2>

Return number of ADP arguments.

<h3>Syntax</h3>

ns_adp_argc

<h3>Description</h3>

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



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_argv>ns_adp_argv</a></h2>

Return the value of an ADP argument.

<h3>Syntax</h3>

ns_adp_argv index

<h3>Description</h3>

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.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_bind_args>ns_adp_bind_args</a></h2>

Bind ADP arguments to names.

<h3>Syntax</h3>

ns_adp_bind_args var1 ?var2? ?...?

<h3>Description</h3>

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.

<h3>Example</h3>

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

<p>

In foo.adp, the two arguments are bound as follows:
<br>
ns_adp_bind_args x y

<p>

The value "bar" is assigned to the variable x, and the value "baz" is
assigned to the variable y.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_break>ns_adp_break</a></h2>

Stop processing of ADP and flush all output.

<h3>Syntax</h3>

ns_adp_break ?return_value?

<h3>Description</h3>

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.

<p>

The return_value, if specified, becomes the return value of the ADP.

<p>

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:
<pre>
  * 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?
</pre>

<p>

The ns_adp_return function returns up only one level.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_debug>ns_adp_debug</a></h2>

Connect to TclPro debugger.

<h3>Syntax</h3>

ns_adp_debug ?procs? ?host? ?port?

<h3>Description</h3>

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



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_dir>ns_adp_dir</a></h2>

Return directory where ADP resides.

<h3>Syntax</h3>

ns_adp_dir

<h3>Description</h3>

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.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_dump>ns_adp_dump</a></h2>

Return ADP output buffer.

<h3>Syntax</h3>

ns_adp_dump

<h3>Description</h3>

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



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_eval>ns_adp_eval</a></h2>

Evaluate an ADP.

<h3>Syntax</h3>

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

<h3>Description</h3>

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.

<p>

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.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_exception>ns_adp_exception</a></h2>

Return ADP exception state.

<h3>Syntax</h3>

ns_adp_exception state

<h3>Description</h3>

This function returns the current ADP exception state. Possible values
are:

ok: ADP was evaluated successfully<br>

overflow: Stack overflow occurred. This might happen, for example, if
there was a recursive call to ns_adp_include.<br>

abort: An attempt to debug failed or ns_adp_abort was called.<br>

break: ns_adp_break was called<br>

unknown: Unrecognized exception status.  This should not occur.

<p>

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.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_include>ns_adp_include</a></h2>

Parse an ADP file and include in page.

<h3>Syntax</h3>

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

<h3>Description</h3>

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.

<p>

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.

<p>

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.

<p>

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.

<p>

This call can only be used from an ADP.  Use "ns_adp_parse" to parse
ADPs from outside the context of an ADP.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_parse>ns_adp_parse</a></h2>

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

<h3>Syntax</h3>

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

<h3>Description</h3>

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.

<p>

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 &lt;%
... %&gt; syntax. The -string syntax is the default.

<p>

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.

<p>

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.

<p>

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.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_puts>ns_adp_puts</a></h2>

Write string or Tcl command output to page.

<h3>Syntax</h3>

ns_adp_puts string

<h3>Description</h3>

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.

<h3>Example</h3>

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



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_registertag>ns_adp_registertag</a></h2>

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

<h3>Syntax</h3>

ns_adp_registertag tag ?endtag? adpstring

<h3>Description</h3>

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.

<p>

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.

<p>

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.

<p>

There are two ways to use ns_adp_registertag, with and without the
endtag parameter:

<pre>
  * 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.
</pre>

Note: This function is best used in a .tcl file rather than an .adp
file, because the parser will be confused by the &lt;% ... %&gt; syntax even
though they are in braces.

<h3>Example</h3>

<pre>
ns_adp_registertag printdate {

The current date is: &lt;% ns_adp_puts [ns_httptime [ns_time]] %&gt;

}
</pre>

In your HTML, you simply include a tag called "&lt;PRINTDATE&gt;".
This can be extended to provide XML-like template pages for content.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_return>ns_adp_return</a></h2>

Stop processing of ADP and flush all output.

<h3>Syntax</h3>

ns_adp_return ?return_value?

<h3>Description</h3>

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.

<p>

The return_value, if specified, becomes the return value of the ADP.

<p>

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.

<p>

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.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_stream>ns_adp_stream</a></h2>

Begin ADP streaming.

<h3>Syntax</h3>

ns_adp_stream

<h3>Description</h3>

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.

<p>

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.

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



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_tell>ns_adp_tell</a></h2>

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

<h3>Syntax</h3>

ns_adp_tell

<h3>Description</h3>

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.

<p>

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.



<p>

<hr>

<br>





<h2><a href=./ name=ns_adp_trunc>ns_adp_trunc</a></h2>

Clear ADP output buffer.

<h3>Syntax</h3>

ns_adp_trunc

<h3>Description</h3>

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.

<p>

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



<p>

<hr>

<br>





<h2><a href=./ name=ns_register_adptag>ns_register_adptag</a></h2>

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

<h3>Syntax</h3>

ns_register_adptag command ?endcommand? proc

<h3>Description</h3>

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.

<p>

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.

<p>

There are two ways to use ns_register_adptag, with and without the
endcommand parameter:
<pre>
  * If the endcommand parameter is specified, the procedure you
    specify with proc must be of the form:
proc myadpproc { string tagset }
</pre>

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.

<p>

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.
<pre>
  * 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 }
</pre>

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.

<h3>Example</h3>

Suppose you want to register a tag that displays the enclosed text
only if it is Christmas. You could register the tag as follows:

<pre>
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
    }
}
</pre>


Then, in an ADP, you use these tags:

<pre>
&lt;christmas&gt;Merry Christmas to all, and to all a good night!&lt;/christmas&gt;
</pre>


In another example we show how to use a registered tag without an
endcommand.  The tag is registered as follows:

<pre>
ns_register_adptag hello helloproc

# Note: We are registering a Tcl proc.
proc helloproc { tags } {
    return "Hello, [ns_set get $tags name]."
}
</pre>

In an ADP, you use this tag:

<pre>
&lt;hello name=Bob&gt;
</pre>

This can be extended to provide XML-like template pages for content.

  

<p>

<hr>

<br>

</body>
</html>