mv/WEB Overview

The mv/WEB processor is a program that is used to convert a top-down MultiValue web application program into a series of event driven web "pages" that are processed by the PicLan-IP Coyote Web Server. This allows MultiValue applications developers to more easily and quickly develop and deploy web applications without having to deal with the low-level intracasies of event processing and persistence.

Additional documentation:

• New Features for build 2.0.0.118
• New Features for build 2.0.0.116
• mv/WEB mv/BASIC Syntax Documentation

The "Standard" Web Application Programming Environment

The underlying problem is one of "persistence".  Persistence is the description of the necessity for the software running on the web server to remember where it is during the execution of a multi-page web application. Most application programs take persistence for granted.  Because a standard MultiValue terminal application runs top-down, persistence is simply the state of the programs variables and the programs current execution location as the program runs.  Web applications do not work like this. The only mechanism for persistence with a web application is to let the web browser store data variables that are maintained from page to page (either in HTML form "hidden input fields" or in browser "cookies"). This environment can make implementing multi-page applications confusing unless an adequate toolkit is available to ease the task of implementing application persistence.

The Top-Down MultiValue Environment

Programming the Web "Top-Down"

The general principal of mv/WEB is that your application can write any standard mv/BASIC code except PRINT and INPUT statements (you can actually use PRINT statements for debugging, but the web user will not see this).  Instead of PRINT statements, you build dynamic web pages to display to the user.  Instead of INPUT statements, the user can fill in HTML form statements on the web pages that you build. The result is an environment that seamlessly integrates page at a time HTML form processing with top-down mv/BASIC applications.

Laying Out Your Application

About storing source code

The mv/WEB processor takes as source documents both mv/BASIC source code and HTML source code.  Both of these document types are simple text documents.  In order to allow for maximum flexibility in where these documents are stores, you actually have three choices of where mv/WEB can read source documents from:

• As items in a standard MV or Pick format data file.
• As text files in an underlying host accessible file system.
This allows hosted PicLan-IP host systems like D3, Universe, and mvBase the convenience of storing source code in NT or Unix directories instead of requiring that they be explicitly imported into Pick.
• As text files in a PicLan DOS Services Gateway accessible file system.
This allows native PicLan-IP host systems like AP/Pro, Mentor PRO, and Sequoia PRO the convenience of storing source code in network directories instead of requiring that they be explicitly imported into Pick.

Where to Start

After You Layout Your Basic Pages

• All web pages will have a single <form> ... </form> structure
• If you use a web page that does not have a submittable form, then that page is a "dead end".  This means that the page has no way of linking back to the running of the web application.  You should use these pages for the final display page or for non-recoverable errors that require the user start over.
• Web pages cannot have multiple <form> areas.
• The <form> tag should not have a "target" parameter
• You can include a target parameter if you need to switch between secure and non-secure servers.  More on this is documented in the PicLan-IP SSL redirector documentation that is currently under preperation.
• The <form> tag must always run with method set to "post".  If you leave out the method tag, mv/WEB will add it for you.  If you set the method tag to something other than post, then mv/WEB will change the tag to post.
• All web pages should have at least one "submit" button or submit clickable image.
• It is perfectly acceptable to have several submit buttons and your mv/BASIC application code can easily test to see which button was pressed.
• Web pages should not have standard <a href=...> ... </a> links. If you include a standard HTML hypertext link and the user follows it, they will not be able to return to the web application.  Use "submit" buttons and clickable images to allow the user to traverse from page to page.
• You can use JavaScript to make hypertext links "submit" the current page.
• HTML forms should not have any hidden input fields.  The mv/Web generator will add a single hidden input field.  This is all that is required to implement as many "persistent variables" as you wish.
• JavaScript programmers can add additional hidden input fields as desired.
• The web pages must not have a PicLan-Ip/BASIC section.  You can include PicLan-IP active content insertion points into the page, but your running MultiValue application code is stored in the main-line core document and not with each page.
• If you use insertion points, mv/WEB assumes that you are using vertical bar characters | | as insertion delimiters.

