The following flags may appear after the variable list in the
TABLEForces the listed variables to be exported to the state table, even when in a
URLForces the listed variables to be exported to the URL state, even when not in a
QUERYThe 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.
USEROKAllows "user" variables - URL query string and content variables, i.e. from an HTML form - to override state values on initialization.
QUERY is given, where
the variables are exported depends on whether they're in a
at the time (see above). The
QUERY flags are mutually exclusive.
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 (
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
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>
<FORM METHOD=post ACTION=$url/>
Query: <INPUT NAME=query VALUE="$query">
<SQL "select x, y, z from table where Field like $query">
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
USEROK is set. Without this flag, the
original value of
$query would be preserved: the user would not
be able to change it.
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,
$user are exported:
<EXPORT $query QUERY>
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>
$user are saved when
is printed. Since
$user is not being looped over in the
SQL loop, it is a state-table variable when
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.
$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
$id, for the appropriate book. The
function can then select the given book by
$id and print more
detailed info on it.
$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
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.
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.
$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
Variables are exported from the scope of the
This means that a local variable of the same name as an
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
option lest it grow too large.
EXPORTing any data to
URL should not be considered
secure, as the data is compressed but not encrypted.
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.
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
QUERY may also increase Web
server log size.