Structure of a Miva Script Program

Introduction

Miva Script programs are HTML documents that also contain tags (commands) 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 are 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 preprocessor) and of individual tags being executed.

Miva Script programs use the following kinds of auxiliary files:
File Type
Description
Delimited (Flat) Data Files
Text files that contain one record per line, with fields separated by one or more ASCII characters. The last line should be blank.
Miva Database Files
Databases that can be ordered by multiple index files. A database may have a memo file (.dbt file) associated with it.
Miva Index Files
Files that create an ordered view of the database files.

When a browser requests a Miva Script document, Miva Empresa or Miva Mia pre-processes the document before passing it on to the browser:

The Miva Script tags 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).

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 the following URL:

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.

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:

These features are explained further in the sections that follow.

About 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>

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.

About 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 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.

Using JavaScript with Miva Script

JavaScript and Miva Script cannot interact directly, because they are processed at different points in the document-processing cycle: Miva Script code is pre-processed, before the document gets to the browser, whereas JavaScript is processed in the browser after the browser receives the document (which has already been processed by Miva). However, some interactions are possible since JavaScript code can be embedded in Miva Script documents (for example, in a <SCRIPT> tag, or as the target of a URL), just as it can be in regular HTML documents. Therefore, keep the following items in mind:

Keep in mind, though, that the JavaScript code can interact directly only with the HTML code in your document, not the Miva Script code.

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>

Another Example:

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

Exiting from a Program

<MvEXIT>

The <MvEXIT> tag causes the script in which the exit tag resides to terminate. <MvEXIT> is a tag.

Syntax:

<MvEXIT>

Note: An <MvEXIT> in a script called with <MvDO> causes only the script containing the <MvEXIT> to terminate.