14 November 1997

                              CGI Notebook v1.30

   It is assumed that you are the Webmaster administrating the server and
   are already familiar with the HTML language tags and their uses. Also,
   that you understand the operation of the OS/2 Warp environment and can
   perform the described tasks in the documentation.


This software is provided on an "as-is" basis.  I offer no warranty on this
software whatsoever, and you use it at your own risk.

This software is freeware so you may freely use and distribute it.


1. What is the CGI notebook?

    The CGI Notebook is a CGI (Common Gate Interface) program  which allows
you to ask users of your  Web Pages  for some  information  and records the 
information to desired file(s). In addition, visitors of your site can view
the information if you allow it.
    I wrote the program to help Webmasters which are not familiar with  CGI 
programming to record forms (<FORM> tag) data in a file. The Notebook
will help to make Guest Book, Registration Form and so on ...

2. System requirements.

    OS/2 Warp 3 or later and Web Server software (e.g. Internet Connection 
Server) installed on your computer. 

3. Installation.

    Archive cginb130.zip contains:
        nb.exe        -  executable file
        nb.cfg        -  notebook configuration file
        example.ndf   -  example of notebook definition file
        example.rsp   -  example of response file
        example.snb   -  example of template file for viewing notebook data
        example.usr   -  example of user configuration file
        nb.htm        -  HTML example of using of the Notebook
        readme        -  this file

     
    It is easy to install the Notebook. 
    Make directory /notebook inside the /cgi-bin directory of your Web server, 
then put files nb.exe, nb.cfg into /cgi-bin and example.ndf, example.rsp, 
example.snb, example.usr into /cgi-bin/notebook directory.

    HTML file nb.htm contains an example of use the Notebook and you may 
put the file whereever you want in your Web pages directories.

4. Using the Notebook.

    4.1. Simple use.

    Type URL http://yourhost/path_to_nb.htm/nb.htm in your browser. 
You will see an example of using the Notebook.

    4.2. Normal use.
    4.2.1. Setting up notebooks.

    First you have to describe a notebook in nb.cfg file.
The file contains a number of lines which describe different notebooks.

Format of nb.cfg file is:

identificator1=notebookDefinitionFile1
identificator2=notebookDefinitionFile2
...

where
    identificatorI - a key string to select the notebook
    notebookDefinitionFileI - file which describes the notebook

Example of nb.cfg:

main=notebook\example.ndf

    Above line says that notebook "main" uses file "notebook\example.ndf" as
a definition file.

    Examle of a definition file is example.ndf.
The file is well commented and you should view the file.
There are four keyword which are defined in the file:

    Data         - file which data are stored in after submitting
    ResponceFile - file which will be sent to remote after submitting
    ShowFile     - file which is used as a template for viewing
                   notebook data
    UserConfig   - configuration file for the notebook

    ResponceFile is a plain HTML document and ShowFile is almost a plain HTML 
document.

    UserConfig is intended for setting some parameters, templates and
access filters for the notebook.
    Examle of the file is example.usr.
    The parameters in the UserConfig are:
    
        Title - string, title of the notebook
        WrapLongLines - integer value in range from 0 to 256,
                        if a line in the notebook data will be longer than
                        the value then the line will be wrapped, 0 means 
                        no wrapping
        LinkUrl       - Yes/No, if url will be found in the notebook data
                        then the url will be replaced with
                        <A HREF="url">url</A>

    The templates in the UserConfig are:
        BeginShowEntryTemplate - template for showing all entries (records)
                                 in the notebook
                                 The template starts with

                                 BeginShowEntryTemplate=

                                 and ends with

                                 EndShowEntryTemplate

        BeginShowVariableTemplate - template for showing all or specific 
                                 variables (fields)
                                 Variable has the same name as a input element
                                 in FORM tag. So for
        <INPUT TYPE="text" NAME="First name" VALUE="" SIZE="25" MAXLENGTH="50">
                                 variable name is "First name".
                                 The template starts with

                                 BeginShowVariableTemplate=[variablename]

                                 and ends with

                                 EndShowEntryTemplate

                                 If the variablename is not specified
                                 then the template is used for all 
                                 variables which have not its own template.

    In a template you can use metasymbols:
        $d - number of the message
        $rn - remote name
        $ra - remote adr
        $t - time
        $va - all variables should be appeared here (only for ShowEntryTemplate)
        $vn - name of current variable in ShowVariableTemplate
        $vv - value of current variable in ShowVariableTemplate
    
    The filter in the UserConfig is an access filter. You are able to 
specify hosts which can access variables in the notebook.
    The filter starts with

Access

and ends with

EndAccess

    Access lists for variables are between these lines.
Format of access list is:

Variablename = host1,host2...

The variable will be accessed only from these hosts.
If no filter specified for a variable then the variable can be accessed from any 
hosts.

    4.2.2. Recording data in a notebook 

    After describing a notebook in nb.cfg, you have to insert to your Web page 
the <FORM> tag:

   <FORM METHOD="POST" ACTION="/cgi-bin/nb">
    <INPUT TYPE="hidden" NAME="notebookident" VALUE="main">

    <!-- Your input elements here -->

    <INPUT TYPE="submit" VALUE="Submit to the notebook"> <INPUT TYPE="reset" VALUE="Clear Note">  
   </FORM>
    
    Values are:

        notebookident - identificator of the notebook (see nb.cfg format)

    If you use Russian language then you have to add line:

    <INPUT TYPE="hidden" NAME="codepage" VALUE="ibm866">

