Miva Script Reference Manual

Miva Script programs

Miva Script programs are HTML documents that also contain tags from the Miva Script programming language. Miva Script is a 'server-side' scripting language that is implemented by Miva Empresa and Miva Mia rather than by the browser (by contrast, a 'client-side' language such as JavaScript is implemented by the browser). Miva Script programs can also be called scripts, active documents, or simply documents. Miva Script tags correspond to typical programming language constructs such as assignment statements, conditional expressions, loops, and input/output statements, as well as Miva Script's special database, mail, and commerce functionality. Miva Script tags are XML-based: they have the same format as HTML tags; the element names (for example, <MvASSIGN>) indicate their function; and the attributes specify values that the tags operate on. Miva Script tags can be freely mixed with HTML tags. We speak of Miva Script programs being interpreted (by the Miva Empresa or Miva Mia pre-processor) and of individual tags being executed.

1. The Miva Script tags (commands) are executed, and replaced by the results of the execution, which is generally a mixture of HTML tags and text (there may also be input to and output from external files).
2. The pre-processed document, consisting of the original HTML tags and text, together with the tags and text generated by Miva Empresa or Miva Mia, is served to the browser and displayed.

Creating URLs for Miva Script programs

Miva Script programs should have a distinctive file extension. Unless some other extension has expressly been established on your system, we recommend the .mv extension.

The URL that you use to access your documents depends on whether you are using Miva Empresa or Miva Mia, and in the case of Miva Empresa, how the server is configured.

Miva Empresa

If Miva Empresa is running as a CGI application, it will be installed in the cgi-bin directory on your server. Typically Miva Empresa can be accessed by a URL in the following format:

http://www.your_isp.com/cgi-bin/miva

If in doubt, you should confirm this location with your ISP.

If your ISP is providing you with a virtual domain, Miva Empresa can be configured to run with a URL of the following format:

http://www.your_domain.com/cgi-bin/miva

When Miva Empresa is installed and configured, a specific directory is designated as the Miva Script document directory (with the mivaroot parameter in the Miva Empresa global configuration file). This is the default location for running Miva Script programs on your server. To run programs located in that directory, you would use a URL of the following form:

http://www.your_isp.com/cgi-bin/miva?scriptname.mv

That is, put a '?' between the Miva Empresa URL and the script name. If you are running a virtual domain, use the other form of the Miva Empresa URL:

http://www.your_domain.com/cgi-bin/miva?scriptname.mv

If authorized, individual users can also run scripts from their home directories. Miva Empresa designates a subdirectory of the user's home directory as their script directory. By default this is the directory public_html, but Miva Empresa can be configured to use another directory by way of the userdir parameter in the Miva Empresa global configuration file. To run a script called apples.mv in his or her public_html directory, the user jsmith would use the following URL:

http://www.your_isp.com/cgi-bin/miva?~jsmith/apples.mv

That is, the '?' should be followed by ~username, followed by the script name.

The NSAPI (Netscape API) version of Miva Empresa does not require that a Miva Script document be in a particular location; instead, the file name extension .mv triggers Miva Empresa. For example:

http://www.your_isp.com/apples.mv

Miva Mia

If you are running Miva Mia, there is only one Miva Script document folder, also called the HTML document folder, whose location is indicated in the WWW tab of the Miva Mia properties dialog. The URL for accessing the Miva Mia server is indicated in the Status tab. Typically, a script in your documents folder can be accessed with a URL in one of the following forms:

http://host.domain/script.mv
http://your_IP_address/script.mv
http://localhost/script.mv
http://127.0.0.1/script.mv

See the Miva Mia Administration page for more information.

Data files

Data files (external input and output files, database files, database indexes) used by Miva Script programs must be stored in specific locations.

For Miva Empresa these locations are set for specific users or groups in the Miva Empresa authorization file. By default, a user's data directory is the directory mivadata in their home directory. Contact your ISP or system administrator to find out the configuration for your server.

For Miva Mia the data folder is indicated in the WWW tab of the Miva Mia properties dialog.

There is no limit on the length of a filename that can be used by Miva Script, except for any limit that may be imposed by the operating system.

Writing a Miva Script program

This section describes a small Miva Script program to get you started. Even if you don't understand everything, you may find it useful to enter the program and open it with your browser, just to get an idea of what Miva Script programming is like and how to run a program.

<HTML>
<HEAD>
<TITLE>A simple Miva Script program</TITLE>
</HEAD>
<BODY>
<H2>A simple Miva Script program</H2>
<MvASSIGN NAME="var1" value="5">
<MvASSIGN NAME="var2" value="8">
<P><b>The answer is: <MvEVAL EXPR="{var1 + var2}">.</B></P>
</BODY>
</HTML>

If you save this document in the Miva Script document folder and submit it to your browser, Miva Empresa or Miva Mia will process it and send the results to the browser. The browser should display something like this:

A simple Miva Script program The answer is: 13.

Even though this program is simple, it illustrates several important features of Miva Script programs:

• Miva Script tags can be mixed freely with regular HTML tags.
• Variables: the two <MvASSIGN> tags assign values to variables.
• Expressions: {var1 + var2} is an expression that adds together the values of two variables.
• Evaluation: the <MvEVAL> tag evaluates the EXPR (expression) and displays the result.

These features are explained further in the sections that follow.

Tags

All Miva Script tags (also called elements) consist of a start-tag, such as <MvIF>, and sometimes an end tag, such as </MvIF>, that begins with the '</' characters.

End-tags are either required or prohibited: tags that can have end-tags must have them in order for the program to be correct; for all other tags, end-tags are prohibited. Tags for which end-tags are prohibited are called empty tags. Not only do empty elements not have end-tags, you cannot enter any 'content' for these elements, except for attribute values in the start-tag.

