FS_WEB User Manual

For you start using FS_WEB you should read the following toppics:

1. Access rights to directories and path for files.
2. Who is the CGI user.
3. Screen I/O and programming structure for CGI.
4. How to compile & link to use as CGI and/or HTML file creation.
5. Command syntax.

• I/O redirection
• Text Format (new commands 3/2000)
• Data retrieval (new commands 3/2000)
• Form creation
• Menu creation
• Graphics commands
• Table of named colors (new 3/2000)

6. Order of command execution.
7. Sample program for CGI.
8. Sample program for HTML.
9. Making files available.
10. Javascript Sample codes.
11. Errorsys. (new 3/2000)

1. Access rights to directories and path for files.

The directory where  the executable will be located is usually called cgi-bin, and for reasons of safety, usually only the user "root" (or webadmin) and the user "nobody" have the read and execute permissions (drwx---r-x). The cgi-bin directory is aliased in the Web server configuration file to a physical path, e.g. to /usr/local/httpd/cgi-bin, see example below.

Therefore you should flag the executable with the "root" or "webadmin" permissions. To do so, you may:

1. Login with your user ID and execute the command su <enter> giving the "root" user's password.
2. Login as user "root".
3. Alternatively, login as a special Web administration user, e.g. "webadmin". This will increase the security - or may be required when you have not the "root" permissions, like on servers located at provider site.

If you want that your CGI script or executable have an access to DBF files, specify a read or read/write permission to these files for the user "nobody" and "root" or "webadmin". This is the minimal, quite unsecure requirement. For a better security, consider:

Unix & Web security: The cgi-bin directory needs to have access rights for everybody or at least for the user "nobody". Therefore, don't put your DBFs (or other internal files) directly in the cgi-bin or in the document directory, but in a separate directory where only the CGI applications and scripts have an access, for example in the special /cgi-bin/data directory. This directory and the data there becomes restricted access rigths, e.g. only for the "root" or "webadmin" user. To do so, flag this directory with rwx------ and the data there with rw------ permission. The application or script in the /cgi-bin directory should then have permissions granded to "root" or "webmaster", i.e. set by the "s" (or 4xxx) flag,  which enables the executable also the data access.  Example:

