Web Host Resources

Print Document Table of Contents

Miva Merchant Script Compiler 5 User's Guide For Windows

Scope

This guide covers the basics of the Miva Merchant Script Compiler" on the Windows operating system.

Those just starting out will find simple, step-by-step instructions for installing the Compiler, setting up the development environment, and compiling an example file. More advanced users will appreciate a complete listing of usage options and error codes.

Subjects not within the scope of this guide include the MivaScript" language, programming techniques, and the use of other Miva Merchant products.

Audience

This guide is written for anyone who wants to install and use the Miva Merchant Script Compiler under Windows. Typical users include commercial developers of Miva Merchant" modules, web site designers, and technically-inclined online merchants.

Conventions

To make this guide easier to read, these typographical conventions are used:

Names of files, and folders, such as mvc.exe, in the BIN folder, are displayed in bold text. Also the names of buttons, fields, and tabs in dialog boxes are shown in bold.

MivaScript and anything entered at the command line are displayed in a monospaced font. Some wrapping will be inevitable, due to the length of lines of code. Blocks of code removed for the sake of brevity are indicated by ellipses (...). For example:

<MvFUNCTION NAME = "My_New_Function">

<MvASSIGN NAME = "l.ok" VALUE = "1">

<MvIF EXPR = "{ l.ok }">

...

</MvIF>

<MvFUNCTIONRETURN VALUE = "{ l.ok }">

</MvFUNCTION>

Compiled MivaScript - An Overview

The Miva Merchant Script Compiler assembles and compiles compatible MivaScript files into a cross-platform, web-based executable that runs under the Miva Merchant Empresa Virtual Machine.

Benefits of Compiling Your MivaScript Code

Compiled MivaScript, like with most programming languages and applications, has many advantages over interpreted code, both for the developer, and for the end-user.

Code Syntax Checking  

If there is a problem with the syntax in your MivaScript code, a tag that was never closed, for instance, the compiler will find it, and provide information to help you locate and correct the problem. You produce a higher quality product for your customers.

Faster Program Execution  

Because the program has been converted by the Miva Merchant Script Compiler into streamlined machine code that the computer can understand directly, your programs run faster than non-compiled programs, which must be interpreted by the engine at the time they are run, every time they are used.

Code Obfuscation

With compiled code, when you sell or provide an application to others, they can run it, but cannot read your source code. This protects your investment of time, and prevents others from copying your code, or the ways you accomplish tasks in your programs.

Reduction or Elimination of Runtime Syntax Errors

When you compile your MivaScript applications, any syntax errors will be found and pointed out to you at compile time, when you can fix them. Your customers, or visitors to your site, will rarely or never experience a problem.

Access to External Functions

Compiled MivaScript applications can take advantage of functions written in other programming languages, like C/C++ or Java. You can call functions provided in the Miva Merchant libraries, or create functions of your own.

Royalty-Free Application Distribution

You can use the built-in functions provided with the Miva Merchant Script Compiler, and incorporate them into your products, royalty-free. In addition, users of the Miva Merchant Limited Source Kit" can use the files provided as the basis of their own products, also royalty-free.

Cross-Platform Execution

Miva Merchant Empresa Virtual Machine", the engine that runs MivaScript applications on the server, is available for both Windows and UNIX/Linux servers. That means your programs will be able to run on almost any server available today.

Create Assembly Language

In the normal process of compiling, MivaScript code goes through the normally-unseen step of being converted into Miva Merchant Assembly Language. Although, the assembly and compilation usually occur in only one visible step, there is an easy way to stop the process before compilation, and save the Miva Merchant Assembly Language in a .mva file, which can be used as a debugging tool. (Assembler documentation is beyond the scope of this guide.)

The Miva Merchant Development Environment

Before we can get started writing and compiling MivaScript modules and applications, we first need to set up the environment under which the compiled files will run. Since MivaScript applications are browser-based, we will need to set up a local server environment, along with some directory structures where the applications will expect to find their associated files.

