Flags

The following flags may appear after the variable list in the EXPORT directive:

• TABLE Forces the listed variables to be exported to the state table, even when in a LOOP.

• URL Forces the listed variables to be exported to the URL state, even when not in a LOOP.

• QUERY The listed variables will be exported in a URL-encoded query string ($urlq). Note that the values will be plainly visible, and that type information (e.g. string vs. integer) may be lost on re-invocation, since the variables are just strings. Also, the values will have the lower initialization precedence of query string variables, since they're not true state variables.

• USEROK Allows "user" variables - URL query string and content variables, i.e. from an HTML form - to override state values on initialization.

If neither URL, TABLE nor QUERY is given, where the variables are exported depends on whether they're in a LOOP at the time (see above). The URL, TABLE and QUERY flags are mutually exclusive.

The USEROK flag alters the precedence for the listed variables, making form values have the highest precedence for initialization, instead of state values (the default). This affects which values are used to initialize a variable on startup, when more than one source is present (e.g. a variable was submitted in a form and present in the URL state).

Normally, the state values (URL and TABLE) have precedence over any other source. This is because state values are controlled by the script and are considered (semi-)private, but the form variables are controlled by the (possibly malicious) web user: the script's values are preferable. Thus any extraneous form variables sent by the browser do not normally affect EXPORTed variables.

However, in some cases it may be desirable to allow form variables to override state values. For example, a user's query may be EXPORTed to save it across invocations for future searches, but the user should be able to alter it at any time. In this case, the USEROK flag should be set:

<EXPORT $query USEROK>
...
<A NAME=main>
  <FORM METHOD=post ACTION=$url/>
    Query: <INPUT NAME=query VALUE="$query">
           <INPUT TYPE=submit>
  </FORM>
  <SQL "select x, y, z from table where Field like $query">
    ...
  </SQL>
</A>

In the above example, the user's $query value is remembered across invocations because it is EXPORTed. However, a new value can be set from the form and will override the saved value on submission, because USEROK is set. Without this flag, the original value of $query would be preserved: the user would not be able to change it.

EXAMPLE
A book search might generate a list of matching books, with a URL for each book. Each URL brings up details on that book, based on its id. In addition, the user's query, $query, is to be remembered across invocations, in a format easily viewed in server logs. Also, we want to remember the user's name from their login. Thus, $id, $query and $user are exported:

<EXPORT $id>
<EXPORT $query QUERY>
<EXPORT $user>
...
Hello, $'user'.  These are the books that match your query:
<SQL "select id, Title from books where Title like $query">
  <A HREF=$url/details.html$urlq>$Title</A>  <BR>
</SQL>

The variables $id and $user are saved when $url is printed. Since $user is not being looped over in the SQL loop, it is a state-table variable when $url is printed, and is saved once, to the state table. All the URLs generated in the SQL loop will have the same value(s) for $user. This is fine, because $user is unlikely to change during the session.

However, $id is a loop variable, because it is set by the SQL loop: thus it is saved to the URL state instead. Each URL will have the same value for $user, but a single, different value of $id, for the appropriate book. The details function can then select the given book by $id and print more detailed info on it.

The $query variable is flagged QUERY, so it is exported to a query string when $urlq is printed. Though it has a constant value in this SQL loop, were it to change each time it would have a different value in $urlq. Its value is plainly visible in the overall URL, thus enabling easy query tracking via Web server logs. Note that it is appended after the function/MIME part of the URL.

CAVEATS
The QUERY flag was added in version 2.1.898900000 19980626.

EXPORT is a directive, and as such must appear before the first function in the script. Variables are not actually saved, however, until the $url variable is printed.

The $url and $urlq variables must be printed to initiate state retention: referring to them in an assignment or function call will not save state.

The maximum URL length is arbitrarily fixed at 512 characters to help prevent truncation by browsers; if URL state variables have values that are too long when $url is printed, some or all of the variables will not be exported.

Note that state-table variables are only saved once to the state table. URL and query state variables, however, are written to the URL any number of times, every time $url or $urlq is printed.

Variables are exported from the scope of the $url location. This means that a local variable of the same name as an EXPORT will be EXPORTed if it is in scope when $url is printed.

The state table vortex (and the database if needed) is created on the fly at run time if it does not exist, whenever $url is printed or a URL with state variables is accessed. Since old state information is not erased from the table, it is advisable to occasionally clear it with the -W command-line option lest it grow too large.

EXPORTing any data to URL should not be considered secure, as the data is compressed but not encrypted. EXPORTing to QUERY will present data in the clear to users, as this is intended for logging. Any sensitive data such as login info should be saved via another mechanism, e.g. encrypted to a cookie.

The USEROK and QUERY flags should only be given for variables that are expected to be modified by the Web user. The QUERY flag lowers the initialization precedence of the variables, since they are not true state variables but are part of a query string. Variables EXPORTed this way may also lose type information (or suffer truncation if binary) because they are stored as strings. EXPORTing as QUERY may also increase Web server log size.