Ns adp include - Revision history

Akhassin at 08:01, 14 June 2010

2010-06-14T08:01:21Z

Akhassin at 07:59, 14 June 2010

2010-06-14T07:59:08Z

Akhassin at 06:51, 14 June 2010

2010-06-14T06:51:50Z

Akhassin at 06:38, 14 June 2010

2010-06-14T06:38:17Z

Akhassin at 05:58, 14 June 2010

2010-06-14T05:58:28Z

Akhassin at 04:45, 14 June 2010

2010-06-14T04:45:34Z

Akhassin at 04:44, 14 June 2010

2010-06-14T04:44:06Z

Dossy: formatting tweaks, fix example

2005-12-05T17:48:28Z

formatting tweaks, fix example

WikiSysop: imported from WiKit id 191

2004-06-25T17:22:18Z

imported from WiKit id 191

New page

Man page: http://aolserver.com/docs/tcl/ns_adp_include.html

----

'''NAME'''

: ns_adp_include - Parse an ADP file and return its output

'''SYNOPSIS'''

: '''ns_adp_include''' ''file ?args ...?''

'''DESCRIPTION'''

: This command reads ''file'' and parses its contents as an ADP and returns the output to the caller. ''file'' is relative to the caller's directory unless an absolute pathname is used. Optional ''args'' can be passed which are accessed using [[ns_adp_argc]], [[ns_adp_argv]] and [[ns_adp_bind_args]] commands in the callee.

: Note that ADP streaming cannot be turned on using [[ns_adp_stream]] from within an ADP executed with the '''ns_adp_include''' command. Tcl commands in the ADP will be evaluated in a new scope.

: ADPs can be nested by including each other up to the maximum of 256 levels deep.

: This command is only available from an ADP. Use [[ns_adp_parse]] to parse ADPs from outside the context of an ADP.

'''EXAMPLES'''

###
### Example #1: Callee outputs directly to ADP output buffer.
###

# In a.adp:
<% ns_adp_include b.adp %>

# In b.adp:
<% ns_adp_puts "Hello, world!" %>

###
### Example #2: Caller outputs to ADP buffer.
###

# In a.adp:
<% ns_adp_puts [[ns_adp_include b.adp]] %>

# In b.adp:
<% return "Hello, world!" %>

'''SEE ALSO'''

: [[ns_adp_abort]], [[ns_adp_append]], [[ns_adp_argc]], [[ns_adp_argv]], [[ns_adp_bind_args]], [[ns_adp_break]], [[ns_adp_debug]], [[ns_adp_debuginit]], [[ns_adp_dir]], [[ns_adp_dump]], [[ns_adp_eval]], [[ns_adp_exception]], [[ns_adp_mime]], [[ns_adp_mimetype]], [[ns_adp_parse]], [[ns_adp_puts]], [[ns_adp_registeradp]], [[ns_adp_registerproc]], [[ns_adp_registertag]], [[ns_adp_return]], [[ns_adp_safeeval]], [[ns_adp_stats]], [[ns_adp_stream]], [[ns_adp_tell]], [[ns_adp_trunc]]

----

[[Category Documentation]] - [[Category Core Tcl API]]

@@ Line 157: / Line 157: @@
          return $parsedResult
+     }
 </pre>

@@ Line 13: / Line 13: @@
 : This command reads ''file'' and parses its contents as an ADP with the generated output written to the adp buffer and returns the ''adp return value'' (i.e. from return, ns_adp_return or the last tcl command in the adp) to the caller.  ''file'' is relative to the caller's directory unless an absolute pathname is used. Tcl commands in the ADP are evaluated in a new scope one level below the caller just like when calling a proc. Optional arguments can be passed which are accessed using [[ns_adp_argc]], [[ns_adp_argv]] and [[ns_adp_bind_args]] commands in the callee.
-: The optional ''-cache seconds'' argument specifies the time to cache the results of execution (i.e. the output written to the adp buffer).  Output generated by any scripts and included ADPs is saved for subsequent requests except ns_adp_included blocks that specify the -nocache switch as part of the ns_adp_include command.  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.
+: The optional ''-cache seconds'' argument specifies the time to cache the results of execution (i.e. the output written to the adp buffer). Output generated by any scripts and included ADPs is saved for subsequent requests except ns_adp_included blocks that specify the -nocache switch as part of the ns_adp_include command.  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.
 : Note that ADP streaming cannot be turned on using [[ns_adp_stream]] from within an ADP executed with the '''ns_adp_include''' command.
@@ Line 71: / Line 71: @@
 :* Each thread/interpreter maintains a cache of ADP code which includes the result of parsing adp tags and byte-code compiling (but not executing) the resulting tcl code
 :* Plus the per-interpreter cache includes pointers to text regions in a shared area (tied to a specific virtual server). When all threads no longer point to the shared text, it's free'd from memory.