• You can include HTML form elements including:
• Text input boxes
• Text password input boxes
• Select menus
• TextArea multi-line text boxes
• Check boxes
• Radio Buttons
• Submit Buttons
• Clickable images
• You can include standard PicLan-IP document insertion points using your core document variables and computation results.

Using HTML form "input" statements

• Text input boxes
• Text passwork input boxes
• Select menus
• TextArea multi-line input boxes
• Check Boxes
• Radio Buttons

Text Input Boxes

Text input boxes are bi-directional edit fields that can be used to both display data from mv/BASIC variables and to acquire data from the user and store those elements into mv/BASIC variables.

When you define a text input form field, you use the name of an mv/BASIC variable or dynamic array reference as the name of the form field. Examples of this in HTML source format would be:

<input type="text" size="30" name="D">

<input type="text" size="30" name="X&lt;12,4&gt;">

The first example will setup an input field that edits the mv/BASIC varaible 'D'.  The second example edits the mv/BASIC dynamic array reference 'X<12,4>'.  Note that the raw HTML code will "quote" delimiter character like '<' and '>' (into &lt; and &gt;).  If you use an HTML editor like Front Page to create your HTML documents, you should be able to type variable names in the 'X<12,4>' format and the HTML editor should quote this for you.

The behavior of text input boxes is that the value of the specified variable or dynamic array reference will be used as the initial value for the text input field when the HTML page is displayed.  The user can then edit this value and the new value will be stored into the same mv/BASIC variable or dynamic array location when the form is submitted back to the server.

Text input boxes support several "options" that control formatting. You can use text input fields such as:

<input type="text" size="30" name="D" conv="D4/">

This statement will apply an OCONV(D,'D4/') conversion to the data before it is presented to the user and an ICONV(D,'D4/') to the data that the user types in before it is presented back to your mv/BASIC application code.  You typically use these functions for handling dates and money input fields.

You can also specify iconv="..." and oconv="..." seperately to allow for different conversion strings for input and output operations. You cannot use the iconv/oconv and conv syntaxes with the same input field.

Text Password Boxes

Text password fields are identical to text fields with the exception that the user will see asterisks echo instead of seeing the editable data.

TextArea Controls

Test area controls are input fields that are used for multi-line text data entry and editing.  mv/Web processes these fields with the following syntax:

<textarea name="X&lt;12&gt;" ...>
</textarea>

If the mv/BASIC variable specified in name is a simple variable, then the textarea box will manipulate a multi-attribute Pick variable with one attribute per line.  If the mv/BASIC variable specifies an attribute extraction, then multiple values will be manipulated.  If the mv/BASIC variable specifies a value extraction, then multiple sub-values will be manipulated.

Conversion operators are not supported on TextArea controls.

Select Controls

Select controls allow a user to select one or more elements from a drop-down list of selections.  The format of mv/Web Select controls is:

<select name="X Y" ...>
</select>

The first variable name contains a list of text lines that are used to populate the select control.  This list can be multi-attribute, multi-value, or multi-sub-value depending on whether a simple variable or dynamic array expansion is specified.

The second variable contains a related set of multiple attribute, value, or sub-value entries that are used to specify which select elements are selected.  This arrays contains integer numbers that relate to the first variables elements.  An example of building these elements would be:

X<1> = 'Line 1'
X<2> = 'Line 2'
X<3> = 'Line 3'

Y<1> = 1
Y<2> = 3

The page is then called with a select control:

<select name="X Y" MULTIPLE>
</select>

When this page is called, "Line 1" and "Line 3" will start highlighted. After the page is submitted, the variable Y will contain a multi-attribute dynamic array of the indexes of the lines that are highlighted.  The variable X will not be modified by this operation.

Check Boxes

Check boxes give you the ability to ask true/false questions of the user. A checked box is true ('1') and a non-checked box is false ('0').

When you define a checkbox input form field, you use the name of an mv/BASIC variable or dynamic array reference as the name of the form field. Examples of this in HTML source format would be:

