NAME

       ns_adp_abort, ns_adp_break, ns_adp_exception, ns_adp_return - ADP exception handling

SYNOPSIS

       ns_adp_abort ?result?
       ns_adp_break ?result?
       ns_adp_exception ?varName?
       ns_adp_return ?result?
_________________________________________________________________

DESCRIPTION

       These commands enable early return and interrupt of an ADP execution.  Internally, the exception routines
       sets  a flag and return TCL_ERROR to begin unwinding the current Tcl call stack and return control to the
       ADP evaluation engine.  It is possible for an enclosing catch command to catch the exception and stop Tcl
       from returning control to ADP.  The ns_adp_exception command can be used to test for this condition.

       ns_adp_abort ?result?
              This command stops ADP processing, raising an execution and unwinding the stack to the  top  level
              as  an error condition.  The request handling code which invokes the first ADP file will normallly
              generate an error message in this case, ignoring the contents of the output buffer, if any.   Note
              that  the exeception can be caught by a catch command in script block which executes ns_adp_abort.
              However, when that block returns control to the ADP execution engine, the stack will  be  continue
              to  be unwound.  The optional result argument, if present, will be used to set the Tcl interpreter
              result string.

       ns_adp_break ?result?
              This command stops execution of ADP and unwinds the ADP  call  stack.   Unlike  ns_adp_abort,  the
              request handling code will generate a normal HTTP response with any contents of the output buffer.
              The optional result argument, if present, will be used to set the Tcl interpreter result string.

       ns_adp_exception ?varName?
              This  command  returns  a  boolean  value  if  an exception has been raised.  The optional varName
              provides the name of a variable to store one of ok, break, abort, or return to indicate  the  type
              of exception raised.

       ns_adp_return ?result?
              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.  The optional result argument, if present, will be used to
              set the Tcl interpreter result string.

EXAMPLE

       The following example demonstrates halting execution of the ADP after returning a complete response  with
       one of the ns_return style commands:

              <%
              if !$authorized {
                ns_returnunauthorized; # Send complete response.
                ns_adp_abort; # Execution stops here.
              }
              %>.

SEE ALSO

       ns_adp(n)

KEYWORDS

       ADP, dynamic pages, exception

AOLserver                                              4.5                          ns_adp_exception(3aolserver)