1. 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 Merchant Empresa and Miva Merchant 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 Merchant Empresa or Miva Merchant 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 Merchant Empresa or Miva Merchant 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 Merchant Empresa or Miva Merchant 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 Merchant Empresa or Miva Merchant Mia, and in the case of Miva Merchant Empresa, how the server is configured.

Miva Merchant Empresa

If Miva Merchant Empresa is running as a CGI application, it will be installed in the cgi-bin directory on your server. Typically Miva Merchant 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 Merchant Empresa can be configured to run with a URL of the following format:

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

When Miva Merchant Empresa is installed and configured, a specific directory is designated as the Miva Script document directory (with the mivaroot parameter in the Miva Merchant 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 Merchant Empresa URL and the script name. If you are running a virtual domain, use the other form of the Miva Merchant 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 Merchant Empresa designates a subdirectory of the user's home directory as their script directory. By default this is the directory public_html, but Miva Merchant Empresa can be configured to use another directory by way of the userdir parameter in the Miva Merchant 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 Merchant Empresa does not require that a Miva Script document be in a particular location; instead, the file name extension .mv triggers Miva Merchant Empresa. For example:

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

Miva Merchant Mia

If you are running Miva Merchant 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 Merchant Mia properties dialog. The URL for accessing the Miva Merchant 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 Merchant 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 Merchant Empresa or Miva Merchant 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 the 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 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

You can use a Miva Script tag as the value of the attribute of an HTML tag, and you can use an HTML tag as the value of the attribute of a Miva Script tag.

With a Macro

<MvASSIGN NAME="guestURL" VALUE= "<A HREF = "/guestbook">Say HI</A>"
MvEVAL EXPR = "{guestURL}"

Without Using a Macro:

<MvASSIGN NAME = "url2" VALUE = "http://www.cnn.com">
<a href ="{url2}">Click Here </a>

Another example:

<MvASSIGN NAME="textbox" VALUE= " <INPUT TYPE='text' NAME='speak'> ">
<MvEVAL EXPR = "{textbox}"
This example 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 empty tag.

Syntax:

<MvEXIT>

Note: An <MvEXIT> within a FUNCTION in a script called with <MvDO> also causes the script containing the <MvDO> to terminate. Therefore, to exit from a script called by <MvDO>, without exiting from the calling script, use <MvFUNCRETURN>.