<input type="checkbox" name="D">

<input type="checkbox" name="X&lt;12,5&gt;">

The first example will setup an input field that is based on the mv/BASIC varaible 'D'.  If the value of the variable 'D' evaluates to "true" then the checkbox will start checked.  Otherwise, the checkbox will have an initial state of cleared.  After the user submits the data entry screen, the variable will have the value of '0' or '1' depending on whether the checkbox is clear or checked.  You can also use dynamic array references to refer to checkbox input fields.

Radio Buttons

Radio buttons allow you to create a fixed number of possible input values. The user can select a single button from a group.  Each button has a value.  When the HTML page is first displayed, the radio button that has a value that matches the associated mv/BASIC variable or dynamic array reference will be checked.  After the HTML page is submitted, the mv/BASIC variable or dynamic array reference will contain the value associated with the checked button.

When you define a group of radio buttons, you use the name of an mv/BASIC variable or dynamic array reference as the name of the form field. You setup a "value" that is the value associated with a particular button. To create a grouping of associated buttons, you assign the same mv/BASIC variable name or dynamic array reference to each button in the group. Examples of this in HTML source format would be:

<input type="radio" name="D&lt;40&gt;" value="0"> 0-users <br>
<input type="radio" name="D&lt;40&gt;" value="8"> 8-users <br>
<input type="radio" name="D&lt;40&gt;" value="16"> 16-users <br>

This example will assign the mv/BASIC dynamic array reference the values of 0, 8, or 16 depending on which button is checked.  The initial value for the button will depend on the starting contents of 'D<40>'. If the starting contents are 0, 8, or 16, then the appropriate button will be checked. If the starting contents are otherwise, then no button will be checked.

Using HTML "submit" Statements

• "submit" buttons
• "clickable" images

"submit" buttons

Your HTML form can have any number of "submit" buttons that allow the users to perform various tasks.  Each of these submit button has a unique mv/BASIC variable name or dynamic array reference associated with it. If the user presses one of these buttons, your application code will resume control with the variable or dynamic array reference associated with the pressed button set to '1'.  Variables or dynamic array references for other button that were not pressed are set to '0'.  This allows you application code to easily test to see which button was pressed.

An example of the HTML source for a "submit" button is:

<input type="submit" name="CONT" value="Continue">

This example will set the mv/BASIC variable 'CONT' to '1' if the user presses the button labeled "Continue".

"clickable" images

Your HTML form can also have any number of clickable images.  These behave exactly the same way as submit buttons, but because they are graphics elements, they give you more flexibility in page appearance.  Again, each image should have a unique mv/BASIC variable name or dyanmic array reference associated with it.

An example of a clickable image in HTML source would be:

<input type="image" name="BACK" src="IMAGES/LEFT.GIF"
     alt="Back" align="bottom" border="0" width="32"
     height="32">

This example will set the mv/BASIC variable 'BACK" to '1' if the user clicks on the image LEFT.GIF.

Extentions for JavaScript Programmers

Creating HTML Form Fields that mv/Web Ignores

If you create an HTML form field with a name that begins with an underscore, the mv/Web generator will remove the underscore but otherwise ignore the tag passing it through to the output page.  This allows you to create input fields that are your responsibility to maintain with a minimum of syntax.

Naming HTML Form Fields

If you are writing client-side JavaScript code, the mv/Web generator will name HTML form fields as integer number (1, 2, 3, etc.).  mv/Web uses these short names to minimize network transmission size so that your web applications runs with maximum efficiency. Unfortunately, this can make referencing these fields from JavaScript functions somewhat inconvenient.

To help you with JavaScript coding, you can override the default behaviour of mv/Web and specify your own field names with the following syntax:

<input type="text" name="VAR1 FName" ...>

The mv/Web generator will use VAR1 as the mv/BASIC variable name to manipulate and call the field FName when generating the page. This allows your JavaScript code to reference FName when referring to this HTML form field.

All mv/Web supported HTML form fields include this support:

