MivaScript Guide

MivaScript version: 4.0x
Guide Revision 1.0

This document and the software described by this document are copyright 2002 by Miva Merchant Corporation. All rights reserved. Use of the software described herein may only be done in accordance with the License Agreement provided with the software. This document may not be reproduced in full or partial form except for the purpose of using the software described herein in accordance with the License Agreement provided with the software. Information in this document is subject to change without notice. Companies, names and data used in the examples herein are fictitious unless otherwise noted.

Miva Merchant is s registered trademark of Miva Merchant Corporation. MivaScript, MivaScript Compiler, Miva Merchant Order, Miva Merchant, Miva Merchant Mia, Miva Merchant Empresa, the Miva Merchant "blades" logo, Miva Merchant Engine, and Miva Merchant Virtual Machine, are trademarks of Miva Merchant Corporation. Windows is the registered trademark of Microsoft Corporation. All other trademarks are the property of their respective owners. This document was developed and produced in San Diego, CA, USA.

MIVA MERCHANT CORPORATION WILL NOT BE LIABLE FOR (A) ANY BUG, ERROR, OMISSION, DEFECT, DEFICIENCY, OR NONCONFORMITY IN MERCHANT OR THIS DOCUMENTATION; (B) IMPLIED MERCHANTIBILITY OF FITNESS FOR A PARTICULAR PURPOSE; (C) IMPLIED WARRANTY RELATING TO COURSE OF DEALING, OR USAGE OF TRADE OR ANY OTHER IMPLIED WARRANTY WHATSOEVER; (D) CLAIM OF INFRINGEMENT; (E) CLAIM IN TORT, WHETHER OR NOT ARISING IN WHOLE OR PART FROM MIVA CORPORATION'S FAULT, NEGLIGENCE, STRICT LIABILITY, OR PRODUCT LIABILITY, OR (F) CLAIM FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES, OR LOSS OF DATA, REVENUE, LICENSEES GOODWILL, OR USE. IN NO CASE SHALL MIVA MERCHANT CORPORATION'S LIABILITY EXCEED THE PRICE THAT LICENSEE PAID FOR MERCHANT.

MS1005-01 (Rev. 1.0) MivaScript 4.0x

Table of Contents

MivaScript Guide

MivaScript Tags List

Introduction

Expressions

Operators

Variables

Built-In System Variables

Functions

Built-in Functions

Assignment and Evaluation Tags

Configuration and Function Tags

Localization Tags

Database Tags

Email Tags

External File Tags

Flow Control Tags

HTTP and Commerce Server Tags

MivaScript Tags List

<MIVA>

<MvADD>

<MvASSIGN>

<MvASSIGNARRAY>

<MvCALL>

<MvCALLSTOP>

<MvCLOSE>

<MvCLOSEVIEW>

<MvCOMMERCE>

<MvCOMMERCESTOP>

<MvCREATE>

<MvDELETE>

<MvDIMENSION>

<MvDO>

<MvELSE>

<MvELSEIF>

<MvEVAL>

<MvEXIT>

<MvEXPORT>

<MvFILTER>

<MvFIND>

<MvFUNCTION>

<MvGO>

<MvHIDE>

<MvIF>

<MvIMPORT>

<MvIMPORTSTOP>

<MvLOCALIZED>

<MvLOCALIZED-TEXT>

<MvLOCALIZED-TOKEN>

<MvLOCKFILE>

<MvMAKEINDEX>

<MvMEMBER>

<MvOPEN>

<MvOPENVIEW>

<MvPACK>

<MvPOP>

<MvPOPDELETE>

<MvPOPSTOP>

<MvPRIMARY>

<MvQUERY>

<MvREINDEX>

<MvREVEALSTRUCTURE>

<MvSETINDEX>

<MvSKIP>

<MvSMTP>

<MvUNDELETE>

<MvUPDATE>

<MvWHILE>

<MvWHILESTOP>

Introduction