The <MvIF> tag requires an end-tag:

<MvIF EXPR="{age GT 6}">
...some code and/or text...
</MvIF>

<MvEVAL> is an empty tag that has attributes:

<MvEVAL EXPR="{age + 1}">

<MvELSE> is an empty tag that has no attributes:

<MvELSE>

The summary sections in this manual for each tag will indicate an end-tag if one is required.

If an element with paired tags is nested inside another element, the tags must be balanced; that is, the innermost element's start- and end-tags must both be between the start- and end-tags of the outermost element. For example:

<MvCOMMENT> Incorrect! </MvCOMMENT>
<MvWHILE ...>
    <MvIF ...>
...
</MvWHILE>
    </MvIF>

<MvCOMMENT> Correct! </MvCOMMENT> 
<MvWHILE ....>
    <MvIF...>
...
    </MvIF>
</MvWHILE>

If you use a context-sensitive editor such as HoTMetaL PRO to create Miva Script code, this kind of problem will not happen.

Attributes

Most start-tags can contain attributes: these are names that are assigned a value surrounded by double-quotes. Attribute values are data or other instructions that are used by a Miva Script or HTML tag. For example:

<MvASSIGN NAME="age" VALUE="10">

This tag has two attributes, NAME and VALUE, with values age and 10, respectively. The <MvASSIGN> tag assigns the value (10) specified with VALUE to the variable (age) specified with NAME.

Attribute values must be surrounded by double quotes for SGML and XML conformance.

Attribute values are often specified as literal values (text or numbers), as in the example above. Any attribute value can be specified as an expression or macro, however. Before the tag containing the attribute is executed, the expression or macro will be evaluated and the resulting values assigned to the attribute. For example:

<MvASSIGN NAME="person1" VALUE="shirley">
<MvASSIGN NAME="&[person1];" VALUE="{5+10}">

In the second <MvASSIGN>, the macro &[person1]; evaluates to 'shirley', and {5+10} evaluates to 15, so this tag is equivalent to:

<MvASSIGN NAME="shirley" VALUE="15">

In the tag summary sections of this manual, the expected values given for attributes indicate the values' semantics, that is, what kind of value--filename, mail server, function name, URL, etc. is required. In some cases, the value of an attribute must be one or more variables; otherwise, a literal, expression, or macro can be used to provide the attribute value. (A macro that evaluates to a variable name can also be used in place of a variable name.)

Using tags inside tags

Miva does not interpret tags used inside other tags as attribute values. For example, the following tag will not have the (intended) effect of specifying a URL:

<A HREF='<MvEVAL EXPR="{guestbook_url}">'>Say hi</A>

Sometimes you can accomplish what you want to do by using a macro. You could rewrite the previous example as follows:

<A HREF="&[guestbook_url];">Say hi</A>

In general you you cannot use a Miva Script tag as the value of the attribute of an HTML tag, but you can use an HTML tag as the value of the attribute of a Miva Script tag. For example:

<MvEVAL EXPR="<INPUT TYPE='text' NAME='speak'>">

Another way to express this is:

<MvASSIGN NAME="textbox" VALUE="<INPUT TYPE='text' NAME='speak'>">
&[textbox];

These examples will display a text box in the browser.

You can use the same constructions to run other HTML code, such as applets.

If you embed a tag containing attributes in an attribute, you must use a different quote character to delimit the attributes of the embedded tag than is used to delimit the attribute in which the tag is embedded. See Using quotes and other special characters in expressions for more information.

Putting comments in your program - MvCOMMENT

A comment is a piece of code that is not executed or displayed, but is present to indicate what the program is for and what individual pieces of code do. Comments are invaluable to someone unfamiliar with the program who is trying to understand it, or even to the program's author, who may be reading it again several weeks or months after writing it. Comments are also useful when you are developing, debugging , and testing your program: you can surround with comments lines of code that you think may have problems, to make sure they do not get processed, and then observe the results when the program is run.

Comments start with <MvCOMMENT> and end with </MvCOMMENT> :

<MvCOMMENT> this is a comment </MvCOMMENT>
<MvCOMMENT> 
This is a comment too, 
because comments can 
span multiple lines. 
</MvCOMMENT>

Text or code placed between <MvCOMMENT> and </MvCOMMENT> tags will not be passed on to the Miva Engine or the browser--it is completely ignored. .

You can also use ordinary HTML comments; these are passed to the browser but are not displayed. For example:

<!-- I am a comment. -->

Miva Script variables

A variable is a name that is associated with a value. For example, the name x could have the value 10, or, since it's helpful to use names that indicate what they're used for, age could have the value 10.

In Miva Script, a variable name can consist of the letters a through z (upper and lower case), the underscore, '_', and the digits 0 through 9. Other characters are permitted if they are 'escaped' with a backslash. For example:

<MvEVAL EXPR="{age\-old}">

This evaluates the variable age-old; without the backslash, this expression would be interpreted as the value of age minus the value of old. The backslash is not required if the variable is used in a macro.

The period (dot), '.', character can appear in variable names, but only when following a prefix that indicates the scope in which the variable is understood.

If the variable will be used in an expression, the variable name must start with a letter or an underscore. Variables that start with numbers are not supported in expressions unless they start with a scope prefix (g., l., s., or d.). Variables used in macros are permitted to start with a number.

It is recommended that you avoid using variable names that start with numbers or contain 'escaped' characters, unless they are required because they correspond to the names of fields in an HTML form, and no alternative names can be used.

Miva Script variable names are not case-sensitive: the variable age is the same as AGE and Age.

Here are some examples of valid and invalid usage:

