UNIX shell scripts for launching Business Basic programs as CGI scripts. Both on-demand and shared directory models are supported.
Visual PRO/5 version of Business Basic Windows executables for launching either standard (console-based) CGI or WIN-CGI applications.
Business Basic programs (ut*.wbb) designed to simplify Business Basic CGI programs. Most of these programs are CALLed.
Business Basic programs (rs*.wbb) to perform simple data transfer over a dedicated serial line, facilitating safe data access to live data from a nearby Web server.
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. |
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. |
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
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
Start the browser (Internet Explorer or Netscape), and point it to the CGI Program/Script in the web servers 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.
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.
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). |
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