Click here to see the demosite.prgIMPORTANT:README before starting.

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.
  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
Notes:

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.

2. Who is the CGI user.

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.

3. Screen I/O and programming structure for CGI.

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:


  2. 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.

  3. All screen output are redirected to the Client's browser via Web-server.
  4. 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:

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.

4. How to compile & link to use as CGI and/or HTML file creation..

You can use FS_WEB for two diferent things:

  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.

6. Order of command execution.

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:

Right
WRONG
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.


FS_WEB command
SAY TEXT "Hello Internet!" BOLD ITALIC
HTML source code
<B><I>Hello Internet!</I></B>
You'll see
Hello Internet!

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.

7. Sample program for CGI.

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

8. Sample program for HTML.

  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

9. Making files available.

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:

Graphics:
All files from the graph directory of fsweb
(0.gif...10.gif, clear.gif, black.gif and graph.js)
Menus:
All files from the menu directory of fsweb
(arrows.gif, arrows2.gif and menu.js and menu_api.js)

10. Javascript Sample codes.

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

11. Errorsys.

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
ProcFileProcNameProcLine
FSERROR_ERRCALLER 186
ADMININC_CLIE 208
SALESMAIN 78


Aliases in use
 WAAliasRecno#IndexOrder#IndexKey
  1CLIENT 2 1field->cod
  2SALES 1 1field->cod
  3HOUSE 46 1field->cod +field->grup
  4CONFIRM 2 1field->cod +field->addr +field->grup +dtos(field->dtini)
* 5GRUPO 1 1field->cod +field->grup

SALES        19: CB_1_19_15()
FSERROR      186: _ERRCALLER()
ADMIN        208: INC_CLIE()
SALES        78: MAIN()
         4


© 2000 Jorge E.Hime Somers
JHSomers@Somers.com.br