Basic Web Utility Contents

Toolkit Contents

Installing and Configuring the Basic Web Utility

UNIX

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

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 webserver'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 webpage, 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 webserver's home drive must not be DSKSYN'd, 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 webserver 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

BBPROG

Specifies the program that Visual PRO/5 will run. This program will be responsible for creating the contents of the resultant html page.

BBEXEC

Specifies the full path to the vpro5 executable.

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 DSKSYN's and a PREFIX that allows Visual PRO/5 to load the Basic Web Utility programs and the program specified by BBPROG above.

MEM

Specifies the amount of memory to start the Visual PRO/5 with.

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.

USERID

Specifies the userid value to use when connecting to a data server. If no Data Server is required, use a dummy value.

 

 Configuration Requirements and Samples after Installation

To use Basic Web Utility, ensure the following are installed:

 

Configuration

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


Executing the CGI Program/Script

Start the browser (Internet Explorer or Netscape), and point it to the CGI Program/Script in the web server’s cgi-bin directory For example:

With a Windows Web Server:

http://web_server/cgi-bin/stdcgi.exe

With a UNIX Web Server:

http://web_server/cgi-bin/bwu.cgi

Once it finds the Web Server and executes the program saved above, the words "My First Web Test Program" are displayed in a bold header font.

 

Troubleshooting

Errors can often occur when developing web-based applications, and the above suggestions combined with the following troubleshooting guide can help get an application working quickly.

Error Messages

Remember, all applications should include error trapping to handle any problems that may arise. Errors that can be trapped include user escapes, missing files, and end of file errors. These errors can occur outside the calls to the Basic Web Utility set.

The BASIS Web Utility programs include error trapping as an aid during the development cycle. If any errors occur, a log file (BWWERR.log) is created in the current working directory of the program being run. This may not necessarily be the current working directory of PRO/5, but the directory where the script (stdcgi.exe) resides.

Errors returned by the stdcgi.exe (reported to the browser and the BWWERR.log) are:

Error Message

Description

"Can't generate work file 1"

Could not create the first temporary file.

"Can't open work file 1"

Could not open the first temporary file.

"Can't generate work file 2"

Could not create the second temporary file.

"Can't open work file 2"

Could not open the second temporary file.

"Can't open parameter file stdcgi.bat"

Could not open the batch file.

"Couldn't start task!"

Could not start vpro5.(or other exe specified in the batch file).

"Result couldn't be found"

Could not open temp file that contains the output from vpro5.

 

Errors returned by the wincgi.exe (reported to the browser and the BWWERR.log) are:

Error Message

Description

"Can't open parameter file wincgi.bat"

Could not open the batch file.

"Sorry: can't start CGI task. Try again later"

Could not start vpro5 (or other exe specified in the batch file).

Debugging Programs during Development

The most common method of debugging a program is to single step through it. (Additional information on the single step verb can be found in the Commands Manual under ‘Single Step.’) Always set Byte 1 Bit $08$ of the options vector before beginning, or errors may occur in public (or called) programs. This also enables console mode and debugging in public programs.

An alternate method of debugging an application is to have the program create dummy files before each step of the program. This method makes it possible to know exactly which utility failed. Using the example from the Configuration section above, a line was added to create a string file before each call to a Basic Web Utility program to help determine exactly which call failed.

 

0005 STRING "d:/bwu/progs/bwustarted",ERR=0050

0010 CALL "utcgi.wbb",ENV$,CGI$,ERRMSG$

0015 STRING "d:/bwu/progs/bwu15",ERR=0050

0020 CALL "uttags.wbb","h1"," My First Web Test Program",HTML$

0025 STRING "d:/bwu/progs/bwu25",ERR=0050

0030 CALL "utsend.wbb",HTML$

0035 STRING "d:/bwu/progs/bwu35",ERR=0050

0040 CALL "utexit.wbb",CGI$

0045 STRING "d:/bwu/progs/bwuworked",ERR=0050

0050 RELEASE

 

 

Return to first page