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