<input type="checkbox" name="VAR FName" ...>
<input type="submit" name="VAR FName" ...>
<input type="text" name="VAR FName" ...>
<input type="password" name="VAR FName" ...>
<input type="textarea" name="VAR FName" ...>

The clickable image control can have two equivelent syntaxes:

<input type="image" name="VAR" alt="FName" ...> or
<input type="image" name="VAR FName" ...>

These two syntaxes will generate the same HTML page.

Select boxes use the syntax:

<select name="VAR1 VAR2 FName" ...></select>

Radio buttons are supported with the syntax:

<input type="radio" name="VAR Fname" ...>

You are required to insure that all radio buttons in the group use the same VAR FName coding so that the group is maintained as a group.

Writing the Core Application Module

For detailed documentation on mv/WEB Basic Syntax elements:

• Detailed mv/WEB Syntax Documentation

Defining a module as a main-line PROGRAM or SUBROUTINE

The first line of your application source code item should be:

_PROGRAM destfile destname

or

_SUBROUTINE destfile destname {parameter{,parameter...}}

The PicLan-IP Web Application Generator will store the resulting web application in a MultiValue data file.  You must specify a file and item-id to store the destination application.  When a main-line _PROGRAM is defined, the application URL page will get the name that you specify in the _PROGRAM statement with .HTM appended to the end.  If you are defining a _SUBROUTINE module, this code is not directly referenceable from the web but must be _CALLed from an _PROGRAM application.  Subroutines may have a parameter list to pass data to and from subroutines.

Defining variables

When you write your core application, you will first need to define three types of mv/BASIC variables:

• "Persistent" variables
• "Common" variables
• "File" variables for open MultiValue data files

In addition, you can use any number of temporary mv/BASIC variables without defining them.  These variables will be purely local to your mv/BASIC core application program and will reset to "unassigned" whenever an HTML page is called.  You can use either local application variables or defined persistent variables to pass data to HTML pages.

Persistent variables

A persistent variable is a variable that will maintain it's value for the life of the application's execution.  You use persistent variables for all storage elements that need to exist across HTML page calls. You can store any legal MultiValue string element in persistent variables including dynamic arrays.  You cannot declare the following elements as persistent variables:

• Dimensioned arrays
• File variables
• Select variables

If you declare a persistent variable in a _SUBROUTINE module, these variable values will be initialized to a null string whenever the subroutine is called.

You should also try to keep the number of persistent variables to a "reasonable" level.  The PicLan-IP Web Application Generator saves the contents of persistent variables by storing them in a workfile (WWW.CTRL,APP.STATES) when every HTML page is called.  The larger the persistent variables size is, the more overhead there will be on the Pick host.  If your persistent variables are less than 10K in total string size, this should not be a concern to you.

Persistent variables are defined by entering the following line at the top of the core source code document:

_PVAR variable{,variable}

You can define multiple mv/BASIC variables on a single line or you can use multiple _PVAR lines within a single application.

Common variables

A common variable is a special-case persistent variable that is shared between main-line and subroutine modules in the same way as COMMON is declares in a standard mv/BASIC application.

Common variables are defined by entering the following line at the top of the core source code document:

_CVAR variable{,variable}

You can define multiple mv/BASIC variables on a single line or you can use multiple _CVAR lines within a single application.  If you use common variables to pass data between main-line programs and subroutines, it is your responsibility to insure that the number of variables and order of variables defined in common matches.

Local variables

Local variables are no longer defined as of version 2.0.0.115.  This means that you should remove _LVAR statements from any existing PicLan-IP web application modules.  One behavior difference that may impact existing programs is how local variables were initialized.  In older releases, _LVAR variables would be initialized to null strings.  With 2.0.0.115, local variables will start out as "unassigned" and you need to explicitly set their values or else the run-time web server will abort on a "unassigned, zero used" error.

File variables

You have two choices of how to allocate file variables within your core application module.

You can manually open MultiValue files with the OPEN statement each time that you need to access the file.  Remember that the file variable will be erased whenever you call an HTML page, so you will have to re-open your data files after each HTML page is called.