Directories & Files the Compiler Will Use

All the files discussed below will be installed, and the directories created for you, under the main directory of C:\MSC, when you install the Miva Merchant Script Compiler.

Executables

The following executables will be installed in the BIN directory:

Built-in Libraries

The built-in libraries will be installed in the BUILTINS directory:

Applications Programming Interface (API)

The MivaScript API files, which will be installed in the API directory, provide of a set of routines that enable the C programmer to extend the behavior of the Miva Merchant Virtual Machine.

Functions provided in the API are documented in the MivaScript API Reference Guide, which is available at http://www.mivamerchant.com/docs/.

Examples

The final folder installed with the Miva Merchant Script Compiler is the EXAMPLES folder. The example files are not required for the compiler to function. This directory includes the not-yet compiled MivaScript files for 3 simple browser-based game applications. We will be using them later, when we learn how to compile files.

A Directory for Your Source Code Files

A convenient way to organize your application files is to create a separate directory, perhaps MyScripts, with sub-directories for each application. You can compile MivaScript files in any directory.

Miva Merchant Mia - Personal Web Server & Virtual Machine

You can compile MivaScript applications with the Miva Merchant Script Compiler alone, but to run them, you will need either Miva Merchant Mia" or Miva Merchant Empresa Virtual Machine" on your system. Miva Merchant Empresa Virtual Machine is a web server plug-in. Miva Merchant Mia is a personal web server, for testing and development on your local machine.

You can download Miva Merchant Mia for free, and find related documentation, at http://www.mivamerchant.com/products/mia/.

If you have not done so already, download and install Miva Merchant Mia Virtual Machine, according to the Miva Merchant Mia Virtual Machine Administration Guide.

The Directory for Compiled Applications, Using Miva Merchant Mia

Although you can compile a file that is located in any directory, to run a compiled MivaScript file (.mvc), it must be in the directory where Miva Merchant Mia looks for scripts. By default, the directory is: C:\MivaMia\HTML, but you can specify a different directory in Miva Merchant Mia if you like.

When you run your scripts, if they use any graphics or other resource files, those files will need to be in that same directory with your .mvc file.

Install & Configure the Compiler

Download the Installation Program

If you have not done so already, download the Miva Merchant Script Compiler installation program from the Miva Merchant FTP site. The instructions for downloading can be found in the e-mail you received when you registered for the Miva Merchant Script Compiler.

If you cannot find that e-mail message, you can call customer support, at 1.866.284.9812 or contact by e-mail at support@mivamerchant.com.

Run the Installation Program

Double-click the downloaded file, msc-v5.02-win32.exe, to launch InstallShield. Follow the prompts to install the Miva Merchant Script Compiler. The directories discussed earlier will be created, and the necessary files installed in them.

Tell Windows Where to Find the Compiler

Go to the Control Panel.

Go to System.

Select the Advanced tab.

Click the Environment Variables button.

Under System Variables, in the Variables list, highlight the variable Path, then click the Edit button.

At the end of the existing Variable Value field, add a semicolon at the end of the existing text to begin a new path, then type

C:\MSC\BIN\

Example:

%SystemRoot%\system32;…;C:\Program Files\Microsoft Office\OFFICE11\Business Contact Manager\;C:\MSC\BIN\

Click OK to save your change.

Click OK again to dismiss the Environment Variables dialog.

Click OK to dismiss the System Properties dialog.

Tell Windows Where to Find the Library Files (.dll):

This time, instead of adding to an existing system variable's value, we are going to create a new system variable, and assign it a value.

• As before, go to the Control Panel.

• Go to System.

• Select the Advanced tab.

• Click the Environment Variables button.

• Under System Variables, click the New button.

• For Variable name, enter MVC_LIB

• For Variable value, enter C:\MSC\BUILTINS\

