{INCLUDE _LOGOS_C.HTM}

mv/WEB
Syntax Documentation

Documentation for build 2.0.0.116

June 22, 1998

mv/BASIC Syntax Statements

The following statements are added to the mv/BASIC language for use with the mv/WEB environment. In order to use any of these statements, they must appear by themselves without other statements or comments on the same line. You can indent these statements with spaces to improve program readability and formatting.

_PROGRAM

You must define the target location that an mv/WEB application file will be generated to. The syntax of this statement is:

_PROGRAM filename itemname

The PLZ program will generate an application with the name "itemname.HTM" in the specified file. You can use this name to access the generated program through the Coyote web server.

This statement must be the first statement in the program.

_SUBROUTINE

If you are defining an mv/WEB subroutine (as opposed to a main-line program), you use the _SUBROUTINE statement to tell the PLZ program the file and name to generate. The syntax of this statement is:

_SUBROUTINE filename itemname {parameter{,parameter...}}

The PLZ program will generate an application subroutine with the name "$itemname.HTM" in the specified file. You can use this generated subroutine as the target of a _CALL statement. You cannot access these subroutines directly from the web but only by calling it from an mv/WEB application.

This statement must be the first statement in the subroutine.

_INCLUDE

You can use the _INCLUDE statement to include source code from other files.

_INCLUDE FILE filename itemname
_INCLUDE HOST hostpath
_INCLUDE DSG dsgname dsgpath

You should use the _INCLUDE syntax instead of the base system INCLUDE statement if the included item has any mv/WEB specific statements.

_CALL

You can use the _CALL statement to call an external mv/WEB subroutine. The syntax of this statement is:

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

You can use this command to call external mv/WEB subroutines. The first parameter can either be the name of the subroutine enclosed in quotes, or an mv/BASIC variable or expression that contains the subroutine name.

_GOSUB

You can use the _GOSUB statement to call a local subroutine. The syntax of this statement is:

_GOSUB label

You should use the _GOSUB statement instead of the system GOSUB statement in any case where the calling subroutine contains any mv/WEB specific statements.

_RETURN

You can use the _RETURN statement to return from an external mv/WEB subroutine or from an internal subroutine that was called with the _GOSUB statement. The syntax of this statement is:

_RETURN

_PVAR

The _PVAR statement is used to define a variable or list of variable as persistent for the application. When a variable is defined as persistent, the mv/WEB environment will maintain the value of the variable across mv/WEB subroutine calls and page calls. The syntax of this statement is:

_PVAR variable{,variable...}

_CVAR

The _CVAR sttement is used to define a common variable or list of variables. Common variables are always persistent for the application. If you define mv/WEB common variables, these variables will be shared between the main-line application and mv/WEB subroutines. The syntax of this statement is:

_CVAR variable{,variable...}

It is good coding practive to create a single item with _CVAR definiations and let all application programs and modules _INCLUDE this definition item. This makes it easier to keep common variables in sync as an application is developed.

_FILE

The mv/WEB environment does not allow open file variables to be stored in persistent or common variabled. You can use the _FILE statement to declare a file that mv/WEB is to open for you. The syntax of this statement is:

_FILE filename variable
_FILE DICT filename variable

Use of this statement is a convenience only. It is actually more efficient for you to open data files to a local variable when you need to use them then it is to use the _FILE statement.

_PAGE

This statement is used to invoke an HTML page that will be created and displayed to the user. The mv/WEB environment will save all persistent and common variables, transmit the page to the user, and then wait suspended until the user submits the page. The syntax of this statement is:

_PAGE FILE filename itemname
_PAGE HOST hostpath
_PAGE DSG dsgname dsgpath

_TIMEOUT

The default behavior for the mv/WEB environment is for application state information to be maintained for 2 hours from the last page access. This statement allows you to adjust this amount of time on a page by page basis. The syntax of this command is:

_TIMEOUT "hh:mm:ss"
_TIMEOUT variable

mv/BASIC Statements with Limitations

The following mv/BASIC statement are either not usable, or have limitations in the mv/WEB environment.

Variable Declarations

You cannot use:

Dimensioned arrays as _PVAR persistent variables
Dimensioned arrays as _CVAR common variables
Standard mv/WEB COMMON statements

You can use NAMED COMMON. Using NAMED COMMON will not interfere with mv/WEB or Coyote, but there is no persistence support, so use of NAMED COMMON can get complicated.

Non string-data variables as _PVAR or _CVAR variables. Specifically, you cannot use:

File variables
Select variables

Program Construction

You cannot use INCLUDE or $INCLUDE type program constructions where the included source code (or any code that it includes) contains any mv/WEB statements.

External Subroutines

You can call external mv/WEB subroutines with the CALL statement provided that the external subroutines:

Use COMMON in a way that does not interfere with Coyote
Execute within a short timeframe appropriate for Web interaction
Executes and return without exiting to TCL
Not attempt to set system locks that are not cleared before the web page transaction completes
Not call any mv/WEB statements

Internal Subroutines

You can call internal subroutines with GOSUB and RETURN provided that:

The internal subroutine does not use any mv/WEB statements
You cannot mix GOSUB/RETURN with _GOSUB/_RETURN. If you call a subroutine with GOSUB, then it must return with a RETURN. Likewise, if you call a subroutine with _GOSUB, then it must return with an _RETURN statement.

Executing Commands

You can execute external mv/WEB commands with the mv/WEB EXECUTE command provided that:

The execute will complete within a short timeframe appropriate for Web interaction
The executed command will return and not log to another account
Not attempt to set system locks that are not cleared before the web transaction completes
Not call any mv/WEB statements

When Variables are Cleared

Variables that are not defined as persistent or common with _PVAR or _CVAR statements will be lost whenever your application program or subroutine encounters any of the following statements:

_PAGE
_CALL
_GOSUB
_RETURN

mv/WEB Run-Time and Compile-Time Limiations

Because of the nature of the mv/WEB environment, there are some limitations as to the number of variables, HTML insertion points, etc.

You can include a maximum of about 490 HTML insertion points in a page
You should try to limit the number of _PVAR and _CVAR variable definitions to several dozen. While it is possible to have several hundred (or even thousand), performance issues can occur. If you need large numbers of data elements, you can use dynamic arrays and mv/WEB does handle these efficiently.
HTML forms can have a very large number of <input ...> fields and the processing should remain efficient even for more than 100 fields per page. Of course, network traffic may start to become an issue for public internet usage if you pass too much data to and from the browser.
It is possible to hit compiler and run-time limitations. These may be platform dependent, but can include:

Too large compiled object code size.

_PAGE references can generate a lot of in-line code if there are a lot of HTML insertion points or HTML FORM <input ...> fields
_CALL references with large parameter lists can generate a lot of in-line code

Too many variables

Some MV implementations may have global and local limits on the number of declared variables.

Pick/64+ is know to limit this to 3000 common variables and 3000 local variables including dimensioned array elements. mv/WEB and Coyote together use most of this allotment, so you application should try to keep the number of _PVAR and _CVAR variables low
Other MV environment seem to have much higher limits if they are limited at all.

Too deep return stack

Whenever a _CALL, _GOSUB, or _RETURN statement is executed, the Coyote web server will recursively call itself adding one internal gosub and two external calls to the system return stack. To avoid run-time limtations, try to avoid:

using _CALL and _RETURN statements that do not actually invoke web pages.

This limitation should not be an issue for most applications that do not accidentaly recursively call themselves.

mv/WEB Syntax Documentation