8. Configuring Miva Processor

---

Introduction

<MIVA> Tag

The <MIVA> tag enables you to configure the level of code interpretation, output, error reporting, and error handling. <MIVA> is an empty tag.

<MIVA

INTERPRET="tags,macros,html_expressions"

STANDARDOUTPUTLEVEL="html,text,compresswhitespace"

DEFAULTMACROENCODING="none,entities,attributes"

ERROROUTPUTLEVEL="syntax,expression,runtime"

ERRORMESSAGE="text_of_error_message"

<TAGNAME>_Error="fatal/nonfatal,display/nodisplay">

You can use as many <MIVA> tags as you need, to turn various features on and off as needed throughout your program. Each <MIVA> tag can specify one or more attributes. The STANDARDOUTPUTLEVEL and ERROROUTPUTLEVEL attributes can also be specified for individual user-defined functions.

When any <MIVA> attribute is omitted, the settings is not changed; its default or current setting is assumed,

The STANDARDOUTPUTLEVEL attribute has an additional option. This is the "compresswhitespace" option. When enabled, it will cause the Miva Engine to eliminate any extra whitespace in the output of Miva Script code.

Configuring Miva Script Code Interpretation

The Miva Script code in a program typically consists of Miva Script tags and macros. You can use the INTERPRET attribute of <MIVA> to specify whether the Miva interpreter will execute tags, macros, html expressions or a combination. By default (that is, if you don't have an explicit setting for INTERPRET) all are interpreted.

The possible INTERPRET values are:

Code	Interpretation
tags	Miva Script tags will be interpreted.
macros	Miva Script macros will be interpreted.
html_expressions	Miva Script expressions will be interpreted inside HTML Tags.
tags, macros,html_expressions	all will be interpreted (the default).
null string	none will be interpreted.

Note: An INTERPRET value consisting of any arbitrary string (such as none) is equivalent to the null string.

Configuring the Miva Script Output

A Miva Script program typically consists of Miva Script tags, Miva Script macros, HTML tags, and text (this includes white space such as new lines between tags). The Miva interpreter always sends the results of any Miva Script tags it interprets to the browser; you can use the STANDARDOUTPUTLEVEL attribute of <MIVA> to indicate whether or not you want the Miva processor to pass HTML tags and text to the browser. By default (that is, if you don't have an explicit setting for STANDARDOUTPUTLEVEL) both are passed to the browser.

Note: Since the Miva Script macros on each line of the document are resolved into their textual equivalents before the Miva Script tags on that line are executed, macro references are treated as just another type of text by STANDARDOUTPUTLEVEL.

STANDARDOUTPUTLEVEL Values

The possible STANDARDOUTPUTLEVEL values are:

• html: HTML tags will be passed to the browser
• text: text will be passed to the browser
• text,html or html,text: both text and HTML tags will be passed to the browser (same as the default)
• null string: neither text nor HTML tags will be passed to the browser. Note that a STANDARDOUTPUTLEVEL value consisting of any arbitrary string (such as none) is equivalent to the null string.

For example, this setting will cause only tags to be sent to the browser:

<MIVA STANDARDOUTPUTLEVEL="html">

One of the most common uses of STANDARDOUTPUTLEVEL is preventing unnecessary and excessive white space in the output of the program: when a line of Miva Script code is executed, any spaces, tabs, or new lines on that line are passed to the browser. To avoid this (and thereby possibly speed up your output), you can set STANDARDOUTPUTLEVEL to html only. This causes all literal text in the document to be suppressed, so if there is some text that you want to display anyway, you must use an <MvEVAL> tag to display it. The output of <MvEVAL> is always passed to the browser, no matter what the value of STANDARDOUTPUTLEVEL is.

Default Macro Encoding

The Miva Script DEFAULTMACROENCODING attribute will assign the default encoding type to all macros. In Miva Script 3.72 and above, there is only one DEFAULTMACROENCODING setting for the entire system. There are three values that can be assigned to the attribute:

Value	Description
none	macros have no encoding
entities	macros are entity encoded
attributes	macros are attribute encoded

Encoding used on an individual macro will override the default macro encoding.

Configuring Error Reporting

Miva Script can report three kinds of errors: Syntax, Expression, and Runtime.

Syntax Errors

Syntax errors are badly formed or missing tags or attributes. For example:

<MvCOMMENT>Badly-formed tag</MvCOMMENT>

<MvIF EXPR="{var}">Hello</MvIF

<MvCOMMENT>Missing attribute</MvCOMMENT>

<MvIF>hello</MvIF>

Expression Errors

Expression errors badly-formed expressions. For example:

<MvCOMMENT>Missing '}'</MvCOMMENT>

<MvEVAL EXPR="{a + b">

<MvCOMMENT>Expected operator, none found</MvCOMMENT>

<MvEVAL EXPR="{a b}">

Runtime Errors

Runtime errors occur from an error with an external file. For example, attempting to read (with <MvIMPORT>) from an external file that does not exist.

ERROROUTPUTLEVEL

The ERROROUTPUTLEVEL attribute of <MIVA> enables you to specify which kinds of errors Miva Script will report. By default (that is, if you don't have an explicit setting for ERROROUTPUTLEVEL) all three types of errors are reported. The possible values are any combination of syntax, expression, and runtime, comma-separated. For example, to have only syntax and expression error messages displayed, you would use:

<MIVA ERROROUTPUTLEVEL="syntax,expression">

To turn off all error reporting:

<MIVA ERROROUTPUTLEVEL="">

You can specify a default error message that will be displayed before other, standard error messages. To do this, specify a value for the ERRORMESSAGE attribute of <MIVA>. The default is the null string. Here is an example:

<MIVA ERROROUTPUTLEVEL="runtime"

ERRORMESSAGE="Now look what you've done! :-)">

If specified, this message will be displayed even if all forms of error reporting are turned off.

Configuring Runtime Error Handling

Whenever executing a Miva Script tag results in an error, the text of the error message is assigned to a variable that has the same name as the tag, but with the _error suffix added. This text is identical to the error message that the script displays by default in the browser window. For example, errors from <MvIMPORT> will be assigned to the variable mvimport_error. Your script can test the contents of these variables and take some action based on the results of this test.

For example:

<MvIMPORT FILE="bogus.dat" FIELDS="v1,v2,v3" DELIMITER=",">

....

</MvIMPORT>

<MvIF EXPR="{'cannot find the file' CIN mvimport_error}">

<PRE>File not found.</PRE>

</MvIF>

Make sure to put the <MvIF> somewhere that it will be executed--if you were to put it inside the <MvIMPORT>...</MvIMPORT> tags, it wouldn't get executed since the <MvIMPORT> loop is not entered if the input file is not found.

This technique can be used to test the results of database operations such as <MvSKIP>, <MvFIND>, and <MvGO>. If you want to suppress the default Miva Script error messages from being displayed in the browser window, you can use the <MIVA> tag as follows:

<MIVA ERROROUTPUTLEVEL="syntax,expression">

This setting leaves out the value 'runtime', thereby turning off runtime error messages.

You can control how Miva Script handles errors for specific tags. For each tag, <MIVA> has an attribute TAGNAME_ERROR (for example, MvIMPORT_ERROR). These attributes can have the following values:

• fatal/nonfatal: fatal will cause all runtime errors for this tag to terminate the script; nonfatal will allow the script to continue.
• display/nodisplay: display will cause runtime error messages for this tag to be displayed; nodisplay will suppress error messages for this tag.

For example:

<MIVA MvIMPORT_ERROR="nonfatal,nodisplay">

This will cause <MvIMPORT> runtime errors to not terminate the script or be displayed.

Note: If the ERROROUTPUTLEVEL attribute exists, its runtime setting (whether present or absent) overrides the display/nodisplay setting made with TAGNAME_ERROR.