• Click OK to save the new system variable.

• Click OK again to dismiss the Environment Variables dialog.

• Click OK to dismiss the System Properties dialog.

Now we have completed the installation of the Miva Merchant Script Compiler, and associated files, on the computer. We just need to register it, then it will be ready to use.

Register the Compiler

Now the compiler is installed. Before using it we need to register it, then create a plain text file (msc_license.dat) to store the license information where the compiler can find it.

First, Gather Your Information:

Before you go online to get your verification code, collect the following information, so you will have it handy:

• • Find your User Name and System Name

    You can find your user name and system name, by typing MVASM -I at the command prompt, and pressing Enter.

  • License Number

    Your license number is in the e-mail you received from Miva Merchant when you purchased the Miva Merchant Script Compiler.

Next, Get Your Verification Code

The process of getting a verification code from Miva Merchant insures that your user name, system name, and license number are valid. The verification code is provided to you when you register the compiler online.

Go to this URL to get your verification code:

https://secure.miva.com/products/compiler/register.mvc

Enter the required Registrant Information.

Enter the System Information (username, system name, and license).

Copy the four lines of text that will be provided there, and paste them into a plain text file using Notepad, or a similar text editor.

Save Your Registration Data

Save the file in the Miva Merchant Script Compiler directory on your system - usually

C:\MSC\msc_license.dat.

Technical Note - License File Location

The Miva Merchant Script Compiler looks for the file containing registration information in one of several places. We have saved it in the ordinary location, and everything should work without further modification. The Compiler will try to locate it first in the file specified in the registry key:

"\HKEY_LOCAL_MACHINE\SOFTWARE\MIVA\Miva Merchant Script Compiler\License File".

This will have been set by the installation program, and will find the file we just created and saved. You should not need to make any changes to the Registry. In case there is ever a problem with the Registry, and the license file appears to be missing, the Compiler will try C:\MSC\msc_license.dat (regardless of what is specified in the Registry).

Finally, if the license file was not found at either of the other locations, it will

look in C:\WINNT\system32\msc_license.dat, on a Windows NT machine, or in C:\WINDOWS\system32\msc_license.dat, under Windows XP.

If the compiler is unable to find the license file, the following message is displayed:

The software was unable to verify that this is a properly licensed installation of the Miva Merchant Script Compiler. This may be due to one of the following causes:

- Invalid or missing licensing information.

- The software is unable to determine your system or user name.

The Miva Merchant Script Compiler is licensed on a per-user basis. If you require additional licenses, they may be purchased from the Miva Merchant General Store.

If you have already purchased a license for the Miva Merchant Script Compiler, registering the license will provide you with the required licensing information, and instructions on how to install the licensing information on your system. You may register your Miva Merchant Script Compiler license at https://secure.miva.com/products/compiler/register.mvc.

Registration Completed

At this point, you have completed the installation and registration process. Your Miva Merchant Script Compiler is ready to use. We will begin by compiling one of the examples provided with the Compiler.

Compile & Run an Example File

The Miva Merchant Script Compiler starts with raw MivaScript source code files (filename.mv), and produces compiled files (filename.mvc). Some handy examples come with the compiler - this would be a good time to try working with one.

Compile a MivaScript File

Just to get the feel of using the Miva Merchant Script Compiler, let's work through a very simple exercise - compiling an existing MivaScript file, from the Examples collection provided with the compiler. We'll do the Cube game here, then you can try the others on your own.

At the Command Prompt, go to the directory that contains the .mv file you want to compile. Type mvc, a space, and the name of the file, with the .mv file extension:

Press Enter. Nothing will appear to have happened at the Command Prompt:

But check in the directory where you are working, and you will see the new .mvc file:

Run Your New Application

You've created a promising-sounding file called cube.mvc - now you'd probably like to see what it does.

