10. Passing Data to a Program

---

Introduction

There are several ways to pass data to a Miva Script program, or from one Miva Script program to another:

• Via the URL that calls the program, as a set of name/value pairs.
• Via the URL that calls the program, as a simple list of values.

Data passed in this way are referred to as arguments. Miva Script will use both conventions to interpret any data passed to a program; we recommend that you choose one or the other for each program and use it consistently within that program.

• In variables generated from HTML FORM objects.
• In 'hidden' FORM variables' specified with the <MvHIDE> tag.

Data passed using these methods are always passed as name/value pairs. You can also pass data by:.

• Storing and/or reading data in a database or text file.
• Storing and/or reading data in a cookie.

Note: Unless a Miva Script variable is passed to another program using one of the methods listed above, it has no meaning outside the currently running instance of the program; that is, its maximum scope is the current program instance.

Name/Value Pairs

Data passed on the URL command line are referred to as arguments. Miva will interpret any data passed to it in this way as both name/value pairs and as a value list. In general it is not a good idea to code the program so that it uses both conventions: we recommend that you choose one or the other for each program and use it consistently within that program.

You can pass data to a Miva Script program using the same syntax that a browser uses to submit a FORM with a METHOD of GET.

• Example using the CGI version of Miva Merchant Empresa:

http://www.server.com/cgi-bin/miva?fruit.mv+fruit1=black+cherries&fruit2=oranges

• Example using the NSAPI version of Miva Merchant Empresa:

http://www.server.com/fruit.mv?fruit1=black+cherries&fruit2=oranges

• Example using Miva Merchant Mia:

http://127.0.01/fruit.mv?fruit1=black+cherries&fruit2=oranges

These examples pass two variable values to the program fruit.mv: fruit1 has the value "black cherries", and fruit2 has the value "oranges". The fruit.mv program can use these variables with the values specified.

Using this syntax, each variable name and its corresponding value must be separated by an equal, '=', sign. Each name/value pair is separated by an ampersand, '&'. Spaces are replaced by a '+' sign, and some special characters (notably newline, '=', and '&') are replaced by '%nn', where the ns are digits from 0-9 and/or letters between 'A' and 'F'.

This method of receiving arguments allows a Miva Script program to process an HTML form submitted with a METHOD of GET.

If a variable name is submitted without a value, the value will default to the name itself.

Some characters cannot be used safely in arguments passed as a list of name/value pairs, but you can replace them by their URL-encoding. These are the most common such characters:

Character	URL-encoding
Space ( )	+
Plus sign (+) (used to represent itself)	%2b
Percent (%)	%2f
Equal (=)	%3d
Ampersand (&)	%26

Value List

Arguments can also be passed as a simple list of values, separated by plus signs. Miva Merchant Empresa will automatically generate variable names corresponding to these values.

• An example calling a program with arguments using the CGI version of Miva Merchant Empresa:

http://www.server.com/cgi-bin/miva?fruit.mv+black%20cherries+oranges

• An example using the NSAPI version of Miva Merchant Empresa:

http://www.server.com/fruit.mv?black%20cherries+oranges

An example using Miva Merchant Mia:

http://127.0.01/fruit.mv?black%20cherries+oranges

With Miva Merchant Empresa (CGI) arguments are passed using the convention file.mv+arg2+arg3+arg4...; that is, arguments follow the filename and are separated by plus signs (+). With Miva Merchant Empresa (NSAPI) and Miva Merchant Mia the convention is file.mv?arg2+arg3+arg4...; arguments are separated from the filename by '?' and after that and are separated from each other by plus signs (+). In this example, the arguments are black%20cherries and oranges. The notation '%20' is used to represent a space character, because spaces cannot appear explicitly in URLs (see below).

The model given above starts with arg2 because of the way Miva Script counts its arguments. The Miva processor automatically creates two types of variables from these arguments. A single variable, with a numerical value, called nargs is created: this variable contains the number of arguments passed to the program. Secondly, a series of variables called arg1, arg2, ..., argN (where N equals nargs, the number of arguments) is created. Each of these will contain the value of the corresponding argument passed to the program in the URL. arg1 is always the name of the program itself (and therefore nargs is always at least 1). The actual arguments start at arg2. Your program code can then do whatever you need with these arguments.

In the example above:

nargs= 3

arg1= fruit.mv

arg2= black%20cherries

arg3= oranges

The following characters cannot be used safely in arguments passed as a value list, but you can replace them by their hexadecimal equivalents, as indicated in the following table:

Character	Hexadecimal Form
Space ( )	%20
Plus sign (+)	%2b
Minus sign/hyphen (-)	%2d
Tilde (~)	%7e

For example:

http://127.0.0.1/fruit.mv?granny%20smith%20apples+oranges

Note: If you pass a null argument (an argument with no value), Miva Script will readjust the list of argument values to ignore the null argument. For example:

http://www.your_server.com/cgi-bin/miva?fruit.mv++oranges

The first argument after the script name is absent. In this example, 'oranges' will become arg2 instead of arg3.

If a Miva Script program is the target of a FORM's ACTION, the values of fields used in the form will be converted into Miva Script variables with the same names as the fields.

Passing Variables

<MvHIDE>

