MvIMPORT#

Imports records from a text file one line at a time where each line ends with a line feed (lf). The tag loops through the file stopping at the end of file (eof), unless terminated using .

Syntax

<MvIMPORT FILE = "string: {  expression } | literal"
          FIELDS = "{ expression } | variable list"
          DELIMITER = "string: {  expression } | literal"
          FILTER_TYPE = "{ expression } | variable name"
          FILTER = "{expression} | variable name">

          <MvIMPORTSTOP>
          <MvIMPORTCONTINUE> 
</MvIMPORT>

Optionally, fields separated by a DELIMITER character or characters can be parsed and stored in variables supplied in the FIELDS attribute.

Attributes#

Attribute	Description
`FILE`	Path and file name relative to the data folder.
`FIELDS`	Comma-separated list of variables where the imported data will be stored.
`DELIMITER`	Delimiter can be null, a single character, or multiple characters. If null, the entire string will be stored in a single variable in FIELDS.
`FILTER_TYPE`	(Optional) Literal keywords: `expression` or `variable`. Specifies what is contained in the FILTER attribute: - `expression` (default): FILTER contains an expression. - `variable`: FILTER contains the name of a variable whose value is a string that can be evaluated as an expression, allowing dynamic filter creation.
`FILTER`	The filter to apply, either an expression (e.g. `"{ NOT alias.d.deleted }"`) or the name of a variable containing such an expression (e.g. `"l.filter"`).

The import loop continues through the file until the end is reached or the loop is terminated with the <MvIMPORTSTOP> tag. The imported line of data can be processed as needed, typically storing the information in a database.

The variable g.recno is automatically created and contains the current record number (line number) in the input file, starting at 1.

Records in data files can be terminated by line feeds (LF), carriage returns (CR), or line feed/carriage return pairs (LFCR). Data files should end with a blank line.

<MvIMPORT> tags can be nested to read data from multiple files within the same block of code.

Important

Since searching in a text file is much slower than searching in a database, if you will be reusing the data it is recommended to import it, store it in a Miva database, and perform searches on the database. This will speed up your scripts and avoid overloading your server.

An alternative to <MvIMPORT> is the file_read() function, which reads an entire file into a single variable at once, from either the data or scripts folders.

Examples#

Displaying Imported Data#

Suppose you have a data file called movies.dat with lines in the format:

Title|Director|Year

for example:

Cape Fear|Martin Scorsese|1991
The Trouble With Harry|Alfred Hitchcock|1955
Dr Strangelove|Stanley Kubrick|1963
Strange Days|Kathryn Bigelow|1995
Clerks|Kevin Smith|1994

<table>
  <tr>
    <th>&nbsp;</th>
    <th>Title</th>
    <th>Director</th>
    <th>Year</th>
  </tr>
  <MvIMPORT FILE="movies.dat" FIELDS="l.title,l.director,l.year" DELIMITER="|">
    <tr>
      <td><MvEVAL EXPR="{ g.recno }"/>.</td>
      <td><MvEVAL EXPR="{ l.title }"/></td>
      <td><MvEVAL EXPR="{ l.director }"/></td>
      <td><MvEVAL EXPR="{ l.year }"/></td>
    </tr>
  </MvIMPORT>
</table>
````

After the first iteration, the variables are populated as:

```text
l.title    = Cape Fear  
l.director = Martin Scorsese  
l.year     = 1991

The automatically-created variable g.recno will contain the current record (line) number, 1. After looping through each line, the final table will look like this:

	Title	Director	Year
1.	Cape Fear	Martin Scorsese	1991
2.	The Trouble With Harry	Alfred Hitchcock	1955
3.	Dr Strangelove	Stanley Kubrick	1963
4.	Strange Days	Kathryn Bigelow	1995
5.	Clerks	Kevin Smith	1994

Filtering the input#

In the previous example, you might be interested only in movies from 1995. Using the FILTER attribute, you can specify a condition that the input data must meet. Records that don’t pass the filter are discarded:

<MvIMPORT FILE="movies.dat"
          FIELDS="l.title,l.director,l.year"
          DELIMITER="|"
          FILTER_TYPE="expression"
          FILTER="{ l.year EQ '1995' }">

<MvIMPORT> will now only return records where l.year = '1995'. The result would be:

	Title	Director	Year
1.	Strange Days	Kathryn Bigelow	1995

Terminating the Import#

Importing can be halted explicitly inside an <MvIMPORT> loop using the <MvIMPORTSTOP> tag. The program jumps to the code following the </MvIMPORT> tag without reading any more input from the data file.

Using the Record Number (`recno`)#

The variable recno, containing the current line number in the file being read, is generated automatically by <MvIMPORT>. A variable named recno is also generated and updated when navigating a database (alias.d.recno). If you use both at once, disambiguate by using g.recno for <MvIMPORT> and db_alias.d.recno for database navigation.

Nested Imports#

It is possible to nest <MvIMPORT> tags. For example, an “outer” <MvIMPORT> could read a list of data file names, and for each line an “inner” <MvIMPORT> could read records from that file. The value of recno always refers to the current nesting level’s line number.