CAPTURE - capture output

`CAPTURE` - capture output

SYNOPSIS

<CAPTURE [flags]>
  ... Vortex code ...
</CAPTURE>

DESCRIPTION
The CAPTURE command redirects (captures) the standard output of the Vortex code within its block, and returns it in $ret at the close of the block. It is useful for saving the output of an entire section of script, rather than laboriously appending many values together. The following flags may be used:

BIN The return value $ret is considered binary (e.g. varbyte). By default the return value is text (varchar).
OUTPUT Also print the output normally to stdout. This is useful if the output is to be displayed anyway, especially if the enclosed code may execute slowly: the output can be displayed as generated while still being captured, without waiting for the entire block to finish.

DIAGNOSTICS
CAPTURE returns the standard output of the Vortex code within the block, as one value.

EXAMPLE
This script uses CAPTURE in a simple page-caching scheme. Common queries are cached in the cache table. If a query is not present already, it is executed and cached:

<!-- Check the cache first: -->
<SQL "select Page from cache where Query = $query">
  <send $Page>
  <RETURN>
</SQL>
<!-- Query wasn't in the cache; execute and save it: -->
<CAPTURE OUTPUT>
  The following books match your query: <P>
  <SQL "select Title from books where Subject like $query">
    <A HREF="$url/details.html">$Title</A>
  </SQL>
</CAPTURE>
<!-- Add it to the cache: -->
<SQL NOVARS "insert into cache values($query, $ret)">
</SQL>

CAVEATS
The CAPTURE statement was added in version 2.1.896900000 19980603.

The output of a CAPTURE block with the OUTPUT flag can still be captured by an enclosing CAPTURE, EXEC, etc. block.