su                                              
# or log-in as e.g. webmaster
egrep "/cgi-bin | /cgi-bin/ " /etc/httpd/*.conf 
# determine the real /cgi-bin path if unknown
cd /usr/local/httpd/cgi-bin
chmod 777                                       
# flag the cgi-bin directory
mkdir data ; chmod 700 data                     
# create and flag the data directory
cp /home/test/myapplic . ; chmod 4700 myapplic  
# copy and flag the executable or script
cd data
cp /home/test/data/* . ; chmod 600 *            
# copy and flag the data by r/w permissions

1. All Unix (and Linux) file names are case sensitive. When your executable file is in mixed or lower case (e.g. "myApplic"), you need to referrer to it exactly same during the invocation or in your html page, e.g. <FORM ACTION="/cgi-bin/myApplic" METHOD="get">, otherwise you'll see a "404 page not found" alert message.

2. Take into consideration, that the executable run in the /cgi-bin directory. So if your html page refers to other html documents or graphics not available in the /cgi-bin directory, use either the full URL path (e.g. <A HREF="http://www.mydomain.com/ mydocument.html"> </A> ) or the relative documents path (e.g. <IMG SRC="/docs/mypict.gif"> ) corresponding to the Web Server configuration.

3. Additional hints for the Web security and setting are available also on the multisoft's page.

CGI is usually executed by a internal "user" called "NOBODY". This user in reality doesn't exist and it doesn't have login permission, but it can execute your cgi program. You can increase the access rights of the executable by the "s" permission, see example above.

The CGI executable file is a program that has some particularities:

1. It doesn't have any data entry via Keyboard but vit STDIN. And the data is sent to the executable by two ways:


POST - Is the most used way by all providers to send a request.
GET - The request is sent as a command line at the URL,
eg:http://server/cgi-bin/test.sh?name=joge%32somers& company=Somers%32software.
As you can see there are no spaces, which are changed by %32, like space all characters which are not between A-Z, 0-1 and a-z are changed by %hh (Hexadecimal code), this conversion is called escape and when we want do convert it back we call is unescape.


2. All screen output are redirected to the Client's browser via Web-server.
3. The program is executed from begin to end for each request, what means the program doesn't stay "running" until the next request is made, look at the steps bellow:

The internet client sends a form to your web-site.
Web-server configures your host's environment and executes a shell.
The shell executes your CGI program.
The CGI program is executed and a function called cgiconnect() transfers all form fields and/or query strings to FlagShip variables.
Then your program chooses which option this requests is for and all outputs after the command BEGIN CGI is sent to STDOUT which is your Web-server which sends to the client.

As you can see we can't say that your program is "running", because the execution time is very short, For best performance try make your CGI execution time be lower then 1 or 2 seconds, is some countries we also have the following problems:

1. Telephone line speed.
2. The speed of your client's computer to process all tags.
3. The number of concurrent users allowed to run a CGI at your ISP.

and at last make your CGI to create small HTML pages and with few TABLES because a large page with a single table will be displayed to the client only when the </TABLE> is received.

If your program checks if all files exists each time it runs, this takes more time for your CGI to be processed, then remove it and make a separate program to make this test when is need, upon your request.

The APACHE web server I've been using at my Linux server is far diferent from MS IIS.
MS IIS each time it receives a request it creates a unique temporary file with all CGI data, only when this file is "closed" then the CGI can "open" it and process the client's request which returns by the same way it came, (the CGI creates a file temporary file which is sent to the client only when is completed), this process makes a big delay to send to the client and makes your server extreamly slow. .

The APACHE web server sends all output straight to the client what makes possible to your program to send a wait message to the client, when some reindexing process is needed to be done.

1. As a CGI executable file.
   Then you need to link the following object and lib:
   libfsweb.a fscgi.o (-lfsweb fscgi.o)
2. To create static HTML files as a result of a report.
   Then you have ONLY to link a lib fsweb.a (-lfsweb) but not the fscggi.o file and you cannot use the following commands: BEGIN CGI... and END CGI. (-lfsweb.a).
   CAUTION: If your also link the object fscgi.o your executable will not have a Keyboard input nor @ row,col output.

Diferent from when you create a HTML using a simple text editor, FS_WEB already "closes" all tags at the same order when "opening" in all commands.

When you use the commands BEGIN / END you must always especify the same paramenters, and at the correct order, see the example bellow:

BEGIN TABLE
	BEGIN ROW
		BEGIN DATA
			DATA
		END DATA
	END ROW
END TABLE

BEGIN TABLE
	BEGIN ROW
		BEGIN DATA
			DATA
	END ROW
END TABLE

When you use the command SAY it's not necessary to specify the end of any tag, because FS_WEB already does it for you, and it will be placed is the same order shown above at the commands.

The only commands which has a BEGIN / END and there is no need to specify parameteres when ending are:Header PreTable / Record PreTable / Footer PreTable.

cgiconnect()
cDemo:=CGIDATA("DEMO")
if cDemo="DEMOTABLE"
  BEGIN CGI TITLE "Tables at Word 97 style"
     BODY bgcolor "LIGHTBLUE" message " Look at me ! " , ;
          " One more message !!!" , " That's all !! re-starting" 
     SAY TEXT "Tables at Word 97 style" FONT "ARIAL" ;
          COLOR NS_NAVY HEADER 5 CENTER
  END CGI
endif

  BEGIN HTML "lookthis.html" TITLE "Tables at Word 97 style"
     BODY bgcolor "LIGHTBLUE" message " Look at me ! " , ;
          " One more message !!!" , " That's all !! re-starting" 
     SAY TEXT "Tables at Word 97 style" FONT "ARIAL" ;
          COLOR NS_NAVY HEADER 5 CENTER
  END HTML

If you use Menu or Graphics commands at your program then you have to create a directory fsweb at the root directory of your homepage (domain), usually the phisical directory is htdocs/, with the following files:

A good reference of Javascript codes is: Developer's corner at Netscape

To simplify debuging we created a new errorsys, which can be customized to meet your special needs. To enable the new errorsys you have to compile it with the following command:
FlagShip errorsys.prg -na -nD -m -q -c -w -oerrorsys.o
And when linking your program you have to include it in the files list. To make the CGI use the new errorsys you have to include the following line at the begining of your MAIN procedure:
ErrorBlock( {|e| FS_DefError(e)} )
The new errorsys will show you a screen like this:

Date 15/03/00 Time:17:13:56 Error BASE/0 cannot find that field fgsGetAliasField: cannot find field 'CAD' Called from ProcFile ProcName ProcLine FSERROR _ERRCALLER 186 ADMIN INC_CLIE 208 SALES MAIN 78 Aliases in use   WA Alias Recno# IndexOrder# IndexKey   1 CLIENT 2 1 field->cod   2 SALES 1 1 field->cod   3 HOUSE 46 1 field->cod +field->grup   4 CONFIRM 2 1 field->cod +field->addr +field->grup +dtos(field->dtini) * 5 GRUPO 1 1 field->cod +field->grup SALES 19: CB_1_19_15() FSERROR 186: _ERRCALLER() ADMIN 208: INC_CLIE() SALES 78: MAIN() 4