<MvCOMMENT>Valid</MvCOMMENT>
<MvEVAL EXPR="{_13user}">
<MvEVAL EXPR="{user_13}">
<MvEVAL EXPR="{g.user_13}>
<MvEVAL EXPR="{g.13_user}">
&[13_user];
&[g.13_user];

<MvCOMMENT>Invalid</MvCOMMENT>
<MvEVAL EXPR="{13_user}">
<MvEVAL EXPR="{g.user.13}">

Unlike in some programming languages, you do not need to declare or define variables--you can just go ahead and use them. Using a variable in an expression without first assigning it a value also does not cause an error (although it may, of course, be responsible for a logic error in your program). Miva Script variables are typeless: the same variable can be assigned a numerical, text string, or boolean (true/false) value.

You can give a variable a value in two ways:

• Assigning a variable name with a value using the Miva Script <MvASSIGN> tag.
• Assigning a variable name by way of a standard input field from an HTML form.

To display the value of a variable, use the <MvEVAL> tag or a macro:

<MvEVAL EXPR="{var}">
&[var];

Using <MvASSIGN>

<MvASSIGN 
   NAME="var"
   VALUE="{expression}|literal">

The simplest way to assign a variable a value is with the <MvASSIGN> tag. For example:

<MvASSIGN NAME="age" VALUE="10">

This gives the variable age the value 10.

<MvASSIGN> has two attributes, NAME and VALUE, which specify the variable name and value, respectively.

Both the name and value can be specific values, such as age and 10 in the previous example, or they can be expressions, which are evaluated only when the program is run. For example:

<MvASSIGN NAME="age" VALUE="{2 + 8}">
<MvASSIGN NAME="age" VALUE="{age + 2}">
<MvASSIGN NAME="age" VALUE="{thisyear - birthyear}">

These examples show three different kinds of expressions (the expressions start with '{' and end with '}'). The first expression consists of two numbers added together. The second expression adds 2 to whatever the current value of age is (this value then becomes the new value of age). The third expression uses two other variables (birthyear and thisyear) and subtracts them to calculate the new value of age.

Although these examples use expressions only in the value of the VALUE attribute, the NAME attribute can also have an expression as its value.

