NAME

       ns_adp_argc,   ns_adp_argv,  ns_adp_bind_args,  ns_adp_dir,  ns_adp_eval,  ns_adp_ident,  ns_adp_include,
       ns_adp_parse, ns_adp_safeeval - ADP execution commands

SYNOPSIS

       ns_adp_argc
       ns_adp_argv ?index?
       ns_adp_bind_args var1 ?var2...?
       ns_adp_dir
       ns_adp_eval page ?arg ...?
       ns_adp_ident ?string?
       ns_adp_include ?-cache seconds? ?-nocache? file ?arg ...?
       ns_adp_parse ?-file file? ?-string string? ?-savedresult varName? ?-cwd path? ?args ... ?
       ns_adp_safeeval page ?arg ...?
_________________________________________________________________

DESCRIPTION

       These commands enable execution of ADP files or strings.  Each call to ns_adp_include results  in  a  new
       ADP  "call frame" similar to a Tcl procedure with local variable scope.  Variables may be passed to these
       call  frames  as  optional  arguements  and  then  accessed  via  the   ns_adp_argc,   ns_adp_argv,   and
       ns_adp_bind_args  commands.   The ns_adp_eval, ns_adp_safeeval, or ns_adp_parse can also accept arguments
       via the same mechanism but execute in the same ADP call frame as their parent, i.e., with the same  local
       variables.  See the ns_adp page for details on ADP syntax and control flow.

       ns_adp_argc
              This  command  returns the number of optional arguments passed to the ADP.  The count includes the
              argument for the ADP file or string.

       ns_adp_argv ?index ?default??
              This command returns the list of arguments passed to the ADP.  If the optional index  argument  is
              specified,  only the given argument is returned instead of the full list.  If the optional default
              argument is specified along with an index argument, it serves  as  the  value  to  return  if  the
              cooresponding index was not passed to the call frame.

       ns_adp_bind_args var1 ?var2...?
              This  command  can  be  used  to set multiple optional ADP arguments to a list of local variables.
              Argument binding begins with argument number 1, i.e., the first argument beyond the  ADP  file  or
              script.

       ns_adp_dir
              This  command  returns  the directory in which the ADP currently being processed resides and which
              relative ADP files will be found.

       ns_adp_eval page ?arg ...?
              This command 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.

       ns_adp_ident ?string?
              This  command  returns  and/or sets an arbitrary version management string for the given ADP file.
              It could be used to specify a header replaced via a CVS/RCS checkin:
              <% ns_adp_ident {$Header: /cvsroot/aolserver/aolserver/doc/ns_adp_include.n,v 1.1 2006/04/13 19:07:12 jgdavidson Exp $} %>

       ns_adp_include ?-cache seconds? ?-nocache? file ?arg ...?
              This command parses the specified file as an  ADP,  including  the  text  blocks  and  any  output
              generated by script blocks in the current output buffer.  The execution occurs in a new call frame
              with private local variables similar to a Tcl procedure.  The filename is the file containing  the
              ADP to be parsed.  If the file is not an absolute filename, the file is considered relative to the
              current ADP working directory which is the directory of the previously  included  file.   Optional
              arguments  (arg...)  can  be  passed  to  the  included ADP; see the ns_adp_argv command above for
              details on accessing the  values  of  these  variables.   The  optional  -cache  seconds  argument
              specifies  the  time  to  cache the results of execution.  All output generated by any scripts and
              included ADP's are saved for subsequent requests unless an included ADP  has  a  -nocache  option.
              The  use of -cache and -nocache can be used to increase performance of ADP used to generated a mix
              of personalized, non-cacheable, content and shared content which changes more slowly.  Under  high
              load,  the  performance  improvement  can  be  substaintial,  especially in cases where the cached
              content is the result of accessing a slow databases or web services.  See the EXAMPLES section for
              an example of using cached output.

       ns_adp_parse ?-file file? ?-string string? ?-savedresult varName? ?-cwd path? ?args ... ?
              This  function  processes  the  specified  ADP  file or string and returns the result as a string.
              Processing a second ADP from inside an ADP is normally  best  done  with  ns_adp_include  as  that
              command  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 -string adp option can be used to parse a string of ADP text.  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.

              The -file file option can be used to parse ADP contained in the given file.  This use  is  similar
              to  that  of  ns_adp_include except the result is returned by the command instead of automatically
              being appended to the output stream.

              The -global and -local options are deprecated. All calls are now local to  the  current  ADP  call
              frame such that the -local option is ignored and the -global option generates an error.

              Additional  arguments  are  passed  to  the ADP execution and can be accessed via the ns_adp_argc,
              ns_adp_argv, and ns_adp_bind_args commands.

       ns_adp_safeeval string ?arg ...?
              The command evaluates the given ADP string in a safe environment which ignores all cases of <% ...
              %>  and  <%=  ... %> commands, only allowing execution of per-defined registered tags.  This usage
              can be helpful to expose a limited set  of  dynamic  functionality  to  publishing  staff  without
              exposing the full command set.

EXAMPLE

       The following example demonstrates passing an argument to an included ADP file:

              <% ns_adp_include included.adp arg1 arg2 arg3 %>

       The variables could be accessed within included.adp with:

              ns_adp_argc
              --> return 4
              ns_adp_argv 1
              --> returns "arg1"
              ns_adp_argv 10 MyDefault
              --> returns "MyDefault" as there is no 10th argument

       The  followiong  example demonstrates using the -cache and -nocache options to the ns_adp_include command
       to enhance performance through caching execution output.  Given the following files:

       top.adp:
              <% ns_adp_include -cache 60 cached.adp %>

       cached.adp:
              <%
              ns_adp_puts "Time at cache: [ns_time]"
              ns_adp_include -nocache nocache.adp
              %>

       nocache.adp:
              <% ns_adp_puts "Time now: [ns_time]" %>

       the results of cached.adp will only update once every 60 seconds while the results of nocache.adp will be
       executed on each request, even though it's included withing cached.adp.

SEE ALSO

       ns_adp_ctl(1), ns_adp_puts(n), ns_adp_flush(n), ns_adp_close(n)

KEYWORDS

       ADP, dynamic pages, execution