You can let the PicLan-IP Web Application Generate open data files for you by using the _FILE tag:

_FILE variable file_name

This will cause the generated programs to automatically open the specified file each time the core application is entered.

The _FILE command is intended as a convenience.  It is actually much less efficient that manually opening files as they are needed because the files will be opened every time that a page is submitted even though you may not need to use the files every time.

You can specify multiple _FILE lines to open multiple files.

Calling HTML Pages

You invoke HTML pages by including a _PAGE line in your source document:

_PAGE FILE file_name item_name
_PAGE HOST host_path
_PAGE DSG dsg_name dsg_path

The three formats of the _PAGE command allow you to store your HTML documents either in MultiValue data files, or in host directories accessible either through host file access calls (for Unix and NT host) or PicLan DSG calls (for native hosts).

What happens when you call a page

When you call an HTML page, any insertion points that you have in the page will be resolved.  This allows you to build mv/BASIC variables that will then be merged with |...| merge points in the page.  You should define these varaibles as either persistent or local variables so that they will be passed successfully to the called page.

Next, any HTML form input fields are setup with their initial values based on the values in their corresponding mv/BASIC variables or dyanamic array references.  The page is then transmitted to the user.

After the user processes the page and selects a submit button or clickable image, control is returned to the application.  The first step that occurs is that all of the HTML form input fields in the application are read into their corresponding mv/BASIC variables or dynamic array references. Once the input fields have been read, control is passed back to your application code.

Deciding what to do after a page returns

After an HTML page has been called, if the user clicks on a submit button or clickable image, control will return to your application.  You can test for which button or image a user clicked on by simply testing the associated variable or dynamic array reference for the value of '1':

BEGIN CASE
   CASE BACK
      ... the user hit the back button
   CASE CONT
      ... the user hit the continue button
END CASE

You can also access the contents of HTML input text boxes, check boxes, and radio button by simply accessing the associated value of the mv/BASIC variable or dynamic array reference.

Calling Web Subroutines

You can call other web application subroutines that are stored in the same application code file by using the _CALL statements as in:

_CALL "subname" {parameter{,parameter...}}
_CALL variable {parameter{,parameter...}}

The subname is the name of the subroutine to call.  With build 2.0.0.116, you now must enclose this subroutine name within quotes.  You can also set the value of a variable to the subroutine name.

Parameters may be either variables or dynamic array references, which pass bi-directionally, or constants or calculations which are passed to the subroutine but do not pass back.  If the specified string contains a quote character or an operator (like :, +, etc.) then the string is assumed to be a one-way parameter.

Calling Local Subroutines

It is permissible to call local subroutines with:

_GOSUB label

This is a new feature of build 2.0.0.116.

Returning from Subroutines

An external or local subroutine returns control to the calling application with the _RETURN statement:

_RETURN

This statement has no parameters and must be placed on a line by itself.

Putting It All Together

PLZ FILE filename appname (options)
PLZ HOST path (options)
PLZ DSG dsgname path (options)

• appname.HTM - an HTML page that is the entry point for the application
• subroutines will generate files with the name $appname.HTM and cannot be called directly
• _appname.INCLUDE - an include item that defines your persistent and local variables
• _appname.HEAD - an include item that processes general entry processing whenever a page is submitted
• _appname.1 - an include item for each _PAGE or _CALL reference
• _appname_PGn.HTM - an HTML page for each _PAGE reference
• copies of local images (typically .GIF and .JPG files)

PLZ options include:

• (Z - expand INCLUDEd module pieces into the main-line generated document. This can make debugging easier because error-message line numbers can be looked at more closely and are not hidden within included items.

Setting up Web Server Access

HTTP DIR=*:80 /APP/ FILE APP.FILE

Accessing IMAGES within the Application

In order for images to be imported correctly, you must be sure to use relative link addresses to images.

Running the Application

http://www.domainname.com/app/custquery.htm

An Overview of Application Organization