in FORM tag.

    codepage - ibm866, win1251 or koi8r for translation 
               beetwin cyrillic codepages. Set codepage which your
               clients use. 

    If you use only English then don't insert codepage line in FORM tag
becouse if codepage variable is defined  then the CGI notebook will go
to cyrillic mode and use Russian messages instead of English.

    
    Inside the form you may insert any input elements.

    Data are stored in the specified file ( Data keyword in definition file ) 
in the next format:
:START
RemoteName= "remotehostname"
RemoteAddress= "remotehostaddress"
Time= "date&time"
:Variable1
valueofVariable1
:Variable2
valueofVariable2
...
:END


    4.2.3. Multiple notebooks support

    File 'nb.cfg' and 'notebookident' are needed for handle a number of 
different notebooks.
    For example, you need 2 different notebooks. First notebook is Guestbook,
second is Notebook_for_Clients.
You can do it.
File nb.cfg should contains data like that:

Guestbook=notebook/guest
Notebook_for_Clients=notebook/client

    The definition file notebook/guest will contain:
Data = guests
ResponceFile = guests.rsp
ShowFile = guests.snb
UserConfig = guests.usr

    The definition file notebook/client will contain:
Data = clients
ResponceFile = clients.rsp
ShowFile = clients.snb
UserConfig = clients.usr
        
Then you write in your guest page:

   <FORM METHOD="POST" ACTION="/cgi-bin/nb">
    <INPUT TYPE="hidden" NAME="notebookident" VALUE="Guestbook">

    <!-- Your input elements here -->

    <INPUT TYPE="submit" VALUE="Submit to the notebook"> <INPUT TYPE="reset" VALUE="Clear Note">  
   </FORM>

and in clients page

   <FORM METHOD="POST" ACTION="/cgi-bin/nb">
    <INPUT TYPE="hidden" NAME="notebookident" VALUE="Notebook_for_Clients">

    <!-- Your input elements here -->

    <INPUT TYPE="submit" VALUE="Submit to the notebook"> <INPUT TYPE="reset" VALUE="Clear Note">  
   </FORM>

So you have 2 different notebooks.

First notebook: 
ident = Guestbook
file to save data = notebook/guests
file to send to remote = notebook/guests.rsp
template to view the notebook = notebook/guests.snb
notebook configuration file = notebook/guests.usr

Second notebook: 
ident = Notebook_for_Clients
file to save data = notebook/clients
file to send to remote = notebook/clients.rsp
template to view the notebook = notebook/clients.snb
notebook configuration file = notebook/clients.usr

    4.2.4. Viewing data in notebook

    The CGI notebook allow to view notebook data with Web browser.

    To view notebook data you have to insert next FORM tag in your Web page:

   <FORM METHOD="POST" ACTION="/cgi-bin/nb">
    <INPUT TYPE="hidden" NAME="notebookident" VALUE="view:main">
    <INPUT TYPE="submit" VALUE="View the Notebook">
   </FORM>

    So you have to prepend identificator of a notebook to be viewed with 'view:'.
File example.snb is a template which is used to show notebook data as well as
templates in example.usr

NOTE: 
----
If you use Apache Web Server you have to replace
ACTION="/cgi-bin/nb"
with
ACTION="/cgi-bin/nb.exe"
in all forms

ENDNOTE
-------

5. CGI Notebook Revisions.

v1.00 - first release, non public, has a great security bug
v1.01 - cyrillic codepage support added. Still non public. 
        Security bug not fixed.
v1.10 - security bug fixed. First version with nb.cfg.
v1.20 - View notebook feature added. Reverse DNS lookup added.
v1.21 - Added support for ICS and GoServer. Little changes in documentaion.
v1.22 - No changes in executables. Corrections in nb.rsp, nb.snb and readme.
        Apache server support: note in documentation.
v1.23 - Little bug in view feature fixed. Added word wrap feature. 
        Changes in documentation. Format of nb.cfg is changed.
v1.24 - Changes in documentation related to PlanetWide Web Server.
        New version 1.13 of the server works properly with CGI.
v1.25 - All messages in cyrillic mode are translated to Russian
        Little quirk when incorrect calling is fixed.
v1.30 - Major release. A lot of features nave been added. Documentation
        has been changed. New format of configuration files and new 
        set of files which is included in the distribution zip.
        New features are:
        1. Human readable text configuration files.
        2. URLs appear as underlined links while viewing.
        3. Configurable templates to view all data and each field in the notebook.
        4. Controlled access to each field stored in the notebook. You can enable 
           access from one host and disable from all other.

6. Acknowledgements.

    Special thanks to Ted Romer, who has helped me in improving the CGI 
Notebook.

7. Conclusion.

    If you have ANY problems with the Notebook that I can help you with, 
send me E-mail to 

Vitali.Pelenyov@dpt.ustu.ru 

or leave your message in my notebook: 

http://194.226.228.11/eng/nb.htm

Latest version of the Notebook is available in my FTP archive

ftp://194.226.228.11/pub/os2/tcpip/cginb.zip

Mirror of the CGI notebook home page is:

http://www.watermaid.dyndns.com/~cosmos/nb/nb.htm

My site is up from 4 to 11 GMT.

If you use the Notebook, send me some mail and let me know. 
I would love to hear from you.

Sorry for any typos and bad grammar. I will gladly accept any corrections to
this short manual.

Vitali Pelenyov ( Vitali.Pelenyov@dpt.ustu.ru )
