CGI Web Server Interface

The CGI web server interface is located in the runtime/cgi subdirectory. To use it, copy the following files to the cgi-bin (or Scripts for PWS or IIS) directory of your web server:

a CGI jig file (e.g. kwcgibasic.xpl) from runtime/cgi
a CGI executable file (e.g. kwcgibasic.exe (Windows) or kwcgibasic (Unix)) from runtime/cgi. Note this file has the same name as the jig .xpl file.
kwcgirun.plm from runtime/cgi
amzi.cfg from workshop
amzi.dll (Windows) or libamzi.so (Unix) from workshop
aodbc.lsx from workshop (Windows)
aosutils.lsx from workshop
a knowledgebase file (.kb) from samples modifed as described in the following section

Question_Top and Output_Continue

In your main knowledgebase object, you must have these minimal HTML elements which are inserted above and below all questions asked of the user:

Property Name	Windows Minimal Value	Unix Minimal Value
question_top	<HTML> <HEAD></HEAD> <BODY> <FORM METHOD="POST" ACTION= "/Scripts/kwcgibasic.exe%system(cgi_parameters)%">	<HTML> <HEAD></HEAD> <BODY> <FORM METHOD="POST" ACTION= "/cgi-bin/kwcgibasic%system(cgi_parameters)%">
question_bottom	<INPUT NAME="Submit" TYPE="Submit" VALUE="Continue"> </INPUT> </FORM> </BODY> </HTML>	<INPUT NAME="Submit" TYPE="Submit" VALUE="Continue"> </INPUT> </FORM> </BODY> </HTML>
output_continue (not in all Jigs)	<FORM METHOD="POST" ACTION= "/cgi-bin/kwcgibasic.exe%system(cgi_parameters)%"> <INPUT NAME="Submit" TYPE="Submit" VALUE="Continue"> </INPUT> </FORM>	<FORM METHOD="POST" ACTION= "/cgi-bin/kwcgibasic%system(cgi_parameters)%"> <INPUT NAME="Submit" TYPE="Submit" VALUE="Continue"> </INPUT> </FORM>

In addition, some jigs (notably Basic) also have an output_continue property in the knowledgebase object. This is used when there is output for the user and the reasoning process is not complete. That is, some intermediate results or information are being displayed for the user. In this case the output_continue contents are added to the web page and are an empty HTML form that continues the reasoning process. The program name used in question_bottom and output_continue must be the same and must match the name of the executable program in your cgi-bin or Scripts directory.

In addition the following properties are passed to your web server:

Parameter	Description	Example
charset	The character set used in your knowledgebase	big5

Running in Your Web Browser

To run your knowledgebase, type into your browser one of the following URLs:

Unix: http://127.0.0.1/cgi-bin/kwcgibasic?[kb_file='hello.kb']
Windows: 
http://localhost/Scripts/kwcgibasic.exe?[kb_file='hello.kb']

Replace the 127.0.0.1 or 'localhost' with the name (www.company.com) or IP address of the server you have installed the KnowledgeWright CGI script on.

CGI Parameters

There are additional parameters that you can specify in the square brackets. The full set of parameters are:

Parameter	Description	Examples
kb_file	The name of the knowledgebase file	'amzi_website_advisor.kb'
directory	The directory where the kb_file is located.	'c:\InetPub\Scripts' '/usr/local/apache/cgi-bin'
temp_directory	The directory where the temporary session files are created as well as log files (if you have specified one) and any other temporary files needed by KnowledgeWright. Note CGI programs must have write access to this directory.	'c:\InetPub\temp' '/usr/local/apache/cgi-bin/temp'
log_file	The name of the log file that details the execution. It will have the same contents as the log in the KnowledgeWright Workshop.	'kwrun.log'
results_file	The pathname of a file to write the session results to.	'c:/InetPub/Scripts/results.log'

Results File Format

If you specify a results file in your CGI parameters, KnowledgeWright will create a file of the following format:

session("<GMT 
Date/Time>", [<Known Name> : <Known Value>, ...], [<CGI 
Parameter Name> : <CGI Parameter Value>, ...]).

The list of known values is everything that KnowledgeWright determines during its reasoning process. So it includes answers from the user, values of goals, results of queries, etc. The CGI parameters follow the CGI standard and include the IP address, browser name, script, etc.

Debugging CGI Problems

KnowledgeWright includes a Windows test program called 'kwtestcgi.exe'. It can be used in multiple ways.

First, you can just run it from your browser by typing one of the following URLs:

Unix: http://127.0.0.1/cgi-bin/kwtestcgi
Windows: 
http://localhost/scripts/kwtestcgi.exe

Run in this way, it will print out the current directory and then an error message about not being able to load kwtestcgi.xpl. This will let you determine if the the .xpl file can be found.

If you still get an error (usually incomplete HTTP headers), see the sections below on setting up IIS/PWS and Apache. Under Windows, double-check that amzi.dll, aosutils.lsx and aodbc.lsx are in your Scripts directory. Check your file owner and read permissions in either the IIS/PWS Control Console or under Unix via the command line.

If you are still having problems, copy 'kwtestcgi.xpl' to your cgi-bin/scripts directory. Then run it again as specified above. You should get an error message saying there is no kb file specified. If you get any other message, there is a problem with your web server's configuration.