-:* When enabled, the output cache is simply the replacement of what would have been per-interp byte code blocks with pointers to combined runs of text.
+:* When enabled, the output cache is simply the replacement of what would have been per-interp byte code blocks with pointers to combined runs of text. The output cache is shared.
-:* Files on disk are checked on each request, whether execution caching is enabled or not, via a stat call.  On Unix the key in the cache is device/inode (which allows the same file pointed by multiple symlinks to be only read once) and on Windows it's the filename.
+:* Files on disk are checked on each request, whether output caching is enabled or not, via a stat call.  On Unix the key in the cache is device/inode (which allows the same file pointed by multiple symlinks to be only read once) and on Windows it's the filename.
+:* If the file on disk has changed, byte-code, text regions and output caches are flushed and regenerated.
 '''SEE ALSO'''

@@ Line 69: / Line 69: @@
 : With the new output caching in AOLserver 4.5, there is now a three-tier caching system for adp files - cache of static text blocks, cache of parsed adp scripts and resulting tcl byte-code and cache of execution/output - implemented as follows:
-* Each thread/interpreter maintains a cache of ADP code which includes the result of parsing adp tags and byte-code compiling (but not executing) the resulting tcl code
+:* Each thread/interpreter maintains a cache of ADP code which includes the result of parsing adp tags and byte-code compiling (but not executing) the resulting tcl code
-* Plus the per-interpreter cache includes pointers to text regions in a shared area (tied to a specific virtual server). When all threads no longer point to the shared text, it's free'd from memory.
+:* Plus the per-interpreter cache includes pointers to text regions in a shared area (tied to a specific virtual server). When all threads no longer point to the shared text, it's free'd from memory.
-* When enabled, the output cache is simply the replacement of what would have been per-interp byte code blocks with pointers to combined runs of text.
+:* When enabled, the output cache is simply the replacement of what would have been per-interp byte code blocks with pointers to combined runs of text.
-* Files on disk are checked on each request, whether execution caching is enabled or not, via a stat call.  On Unix the key in the cache is device/inode (which allows the same file pointed by multiple symlinks to be only read once) and on Windows it's the filename.
+:* Files on disk are checked on each request, whether execution caching is enabled or not, via a stat call.  On Unix the key in the cache is device/inode (which allows the same file pointed by multiple symlinks to be only read once) and on Windows it's the filename.

← Older revision		Revision as of 06:38, 14 June 2010
Line 65:		Line 65:

	</pre>		</pre>
		+
		+	'''NOTES'''
		+	: With the new output caching in AOLserver 4.5, there is now a three-tier caching system for adp files - cache of static text blocks, cache of parsed adp scripts and resulting tcl byte-code and cache of execution/output - implemented as follows:
		+
		+	* Each thread/interpreter maintains a cache of ADP code which includes the result of parsing adp tags and byte-code compiling (but not executing) the resulting tcl code
		+	* Plus the per-interpreter cache includes pointers to text regions in a shared area (tied to a specific virtual server). When all threads no longer point to the shared text, it's free'd from memory.
		+	* When enabled, the output cache is simply the replacement of what would have been per-interp byte code blocks with pointers to combined runs of text.
		+	* Files on disk are checked on each request, whether execution caching is enabled or not, via a stat call. On Unix the key in the cache is device/inode (which allows the same file pointed by multiple symlinks to be only read once) and on Windows it's the filename.
		+
		+

	'''SEE ALSO'''		'''SEE ALSO'''

@@ Line 7: / Line 7: @@
 '''SYNOPSIS'''
-: '''ns_adp_include''' ''?-cache seconds? ?-nocache? file ?arg arg ...?''
+: '''ns_adp_include''' ''?-cache seconds |-nocache? file ?arg arg ...?''
 '''DESCRIPTION'''

@@ Line 13: / Line 13: @@
 : This command reads ''file'' and parses its contents as an ADP with the generated output written to the adp buffer and returns the ''adp return value'' (i.e. from return, ns_adp_return or the last tcl command in the adp) to the caller.  ''file'' is relative to the caller's directory unless an absolute pathname is used. Tcl commands in the ADP are evaluated in a new scope one level below the caller just like when calling a proc. Optional arguments can be passed which are accessed using [[ns_adp_argc]], [[ns_adp_argv]] and [[ns_adp_bind_args]] commands in the callee.
-: The optional ''-cache seconds'' argument specifies the time to cache the results of execution (i.e. the output written to the adp buffer).  Output generated by any scripts and included ADPs is saved for subsequent requests except ns_adp_included blocks that specify the -nocache switch as part of the ns_adp_include command.  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.
+: The optional ''-cache seconds'' argument specifies the time to cache the results of execution (i.e. the output written to the adp buffer).  Output generated by any scripts and included ADPs is saved for subsequent requests except ns_adp_included blocks that specify the -nocache switch as part of the ns_adp_include command.  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.
 : Note that ADP streaming cannot be turned on using [[ns_adp_stream]] from within an ADP executed with the '''ns_adp_include''' command.