MivaScript applications need to run under the Miva Merchant Virtual Machine on a web server - Miva Merchant Mia or Miva Merchant Empresa. (If you have not already installed Miva Merchant Mia Virtual Machine, you will need to do so before you can run your compiled file.) Just move cube.mvc into the directory where Miva Merchant Mia will look for your web scripts (by default, C:\MivaMia\HTML).

If your application requires any graphics (as this one does - the two .gif files), copy those into that same directory.

Now open a browser window, and enter http://localhost/cube.mvc (or whatever application you created), press Enter, and presto  

Here is how your compiled example script, cube.mvc, looks when it is running in the browser:

You have successfully installed and configured the Miva Merchant Script Compiler. You've used it to compile one of the example files provided for practice. Good job!

Next, we will cover the more general aspects of using the compiler. But first, take a break and play with your new game. If you want to, you can compile and run the other examples (all games), too.

Using the Compiler

Running the Compiler

The Miva Merchant Script Compiler runs from the command-line. In Windows, run the Command Prompt to open a text-based window.

To display a brief summary of compiler commands, type:

mvc --help

Yes, those are two dashes in a row, following a space.

To display the Miva Merchant Script Compiler version number

mvc --version

Compiling a MivaScript File

Navigate, via DOS directory commands, to the directory where the file is located. Once there, type the following command.

mvc <options, see below> myfilename.mv

Compilation Options

Every time you run the Miva Merchant Script Compiler you need to specify any options you want to use - that is, the options don't "stick" - they revert to the default each time.

You set the options described below by entering a hyphen, followed by the appropriate letter, between mvc, and the name of the file to be compiled. For example:

c:\...\MyScripts> mvc -w 5 cube.mv

Specifying the Target Version of the Miva Merchant Empresa Engine

By default, the compile will create code for the current engine. To specify another version of the Miva Merchant Empresa engine on which the compiled code will run, use the C flag, with the version number of the engine, as shown here:

mvc -C 4.14 <filename.mv>

If the code cannot be correctly compiled for the specified version — that is, if functions that were not supported for that version are included in the code — it will be compiled for version 5 and an error message will be displayed.

Setting Warning Levels

See Appendix A for a list of compilation warnings, and the codes you can use to set the warning options described here. The following options are available from the command prompt. For these options, <warning> may be either:

One or more warning code numbers, separated by commas

  The keyword all, which indicates all warnings

Where the <options> go, type one of the following, or accept the default warning levels. The brackets are not typed:

-w <warning code(s)>     Suppresses the specified warnings

-W <warning code(s)>     Enables the specified warnings

-X <warning code(s)>     Aborts compilation on the specified warning

The above illustrates how you would compile the Cube game, with all warnings enabled.

Remember - Compilation options, including warning level settings, are in effect only during the compilation for which they were set. The default settings are used unless a specific option is specified each time.

Specifying an Alternative Library Directory

If you want to compile using an alternative set of library files (.dll), you can override the default location of the MVC_LIB directory with -B, and the full directory path. For instance:

mvc -B c:\mydevdirectory\mydlls filename.mv

Creating Miva Merchant Assembly Code

To create a .mva file (Miva Merchant Assembly Code), stopping short of creating a .mvc file, type:

mvc -c <filename.mv>

Calling a Function in a Second MivaScript File (New in v.5)

A new expression syntax allows a function to be called in a second MivaScript file (as the MvDO tag does).

"[" filename-expression "]." function-name "(" (parameter

(,parameter)) ")"

Examples:

<MvEVAL EXPR = "{ [ g.filename ].functionname( param1, param2 ) }">

<MvEVAL EXPR = "{ 'value = ' $ [ 'lib.mvc' ].functionname( param1,

param2 ) }">

Understanding Warning & Error Messages

Error and warning messages are designed to help you find and fix problems in your code. Each message provides the following information:

• The name of the file in which the problem occurred.

• The line number within that file.

