ns_adp_exception(3aolserver)				    AOLserver Built-In Commands 			      ns_adp_exception(3aolserver)

__________________________________________________________________________________________________________________________________________________

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  com-
       mand  to  catch the exception and stop Tcl from returning control to ADP.  The ns_adp_exception command can be used to test for this condi-
       tion.

       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.  How-
	      ever,  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 spec-
	      ified,  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  com-
       mands:

	      <%
	      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)