Summary

<MvHIDE> tags should be used only inside forms. When the form is submitted, the variables and their values are passed to the receiving program (specified by the <FORM> element's ACTION attribute) as name/value pairs (if METHOD is 'GET') or in the standard input (if METHOD is 'POST'). This provides a way to pass variable values to the program called by the form.

<MvHIDE> tags are converted into one or more 'hidden' <INPUT> tags, corresponding to each of the variables var1, var2, var3 specified by FIELDS (required).

<FORM ACTION="..." METHOD="GET|POST">

...

<MvHIDE FIELDS="var1,var2,var3,...">

...

</FORM>

If variable var1 has value x, and var2 has value y (x and y are literals), then:

<MvHIDE FIELDS="var1,var2">

is converted in place to:

<INPUT TYPE="hidden" NAME="var1" VALUE="x">

<INPUT TYPE="hidden" NAME="var2" VALUE="y">

By default, when a Miva Script program calls another Miva Script program (which could be a re-invocation of the same program) the values assigned to variables in the currently running program are not available in the program that is called. Another way of expressing this is to say that the scope of a variable is the currently running program.

As described above, one way to pass variables to a Miva Script program is to include them as name/value pairs on the URL by which the program is called. This isn't always convenient, since you may not know when you construct the URL which values and variables you want to pass. Miva Script provides the <MvHIDE> mechanism to make it easy for programs to pass variables to other Miva Script programs.

Recall that if a Miva Script program is the target of a FORM's ACTION, the values of fields used in the form will be converted into Script variables with the same names as the fields, and these variables and their values will be available in the target program. Normally these fields are visible objects such as text boxes and radio buttons, whose values are entered by the user. HTML also provides so-called 'hidden' form fields: these fields have a name and value like other form fields, but have no visual representation in the browser. Hidden fields can be used to pass variable values to a Miva Script program; <MvHIDE> provides a convenient method of generating hidden fields 'on the fly', when the form is submitted. In general, if you have variables v1, v2, v3, ..., vN whose literal values are x1, x2, x3, ..., xN, then an <MvHIDE> tag of the form <MvHIDE FIELDS="v1,v2,v3,...,vN"> will be converted to the following when the form is submitted:

<INPUT TYPE="hidden" NAME="v1" VALUE="x1">

<INPUT TYPE="hidden" NAME="v2" VALUE="x2">

<INPUT TYPE="hidden" NAME="v3" VALUE="x3">

...

<INPUT TYPE="hidden" NAME="vN" VALUE="xN">

For example, if v1 has the value 6, v2 the value 8, and v3 the value 10, then:

<MvHIDE FIELDS="v1,v2,v3">

Is converted to:

<INPUT TYPE="hidden" NAME="v1" VALUE="6">

<INPUT TYPE="hidden" NAME="v2" VALUE="8">

<INPUT TYPE="hidden" NAME="v3" VALUE="10">

The variables do not have to be originally specified as literals: Miva Script resolves the literal value when it processes the <MvHIDE> tag.

<MvHIDE> has no useful effect if it occurs outside a form.

Note: Variables corresponding to fields that are already part of the form should not also be passed to the receiving program using <MvHIDE>.

Passing Multiple Form Variables of Same Name

When a Miva script is the target of a FORM's ACTION, the variable can still be referenced without qualifier to get a comma-separated list of the multiple responses.

The variable can now be addressed as a one-based array, with each of the values occupying one element.

Example:

<MvIF EXPR="{commalist ne ''}">

<MvASSIGN NAME="expected" INDEX="1" VALUE="value 1">

<MvASSIGN name="EXPECTED" index="2" value="value 2">

<MvASSIGN name="EXPECTED" index="3" value="value 3">

<MvASSIGN name="EXPECTED" index="4" value="value 4">

<MvASSIGN name="EXPECTED" index="5" value="value 5">

<MvASSIGN name="EXPECTED" index="6" value="value 6">

<MvASSIGN name="EXPECTED" index="7" value="value 7">

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

<MvASSIGN NAME="l.count" VALUE="{1}">

<MvASSIGN NAME="l.max" VALUE="{miva_array_max(commalist)}">

<MvWHILE EXPR="{l.count le l.max}">

<MvIF EXPR="{commalist[count] ne expected[count]}">

<MvEVAL EXPR="{'failed at ' $ count $ ', expected '

$ expected[count] $ ', got' $ commalist[count]}">

<MvASSIGN NAME="l.success" value="0">

</MvIF>

<MvASSIGN NAME="count" VALUE="{count + 1}">

</MvWHILE>

<MvIF EXPR="{l.success eq 0}">

Failed

<MvELSE>

Succeed

</MvIF>

<MvELSE>

Please press the button below to start the AddFormVariable test

</MvIF>

<form>

<input name="commalist" value="value 1" type="hidden">

<input name="commalist" value="value 2" type="hidden">

<input name="commalist" value="value 3" type="hidden">

<input name="commalist" value="value 4" type="hidden">

<input name="commalist" value="value 5" type="hidden">

<input name="commalist" value="value 6" type="hidden">

<input name="commalist" value="value 7" type="hidden">

<input SIZE="10" value="Start Test" type="submit">

</form>