CgiForms


CgiForms is copyright (c) 1997 by Myron Turner, the author of CgiForms, and is distributed for free use in non-commercial applications created for educational or cultural purposes. Use in commercial application requires permission from the author.
Permission to use, copy, modify, and distribute this software and its documentation for non-commercial purposes is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty.

Myron Turner Coordinator, Manitoba Visual Arts Network email: mturner@cc.umanitoba.ca phone: (204)284-8387


Introduction to Using CgiForms


CgiForms is a set of C++ classes designed to give direct and easy access to the CGI gateway and to the processing of FORMS. There is an interface class--the CGI Class--which provides access to the facilities of the other classes, which do the actual work and which are included in the CGI Class as member classes. The CGI Interface Class enables you to write programs for processing FORMS without knowing about these other classes. This document gives you a few examples of how to do this.

When the CGI class is instantiated, the system environment variables and the NAME/VALUE pairs from your FORM are retrieved, and the http Content-type header is sent out, which is by default this line:

"Content-Type: text/html\n\n"
This means that you are immediately ready to process your FORM.

You can use the CGI class as a base class for your own CGI class, and the file mycgi.cpp gives an example of a program which uses the CGI Class as a base class. However, the present document demonstrates how to use the CGI Interface Class directly, without deriving your own classes or knowing how to use the member classes of the CGI Interface. For short programs you can work wholly with the main() function, which is what the examples below do.

If you simply want to display your environment variables and your NAME=VALUE pairs, you could write the following program:

 #include "cgi.h"
  void main()
   {
     CGI cgi;              //create an instance of the CGI class
     cgi.display_env();     //list environment values
     cgi.display_fields();  //list NAME/VALUE pairs
   }

For processing your environment variables and/or your NAME=VALUE pairs, you have access to them through two CGI functions.

char const * GGI::getenv_var(int name) const
char * GGI::getfieldvalue(char *name)
For the environment variables, you supply getenv_var with an integer constant that takes the form of the required CGI environment variable, in caps, preceded by an underscore, e.g.
_QUERY_STRING, _REMOTE_HOST, _REMOTE_ADDR
These constants are defined in environ.h.

To retrieve a VALUE from the NAME/VALUE fields, you call getfieldvalue() with a char pointer to NAME, and it returns a pointer to VALUE. The following example program processes a FORM, first getting the name of an output file from the environment variable PATH_TRANSLATED and then extracting the VALUE from a NAME/VALUE pair and adding it to a file:

 #include "cgi.h"
 #include <unistd.h>
 #include <fcntl.h>

 void main()
 {
   CGI cgi("text/html");   // create an instance of the CGI class
  int log = -1;           // file handle initialized to error

     // get file name and path
     char const *logfile = cgi.getenv_var(_PATH_TRANSLATED);

   // output message to html file
  cout << "<h1>This is a test</h1>\n";
  cout << "<br><b>Attempting to write new data to "
   << logfile << "</b>\n";

    // open file for append
  if (logfile)
     log = open(logfile, O_CREAT|O_RDWR|O_APPEND);

 if (log == -1)   // check for file error
  {
    cout << "<h3> Unable to open log file </h3>";
      return;
 }

    // get VALUE for NAME="field1"
 char const *field = cgi.getfieldvalue("field1");

   // add field to file
   size_t strL = strlen(field);
   if  ( write(log, field, strL) < strL)
    {             // write error message to html file
       cout << "<h3> Log file NOT updated</h3>";
      close (log);
      return;
   }
  close(log);

  // write Success Message to html file
 cout << "\n<p><b>The Log file has been successfully
   updated:</b><br>\n";
  cout << "<b>\""<< field << "\" has been added to "
  << logfile  << "</b>\n";

}

There is only one other function that you might need to know, if you choose not to familiarize yourself with the member classes of the CGI Class. This is
void zerofldflags();
In some FORMS, there is more than one instance of a NAME, i.e. the same NAME may have several VALUES. For instance, you might have a selection of databases to search and give a choice of one or more of these databases. This is possible, for instance, with the Checkbox type of the Input tag:
DB 1<input type="checkbox" name="dbase" value = "db1"> <br>
DB 2<input type="checkbox" name="dbase" value = "db2"> <br>
DB 3<input type="checkbox" name="dbase" value = "db3"> <br>
In such cases, if you retrieve the values once and want to retrieve them at a later point in your program, you must call zerofldflags(), or else they will not be available. Such a case could arise, for instance, if you call getfieldvalue() from two different functions:
     func_1(CGI &cgi)
       {
          char dbase[3][25];
          for(int i = 0; i < 3; i++)
             strcpy(dbase[i], cgi.getfieldvalue("dbase"));
                                    // the rest of the function
       }

     func_2(CGI & cgi)
       {
           cgi.zerofldflags();
           char *firstdbase = cgi.getfieldvalue("dbase");
                                    // the rest of the function
       }
The mechanism behind zerofldflags is explained in the manual in the description of the Fields Class, which provides additional functions relevant to this situation; as well a more detailed treatment of zerofldsflags() is also given.

The CGI Class and the other classes which make up CgiForms are described in detail in the Manual. Among the Classes is an HTML Class which provides labor-saving routines for writing code to output HTML, including facilities for creating Tables and Lists.