MivaScript programs are HTML documents that also contain tags (commands) from the MivaScript programming language. MivaScript is a server-side scripting language that is implemented by the Miva Merchant Virtual Machine, rather than by the browser. By contrast, a client-side language, such as JavaScript, is implemented by the browser. MivaScript programs are called scripts, active documents, or simply documents. MivaScript tags correspond to typical programming language constructs such as assignment statements, conditional expressions, loops, and input/output statements, as well as MivaScript's special database, mail, commerce, configuration, and external database functionality.

MivaScript 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. MivaScript tags can be freely mixed with HTML tags.

MivaScript programs are compiled by the MivaScript Compiler, then run under the Miva Merchant Virtual Machine. (Either the Windows desktop version, Miva Merchant Mia, or the server version, Miva Merchant Empresa.)

When a browser requests a MivaScript document (.mvc), the Miva Merchant Virtual Machine executes the contents of the document before passing it on to the browser.

About This Guide

This MivaScript Guide contains the names and syntax for tags, variables, expressions, literals, operators, arrays and structures, functions, and system variables, with only brief descriptions, if any. For detailed information, examples, full descriptions, and explanations, see the MivaScript Reference Guide or the MivaScript User's Guide at http://www.miva.com/support/docs/api.

Expressions

Expressions can contain variables, literal values (text or numbers), functions, and operators, which indicate how the other components in the expression are to be evaluated.

• See "Variables" and "Built-In System Variables"
• See "Operators".
• See "Functions" and "Built-in Functions"

In general, MivaScript expressions are used to:

• create a new value. (See "<MvASSIGN>".)
• evaluate an expression's logical "truthfulness."

  For example, an expression can evaluate a condition, and take an action based on the results. See "Flow Control Tags."

  • Any expression that is equal to 0 (zero) or a null string is considered false.
  • All others are considered true. True is often represented by 1 (one).

Expression Syntax

Expressions are enclosed within double quotes, and when it is an attribute value, curly brackets must immediately precede and follow the quotes.

Spaces

Inside an expression, spaces are not significant (that is, they do not affect how the expression is evaluated) except in the following ways:

• If an operator contains characters that can also occur in a variable name, then it must be separated from the other components by one or more spaces.
• Spaces inside literal strings are significant.

Literal

An expression consisting of only a literal string does not require curly brackets. If a literal string is inside curly brackets, it must be surrounded by single quotes. For example:

Null

You should represent a null string in an expression as two single quotes (' '):

The expression {0 EQ ' '} ("does zero equal the null string?") returns 1 (true).

See the MivaScript Reference Guide for detailed descriptions and examples of expressions containing literal text, numbers, variables, functions, and operators.

Operators

Order of Precedence

You can also override the built-in precedence by surrounding sub-expressions with parentheses, '(' and ')'.

1. Sub-expressions inside parentheses, '(' and ')', are evaluated first.
2. Each operator is assigned a precedence, and if there is a choice of which operator to evaluate first, the operator with higher precedence is evaluated.
3. If two operators have the same precedence, the left most one is evaluated first.

Operator Precedence

From highest to lowest MivaScript Operators:

• NOT
• ROUND, CRYPT, MOD, SUBSTR, POW
• /, *
• +,-,$
• IN, CIN, EIN, ECIN, EQ, NE, GE, LE, LT, GT
• AND, OR

Arithmetical Operators

A minus sign can precede a literal number to make it negative (for example, -3.14), but, otherwise, must be used strictly as a binary operator: {-x} evaluates to the literal string
'-x'; to express the negative of a value, use {-1*x} or {0-x}. Using +, /, or * as a unary operator results in an expression error.

Operator	Name	Description
+	Addition	expr1 + expr2
-	Subtraction	expr1 - expr2
*	Multiplication	expr1 * expr2
/	Division	expr1 / expr2
POW	POWer	expr1 POW expr2 Raise expr1 to the power expr2 Example: 3 POW 4 is 34, or 81. See also the built-in function power().
MOD	MODulu	expr1 MOD expr2 Returns the integer remainder from expr1/expr2 Example: 26 MOD 7 is 5. See also the built-in function fmod(), which returns floating point remainders.
ROUND	Number rounding	number ROUND places Rounds number up or down to places decimal places. Example: 123.45676 ROUND 2 is 123.46 See also the built-in function.

