Interfacing Forms to Xic Scripts

If a form has an action which is in the format ``action_local_xic scriptname'' then, when the submit button is pressed, the script in scriptname will be called, with the following:

• The preprocessor variable SUBMIT is defined.
• A string-type variable is created for each active form element. The variable name is that of the name field in the form element tag (so these must be unique). The value of the variable is from the value tag of the selected button, or the text of a text-entry object. The variable is defined only if the text object had text, or if a check button was pressed.

Within the script, one must supply the following logic:

• Determine if the SUBMIT preprocessor variable is defined. If yes, than the script was called by a form, otherwise the script was called by a button in the User Menu. Note that this enables the script to initiate showing the form, as will be seen in the example below.
• For each variable, the script must identify if the variable was set, i.e., a text entry had text, and possibly convert the text to a numeric value. The input should also be sanity checked at this point.

Below are the first few lines of an example script which could interface to the example form given above. When the script is selected in the User Menu, it will display the help window containing its input form. When the submit button of the form is pressed, the script will be called again, and the data processed.

#ifndef SUBMIT
# SUBMIT is not defined, so we are being called from the User Menu
# pop-up our input form in the HTML viewer and exit
TextCmd("help spform.html")
Exit()
#endif

# We are being called from the form (SUBMIT is defined)
# First check the option menu return.  The entries are digits, which must
# be converted from text strings to real values
#
if Defined(opmenu)
    num = ToReal(opmenu)
else
# This should never fail, since the option menu always has a selection
    ShowPrompt("number of turns unknown")
    Exit()
end

# Next check the return from a text entry object.  Exit if the variable
# is undefined (text input empty), or the result is a bad numeric value
#
if Defined(pwidth)
    width = ToReal(pwidth)
    if (width < 0)
        ShowPrompt("Bad input (< 0) for width: ", width)
        Exit()
    end
 
    ShowPrompt("width unknown")
    Exit()
end

(check other input variables)
(perform calculations/operations)
Exit

This is typical boilerplate for a form-entry script.