@@ Line 61: / Line 61: @@
      # The output of cached.adp will only update once every 60 seconds except for the portion
-     # that is the output of nocache.adp, which  will be executed on each request,
+     # that is the output of nocache.adp, which will be executed on each request,
      # even though it's included within cached.adp.

@@ Line 3: / Line 3: @@
 '''NAME'''
-: ns_adp_include - Parse an ADP file and return its output
+: ns_adp_include - Parse an ADP file with the generated output written to the adp buffer
 '''SYNOPSIS'''
-: '''ns_adp_include''' ''file ?args ...?''
+: '''ns_adp_include''' ''?-cache seconds? ?-nocache? file ?arg arg ...?''
 '''DESCRIPTION'''
-: This command reads ''file'' and parses its contents as an ADP and returns the output to the caller.  ''file'' is relative to the caller's directory unless an absolute pathname is used.  Optional ''args'' can be passed which are accessed using [[ns_adp_argc]], [[ns_adp_argv]] and [[ns_adp_bind_args]] commands in the callee.
+: This command reads ''file'' and parses its contents as an ADP with the generated output written to the adp buffer and returns the ''adp return value'' (i.e. from return, ns_adp_return or the last tcl command in the adp) to the caller.  ''file'' is relative to the caller's directory unless an absolute pathname is used. Tcl commands in the ADP are evaluated in a new scope one level below the caller just like when calling a proc. Optional arguments can be passed which are accessed using [[ns_adp_argc]], [[ns_adp_argv]] and [[ns_adp_bind_args]] commands in the callee.
-: Note that ADP streaming cannot be turned on using [[ns_adp_stream]] from within an ADP executed with the '''ns_adp_include''' command.  Tcl commands in the ADP will be evaluated in a new scope.
+: The optional ''-cache seconds'' argument specifies the time to cache the results of execution (i.e. the output written to the adp buffer).  Output generated by any scripts and included ADPs is saved for subsequent requests except ns_adp_included blocks that specify the -nocache switch as part of the ns_adp_include command.  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.
 : ADPs can be nested by including each other up to the maximum of 256 levels deep.
-: This command is only available from an ADP.  Use [[ns_adp_parse]] to parse ADPs from outside the context of an ADP.
+: This command is only available from an ADP page or script.  Use [[ns_adp_parse]] to parse ADPs from outside the context of an ADP.
 '''EXAMPLES'''
@@ Line 23: / Line 25: @@
 <pre>
      ###
-     ### Example #1: Callee outputs directly to ADP output buffer.
+     ### Example #1: Callee writes the output directly to ADP output buffer, also using passed arguments.
      ###
      # In a.adp:
-     <% ns_adp_include b.adp %>
+     <% ns_adp_include b.adp Bob%>
      # In b.adp:
-     <% ns_adp_puts "Hello, world!" %>
+     <% ns_adp_puts "Hello, [ns_adp_argv 1 world]!" %>
      ###
-     ### Example #2: Caller outputs to ADP buffer.
+     ### Example #2: Caller writes the adp return value to ADP buffer.
      ###
@@ Line 40: / Line 42: @@
      # In b.adp:
-     <% return "Hello, world!" %>
+     <% return "Hello, [ns_adp_argv 1 world]!" %>
 </pre>

@@ Line 1: / Line 1: @@
-Man page: http://aolserver.com/docs/tcl/ns_adp_include.html
+{{manpage|ns_adp_include}}
 '''NAME'''
@@ Line 23: / Line 21: @@
 '''EXAMPLES'''
      ###
      ### Example #1: Callee outputs directly to ADP output buffer.
@@ Line 38: / Line 37: @@
      # In a.adp:
-     <% ns_adp_puts [[ns_adp_include b.adp]] %>
+     <% ns_adp_puts [ns_adp_include b.adp] %>
      # In b.adp:
      <% return "Hello, world!" %>
 '''SEE ALSO'''
@@ Line 47: / Line 47: @@
 : [[ns_adp_abort]], [[ns_adp_append]], [[ns_adp_argc]], [[ns_adp_argv]], [[ns_adp_bind_args]], [[ns_adp_break]], [[ns_adp_debug]], [[ns_adp_debuginit]], [[ns_adp_dir]], [[ns_adp_dump]], [[ns_adp_eval]], [[ns_adp_exception]], [[ns_adp_mime]], [[ns_adp_mimetype]], [[ns_adp_parse]], [[ns_adp_puts]], [[ns_adp_registeradp]], [[ns_adp_registerproc]], [[ns_adp_registertag]], [[ns_adp_return]], [[ns_adp_safeeval]], [[ns_adp_stats]], [[ns_adp_stream]], [[ns_adp_tell]], [[ns_adp_trunc]]
-----
+[[Category:Core Tcl API]]