Comparison Operators

These operators are used to compare two numbers or two text strings. In text string comparisons, lowercase letters are considered to be greater than uppercase letters. Two strings are equal only if the case (upper or lower) matches letter-by-letter. These operators all give a value of 1 (true) or 0 (false).

Operator	Name	Description
GT	Greater Than	expr_a GT expr_b Tests whether expr_a is greater than expr_b
LT	Less Than	expr_a LT expr_b Tests whether expr_a is less than expr_b
EQ	EQual To	expr_a EQ expr_b Tests whether expr_a is equal to expr_b Two strings are equal only if the case (upper or lower) matches letter-by-letter.
NE	Not Equal To	expr_a NE expr_b Tests whether expr_a is not equal to expr_b
GE	Greater Than or Equal To	expr_a GE expr_b Tests whether expr_a is greater than or equal to expr_b
LE	Less Than or Equal To	expr_a LE expr_b Tests whether expr_a is less than or equal to expr_b

Logical Operators

These operators are used with 'true' or 'false' expressions. For example:

<MvIF EXPR="{age GE 17 AND age LT 80}">

This expression is true if both expressions '{age GE 17}' and '{age LT 80}' are true.

Operator	Name	Description
NOT	Logical NOT	NOT expr Returns the opposite of expr (if expr is false, NOT expr is true, and vice versa). Notice that this operator is unary: it acts on one expression, not two.
AND	Logical AND	expr_a AND expr_b This expression is true if both expr_a and expr_b are true.
OR	Logical OR	expr_a OR expr_b This expression is true if either of expr_a and expr_b is true.

Text String Operators

MivaScript also supports a number of built-in string functions.

Operator	Name	Description
$	Concatenate strings	expr_a $ expr_b Concatenates (joins) the strings expr_a and expr_b together. For example, {'fred' $ 'flintstone'} would result in 'fredflintstone'.
IN / CIN	Beginning position	expr_a IN expr_b expr_a CIN expr_b Returns the beginning position of expr_a contained in expr_b. For example, {'da' IN 'canada'} returns 5, because 'da' begins at the fifth letter in 'canada'. IN is case-sensitive: it will find matches only if the matched sub-string in expr_b has the same case, letter-by-letter, as expr_a. Use the CIN operator if you want to make your comparison case-insensitive. Notice that if you use literal strings in this expression you have to surround them with single quotes.
EIN / ECIN	End position	expr_a EIN expr_b expr_a ECIN expr_b Returns the end position of expr_a contained in expr_b. For example, {'dia' IN 'canadian'} returns 7, because 'dia' ends at the seventh letter in 'canadian'. EIN/ECIN returns 0 when the left operand is NULL. This fixes backward compatibility with MivaScript v3.57 and earlier "Htmlscript" versions. ECIN is the case-insensitive version of EIN.
CRYPT	Encrypt a string	plaintext CRYPT key Performs a one-way encryption, similar to that provided with the UNIX crypt command. The string plaintext is encrypted using the string key (this string is sometimes called a 'salt'). CRYPT always yields the same result when applied to a particular plaintext and key. FreeBSD applications can take advantage of crypt(3) features.

Bitwise Operators

These operators act on numbers at the binary or 'bit' level.

