<MvFUNCTION>

User defined functions enable you to write re-usable code that can be called on to perform operations at any point in your program, by calling the function within an expression. Even if a function is only called once in your program, moving the code out of the main body of the program and replacing it with a function call still helps to make the program more 'modular', easier to read and debug. A function may output HTML to the screen, perform database I/O or optionally return a value.

Attributes

• NAME: Required, literal function name, defines the name that will be used to call the function.
• PARAMETERS: Optional comma separated list of variable names, assigned without any variable prefix; (parameter variables are always local) and the optionally the keyword var  (variable by reference)
• STANDARDOUTPUTLEVEL: Optional keywords: html, text, compresswhitespace. Specifies what displays in the browser. If empty, output is suppressed unless explicitly output using the <MvEVAL> tag.
  • html: Default. HTML is output to the browser.
  • text: Default. Text (non html) is output to the browser.
  • compresswhitespace: will cause Miva Script to eliminate extra whitespace in the output of Miva Script code. Whitespace is leading and trailing spaces, tabs, and new lines.
• ERROROUTPUTLEVEL: Optional keyword: runtime.  Runtime errors display in the browser. If empty, error output is suppressed. If omitted, defaults to runtime.

Examples

A function can appear anywhere in your program and can be called from anywhere. They do NOT need to be physically encountered by the compiler before calling them. In other words, functions can be forward referenced. Functions can be simple or complex and may even call additional nested function.  Functions can recursively call themselves though care must be taken not to cause an infinite loop.

This function illustrates the basic syntax an adds two numbers together. The function is called within the <MvASSIGN> tag, just like any built in Miva Script function.

<MvFUNCTION NAME="add" PARAMETERS="num1, num2" STANDARDOUTPUTLEVEL="html,text" >
    <mvIF EXPR"{l.num1 OR l.num1}">
        <MvFUNCRETURN VALUE="{ l.num1 + l.num1 }">
    </MvIF>
    <MvFUNCTIONRETURN VALUE = "0">
</MvFUNCTION>

<MvASSIGN name="l.grand_total" value="{ add(l.subtotal, l.shipping_charges) }">

Parameters

Examine the PARAMETERS attribute, above and compare it with the add in the <MvASSIGN > tag;

add(l.subtotal, l.shipping_charges)

The value in l.subtotal  is passed as num1 in the function. The value in l.shipping_charges is passed as num2 as defined by the PARAMETERS attribute. Parameter assignments are done in the order that the arguments appear.

Parameters are variables whose scope is local to the function, that is, their values are not available outside the function, unless you pass the variable by reference using the keyword VAR.

Passing Variables by Reference

When defining a function, a parameter variable may have an optional keyword VAR after the variable name, signifying that the parameter would be passed by reference. Instead of passing the value (or a copy) , the variable itself is passed such that any changes to the variable in the function will be reflected in the variable used in calling the function. This makes passing arrays and structures more efficient preserving all elements members. It also allows you to pass empty array variables that are populated inside the function, instead of returning the array in the <MvFUNCTIONRETURN> tag.

In this example a function passes an empty variable l.products by reference, that is populated inside the function.

<MvASSIGN name="l.count" value="{ Category_Products_Load(l.category_id, l.products) }">

<MvFUNCTION NAME="Category_Products_Load"
            PARAMETERS="category_id, products VAR" STANDARDOUTPUTLEVEL="" >

    Open database files an populate a structured array
    l.products[n]:field1, l.products[n]:field2 etc.

    Return the number of products loaded into the array.
    <MvFUNCTIONRETURN VALUE = "{ l.product_count}">
</MvFUNCTION>

Variable Scope

Local variable defined and used within the function remain local and have no scope outside the function. In the example below, the value of  l.valid is only visible to the function. The same local variable name may be declared outside the function without conflict. Parameter variables are not prefixed because they are by definition local.

Calling Functions

In this example three methods for calling functions are shown.

<MvASSIGN NAME="g.result"
          VALUE="{ IsURL('http://www.google.com/') }">

<MvEVAL VALUE="{ IsURL('http://www.google.com/') }">

<MvIF EXPR="{ IsURL('http://www.google.com/') }">
    This is Google.
<MvELSE>
    Hey, You're not Google...
</MvIF>

Returning from Functions

You may exit a function at any time by using the <MvFUNCTIONRETURN> tag.  Function do not have to return a value. In that case it may be omitted.

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

<MvFUNCTIONRETURN>

Important Considerations

• Function code is not executed until it is called. When the Miva Script file is processed, the function definitions are read, but not actually executed until there is a function call.
• If you pass a text string as an argument to a variable, it should be in single quotes:  func1(1,2,'banana')
• While defining parameters is often helpful, it is not mandatory. For example, you may want to pass or update a 'global' variable directly.
• An <MvFUNCRETURN> tag is optional; you would use it if you needed to return a value to the place where the function was called.
• In addition to parameters defined with the PARAMETERS attribute, you can use 'local' variables that are meaningful only inside the function. These variables must start with the l. or local. prefix. For example:
• Miva Script supplies a large number of built-in functions to help you carry out time, string, numeric, and file system operations. Built-in functions are used in exactly the same way as user-defined functions, but generally run faster than ordinary Miva Script code.
• A recursive function call occurs when a function calls itself. There is a limit on the number of recursive function calls at run-time. This limit is fixed at 23 for Miva Merchant Mia; the default limit for Miva Merchant Empresa is 23, but this can be changed by the server administrator via the maxfunctiondepth setting in the global configuration file.

Function Libraries

This example test a string containing a URL and returns true if correctly formatted. It outputs nothing to the screen itself. It could be used in other programs so it could become part of a larger library of common functions.

<MvEVAL EXPR="{ IsURL('http://www.google.com/') }">

<MvFUNCTION NAME = "IsURL" PARAMETERS = "url" STANDARDOUTPUTLEVEL = "">
    <MvASSIGN NAME = "l.valid" VALUE = "{len(l.url) GT 0}">
    <MvIF EXPR = "{l.valid}">
        <MvASSIGN NAME = "l.valid" VALUE = "0">
        <MvASSIGN NAME = "l.valid"
                  VALUE = "{l.valid OR (tolower(substring(l.url, 1, 7)) EQ 'http://')}">
        <MvASSIGN NAME = "l.valid"
                  VALUE = "{l.valid OR (tolower(substring(l.url, 1, 8)) EQ 'https://')}">
    </MvIF>
    <MvIF EXPR = "{l.valid}">
        <MvASSIGN NAME = "l.valid" VALUE = "{len(l.url) GT 7}">
    </MvIF>
    <MvIF EXPR = "{l.valid}">
        <MvASSIGN NAME = "l.valid" VALUE = "{('..' IN l.url) EQ 0}">
    </MvIF>
    <MvIF EXPR = "{l.valid}">
        <MvASSIGN NAME = "l.valid" VALUE = "{(' ' IN l.url) EQ 0}">
    </MvIF>
    <MvFUNCTIONRETURN VALUE = "{l.valid}">
</MvFUNCTION>

Often functions are be contained in external compiled "library" files and called by your program by evaluating an expression; see <MvEVAL>, or called directly; See <MvDO>.

Notice the square bracket notation that indicates an external file. The brackets can contain a literal file name as show or an expression or variable e.g [ g.module_library_util ]

<MvEVAL EXPR="{ [ 'myfunctions.mvc' ].IsURL('http://www.google.com/') }">

Alternatively, functions contained in external un-compiled "library' files can be included in your program at compile time using <MvINCLUDE>

<MvINCLUDE FILE = "../library/myfunctions.mv">