TIMPORT - general purpose data import

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 they are appended in a list, yet only the current value returned is visible inside the loop. SKIP and MAX behave similarly, 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, while ROW causes the variables to be returned as single values, instead of being appended 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, nor is $null significant.

A BREAK statement may be given inside the loop to exit prematurely.

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 ROW $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.

SEE ALSO
SQL, LOOP, BREAK