Operator	Name	Description
BITAND	Bitwise AND	expr_a BITAND expr_b Perform a logical AND on the bits of expr_a and expr_b.
BITOR	Bitwise OR	expr_a BITOR expr_b Perform a logical OR on the bits of expr_a and expr_b.
BITXOR	Bitwise Exclusive OR	expr_a BITXOR expr_b Perform a logical exclusive OR on the bits of expr_a and expr_b (return the number whose bits are equal to 1 in either, but not both, of the original numbers).
BITOC	Bitwise ones complement	BITOC expr Flip the bits of expr (including the 'sign bit'). This operator is unary: it acts on one number, not two. Example: {BITOC 9}. 9 in binary form is '1001'; including the 'sign bit' (left most bit), which indicates that the number is positive, it is '01001'. Flipping these bits gives '10110'. Since the sign bit is now '1', the number is negative. According to the rules of binary arithmetic, '0110' interpreted as a negative number is '-10'.
BITSL	Bitwise shift-left	expr_a BITSL expr_b Shift the bits of expr_a to the left by expr_b places. The leftmost bits are lost, and the rightmost bits are replaced by zeroes.'{23 BITSL 2}' is interpreted as follows: 23 is 00010111 in binary form; shifting these bits left two places gives 01011100, or 92 in decimal format.
BITSR	Bitwise shift-right	expr_a BITSR expr_b Shift the bits of expr_a to the right by expr_b places. The rightmost bits are lost, and the leftmost bits are replaced by zeroes.

Variables

Prefixes and Scope

Prefixes in the variable name define its scope in the current program. The variable scopes available in MivaScript are:

• Local

  (prefix local or l): Scope is only inside the <MvFUNCTION> block.

• Database

  (dbname.database.var or dbname.d.var): Scope is named database.

• System

  (prefix system.varname or s.varname): Used when a built-in system variable or a variable that is generated by an <MvSMTP>, <MvPOP>, or <MvCALL> loop is named.

• Global

  (prefix global or g): Scope is the entire program

If scope is not defined, the Virtual Machine checks to see if a previously scoped variable of same name exists and has scope in current location, in the following order:

• system variable (s.var or system.var)
• local variable (l.var or local.var)
• database variable (d.var or database.var)
• global variable (g.var or global.var or var)
• if no variable var (with any prefix) exists, then, var is created as a global variable

If the variable will be used in an expression, the variable name must start with a letter or an underscore.

Built-In System Variables

System variables are automatically initialized when a MivaScript program begins execution. There are two types of system variables:

• Static system variables

  values are set only when script begins execution.

• Dynamic system variables

  values are set each time they are used in an expression.

All of the time-related variables (except for dyn_time_remaining and globaltimeout) have both static and dynamic versions: the dynamic variables start with the dyn_ prefix. With the exception of recno, all other system variables are static.

Time Variables

CGI, HTTP, and Other Variables

All available CGI environment variables are automatically converted into static MivaScript system variables upon start-up. All HTTP headers are saved in environment variables and therefore are also converted to MivaScript static variables. The availability of environment variables depends on the server software; the availability of HTTP headers also depends on the browser; therefore, not all variables listed here are guaranteed to be available in all circumstances. For more information on HTTP headers and environment variables, consult a CGI reference and/or your server documentation.

Accessibility Codes

Origin:

S: generated by Miva Merchant Virtual Machine, Miva Merchant Mia

E: if available, inherited from environment

H: if available, inherited from HTTP header (via the environment)

Platform:

C: accessible with CGI version of Miva Merchant Virtual Machine

N: accessible with NSAPI version of Miva Merchant Virtual Machine

P: accessible with Miva Merchant Mia

For example, E: C,N means that the variable in question is inherited from the environment and is accessible in the CGI and NSAPI versions of Miva Merchant Virtual Machine.