Next try specifying a kb file. First try a very simple one like 'hello_1.kb'. Copy it to your cgi-bin/scripts directory and run it as follows:

Unix: 
http://127.0.0.1/cgi-bin/kwtestcgi?[kb_file='hello_1.kb']
Windows: http://localhost/scripts/kwtestcgi.exe?[kb_file='hello_1.kb']

If the kb file is not being read and exists in the directory kwtestcgi is looking for it is, then check your file owner and read permissions in either the IIS/PWS Control Console or under Unix via the command line.

Open a KnowledgeWright Log File

The next thing to do when you encounter a problem is to specify a log_file in the query string where you invoke kwcgirun.exe.

To specify your kb file and a log file:

Unix: 
http://127.0.0.1/cgi-bin/kwtestcgi?[kb_file='hello.kb',log_file='kwrun.log']
Windows: 
http://localhost/scripts/kwtestcgi.exe?[kb_file='hello.kb',log_file='kwrun.log']

This will create a log file in the same directory as kwtestcgi. Study its contents, especially at the bottom to see if the problem is explained. If you do not get an obvious error message, then in your cgi-bin or Scripts directory, create two blank files; one named 'kwrun.log' and the other named 'session_127.0.0.1.kws'. If it still fails under Windows, use the IIS/PWS Control Panel or File Manager to check the owner and permissions on these files to ensure they can be written to. Under Unix, use the command line to do the same.

Double-Check the CGI Program Name in the Knowledgebase Object

If the knowledgebase does not start-up correctly, check the knowledgebase object to ensure the program name being executed in question_top corresponds with your operating system. For example, using the Basic jig under Windows, the program name is 'kwcgibasic.exe' and under Unix it is 'kwcgibasic'. Check the directory too. Under Windows it is usually 'Scripts' and under Unix it is usually 'cgi-bin'. Also, some jigs also have an output_continue property. If so, ensure the directory and program name specified there is correct.

Open an Amzi! Logic Server Trace File for Amzi! Tech Support

If that does not make the problem clear, the next step is to specify a log file in Amzi! Prolog + Logic Server. To do this, add the following lines to your amzi.cfg file in the cgi-bin or scripts directory:

apitrace 
= on logfile = c:\amziapi.log

If you need technical support, please e-mail the browser output when you run kwtestcgi, your KnowledgeWright log file and Amzi! Logic Server trace file along with your knowledgebase to tech support.

Setting Up Microsoft's PWS and IIS

By default, Personal Web Server (PWS) and IIS, do not have a directory named "cgi-bin". Instead their is a directory named "scripts" under "wwwroot" and this is where you can run CGI programs from. However, the URL to invoke KnowledgeWright from scripts reads a like this:

http://127.0.0.1/scripts/kwcgibasic.exe?[kb_file='hello.kb']

Also by default PWS and IIS do not allow the execution of CGI programs. In order to allow this, you must enable "Execute" permission on your 'Scripts' directory. How you do this varies widely by your version of PWS/IIS. Here are some methods to try:

Right-click on the directory name and selecting the "Properties" command, then choose the "Web Sharing" tab on the pop-up window. Select the folder name, click "Edit Properties" then make sure that "Execute" is checked.
Open up PWS/IIS Manager and select the "Advanced" icon. Select the folder named 'Scripts', click "Edit Properties" then make sure that "Execute" is checked.
Open the Control Console (usually found under 'Administrative Tools' in your 'Settings' / 'Control Panel') to make sure the properties for 'Scripts' directory have execute permissions for 'Scripts and Executables' and NOT 'Scripts Only'.

You may also need to create a temporary directory (we recommend you put it outside the wwwroot subtree on a production server). Make sure your web server process has full access to that directory (to read, write, create and delete files). Then specify that directory as temp_directory when invoking your knowledgebase as follows:

Unix: http://127.0.0.1/cgi-bin/kwtestcgi?[kb_file='hello.kb',temp_directory='/usr/local/apache/temp']
Windows: 
http://localhost/scripts/kwtestcgi.exe?[kb_file='hello.kb',temp_directory='C:\\InetPub\\temp']

Setting Up Apache

In order to use Apache with KnowledgeWright you need to set the LD_LIBRARY_PATH environment variable in your configuration file (normally apache/conf/httpd.conf) by adding the following line:

SetEnv 
LD_LIBRARY_PATH .

(note the lone period). If you already have set this variable, then make sure dot (.) is included in the list of directories. This is needed so that Apache can find libamzi.so and aosutils.lsx.

You will also need to create a temporary directory (we recommend you put it outside the htdocs and cgi-bin subtrees on a production server). Make sure your web server process has full access to that directory (to read, write, create and delete files). Then specify that directory as temp_directory when invoking your knowledgebase.

Modifying the CGI Interface (Full Version)

In order to modify the CGI interface you will need the current version of Amzi! Prolog + Logic Server, which can be downloaded from www.amzi.com. The interface is in kwcgirun.pro. To install your changes simply compile that file with acmp and replace your current kwcgirun.plm with the new one.

Copyright ©1995-2006 Amzi! inc. All Rights Reserved. Privacy Policy.
Amzi!, KnowledgeWright and WebLS are registered trademarks and Adventure in Prolog, Logic Server, Logic Explorer, Adventure in Prolog and Subscription Plus are trademarks of Amzi! inc.