Variables

This section discusses the use of variables in webMathematica pages. It covers the way that input variables are processed as well as issues, such as scoping, that concern the use of local variables in code that appears in webMathematica pages.

There are three kinds of variables in webMathematica: input variables, page variables, and session variables. Variables that start with $$ are input variables; they are given values from the HTTP request and are cleared when the kernel is cleaned when the page is finished. Variables that do not start with $$ only get values if they are assigned values. These assignments last until the page is cleared if they are page variables, and for the lifetime of an HTTP session if they are session variables.

The details of these variables are now discussed.

Input Variables

Input variables are named to start with $$ and are given values if their names are sent with the HTTP request. They have a special name because it is important to know which are the input variables. In the example below, the input variable $$setting will get the value entered into the input element (because the input element uses the name setting). You can test if a variable has a value with the MSP function MSPValueQ.

<input type="text" name="setting" />

<msp:evaluate>
    If[ MSPValueQ[ $$setting], 
        ....
        ]
</msp:evaluate>

One important decision governs whether the value of input variables should or should not be interpreted. If the actual string value of the variable is suitable for your uses, you should use it. Alternatively, the string value may represent some input to a Mathematica command and it will be necessary to interpret it. For interpretation, it must be something that Mathematica can interpret and the result must pass validation by the security system. If you find that you are starting to modify the security system, you should consider working with the uninterpreted values.

Interpretation of Input Variables

If you want Mathematica to compute with an input variable, it must be interpreted. webMathematica provides various functions to help interpretation. It is important that you use these functions because they make use of the security features. If you try to bypass them, you could compromise the security of your system.

MSPBlock and MSPToExpression are provided to obtain expressions from input variables. This is, of course, completely essential for any type of interactivity. There are two stages to this process: the first stage involves interpretation and the second stage involves validation. Interpretation determines the input to Mathematica, and validation ensures that the Mathematica commands to be executed do not endanger the security of your site.

Interpretation is based on the Mathematica function ToExpression that calls a parser to try to determine input to Mathematica. Valid input for MSPBlock and MSPToExpression can be regular Mathematica input or MathML. The following examples demonstrate input processing with MSPToExpression, showing both Mathematica and MathML input.

First, load the MSP application and then lock down the security system. Security is described in its own section.

In[1]:=

In[2]:=

Now you can use MSPToExpression to interpret some Mathematica input.

In[3]:=

Out[3]=

In[4]:=

Out[4]=

Here the input is MathML.

In[5]:=

Out[5]=

In[6]:=

Out[6]=

MSPBlock provides additional functionality to work with the interpreted value of an input variable. This is described further in the Mathematica Function Reference section.

webMathematica carries out validation to ensure the security of the system. Validation involves checking any input that was sent to the server to see if it is safe to be used in a Mathematica computation. You can find more information on the topic in the Security section.

Interpreted versus Noninterpreted Values

As described above, whenever you work with an input variable, you need to decide how to work with its value. You can work with the noninterpreted value and make choices based upon its setting. (This will be a string.) Alternatively, you can interpret the value so that it can be used for computation in Mathematica. This section gives an example of working with both interpreted and noninterpreted values. If you installed webMathematica as described above, you should be able to connect to this JSP via http://localhost:8080/webMathematica/Examples/SimplifyIntegrate.jsp.

Here is a listing of the form element from the JSP SimplifyIntegrate.jsp.

<form action="SimplifyIntegrate.jsp" method="post">
Input:
<br>
<msp:evaluate>
    integrand = Null;
    If[ MSPValueQ[ $$expr],
        integrand = MSPToExpression[ $$expr]] ;
</msp:evaluate>

<input type="text" name="expr"  size="24" 
          value="<msp:evaluate> MSPValue[ $$expr, "Sin[x]^2"]</msp:evaluate>" />
<br/>
<br/>
<msp:evaluate>
    If[ integrand =!= Null,
        res = Integrate[ integrand,x] ;
        If[ $$simplify === "on", res = Simplify[ res]] ;
        MSPFormat[res,StandardForm]]
</msp:evaluate>