Variable	Return Value	Accessibility
apitype	Platform: 'CGI', 'NSAPI', or 'Mia' (Miva Merchant Mia)	S: C,N,P
argN	If a list of values is passed to a MivaScript program, argN is the value of the Nth argument on the URL used to call the script. arg1 always contains the program file name. The first argument after the file name will be arg2, and so forth.	S: C,N,P
auth_type	Authentication method user by the server	E: C,N
callerid	Each time a cookie-enabled browser accesses a MivaScript document, MivaScript creates a 32-character cookie that is unique to that browser and URL. The cookie lasts for one year after being set. Cookies can be turned off in Miva Merchant Virtual Machine; contact your server administrator.	S: C,N,P
content_length	Length of any attached (POST) information	E: C
content_type	Type of data for POST	E: C
documenturl	Contains URL of the currently running MivaScript program. This URL also contains the character between the program name and the command line arguments ('+' for NSAPI and Miva Merchant Mia, and '?' for CGI).	S: C,N,P
gateway_interface	Version of CGI used	E: C
globaltimeout	Maximum total number of seconds that this script can execute.	S: C,N,P
http_accept	Comma-separated list of MIME types (type/subtype) that the browser will accept. This list is very incomplete on most browsers.	H: C,N,P
http_accept_charset	Character sets preferred by the browser (other than the default ASCII or ISO Latin-1)	H: C,N,P
http_accept_language	ISO codes for the languages preferred by the browser	H: C,N,P
http_connection	String that browser sends to the server to preserve a TCP connection (also called a "keep-alive" string). Not supported by all browsers and servers.	H: C,N,P
http_cookie	Contents of all the cookies set for the document.	H: C,N,P
http_host	Remote host name (usually same as server_name)	H: C,N,P
http_pragma	Mode client is running under	H: C,P
http_referer	The document that the current document was accessed from.	H: C,P
http_user_agent	Browser name, platform, version, and library	H: C,N,P
mivaversion new in 4.00	Version of the MivaScript language preprocessor (Replaces the previous s.version)	S: C,N,P
miva_defaultlanguage	Retrieves the current default language setting
miva_language	Retrieves the current language setting
miva_sslavailable new in 4.00	Whether OpenSSL is available for use by <MvCALL>	S: C,N,P
nargs	If a list of values is passed to a MivaScript program, nargs is the number of arguments on the URL, including the program file name.	S: C,N,P
path_info	Extra path information in the URL (a directory path that occurs immediately after the name of the CGI program in the URL)	E: C,N
path_translated	path_info, translated to a physical location by prepending the server document directory to its value	E: C
process_id	Currently running process number	S: C,N,P
query_string	Information passed after a URL and a "?" via the GET method	E: C
remote_addr	IP address of remote host	E: C,N,P
remote_host	The domain name of the remote host	E: C,N,P
remote_ident	Remote user name, from servers that support RFC 931 identification	E: C
remote_user	User name associated with protected script, on servers that support user authentication	E: C,N
request_method	GET, POST, or HEAD	E: C,N,P
script_name	Virtual path to CGI script; not mapped locally to actual path	E: C
server_hostname	The name of the server	E: C,N
server_name	Same as server_hostname	E: C,N,P
server_port	Port under which server is running	E: C,P
server_port_secure	Whether the port is secure (boolean)	E: C
server_protocol	Name and revision of protocol used	E: C,N,P
server_software	HTTP server and version number that processed the request	E: C,P
server_url	server_hostname, in URL format	E: C,N
server_version	Version of the server	E: C,N
user_agent	Same as http_user_agent	H: N

MivaScript also allows site administrators to define their own system variables. Check with your administrator to find out whether any have been added to your site.

Functions

• Define functions using <MvFUNCTION> tag.
• Use <MvEVAL> to display the function's returning value.
• Use <MvASSIGN> to return a function's value(s) with no display, and store the function's value.

Passing Variables by Reference

Parameters are variables whose scope is usually the body of the function. But, a parameter may have an optional "VAR" after the variable name, signifying that the parameter would be passed by reference. Any changes to the variable within the function will be reflected in the variable used in calling the function, and any array elements or structure members will be preserved.

For example:

Built-in Functions

Time Functions

Text String Functions

Boolean-valued String Functions

These functions all start with is and return a true (1) or false (0) value depending on the composition of the string. Each of these functions is based on the C language function of the same name, but is applied to the whole string: isdigit(string) will return true if every character in the string is a digit or null, and false otherwise.

