Installing and Configuring the BASIC Web Utility
UNIX Installation
The BASIC Web Utility works with PRO/5 on any version of UNIX and with any Web server that supports standard CGI. All Web servers support standard CGI, including NCSA, Cern, Apache, and Netscape.
To install the BASIC Web Utility, copy bwu.sh to a CGI directory, or a name recognized as a CGI script (.cgi.). Then, edit the script to start both PRO/5 and the program to run.
|
Parameter |
Description |
|---|---|
|
PGM |
The program to run when PRO/5 starts |
|
MEM |
An optional parameter defining the amount of memory to start the application with. The default is 512. |
|
MAXTRIES |
The number of times the script attempts to start PRO/5 in the event of an error, such as maximum users exceeded. |
|
ERRORLOG |
The file to store messages when MAXTRIES is exceeded. |
|
CONFIG |
The config.bbx file used by the application. |
|
BBEXEC |
The path to the PRO/5 executable. |
Windows 95 and Windows NT Installation
The BASIC Web Utility for Windows 95 and Windows NT is more complicated to set up and configure than for UNIX. As an overview, a windows executable is run from the Web server's scripting directory. This program reads in a configuration file, and executes Visual PRO/5. Visual PRO/5 runs a program that creates the desired Web page, and writes the resultant HTML source to a temporary file. The windows executable then passes the contents of this file back to the browser, and the Web page is displayed.
Because the Windows operating system does not handle stdin and stdout in the same manner as the UNIX operating system, Visual PRO/5 must be run in I/O mode and must utilize temporary files to send information back to the browser. These temporary files are created in the Web server's scripting directory, so Visual PRO/5 must have WRITE permissions to that directory. Additionally, the Web server's home drive must not be disabled via DSKSYN, so that Visual PRO/5 can manipulate these files.
Two separate executables, stdcgi.exe and wincgi.exe, are provided to manage the process. The stdcgi.exe program supports the Standard CGI specification, and is more commonly used. This program should be used when the Web server is running Microsoft IIs or Microsoft Personal Web Server for Windows NT or Windows 95. The wincgi.exe program is used for Web servers that do not support the Standard CGI specification, but rather support the Win CGI specification instead.
When Visual PRO/5 is run on the server, it is executed in the background. This means that SYSWINDOW will not be available for debugging purposes. If Visual PRO/5 encounters an untrapped error while running a program, it will stop running the program and display the error in console mode. Since it is in the server's background, this window will not be visible and it will appear as though both the Client and Web server are hung. In reality, they are simply waiting for the Visual PRO/5 session to complete. Because of this, it is very important that all of the programs trap for unanticipated errors. This is typically done with the SETERR verb.
The first step in configuring the utility set is to copy the appropriate cgi executable (stdcgi.exe or wincgi.exe) to a scripting directory on the Windows Web server, typically called wwwroot/cgi or wwwroot/cgi-bin. The wwwroot directory is the root directory of your Web server and the cgi or cgi-bin directory contains scripts and programs that are executed by the Web server.
Two associated .bat files, stdcgi.bat and wincgi.bat, are text files designed to contain configuration parameters used by the executables to specify howVisual PRO/5 should be run. The .bat file extension is used for historical reasons, and these files are never actually executed as a typical batch file. The appropriate .bat file should be copied to the same directory as the .exe file mentioned above. Both the .exe file and .bat file may be renamed to something more descriptive, such as custquery.exe and custquery.bat. However, they must retain their original extension and the root of the file name must be the same for both files. This allows you to define multiple queries for use with the Web server.
The next step is to edit the .bat file to modify the BBPROG, BBEXEC, BBCONFIG, MEM, BBTERM, and USERID parameters. These parameters are used to tell the cgi executable how to find Visual PRO/5 and what startup options to pass to it. Note that when specifying paths for Visual PRO/5, the configuration file, and the program file, all directories with spaces in their names should be changed to reference the short name. For example, if Visual PRO/5 exists as c:\program files\basis\vpro5\vpro5.exe, the BBEXEC should be set to c:\progra~1\basis\vpro5\vpro5.exe.
|
Parameter |
Description |
|---|---|
|
BBARGS |
Specifies argument so the interpreter. Use this parameter instated of BBCONFIG, BBTERM, MEM, USERID. |
|
BBCONFIG |
Specifies the config.bbx file to be used by Visual PRO/5. The configuration file should have an alias that matches the BBTERM value below. It must also have proper DSKSYNs and a PREFIX that allows Visual PRO/5 to load the BASIC Web Utility programs and the program specified by BBPROG above. |
|
BBEXEC |
Specifies the full path to the vpro5 executable. |
|
BBPROG |
Specifies the program that Visual PRO/5 will run. This program will be responsible for creating the contents of the resultant html page. |
|
BBTERM |
Refers to a terminal alias in BBCONFIG. Often, this has an invisible or minimized mode. Note that some Web servers will not allow a console mode window to activate, regardless of this setting. In this case, debugging must be done with error trapping and logging. |
|
MEM |
Specifies the amount of memory to start the Visual PRO/5 with. |
|
USERID |
Specifies the userid value to use when connecting to a data server. If no Data Server is required, use a dummy value. |
|
TIMEOUT |
Specifies the number of seconds to wait before the stdcgi.exe will forcefully terminate Visual PRO/5. If this parameter does not exist in the parameter list, then stdcgi.exe will wait indefinitely for Visual PRO/5 to terminate on it's own accord. |
Configuration Requirements and Samples after Installation
To use BASIC Web Utility, ensure the following are installed:
-
A Web Server such as Microsoft Personal Web Server (PWS), or IIS (Internet Information Server)
-
Visual PRO/5 revision 2.x
-
The utility set BASIC WEB UTILITY
Visual PRO/5 Configuration
The config.bbx file can be modified to contain only minimal information to get BASIC Web Utility to work. For example, assuming that Web Server, BASIC Web Utility, and Visual PRO/5 reside in different subdirectories on D:\, create a WebConfg.bbx file:
ALIASES=100
FCBS=128
CIBS=128
STBLEN=4096
SETOPTS 00000060000000
PREFIX D:/BBW/ D:/BBW/progs/ D:/BBW/temp/
alias T0 syswindow
DSKSYN A:
DSKSYN B:
DSKSYN C:
DSKSYN E:
…
DSKSYN Z:
In the stdcgi.bat file that was copied to D:\wwwroot\cgi-bin, make the following changes:
set BBPROG=Webtest.bbx
set BBEXEC=d:\basis\vpro5\vpro5.exe
set BBCONFIG=d:\basis\vpro5\WebConfg.bbx
set MEM=1024
set BBTERM=IO
set USERID=dummy
If a shortcut is created for testing purposes, set the Working Directory to D:\wwwroot\cgi-bin because this is where the program will reside. Run Visual PRO/5 with the following command line:
D:\basis\vpro5\vpro5.exe –tT0 –m1024 –cD:\basis\vpro5\WebConfg.bbx
Enter the following program and save it to D:\BBW\progs\ as Webtest.bbx:
0005 SETERR 50
0010 CALL "utcgi.wbb",ENV$,CGI$,ERRMSG$
0020 CALL "uttags.wbb","h1","My First Web Test Program",HTML$
0030 CALL "utsend.wbb",HTML$
0040 CALL "utexit.wbb",CGI$
0050 RELEASE