2. Variables

---

Introduction

A variable is a name that is associated with a value. Because it's helpful to use names that indicate what they're used for, the variable named "age" could have the value 10.

Variable Naming Conventions

In Miva Script, a variable name can consist of the following:

• the letters a through z (upper and lower case)
• the underscore, '_',
• the digits 0 through 9.

Other characters are permitted if they are 'escaped' with a backslash. For example:

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

This evaluates to 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.

Additional Naming Considerations:

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

Valid Naming Conventions:

<MvEVAL EXPR="{_13user}">

<MvEVAL EXPR="{user_13}">

<MvEVAL EXPR="{g.user_13}>

<MvEVAL EXPR="{g.13_user}">

&[13_user];

&[g.13_user];

InValid Naming Conventions

<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 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 assign a variable a value in two ways:

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

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

<MvEVAL EXPR="{var}">

Assigning Values

<MvASSIGN>

Summary

<MvASSIGN> assigns the variable var the value given by expression or literal. <MvASSIGN> is an empty tag.

<MvASSIGN> is also used to assign a value to a specific array, index or structure member. For information about using arrays, see Chapter 5, "Arrays and Structures" on pageÝ24.

Syntax

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

where:

NAME is the name assigned to the variable.

VALUE is the expression or literal for the named variable.

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> attributes NAME and VALUE 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.

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.

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 when the form was submitted.

Note: If a 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.

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 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 the section "Passing Data to a Program".

Prefixes and Scope

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 takes 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:

3. The Miva preprocessor 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.
4. 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.
5. 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.
6. If a global variable g.var, global.var, or var exists then var is interpreted as referring to that variable.
7. If no variable var (with any prefix) exists, then var is created as a global variable.
8. 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:

• Assign new1 the value 10.
• As expected, evaluating new1 displays '10'.
• Since new1 was used for the first time without a prefix, it is a global variable and therefore g.new1 also evaluates to '10'.
• Call the function f1().
• Since new1 is global, it is available inside the function block and (currently) has the same value, 10.
• Assign a new value, 20, to new1.
• Evaluating g.new1 gives '20', indicating that the previous assignment to new1 still referred to the global variable.
• Create a local variable l.new1 and assign it the value 30.
• Evaluating new1 now displays '30'; since a local new1 now exists, new1 without a prefix now refers to that version of the variable.
• The global variable new1 is still available, but you have to use the g. prefix to access it.
• Assign the value 40 to new1.
• Evaluating l.new1 displays '40', indicating that the previous assignment referred to the local version.
• g.new1 (the global variable) still has the value '20'
• 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.

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

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.