Function Name (parameters)	Action
isalnum(string)	Returns true (1) if all characters in string are either alphabetic or digits, and false (0) otherwise.
isalpha(string)	Returns true (1) if all characters in string are alphabetic and false (0) otherwise.
isascii(string)	Returns true (1) if all characters in string are ASCII characters (those with decimal value between 0 and 127), and false (0) otherwise.
iscntrl(string)	Returns true (1) if all characters in string are control characters (those with decimal value between 0 and 31, or 127), and false (0) otherwise.
isdigit(string)	Returns true (1) if all characters in string are digits in the range 0-9, and false (0) otherwise.
isgraph(string)	Returns true (1) if all characters in string are graphic characters (those with decimal value between 33 and 127), and false (0) otherwise.
islower(string)	Returns true (1) if all characters in string are lowercase letters, and false (0) otherwise.
isprint(string)	Returns true (1) if all characters in string are printable characters (same as graphic characters, with the addition of the space character), and false (0) otherwise.
ispunct(string)	Returns true (1) if all characters in string are punctuation characters (non-alphanumeric graphics characters), and false (0) otherwise.
isspace(string)	Returns true (1) if all characters in string are whitespace (space, tab, vertical tab, newline, form feed) characters, and false (0) otherwise.
isupper(string)	Returns true (1) if all characters in string are uppercase letters, and false (0) otherwise.
isxdigit(string)	Returns true (1) if all characters in string are hexadecimal digits (a-f, A-F, 0-9), and false (0) otherwise.

Other String Functions

Function Name (parameters)	Action
asciichar (number)	Returns the character corresponding to number (number must be less than 255).
asciivalue (character)	Returns the ASCII numeric value for character (character must be a single character).
decodeattribute (string)	Returns a copy of string (which is usually a URL) converted from URL-encoded format to ordinary text. This function is the opposite of encodeattribute.
decodeentities (string)	Returns a copy of string in which all HTML entities have been converted to their plain text equivalents (for example, '&lt;' is converted to '<'). This function is the opposite of encodeentities.
encodeattribute (string)	Returns a copy of string (which is usually a URL) in URL-encoded format. Special characters such as space, tilde (~), and the plus sign are converted to hexadecimal %nn format. This function is the opposite of decodeattribute.
encodeentities (string)	Returns a copy of string in which all characters have been converted to their HTML entity equivalents, where applicable (for example, '<' is converted to '&lt;'). This function is the opposite of decodeentities.
gettoken(string, separators, n)	Tokenizes string, using any of the characters in separators as token separators, and returns the nth token. A null string is returned if there is no nth token.
glosub_array( string, search, replace ) (new in 4.00)	Works like glosub(), but search and replace are arrays that are iterated through, each value in the search array found in the string is replaced by the corresponding replace array value.
glosub(string, search, replace)	Global substitution; returns a copy of string in which all instances of string search have been replaced by string replace. (Note: to represent a backslash (\) in replace, use '\\').
len(string)	Returns the number of characters in string.
ltrim(string)	Returns a copy of string with all space characters removed from the left end.
padl(string, length, padcharacter)	Returns a string length characters long, consisting of string padded on the left with as many instances of padcharacter as are needed to make up the full length.
padr( string, length, padcharacter)	Returns a string length characters long, consisting of string padded on the right with as many instances of padcharacter as are needed to make up the full length.
rtrim(string)	Returns a copy of string with all space characters removed from the right end.
substring(string, start, length)	Returns the substring of string, beginning at position start, length characters long.
tokenize( string, replacements ) (new in 4.00)	Returns the string, concatenated with the value of each token contained in replacements. Replacements is an array of structures, each with a token and a value.
Example: <MvASSIGN NAME = "l.replacements" INDEX = "{1}" MEMBER = "token" VALUE = "token1"> <MvASSIGN NAME = "l.replacements" INDEX = "{1}" MEMBER = "value" VALUE = "value"> <MvASSIGN NAME = "l.replacements" INDEX = "{1}" MEMBER = "token" VALUE = "token2"> <MvASSIGN NAME = "l.replacements" INDEX = "{1}" MEMBER = "value" VALUE = "works"> <MVASSIGN NAME = "l.tokens" VALUE = "{ tokenize( 'This is a %token1% that %token2%.' , l.replacements ) }">