Using FlagShip on Web

This document describes how to use FlagShip for html Web document purposes. It tries not to be a detailed manual for configuration of the Web Server or browser, nor a full reference to the HTML language, but gives a general overview sufficient for the programmer to use FlagShip as a database manager for HTML documents. The examples are hold very simple and are ment as a basis for your own programs even without or with a basic HTML knowledge only.

1. Data Structure on the Server

1.a. Directory for HTML documents (Document root directory)

The html documents (*.html) accessed by the Web browser (Navigator, Communicator, Arena, Mosaic, IE etc.) usually resides in a special directory on the server (e.g. /usr/local/httpd/htdocs or /var/local/public/html/docs etc). The Web server (e.g. Apache, Netscape, AOLserver etc.) hides (maps) the true directory structure so, that the Web browser will see this directory (named "Document root directory") as "root", i.e. the / path only. Hence, the Web user (usually of the group "nobody") can access files and subdirectories located below, but not above this Document root directory (an important security aspect). The links from a html document to another one on the same server may be done relatively, e.g. "/other.html" instead of the URL (Uniform Resource Locator) naming convention "http://www.domain.org/other.html", which reduce the Internet transfer and increases the access speed significantly.

Configuration: The name of the document root directory is specified in the /etc/httpd/access.conf and /etc/httpd/srm.conf (or similarly named) configuration files used by the Web server daemon and described in detail in the server documentation. On a remote Web server, contact your provider for the setup details.

Permissions: The document root directory should have a "read" access for everybody (e.g. 755, drwxr-xr-x). The html documents itselves (*.html) have usually only read permission (644, -rw-r--r--).
 

1.b. Directory for CGI Scripts and Executables

The Common Gateway Interface, or CGI, is a means for the HTTP server to "talk" to programs (scripts, executables) on the local or server's machine. As opposite to the static model of reading predefined html documents, the CGI allows to react on the client request and creates specific text or html documents for the browser. The requests from the browser to CGI are passed via environment variables (the most important are QUERY_STRING and PATH_INFO) and/or via stdin, depending on the request type. The QUERY_STRING is filled when the preferred "GET" method is used. The request is in the form <location>?<content>, e.g. http://www.domain.org/cgi-bin/myapplic?CUSTOMERID=1234 or simply /cgi-bin/myapplic?CUSTOMERID=1234.

That script directory contains scripts, executables and data accessed by the HTML documents indirectly via the CGI interface, e.g. by the <FORM ...> tag. This directory will contain the by FlagShip created executable among the databases and indices.

For security reasons, this CGI directory should not be equivalent to, or reside below the Document root directory. Usually, this directory is named cgi-bin and reside parallel to the Document root directory, e.g. /usr/local/httpd/cgi-bin  or  /var/local/public/html/cgi-bin.

Configuration: The location and its mapping to the Web browser (e.g. visible as /cgi-bin) is specified in the above named Web server configuration files. You should also change the properties of the directory to Options none, AllowOveride none in the access.conf file. On a remote Web server, contact your provider for the setup details.

Permissions: The CGI directory may have only execute permissions for everybody (711, drwx--x--x). The scripts or executables have usually only read & execute permission (755, -rwxr-xr-x), while the databases and indices are r/w (666, -rw-rw-rw-).
 

2. Access the database executable via a HTML document

2.a. The HTML document

The most common (and on some commercial servers the only) method to access a CGI script or executable is via the <FORM ...> tag.  Here an example named e.g. "example1.html" posted in the document directory (see 1.a) and invoked by the browser as URL http://www.my.org/example1.html  or locally  http://localdost/example1.html Note the name of the shell script "example1.sh" posted in the CGI directory (see 1.b).

2.b The interface script

The script "/cgi-bin/example1.sh" (invoked in 2.a via the FORM tag) sets the required environment and invokes the by FlagShip compiled executable named "example1" : Don't forget to make the script executable, i.e. "chmod 755 example1.sh"

2.c. The executable

The following FlagShip program is very simple. It checks the incoming request and displays the html data on stdout. Here, we get a customer ID
(via command line for test purposes, or passed by the Web server in the environment variable QUERY_STRING which contain here the string
"CUSTOMERID=<input-value>" according to the NAME parameter in the SETECT (or INPUT) tag. Note the CGI output prefix when #define HEADER_REQUIRED is enabled. It is required for the most common Web servers. The CALL fgsUse4html in the FUNCTION ProgramInit() is required here only for the Demo version of FlagShip, and available in the FS release 4.42.0448 and newer. For older releases, only the Pro or Personal license can be used here.

Now, compile the program (on the server system) by
   FlagShip example1.prg -oexample1
and post the executable into the /cgi-bin directory (see 1.b).

You may invoke it from the command-line by
   ./example1 1234
It displays a HTML document but first reports en error "database not available...".
 

2.d Database maintenance

We have to create a small maintenance program first (or use e.g. dbu). Often the main program checks for the existence of database and indices and creates it when required. But for security purposes on the server, it is better to maintain it separately by the web administrator which has sufficient access rights. Compile
   FlagShip mainten1.prg -omainten1
set the access rights for the web administrator only
   chmod 700 mainten1
and invoke it to create (or modify) the database and index
   ./mainten1
 After the first invocation,  change the permissions of the database and index:
   chmod 666 example1.dbf example1.idx

Check the output of the invocation "./example1 1", it should display a HTML document with two lines of data from the database.

If everything is ok, you're now ready to use the document example1.html (see 2.a) by your preferred Web browser. If something fails, check the access rights.

3. Additional hints

 

See also: standard FlagShip functions Web*() in fsman section FSC.

Last update: Friday, 08-May-1998  by webmaster@fship.com

Back to FlagShip home page