Modular Software - Home PicLan-IP - Home

mv/WEB Overview

Documentation for build 2.0.0.118
August 21, 1998

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:

The "Standard" Web Application Programming Environment

The standard web application programming environment is event driven with event occuring whenever a user submits a page.  The web server receives a request for a resource, perhaps with additional HTML form input data along with browser cookie data, and produces a response web document. Once the response is generated, the web server loses all contact with the client (even the TCP/IP network connection is closed).  This can make developing multi-page web applications (weblications) somewhat difficult.

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

The standard terminal environment for data entry application is usually best described as top down.  The application starts at the top and works its way to the bottom.  The current "state" of the application is a combination of it's current execution point and the contents of the applications variables.  Even though a MultiValue terminal application is not usually considered "event driven", there are still events. In this case the user filling in input fields are the events and the code between the mv/BASIC INPUT statements are the event handlers.

Programming the Web "Top-Down"

The mv/WEB processor allows you to program web application top-down. This allows you to easily transition from the PRINT/INPUT terminal environment to the page at a time web environment without having to totally re-invent your application program logic.

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:
Your application consists of a number of seperate text documents. The core document is an mv/BASIC source code item that contains standard mv/BASIC source code, extension mv/WEB "statements", and calls to invoke some number of HTML formatted web pages.  This core document is stored as a standard item in a MultiValue data file (or in a HOST or DSG accesssible file) in the same manner as an mv/BASIC source code item is stored. The core source item does not actually contain the HTML documents that the user will see and interact with.  These documents are stored in other MultiValue items (or in HOST or DSG accessible files) and are referenced by the core application source code.  This allows you to write the mv/BASIC source code using standard source editor tools (like the Pick line editor) while using graphical HTML authoring tools (like Front Page or Hot Metal Pro) to design HTML display and entry pages.

Where to Start

The best place to start designing your application is to decide what the user will see.  You want to literally lay out what HTML screens the user will be presented with and what actions control the progression from screen to screen.  Remember that the user is still working with a web application so they are presented with an entire screen of information, they then fill in some number of data entry fields/buttons/checkboxes, and then "submit" the form for further processing.  Your MultiValue application code has complete control over what the end-user sees on their screen and on what action to take when the page is submitted.  Your application code has absolutely no control over the user's screen until they hit a submit button.  This makes the entire data entry process take on a very "batch" processing look and feel.  Fortunately, batch processing is ideal for high latency environments of which the public internet is an excellent example.

After You Layout Your Basic Pages

After you have built simple HTML documents for each step of the application, you can start designing the interactions between these HTML pages and your mv/BASIC application code.  There are a couple of assumptions that the PicLan-IP Web Application Generator makes: In general, you can include two type of insertion operations in each page that you build.

Using HTML form "input" statements

If you wish to pass editable data to the user in a web page, you do this by using html form "input" statements.  There are currently four types of input statements that the mv/WEB processor supports:

Using HTML "submit" Statements

In order for a user to submit an HTML form back to your application for further processing they must select a "submit" form elements.  There are actually two type of elements avaialble for this purpose: Both of these elements have the same functionality

"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

After you have designed your HTML web pages, you are ready to hook them together with application mv/BASIC source code.  This core application is stored in standard MultiValue items in the same way that you would store mv/BASIC source code items.  The core application module(s) consists of a number of elements that augment the mv/BASIC language and tell the PicLan-IP Web Application Generator what is going on.

For detailed documentation on mv/WEB Basic Syntax elements:

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: 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: 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

When you are ready to generate an appliation you should place the core application module in a MultiValue data file.  You should name it with the simple name for the appliation.  This name will become a part of the application's URL.  You should not give the core module an extension and it's name should not start with an underscore character and should not contain periods.  Once you have the core application in place, you can generate the run-time HTML pages with the TCL command:
PLZ FILE filename appname (options)
PLZ HOST path (options)
PLZ DSG dsgname path (options)
This command will create the following additional items in the same file as the core module: Once the application is generated, you only need to setup access to the core appname.HTM document to run the application.

PLZ options include:

Setting up Web Server Access

In order to access the application over the web, you must configure the PicLan-IP web server to point a virtual directory to the 'filename" that the application is generated into.  You do this by setting up an HTTP DIR line in the PLIP.CTRL CONFIG item.
HTTP DIR=*:80 /APP/ FILE APP.FILE
This example assumes that you are generating application into a MultiValue file named APP.FILE.  It is perfectly acceptable to generate multiple applications into a single MultiValue data file.

Accessing IMAGES within the Application

The PicLan-IP Web Application Generator will automatically copy local images files into the application file so that an entire application is self-contained. You do not need to setup any additional web virtual directories to support images.

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

Running the Application

Once the application is generated and the PicLan-IP web server is configured to access it's elements, you access the application by typing the URL of the base page.  In this example, this would be:
http://www.domainname.com/app/custquery.htm
While the application is running, all submit requests will use a action type of "POST" and the actual displayed URL will not change (the post operations always post back to the same URL).  This prevents the user from bookmarking the application part of the way through.

An Overview of Application Organization

The easiest way to setup a large application is to have a single main-line application _PROGRAM that logs the user on by validating a user name and password and then presents the user with a menu.  Other parts of the application are then called as web subroutines using the _CALL statement. As such, the user will access the entire application suite from a single URL.
Modular Software - Home PicLan-IP - Home
© Copyright 1996-1998  Modular Software Corporation.All rights Reserved.