If you've played with the patent example, by now you might have noticed that it remembers your last query when you click on a patent for details, even though that's not a form submission. Also, for each patent link, it automatically knows to bring up the correct patent you clicked on, a different one for each link. How does Vortex remember those variables, even though each browser click results in a new call to Vortex from scratch? We call this state retention : retaining the state of the script across invocations. In most languages one has to do this "manually" by embedding variables in URLs.

EXPORT

In Vortex, state retention is automatically handled with the <EXPORT> directive. This tells Vortex what variables are to be preserved for future transactions. In our patent example, we're preserving $id , because it tells us what patent to bring up in the <details> function. Also $skip , which tells us what page in the result set we're on. Finally, $query and $when are remembered, so we can fill out the search form with the user's last query even on a details page.

<EXPORT> variables are saved whenever the special Vortex variable $url is printed. There are three ways this happens, depending on the flag given to <EXPORT> or the use of the variable:

• State table - TABLE
  Variables that are given the EXPORT flag TABLE , or are not in a <LOOP> , are written to the state table (vortex ). These are known as state-table variables.

• URL state - URL
  Variables that are given the flag URL , or are in a <LOOP> or <SQL> loop, have their current value(s) saved, but scrambled to the URL instead. These are known as URL state variables. All of our <EXPORT> variables in the patent example have this flag.

• Query string - QUERY
  Variables that are given the flag QUERY are saved as a URL-encoded query-string to the special variable $urlq .

State saving

When the special variable $url is printed, its value will contain the normal URL to re-invoke the script, but will also reflect URL state variables (scrambled), as well as a handle to the state-table variables. That's why you see gobbledy-gook like /+_wwYmelVlM+e4qwwwqFqc in some URLs: Every time $url is printed in the <SQL> loop, all the <EXPORT> variables are encoded in there.

This is the other magic function of $url : not only is it a URL back to the script, but it preserves state variables as well.

State restoration

When the user clicks one of our $url links, our <EXPORT> variables are automatically restored. So in our <details> function, we know the correct patent $id to select for display. We also know the user's original query, in $query and $when .

What type to use?

As a general rule, small variables that take up little space and only have one value at a time are best saved as <EXPORT nbsp;URL> variables. All of our patent example exports fit this bill; the user's queries are probably small, and so is the $id : while it has 10 different values, it only has 1 value per row in the <SQL> loop. URL variables have the advantage of speed: the state table does not need to be written.

Large variables, on the other hand, should be <EXPORT nbsp;TABLE> . This costs a table write, but we can store very large data.