SYNOPSIS<TIMPORT [options] $schema [FROMFILE] $data|$file[ /]>
[ ... statements ...
</TIMPORT>]
DESCRIPTION
The <TIMPORT>
statement (Texis IMPORT) imports text data into
Vortex variables. The schema argument is a schema (template),
which defines what fields are in the source data and what format they
are in.
The data parameter is the text buffer containing raw data to
be imported. If the FROMFILE
flag is given, it is considered a
filename instead, and that file is read for the import data.
Each value of the buffer or filename variable is imported in sequence.
The returned fields are assigned to Vortex variables of the same name,
one field per value. Each result row returned by <TIMPORT>
adds
another set of values to the variables, and the statements inside the
<TIMPORT>
block are executed. (I.e. a loop occurs for every row
imported, not just for every buffer/filename given.)
Unlike the command-line version of TIMPORT, in Vortex the imported
fields are not inserted into a table. Instead they are returned
as variables for further processing by the Vortex script. This gives
the programmer complete control over what rows go where and how. For
full details on the syntax of schemas and the usage of TIMPORT in
general, see the Texis manual on TIMPORT. Note that the following
TIMPORT keywords do not apply in Vortex, because no table is used:
host
, port
, user
, group
, pass
,
createtable
, database
, droptable
, table
.
The variables returned by <TIMPORT>
behave like <SQL>
variables (here) in that only the current iteration's
return value is visible inside the loop. SKIP
and MAX
also behave as in <SQL>
, giving the number of initial values to
skip, and the maximum number of values to return.
The flags NOVARS
, OKVARS
and ROW
can also be used; as in a <SQL>
statement,
NOVARS
causes no variables to actually be returned,
OKVARS
gives a permitted list of return variables, and ROW
causes the variables to be returned as single values,
instead of being accumulated in a loop.
The $loop
and $next
variables are set as in <SQL>
,
i.e. the current loop iteration count and next-iteration count.
$indexcount
is not set, however.
A BREAK
statement may be given inside the loop to exit
prematurely.
In version 7 and later, the statement may be self-closing (<TIMPORT ... />) instead of terminated with an end tag (</TIMPORT>). The statement is then non-looping: loop/next are not set, though SKIP
/MAX
are still
respected. Return variables accumulate.
EXAMPLE
The following example imports fields from a Unix-style mailbox into
the variables From, Subject, Date and lists
each message:
<$schema = "
# take multiple records from a single file:
multiple
datefmt x, dd mmm yyyy HH:MM:SS
# name type tag default_val
field From varchar />>^\RFrom\x20\P=[^\space]+ UNKNOWN
field Subject varchar Subject UNKNOWN
field Date date Date
field Body varchar />>^=[\alnum\-_]+:\x20=[^\n]+\n\n\P=!\nFrom\x20+
">
<TIMPORT $schema FROMFILE /tmp/mbox>
From: $From <BR>
Subject: $Subject <BR>
Date: $Date <BR>
<P> <PRE>
$Body
</PRE>
<HR>
</TIMPORT>
CAVEATS
The TIMPORT
statement was added in version 2.1.872500000 19970825.
Column variables returned by TIMPORT
are cleared first before
the loop starts, i.e. previous values are lost. However, if no rows
are returned by the command, then the variables are not cleared.
The rows skipped by SKIP
apply after any row(s) skipped
by TIMPORT schema keywords. Thus, if columnar data (format col
or csv
) is imported without the keepfirst
keyword, the
first row is still skipped, even if SKIP
is 0.
TIMPORT
is not available in early Webinator Vortex versions.
Only Commercial Vortex versions after Sep. 1 1997, and Webinator
versions after Sep. 30 1998 contain it.