<br/>
<input type="submit" name="btnSubmit" value="Evaluate">
<br/>
Simplify result: 
<input type="checkbox" name="simplify"  
    <msp:evaluate> If[ $$simplify === "on", "checked=\"checked\""]</msp:evaluate>> 
<br>
</form>

In this example, there are two input variables, simplify and expr, that may be submitted with a request. The first of these is not interpreted and is used to select the action to be taken. Only expr is actually interpreted as Mathematica input ($$expr is used inside MSPToExpression). This is necessary because it represents a general Mathematica expression and will be used as input to Mathematica's Integrate function. The setting of the checkbox is carried by the variable $$simplify, and this is tested to see if it has the value "on". There is thus no need to interpret it. In general it is better not to interpret if it can be avoided.

MSPBlock versus MSPToExpression

webMathematica provides two MSP functions for interpreting input variables: MSPBlock and MSPToExpression. This section contrasts and compares them.

MSPBlock is probably the simpler of the two. It offers a compact and simple way to interpret and use the value of an input variable, as shown below.

<msp:evaluate>
    MSPBlock[ {$$expr, $$num},
        Expand[ $$expr^$$num]]
</msp:evaluate>

Remember that the $$expr in the body, used here in an Expand computation, refers to the interpreted value of the input variable $$expr. If the value of $$expr cannot be interpreted or fails a security test, an exception will be thrown. If $$expr has no value, then the MSPBlock will not be evaluated, and a null result will be returned.

An alternative way to interpret input is to use MSPToExpression. This can use page variables to hold the result of interpretation. It is not quite as neat as the use of MSPBlock, but is somewhat more expressive. Here is an example.

<msp:evaluate>
    poly = Null;
    exponent = Null;
    If[ MSPValueQ[ $$expr, $$num],
        poly = MSPToExpression[ $$expr] ;
        exponent = MSPToExpression[ $$num]] ;
</msp:evaluate>

<msp:evaluate>
    If[ poly =!= Null && exponent =!= Null,
        Expand[ poly^exponent]] 
</msp:evaluate>

This example shows how webMathematica extracts the interpreted value of $$expr and stores it with the page variable poly. This is especially useful if you use the interpreted value in a number of different places.

Page Variables

Standard Mathematica programming constructs such as Block, Module, and Function all work in their typical ways with regard to localization and scoping issues. You can find more information on their operation in standard Mathematica references.

You can use variables in Mathematica code inside of msp:evaluate tags; they can store intermediate values and be used for computation. Since these variables will be cleared when the kernel is cleared, it is not important to put these variables into a normal Mathematica program structure such as Module or Block. Consequently these are called page variables.

In the example below the page variable tmp holds the value Null; it then gets the result of calling MSPToExpression on the input variable $$expr. If MSPToExpression was unable to complete its task, for example, because of a security error, it will throw an exception and tmp will still have the value Null. Later, if tmp is not set to Null, you can be certain that the input was processed without problems and you can use it for calculations.

<msp:evaluate>
    tmp = Null;
    tmp = MSPToExpression[ $$expr] ;
</msp:evaluate>

<p>
<msp:evaluate>
    If[ tmp =!= Null, 
        ....
        ]
</msp:evaluate>
</p>

When the page is finished, tmp will be cleared.

Session Variables

If you want to save any values from one request to the next, you can use MSPSessionVariable to make a session variable. These will be stored in the server and can be used in pages that are part of different requests. They use HTTP sessions and so the session variables for one user are not visible to those of another user (just as the shopping cart at an e-commerce site is for one user and is not visible to another).

In the code fragment below there are two variables; savedInput is a session variable, declared with MSPSessionVariable, while xInput is a page variable. In the second evaluation, if xInput has a value, this is added to savedInput.

<msp:evaluate>
    MSPSessionVariable[ savedInput, {}];
    xInput = Null;
    xInput = MSPToExpression[ $$expr] ;
</msp:evaluate>

<p>
<msp:evaluate>
    If[ xInput =!= Null, savedInput = Append[ savedInput, xInput]];
</msp:evaluate>
</p>

You can work with session variables in just the same way that you work with page variables; assigning them the results of calculations and then later retrieving them. The difference is that session variables last after the page is finished.

An example of MSPSessionVariable is shown in Session.jsp.