Note: <MvASSIGN> should be used instead of the deprecated tag <MvLET>. Miva Script supports this tag to maintain compatibility with older scripts, but it should not be used for new coding. <MvLET> is not XML-compliant and will cause problems if the code is validated or edited with an XML-compliant editor. <MvLET> also cannot use an expression to represent the name of the variable being assigned (by contrast, <MvASSIGN>'s NAME attribute can have an expression as its value).

Assigning variables in HTML forms

A variable can be created and assigned a value in an HTML form. Since HTML forms are the primary way of obtaining input from users, you will often be assigning values to variables using this method.

In an HTML form, each button, text box, pull-down menu, and scrolling list has a name attribute. For each such object, Miva Script creates a global variable whose name is the same as the value of the object's NAME attribute. When the form is submitted, the values entered for each object in the form are assigned to the corresponding variables. For example, the following markup creates a text box with the name speak:

<INPUT TYPE="TEXT" NAME="speak">

Based on this, Miva Script will create a variable called speak; it will be assigned a value if a user enters a value in the text box and submits the form to the Miva Script program, and can then be manipulated and operated upon by the receiving program.

For text boxes and text areas, the value of the variable is whatever text the user enters. Check boxes, radio buttons, scrolling lists, and pull-down menus are defined with a fixed set of one or more possible values, specified by the object's VALUE attribute. The Miva Script variables corresponding to these form objects can have one of these fixed values when the form is submitted, but can be given other, arbitrary values later in the Miva Script code. For example:

<INPUT TYPE="CHECKBOX" NAME="send_info" VALUE="yes">

If this checkbox is turned on when the form is submitted, the variable send_info will have the value yes.

Here is another example, using radio buttons:

<B>Language/langue:</B><BR>
<INPUT TYPE="RADIO" NAME="language" VALUE="english">English<BR>
<INPUT TYPE="RADIO" NAME="language" VALUE="french">Français<BR>

In this example, the variable language can have the value english or french (depending on which button is selected) when the form is submitted.

Note: Variables assigned in HTML forms are not available to a program until the form has been submitted.

Note: An 'image submit' button (<INPUT TYPE="IMAGE"> called name is represented by two Miva Script variables: name.x and name.y will contain the X and Y coordinates of the point that was clicked on when the form was submitted.

Note: If a drop-down list (SELECT tag) has more than one option selected, the value of the variable corresponding to the list will be the value of the last selected option in the list.

See the section Multiple passes through a program for more information on using variables set in forms.

Variable scope

The scope of a variable is the context in which it exists and has meaning. There are two aspects of variable scope: the a variable's scope inside the currently running program, and its scope in another program called by the current program.

By default, the maximum scope of any variable is the currently running program instance; if this program calls another program (or calls the same program a second time), the values of variables in the current program are not automatically available in the second program. There are several methods for passing variables and other data to a program: see Passing data to a program below.

Prefixes in the variable name define its scope in the current program. The variable scopes available in Miva Script are:

• Local: if a variable is created with the prefix local or l (for example, local.age and l.age), and is used inside a function (an <MvFUNCTION>...</MvFUNCTION> block), its scope is only inside that function.
• Database: the scope a variable whose name is of the form dbname.database.var or dbname.d.var is the database named dbname and commands that act on that database.
• System: Whenever a built-in system variable or a variable that is generated by an <MvSMTP>, <MvPOP>, <MvWHILE>, or <MvCALL> loop is named, use the prefix convention system.varname or s.varname.
• Global: if a variable is created with the prefix global or g (for example, global.age and g.age), it is a global variable--its scope is the entire program.

A global variable and a local variable with the same primary name can be used as two different variables if they're prepended with the appropriate prefixes (for example, g.counter and l.counter).

If a variable var without a prefix is encountered, the Miva pre-processor carries out the following steps in order until one of them succeeds:

1. The Miva pre-processor checks if a system variable s.var or system.var exists and has scope in the current location. If so, then var is interpreted as referring to that variable.
2. If a local variable l.var or local.var exists and has scope in the current location, then var is interpreted as referring to that variable.
3. If a database variable d.var or database.var exists and has scope in the current location, then var is interpreted as referring to that variable.
4. If a global variable g.var, global.var, or var exists then var is interpreted as referring to that variable.
5. If no variable var (with any prefix) exists, then var is created as a global variable.

The built-in function miva_getvarlist(scope) returns a comma-separated list of the names of all currently defined variables with the given scope. scope must be a literal string: 'l', 'local', 'g', 'global', 's', 'system'.

Note: For xBase3 databases, use <MvREVEALSTRUCTURE>

The following detailed example illustrates these rules (for simplicity, only global and local variables are contrasted here).

<BODY>
<MvFUNCTION NAME="f1">
E: <MvEVAL EXPR="{new1}"><BR>
F: <MvASSIGN NAME="new1" VALUE="20"><BR>
G: <MvEVAL EXPR="{g.new1}"><BR>
H: <MvASSIGN NAME="l.new1" VALUE="30"><BR>
I: <MvEVAL EXPR="{new1}"><BR>
J: <MvEVAL EXPR="{g.new1}"><BR>
K: <MvASSIGN NAME="new1" VALUE="40"><BR>
L: <MvEVAL EXPR="{l.new1}"><BR>
M: <MvEVAL EXPR="{g.new1}"><BR>
</MvFUNCTION>
A: <MvASSIGN NAME="new1" VALUE="10"><BR>
B: <MvEVAL EXPR="{new1}"><BR>
C: <MvEVAL EXPR="{g.new1}"><BR>
D: <MvASSIGN NAME="junk" VALUE="{f1()}"><BR>
N: <MvEVAL EXPR="{new1}"><BR>
...
</BODY>

The output from this program is:

A: 
B: 10
C: 10
D: 
E: 10
F: 
G: 20
H: 
I: 30
J: 20
K: 
L: 40
M: 20
N: 20

It is worth analyzing this output in detail:

1. Assign new1 the value 10.
2. As expected, evaluating new1 displays '10'.
3. Since new1 was used for the first time without a prefix, it is a global variable and therefore g.new1 also evaluates to '10'.
4. Call the function f1().
5. Since new1 is global, it is available inside the function block and (currently) has the same value, 10.
6. Assign a new value, 20, to new1.
7. Evaluating g.new1 gives '20', indicating that the previous assignment to new1 still referred to the global variable.
8. Create a local variable l.new1 and assign it the value 30.
9. Evaluating new1 now displays '30'; since a local new1 now exists, new1 without a prefix now refers to that version of the variable.
10. The global variable new1 is still available, but you have to use the g. prefix to access it.
11. Assign the value 40 to new1.
12. Evaluating l.new1 displays '40', indicating that the previous assignment referred to the local version.
13. g.new1 (the global variable) still has the value '20'
14. Now the function has terminated; since the local version of new1 has no scope here, evaluating new1 (without a prefix) now refers to the global variable new1 again. It still has the last value assigned to the global variable, on line F.

Note: Variables used in documents in a frameset document are local to the frame in which they are used.

Site variables

System administrators of servers running Miva Empresa can maintain a file called the site variables file that contains definitions for variables (but not functions) that are accessible to all Miva Script programs running on the server. The Miva Mia users can maintain site variables files on their PCs. A variable in the site variables file can be used in the same way as any other global variable. Variables in a the site variables file are intended to be assigned string values only; the results of assigning Miva tags to variables are undefined.

Expressions and literals

An expression is a formula that can be evaluated to give a result. Expressions always occur in attribute values and must be enclosed in curly brackets, '{' and '}'. Expressions can contain variables, literal values (text or numbers), and operators, which indicate how the other components in the expression are to be evaluated.

In general, Miva Script expressions can be used in two ways:

1. They can create a new value.
2. They can be evaluated for their logical "truthfulness". Any expression that is equal to '0' (zero) or a null string is considered false. All others are considered true. True is often represented by '1' (one).

A literal is a number or a string of characters that is not meant to be evaluated: for example: 23 and 'hi there'. Literals don't have to be enclosed in curly brackets.

In general, if an attribute value (except for a macro) needs to be evaluated, it must be enclosed in curly brackets.

When an value surrounded by curly brackets is used in an attribute value, the open bracket must immediately follow the double-quote character that starts the attribute value (that is, there must be no spaces between them; similarly, the closed bracket must immediately precede the double-quote that terminates the attribute value. If you don't do this, the expression will be treated like a literal string. For example:

<MvCOMMENT> Wrong! </MvCOMMENT>
<MvEVAL EXPR=" {a + b} ">

<MvCOMMENT> Right! </MvCOMMENT>
<MvEVAL EXPR="{a + b}">

Here are some examples of expressions:

{age}
{age + 1}
{age GE 17}
{x * (y / z)}
{'a' IN name}

These examples contain:

• Variables (age, name, x, y, z)
• Numbers (1, 17)
• Literal text ('a')
• Arithmetical operators (+, *, /)
• A numerical comparison operator (GE--"greater than or equal to")
• A string (text) comparison operator (IN--"is contained in")

Notice also that a single variable name can be an expression. Conversely, an expression can have as many components as are required.

Inside an expression, spaces are not significant (that is, they do not affect how the expression is evaluated) except in the following ways:

• If an operator contains characters that can also occur in a variable name, then it must be separated from the other components by one or more spaces: {n POW 2} cannot be written as {nPOW2}, but {a + b} and {a+b} are equivalent (since '+' cannot be a character in a variable name).
• Spaces inside literal strings are significant.

One use for expressions that you've seen already is in a variable assignment:

<MvASSIGN NAME="age" VALUE="{age + 10}">

Expressions are also used in conditionals, which test some condition and (usually) take an action based on the results of the test. Here is an example:

<MvIF EXPR="{age GE 17}">
    <p><b>This person is eligible to drive a motor vehicle.</b></p>
</MvIF>

This <MvIF> tag tests the expression '{age GE 17}' ("Is the age greater than or equal to 17?") and if that expression is true (which depends on the current value of age), it prints some text.

An expression consisting only of a literal string does not require curly brackets. If a literal string is inside curly brackets, it must be surrounded by single quotes (that is, the apostrophe or front quote character, '...'). The following tags are equivalent:

<MvASSIGN NAME="person" VALUE="Moira">
<MvASSIGN NAME="person" VALUE="{'Moira'}"> 

If you want to put a literal string of text in an expression that contains operators or variables, surround the literal with single quotes . For example:

<MvASSIGN NAME="boss" VALUE="{'Fred ' $ 'Flintstone')">

Here the literals Fred and Flintstone are surrounded by double quotes.

You should represent a null string in an expression as two single quotes (''):

<MvIF EXPR="{entry EQ ''}">

The Miva Script comparison or logical operators (such as GE and AND) always produce a result of 0 (false) or 1 (true).

Note: An expression consisting of a literal number, for example, {149.99}, evaluates to that number.

Using quotes and other special characters in expressions

Since expressions have to be surrounded by double quotes, you have to use special techniques if you want to put double quotes in expressions.

There are two ways to handle this:

1. Use single quotes instead
2. Use the built-in function asciichar() to represent the double quotes

If you want to assign a string of HTML (but not Miva Script) code to a variable, you can use single quotes instead of double quotes to surround attribute values. The code in the variable can then be passed to the browser using <MvEVAL>. Since the browser cannot execute Miva Script code, you should pass only HTML code to the browser in this way.

<MvASSIGN
     NAME="input1" 
     VALUE = "Address: <INPUT TYPE='text' NAME='address'>"> 
<FORM 
    ACTION = "http://www.sq.com/cgi-bin/quagmire" 
    METHOD = "post">
<MvEVAL EXPR = "{input1}">
</FORM>

This displays:

Address:

The code in this example assigns a string to a variable named input1. The value of input1 is HTML code that generates a text box with the label "Address:". Miva will evaluate input1 to send the HTML code to the browser; it also creates a Miva Script global variable called address (or g.address).

If you really have to use double quotes, you can use the built-in function asciichar(n) to represent the double quotes. asciichar(n) is equivalent to the character whose ASCII code is n. The code for a double quote happens to be 34. You will also need to use the concatenation operator, $, to join this character to the rest of your text. For example:

<MvASSIGN 
    NAME="banner" 
    VALUE="'Home of '$asciichar(34)'The Best 
            Wings in Town'$asciichar(34)'!'">
<MvEVAL EXPR="{banner}">

This displays:

Home of "The Best Wings in Town"!

Notice that the literal parts of the expression have to be surrounded by single quotes.

Other special characters

You can use the asciichar(n) function to represent other characters that you cannot use literally in an expression, for example, carriage return and line feed. If you will be using these characters often you can assign asciichar(n) to a variable and use the variable instead. For example:

<MvASSIGN NAME="dq" VALUE="{asciichar(34)}">
<MvASSIGN NAME="cr" VALUE="{asciichar(13)}">
<MvASSIGN NAME="lf" VALUE="{asciichar(10)}">
<MvASSIGN NAME="crlf" VALUE="{asciichar(13)$asciichar(10)}">
<MvEVAL EXPR="{'Dear User,'$crlf$'Thank you for your interest.'}">

Displaying the result of an expression - MvEVAL

<MvEVAL EXPR="{expression}">

There are many ways of evaluating an expression, but if you want to display the result in the browser, you should use the <MvEVAL> tag. For example:

<p><b>The final amount is: <MvEVAL EXPR="{price*units}">.</b><p>

Another way to think about the <MvEVAL> tag is that it is replaced, in an HTML document, with the result of an expression.

The <MvEVAL> tag has one attribute, EXPR, whose content can be an expression to be evaluated, or a literal string or number. If the content is an expression it must be enclosed in curly brackets, or it will be treated like a literal and not evaluated. Normally, if you want to display a literal you would just enter it directly in the HTML file, rather than using an <MvEVAL>.

When multiple fields in a form are given the same name (e.g. "name"), return values will be comma delimited. For example, the following:

	name1<INPUT TYPE="text" NAME="name"><BR>
	name2<INPUT TYPE="text" NAME="name"><BR>
	name3<INPUT TYPE="text" NAME="name"><BR>
	name4<INPUT TYPE="text" NAME="name">
	<INPUT TYPE="submit VALUE="Submit Query">

The results of "<MvEVAL EXPR="{ name }">"

...will be "1,2,,4"

See also the section on macros.

Miva Script operators

An operator in a Miva Script expression indicates how the data it acts on are to be processed: added, subtracted, compared, joined, bit-shifted, and so forth. In the expressions {age + 10} and {age GT 16}, '+' and 'GT' are operators. The components on each side of the operator are sometimes called operands.

Miva Script operators have a built-in precedence that determines which operator gets interpreted first if there are two or more operators in an expression. You can also override the built-in precedence by surrounding sub-expressions with parentheses, `(' and ')'.

Miva Script provides the following types of operators:

• Arithmetical operators
• Comparison operators
• Logical operators
• Text string operators
• Bitwise operators
• Operator precedence

Arithmetical operators

These operators are used with numbers or numeric expressions.

Miva Script also supports a number of built-in numerical functions.

+

Addition
expr1 + expr2

-

Subtraction
expr1 - expr2

*

Multiplication
expr1 * expr2

/

Division
expr1 / expr2

POW

POWer
expr1 POW expr2
Raise expr1 to the power expr2
For example, 3 POW 4 is 3⁴, or 81.

MOD

MODulus
expr1 MOD expr2
Returns the integer remainder from expr1/expr2
For example, 26 MOD 7 is 5. See also the built-in function fmod(), which returns floating point remainders.

ROUND

Number rounding
number ROUND places
Rounds number up or down to places decimal places.
For example, 123.45676 ROUND 2 is 123.46

Note: A minus sign can precede a literal number to make it negative (for example, -3.14), but otherwise must be used strictly as a binary operator: {-x} evaluates to the literal string '-x'; to express the negative of a value, use {-1*x} or {0-x}. Using +, /, or * as a unary operator results in an expression error.

Comparison operators

These operators are used to compare two numbers or two text strings. In text string comparisons, lowercase letters are considered to be greater than uppercase letters. Two strings are equal only if the case (upper or lower) matches letter-by-letter. These operators all give a value of 1 (true) or 0 (false).

GT

Greater Than
expr_a GT expr_b
Tests whether expr_a is greater than expr_b

LT

Less Than
expr_a LT expr_b
Tests whether expr_a is less than expr_b

EQ

EQual To
expr_a EQ expr_b
Tests whether expr_a is equal to expr_b
Two strings are equal only if the case (upper or lower) matches letter-by-letter.

NE

Not Equal To
expr_a NE expr_b
Tests whether expr_a is not equal to expr_b

GE

Greater Than or Equal To
expr_a GE expr_b
Tests whether expr_a is greater than or equal to expr_b

LE

Less Than or Equal To
expr_a LE expr_b
Tests whether expr_a is less than or equal to expr_b

Note: The expression {0 EQ ''} ("does zero equal the null string?") returns 1 (true).

Tip: To check whether a string is non-null, you can use the expression {string} rather than the longer form {string NE ''}. Similarly, to test whether a number is non-zero, use {number} rather than {number NE 0}.

Tip: Strings that consist of numbers and punctuation characters, and begin with identical numeric prefixes (for example '234-1' and '234-2') are considered equal by EQ. To force Miva Script to perform a true string comparison, prepend the same letter to both sides of the EQ. For example: {'x' $ lhs EQ 'x' $ rhs}

Logical operators

These operators are used with 'true' or 'false' expressions. For example:

<MvIF EXPR="{age GE 17 AND age LT 80}">

This expression is true if both of the expressions '{age GE 17}' and '{age LT 80}' are true.

NOT

Logical NOT
NOT expr
Returns the opposite of expr (if expr is false, NOT expr is true, and vice versa). Notice that this operator is unary: it acts on one expression, not two.

AND

Logical AND
expr_a AND expr_b
This expression is true if both expr_a and expr_b are true.

OR

Logical OR
expr_a OR expr_b
This expression is true if either of expr_a and expr_b is true.

Text string operators

These operators are used with text strings or text string expressions.

Miva Script also supports a number of built-in string functions.

$

Concatenate strings
expr_a $ expr_b
Concatenates (joins) the strings expr_a and expr_b together.
For example, {'fred' $ 'flintstone'} would result in 'fredflintstone'.

IN / CIN

Beginning position
expr_a IN expr_b
expr_a CIN expr_b
Returns the beginning position of expr_a contained in expr_b.
For example, {'da' IN 'canada'} returns 5, because 'da' begins at the fifth letter in 'canada'. IN is case-sensitive: it will find matches only if the matched sub-string in expr_b has the same case, letter-by-letter, as expr_a. Use the CIN operator if you want to make your comparison case-insensitive. Notice that if you use literal strings in this expression you have to surround them with single quotes.

EIN / ECIN

End position
expr_a EIN expr_b
expr_a ECIN expr_b
Returns the end position of expr_a contained in expr_b.
For example, {'dia' IN 'canadian'} returns 7, because 'dia' ends at the seventh letter in 'canadian'. EIN/ECIN returns 0 when the left operand is NULL. This fixes backward comptibility with Miva v3.57 and earlier "Htmlscript" versions. ECIN is the case-insensitive version of EIN.

SUBSTR

Substring
expr SUBSTR 'position, #chars'
Returns the substring of expr that begins at position and is #chars characters in length. For example, {'canadian' SUBSTR '3,5'} returns 'nadia', which starts at the third character in 'canadian', and is five characters long. Note that the right side of a SUBSTR expression must be a string consisting of two numbers separated by a comma, or an expression or macro that evaluates to such a string.

FMT

Format string
expr FMT pattern

The FMT operator enables you to format a string based on a pattern. This operator provides a way to enhance the search, display, and logical processing capabilities of Miva Script active documents. New users are advised to gain some experience with constructing expressions using the built-in string functions before trying FMT. See the section Formatting values for a discussion of FMT string format patterns and modifiers.

CRYPT

Encrypt a string
plaintext CRYPT key

Performs a one-way encryption, similar to that provided with the UNIX crypt command. The string plaintext is encrypted using the string key (this string is sometimes called a 'salt') . key can be any two characters (extra characters will be ignored). Only the first eight characters of plaintext will be used in the encryption. key is used as the first two characters of the encrypted value. CRYPT always yields the same result when applied to a particular plaintext and key.

Bitwise operators

These operators act on numbers at the binary or 'bit' level. For example, BITAND compares the bits of two numbers, and returns a third number whose bits are equal to 1 (turned on) only if the same bits are equal to 1 in both the original numbers. That is, it performs a logical AND on corresponding bits.

The expression '{27 BITAND 13}' is evaluated as follows: 27 has the binary (base 2) form '00011011'; 13 has the binary form '00001101'. The only bits that are equal to 1 in both numbers are the first and fourth (counting from the right); therefore, the result is the number that has those bits equal to one, and all others equal to 0: 00001001, or 9 in decimal form.

BITAND

Bitwise AND
expr_a BITAND expr_b
Perform a logical AND on the bits of expr_a and expr_b.

BITOR

Bitwise OR
expr_a BITOR expr_b
Perform a logical OR on the bits of expr_a and expr_b.

BITXOR

Bitwise Exclusive OR
expr_a BITXOR expr_b
Perform a logical exclusive OR on the bits of expr_a and expr_b (return the number whose bits are equal to 1 in either, but not both, of the original numbers).

BITOC

Bitwise ones complement
BITOC expr
Flip the bits of expr (including the 'sign bit'). Notice that this operator is unary: it acts on one number, not two. Here is an example: {BITOC 9}. 9 in binary form is '1001'; including the 'sign bit' (leftmost bit), which indicates that the number is positive, it is '01001'. Flipping these bits gives '10110'. Since the sign bit is now '1', the number is negative. According to the rules of binary arithmetic, '0110' interpreted as a negative number is '-10'.

BITSL

Bitwise shift-left
expr_a BITSL expr_b
Shift the bits of expr_a to the left by expr_b places. The leftmost bits are lost, and the rightmost bits are replaced by zeroes.
'{23 BITSL 2}' is interpreted as follows: 23 is 00010111 in binary form; shifting these bits left two places gives 01011100, or 92 in decimal format.

BITSR

Bitwise shift-right
expr_a BITSR expr_b
Shift the bits of expr_a to the right by expr_b places. The rightmost bits are lost, and the leftmost bits are replaced by zeroes.

Order of precedence for operators

Sometimes an expression can be interpreted in more than one way, depending on which operators are executed first. For example, {2 + 3 * 4} could be evaluated as 14 or 20, depending on whether the + or the * was evaluated first. In order to make the expected results unambiguous, Miva Script follows three rules:

1. Each operator is assigned a precedence, and if there is a choice of which operator to evaluate first, the operator with higher precedence is evaluated.
2. If two operators have the same precedence, the leftmost one is evaluated first.
3. Sub-expressions inside parentheses, '(' and ')', are evaluated first.

The order of precedence for Miva Script operators, from highest to lowest, is as follows:

• NOT
• FMT, ROUND, CRYPT, MOD, SUBSTR, POW
• /, *
• +,-,$
• IN, CIN, EIN, ECIN, EQ, NE, GE, LE, LT, GT
• AND, OR

According to these rules, {2 + 3 * 4} is evaluated to 14, because '*' has a higher precedence than '+'. If you really want the '+' to be evaluated first, you can use parentheses: {(2 + 3) * 4}. In the expression {2 / 4 * 5}, both operators have the same precedence, so the leftmost one (/) is evaluated first, and the result of the whole expression is 2.5.

Macros

So far you have seen <MvEVAL> used to obtain (and display) the value of variables and expressions. Sometimes you will want to obtain and use a variable value in contexts where <MvEVAL> is not appropriate. For example, you cannot assign the value of a variable to an HTML attribute using <MvEVAL> or a Miva Script expression.

One way to use a variable value is by using it in a macro expression. This allows you to use the contents of a variable as in-line HTML or Miva Script code. The syntax of a macro is:

&[ variable_name ];

When a Miva Script tag is processed, any variables found inside '&[ ...];' will be evaluated before the rest of the tag is parsed and or executed.

Note: A macro can contain only a single variable, and no expressions, literals, or functions.

For example, suppose the variable server_name has the value www.sq.com. The following code uses the value of server name to create a URL:

<A HREF="http://&[server_name];/index.html">Home Page</A>

In this example, the value of server_name will be substituted for the '&[...];'. The tag above is equivalent to:

<A HREF="http://www.sq.com/index.html">Home Page</A>

The characters '&amp;' will also function as the start of a macro: &amp;[var1]; and &[var1]; are equivalent. The semi-colon at the end of a macro is optional, but, if you want a semi-colon to be displayed after a macro, you will have to enter it twice (for example, &[var];;). To summarize, the following four forms are equivalent:

&[variable];
&[variable]
&[variable];
&[variable]

The variable used in a macro can also stand for executable code. The current implementation of Miva Script does not support macros that stand for Miva Script code that involves a loop or other jump. For example:

• <MvIF>
• <MvFUNCTION>
• <MvWHILE>
• <MvCALL>
• <MvIMPORT>

Tip: Both expressions and macros can be used to specify the values of Miva Script attributes. Only macros can be used to specify the values of HTML attributes. This attribute assignment is correct: <FORM ACTION="&[documenturl];"> This form is incorrect: <FORM ACTION="{documenturl}">

Macros provide the capability for "indirection" and self-generating code:

<MvASSIGN NAME="var_a" VALUE="var_b"> 
<MvASSIGN NAME="var_b" VALUE="burrito"> 
<MvEVAL EXPR="{&[var_a];}">

'<MvEVAL EXPR="{&[var_a];}">' will display the value burrito. This may seem surprising at first, but you should consider the order in which the Miva Script code is evaluated. First, the macro substitution takes place: in this step, the expression '&[var_a];' is replaced by the current value of var_a. This is the string, not the variable, 'var_b'. The <MvEVAL...> tag becomes, in effect:

<MvEVAL EXPR="{var_b}"> 

Then the resulting <MvEVAL...> is executed. The EXPR '{var_b}' is evaluated, and its value, the string 'burrito', is displayed.

Many of the functions of macros can also be carried out using the string concatenation operator, '$'. For example:

<MvASSIGN name="firstname" value="Alex">
<MvASSIGN name="lastname" value="DeLarge">
<MvEVAL expr="&[lastname];, &[firstname];">
<MvEVAL expr="{lastname $ ', ' $ firstname"}>

The two <MvEVAL> tags in this example each display the same thing: 'DeLarge, Alex'.

Tip: If the value of a variable contains double quotes, using it in a macro as the value of an attribute may cause a syntax error. The form: EXPR="{var}" is safer than: EXPR="&[var];" In general, you should not use a macro unless you have a very good idea of the format of the value in the variable it contains. See also the following section on security.

Security issues with macros

Because Miva Script macros can be used to insert executable Miva Script code directly into a script, a potential security problem exists. If user input is displayed using a macro, and that input contains executable Miva Script code (such as calls to built-in file manipulation functions) then unexpected and undesirable results may occur. However, good programming practices can prevent this from happening.

Note: A macro in a quoted string that is inside an expression is expanded inside of the quoted string and will not be executed.

1. All user input (for example, input from a FORM, from a data file, from the URL command line, or from a POST action) should be validated to ensure that it does not contain executable code. If it does, it must not be displayed using a macro (or if it is, it must be entity-encoded). Ideally, your script should issue an error message to the user indicating that tags must not be entered. Variations on the the following code fragment will test whether the input contains any executable code (that is, tags). In this example, assume that input from a FORM is contained in the variables field1, field2, field3, field4, and field5.

   <MvASSIGN
       NAME="input"
       VALUE="{field1$field2$field3$field4$field5}">
   <MvIF EXPR="{('<' IN input) OR ('>' IN input)}">
       <P>Invalid input! Please do not enter HTML or Miva Script tags in any field!</P>
   </MvIF>

   Entity-encoding a variable makes the contents of the variable safe and can be used instead of the code above.
2. Use <MvEVAL> instead of a macro to display the values of variables. Macros must be used if you want to insert a variable's value in an attribute, but for displaying text to the browser a macro can always be replaced by an <MvEVAL> tag. For example:

   <MvCOMMENT>Possibly unsafe!</MvCOMMENT>
   ...
   You said: &[someinput];
   
   <MvCOMMENT>Safe!</MvCOMMENT>
   ...
   You said: <MvEVAL EXPR="{someinput}">

3. If your program is not relying on the value of a variable being set via user input, and that variable is being displayed with a macro, the variable should be explicitly initialized (set to some initial value with <MvASSIGN>) in the program. This prevents values from other sources inadvertently or intentionally being output.

Macro encoding

The value of a macro can be URL- or entity-encoded before it is put out. This can be used to make the macro output secure.

Entity-encoding

The following construction converts all characters in the macro output that have HTML entity equivalents to those entities (this is equivalent to applying the encodeentities() function):

&[var:entities];

For example:

<MvASSIGN NAME="Step1" VALUE="Press <Enter>">
&[Step1];<BR>
&[Step1:entities];

This code will display:

Press
Press <Enter>

When &[Step1]; is evaluated, the string <Enter> is passed to the browser; since this is an unknown tag, it is not displayed. When &[Step1:entities]; is evaluated, the '<' and '>' characters are converted to entities: Press &lt;Enter&gt;. This string is displayed as intended in the browser.

URL-encoding

A string that results from a macro evaluation can be URL-encoded to make it safe to use as a name or value in a URL query string (that is, the part of a URL to the right of the '?', if there is one). In this encoding, special characters such as +, %, &, =, and space are replaced by safe equivalents. Note that encoding query strings is not identical to encoding the 'document' part of the URL (the part to the left of the '?'): for example, a space in a query string is encoded as '+', whereas in a document URL it is encoded as '%20'.

The following construction URL-encodes the macro output; this is equivalent to applying the encodeattribute() function.

&[var:attribute];

For example, if var has the value 'R&D', &[var:attribute]; produces 'R%26D'.

You should use this form of the macro if you are using the macro output as a name or value in a query string. Do not encode an entire query string: if you do, the '=' between names and values, and the '&' between pairs will be encoded and thus lose their special meanings.

Configuring the Miva processor

<MIVA
    INTERPRET="tags,macros"
    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, its default 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, or both. By default (that is, if you don't have an explicit setting for INTERPRET) both are interpreted.

The possible INTERPRET values are:

• tags: Miva Script tags will be interpreted
• macros: Miva Script macros will be interpreted
• tags,macros or macros,tags: both tags and macros will be interpreted (the default).
• null string: neither tags nor macros will be interpreted. Note that an INTERPRET value consisting of any arbitrary string (such as none) is equivalent to the null string.

Configuring the output

A Miva Script program typically consists of Miva Script tags, Miva Script macros, HTML tags, and text (this includes white space such as newlines 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.

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 newlines 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. There are three values that can be assigned to the attribute:

• none: marcos have no encoding,
• entities : macros are entity encoded
• attributes: macros are attribute encoded

Configuring error reporting

Miva Script can report three kinds of errors:

• syntax errors: 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: badly-formed expressions. For example:

  <MvCOMMENT>Missing '}'</MvCOMMENT>
  <MvEVAL EXPR="{a + b">
  <MvCOMMENT>Expected operator, none found</MvCOMMENT>
  <MvEVAL EXPR="{a b}">

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

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.

For more information on Miva Script error messages, see Configuring runtime error handling.

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 si