• A two-letter code that describes the type of problem, along with the error code (see the Appendices for complete listings of warning and error messages). A means an assembly problem, and C says there is a compilation problem. W tells you it's a warning, and E indicates an error.

• A plain-text description of the problem.

For example, an actual error message might look like this:

cube.mv:35: CE_167: Function name 'len' not defined or recognized as an external function

The way to read this is "In the file cube.mv, on line 35, there is a problem that resulted in compilation error number 167, described as ."

Troubleshooting

Even when we've done things right, and all is going well, we can run into unexpected behaviors. Here are some common frustrations, and tips for dealing with them:

Q: I tried to get my username and system name, but the command MVASM -I isn't recognized.

A: First, be sure you are using all upper-case letters. The command is case-sensitive.

If that still doesn't work, double-check the System Variables settings described under Install & Configure the Compiler, to be sure they are correct. The MVASM-I function is provided by one of the programs (mvasm.exe) that was installed along with the compiler, in the BIN folder. It could be that Windows doesn't know where to find that application.

Q: When I try to compile a file, I get the message: 'msc' is not recognized as an internal or external command, operable program or batch file.

A: That's because the command to compile with the Miva Merchant Script Compiler is not "msc" (as one might guess), but "mvc". Try remembering it as ".mv compile".

Q: When I try to compile a file, I get the message: mvc1: Unable to open 'filename.mv': The system cannot find the file specified.

A: Make sure you are working from the same directory as the file to be compiled, not, for instance, c:\Documents and Settings\<yourname>.

Q: I know I'm doing everything right, but when I try to compile the file, nothing happens.

A: When a file compiles, with no warnings or errors, it will appear at the command prompt as if nothing has happened. You are left at the command line, without any comment. That's OK - it means your file compiled. To find it, look in the folder where the original .mv file was located - there will be a .mvc file of the same name there.

Q: My application used to run, but I just compiled it again, without errors, and now it's broken.

A: Double check that you typed the ".mv" file extension for the source file you compiled. If  you accidentally typed ".mvc", it would appear to compile without errors or warnings, and will create a new .mvc file, but will not produce usable code.

Q: I got the example, cube.mv, to compile and run, but the graphics didn't show up.

A: Remember to move any graphics required by the application into the same directory or folder, as the .mvc file.

Appendix A: Compilation Warnings

Compilation warnings are issued when it is still possible to compile the file, but something is not quite right in the code. Warnings can help you correct possible problems in your MivaScript. It is possible that the code was intentionally written in a way that resulted in the warning, but it's always best to double-check your work when you see a warning, even though your file compiled.

1. Warnings That are Enabled by Default

2. Unknown attribute name (name)

3. MvDO has a VALUE attribute with no NAME attribute; discarding result

4. Preferred operator datatype does not match constant type; inefficiency or unexpected rounding may occur

5. Unrecognized parameter "x" to "y" attribute

6. Value in comma-separated list is used more than once

7. (tagname) does not use attribute (attribute)

8. MvFUNCTIONRETURN found within an MvLOCKFILE block

9. Suspected misspelled MivaScript tag: (tagname)

10.  - not used -

11. Unscoped variable at 'x'

12. Function name (name) not defined or recognized as an external function

13. MvFUNCTIONRETURN found within an MvCAPTURE block Program is attempting to generate code that is inconsistent with the engine version specified by the -C flag.

Warnings That are Suppressed by Default

    51.  Value (value) does not have any effect for attribute (attribute) in compiled MivaScript

Appendix B: Compilation Errors

Errors, usually a problem with syntax, prevent the code from compiling. When you get an error message from the compiler you will not find a new .mvc file. Be careful that you don't overlook an error message, then proceed to run the .mvc file from an earlier compilation.

Compilation Error Codes and Descriptions

Appendix C: Assembly Errors

Assembly Error Codes and Descriptions

The following are errors that can be generated during the creation of assembly code.