Chapter 4

Comparison of the Various CGI programming Libraries

CONTENTS

• CGI Libraries for C Programming
  • CGIc 1.05
  • CGI-HTML 1.21
• The C++ CGI Class Libraries
  • AHTML
  • Kelly Black's CGI C++ Classes
• Perl Libraries
  • CGI-Lib
• Summary

There are many languages used for CGI programming. With each of those different languages, there is almost always more than one library for CGI. This chapter looks at the libraries, what they have to offer, and rates them.

All of the short synopses of the libraries were rewritten from information taken from the documentation of the library, which is the property of the respective authors.

CGI Libraries for C Programming

The CGI Libraries for the C language that we will review and compare are the following:

• CGIc 1.05
• CGIHTML 1.21

Of all of these CGI libraries for the C language, CGIc is the best for three simple reasons: It is actively maintained, has great documentation, and has good support.

CGIc 1.05

Of the CGI libraries I tested, CGIc had the best documentation and is the only one to offer more than one level of support. Combined with the fact that it is moderately easy to use, this library is the best all-around choice.

CGIc has the following features:

• Has some advanced form handling
• Can handle all of the CGI environment variables
• Can perform automatic redirection
• Can output HTTP error/status codes instead of a document
• Includes a safer version of the system() function
• Allows capturing of CGI sessions for later playback/debugging
• Has a full featured error handling system

The following lists CGIc's functions and procedures and contains a short synopsis of each. If you want more information, see the documentation that comes with CGIc.

• cgiFormString(char *name,char *result, int max). This function returns a cgiFormResultType. It is used to copy strings from input fields. It copies max-1 bytes of the string in the field name to the buffer result. If the field doesn't exist, it copies a blank string to the result buffer. All newlines in this function are represented by the line feed character.
• cgiFormStringNoNewlines(char *name, char *result, int max). This function returns a cgiFormResultType. It is exactly like the cgiFormString function except that all CRs and LFs are stripped out.
• cgiFormStringSpace(char *name, int *length). This function returns a cgiFormResultType. It returns the length of the string pointed to by name and puts it in length.
• cgiFormStringMultiple(char *name, char ***ptrToStringArray). This function returns a cgiFormResultType. If you have more than one input element with the same name or have elements that contain strings that dynamically change, you might want to use this function. It puts the values of all the input elements with the name char *name into the ptrToStringArray.
• cgiStringArrayFree(char **stringArray). This is a procedure. It frees the memory allocated to the stringArray.
• cgiFormInteger(char *name, int *result, int defaultV). Returns a cgiFormResultType. Takes the integer from input field and puts it in result.
• cgiFormIntegerBounder(char *name, int *result, int min, int max, int defaultV). Returns a cgiFormResultType. Takes the integer from the input field if it is in the bounds and puts it in result.
• cgiFormDouble(char *name, double *result, double defaultV). Returns a cgiFormResultType. Takes a floating point value from the input field and puts it in result.
• cgiFormDoubleBounded(char *name, double *result, double min, double max, double defaultV). Returns a cgiFormResultType. Takes a floating point value from an input field if it is in the bounds and puts it in result.
• cgiFormSelectSingle(char *name, char **choicesText, int choicesTotal, int *result, int defaultV). Returns a cgiFormResultType. Takes the selection box (what follows a <SELECT> statement), copies the names of the choices into choicesText, copies the number of choices to choicesTotal, and copies the currently selected choice to result.
• cgiFormSelectMultiple(char *name, char **choicesText, int choicesTotal, int *result, int defaultV). Returns a cgiFormResultType. Like cgiFormSelectSingle, only results should point to an array of integers that represent the selected choices.
• cgiFormCheckboxSingle(char *name). Returns a cgiFormResultType. This function returns cgiFormSuccess if the checkbox is checked and returns cgiFormNotFound if it isn't.
• cgiFormCheckboxMultiple(char *name, char **stringArray, int valuesTotal, int *result, int *invalid). Returns a cgiFormResultType. Like cgiFormCheckboxSingle but handles multiple checkboxes with the same name instead. name points to the name of the checkbox. stringArray points to an array containing the <VALUE> parameter of each checkbox. valueTotal points to the total number of checkboxes. result is an array of integers that contains a 1 for each checkbox checked and a 0 for those that aren't.
• cgiFormRadio(char *name, char **stringArray, int valuesTotal, int *result, int defaultV). Returns a cgiFormResultType. This function is like cgiFormCheckboxMultiple, except that it is for radio buttons instead of checkboxes.
• cgiHeaderLocation(char *redirectUrl). Does not return a value. Redirects the user to the URL specified in redirectURL.
• cgiHeaderStatus(int status, char *statusMessage). Does not return a value. Outputs the status code status and the message statusMessage.
• cgiHeaderContentType(char *mimeType). Does not return a value. Used to tell the browser what type of document you are returning.
• cgiSaferSystem(char *command). Returns an int. This function removes all shell metacharacters and then calls the system command to run the command specified by command.
• cgiWriteEnvironment(char *filename). Returns a cgiEnvironmentResultType. This function writes the current CGI environment to the file specified by filename so that it can be used for later debugging.
• cgiReadEnvironment(char *filename). Returns a cgiEnvironmentResultType. This function reads the CGI environment from the file specified by filename so that it can be used for debugging.
• cgiMain(). Returns an int. This is where the real main program goes.

The following is the rest of the information you need to know about the CGIc library:

• Amount of Documentation: 21 pages; comes in HTML and text format.
• Quality of Documentation: The documentation for this library is very well written and provides answers to every question you will have about the library.
• Commercial License Required/Price: Possibly; see manual for details.
• Actively Maintained: Yes. This library is updated periodically by Thomas Boutell.
• Level of Support: Both e-mail support (free) and priority support (not free) are available.
• Ease of Use: Moderately easy.
• Number of sample programs: three.

The following is a summary of each sample program:

• cgictest.c. This parses the results from testform.htm and prints them out.
• capture.c. This saves the CGI environment for later use and tells the user it did so.
• Cross-Platform Compatibility. Should run on any platform that has a ANSI C compiler.

If you would like more information about CGIc, try the following:

• Author's e-mail address: boutell@boutell.com.
• Author's Web page: http://www.boutell.com.

CGI-HTML 1.21

Of the CGI libraries I tested, CGI-HTML 1.21 was the second best. Unfortunately, it is still in major development and does not offer priority support. On the good side, it offers source code, and it is completely free.

Following are the features of CGI-HTML 1.21:

• Has the most advanced form handling of any of the libraries I had a chance to test.
• Can handle all of the CGI environment variables.
• Can perform automatic redirection.
• Can output HTTP error/status codes instead of a document.

The following lists the procedures and functions of CGI-HTML 1.21 and includes a short synopsis of each. For more information, see the documentation that comes with the library.

• die(). Does not return a value. Kills the program gracefully.
• accept_images(). Returns a short. Determines if the browser supports images. 1 if it does; 0 if it doesn't.
• unescape_url(). Does not return a value. Converts the escape sequences in the URI to real characters.
• read_cgi_input(llist *entries). Returns an integer. Parses the server data and puts it into the linked list pointed to by entries.
• cgi_val(llist l, char *name). Returns a char *. Searches list l for name name and returns it if it is found.
• cgi_val_multi(llist l, char *name). Returns a char **. cgi_val that returns multiple values.
• print_cgi_env(). Does not return a value. Prints the CGI environment variables.
• print_entries(llist l). Does not return a value. Prints out the linked list pointed to by llist.
• escape_input(char *str). Returns a char *. Removes shell metacharacters from the string pointed to by str.
• html_header(). Does not return a value. Prints out the MIME header required for HTML documents.
• mime_header(char *mime). Does not return a value. Like html_header except it uses the MIME string as the MIME type.
• nph_header(char *status). Does not return a value. Used to send directly to the browser (NPH stands for No Parse Header).
• show_html_page(char *loc). Does not return a value. Used to show the HTML page pointed to by loc to the browser.
• status(char *status). Does not return a value. Used to send status messages to the browser.
• pragma(char *msg). Does not return a value. Sends the browser an HTML Pragma header.
• html_begin(char *title). Does not return a value. Sends the HTML tags that should appear at the beginning of any HTML file.
• html_end(). Does not return a value. Sends the HTML tags that should appear at the end of any HTML file.
• h1(char *str). Outputs string str surrounded by <H1></H1> tags. Does not return a value.
• h2 through h6. Same as h1, only different heading levels (for example, H2, H3, and so on).
• list_create(llist *l). Does not return a value. Creates the list pointed to by l.
• list_next(node *l). Returns a node* type. Returns the next node on the list pointed to by w.
• on_list(llist *l, node *l). Returns a short. If node w is on the list l, it returns 1.
• on_list_debug(llist *l, node* w). Returns a short. This is an on_list that is always reliable.
• list_traverse(llist *l, void (*visit) (entrytype item)). Does not return a value. For use with a function that will be used on every node in the list.
• list_insafter(llist* l, node* w, entrytype item). Returns a node* type. Adds the entry after node w and returns the new node.
• list_clear(llist *l). Does not return a value. Frees the memory used by list l.
• newstr(char *str). Returns a char*. Correctly allocates memory for the string.

The following describes the documentation and support available for CGI-HTML:

• Amount of Documentation: Depends on font size used in browser. Comes only in HTML format.
• Quality of Documentation: Not bad, but not professional.
• Commercial License Required/Price: No.
• Actively Maintained: Yes. This library is updated periodically by Eugene Kim.
• Level of Support: Only e-mail support is available.
• Ease of Use: Moderately difficult.
• Number of sample programs: 5.

The following contains a summary of each sample program:

• test.cgi.c: Prints out cgi environment variables.
• query-results.c: Prints out the form that is sent to it.
• mail.cgi.c: Prints out a comment form and mails it by e-mail.
• index-sample.cgi.c: Determines if the browser supports images and sends the appropriate page.
• ignore.cgi.c: Sends a status of 204.

The following describes compatibility information about CGI-HTML:

• Cross-Platform Compatibility: Should run on any platform that has an ANSI C compiler.

If you would like more information about CGI-HTML, you can find it at the following places:

• Author's e-mail address: eekim@fas.harvard.edu.
• Author's Web page: http://hcs.harvard.edu/~eekim/web/cgihtml.

The C++ CGI Class Libraries

Of the two C++ class libraries for CGI that I could find, AHTML is easily the best of the two. It is constantly updated, contains many neat features, and is very easy to use.

AHTML

AHTML is a great C++ class library, and although I am biased towards C++ as a language (not C with a little C++ thrown in, just pure C++), there is no denying it is such. It is the only CGI library of any language to include encryption and encoding/decoding to 4-bit hex and 7-bit alpha.

Following are the features of AHTML:

• Great form handling.
• Can handle all CGI environment variables.
• Includes arrays, matrixes, and linked lists.
• Contains classes for handling bitmaps and other image types.
• Can perform automatic redirection.
• It can output HTTP error/status codes instead of a document.

The following lists the procedures and functions of AHTML and contains a short synopsis of each. For more information, see the documentation. Unfortunately, by the time this book is printed, some of the class names will have been added and or changed. The Web page and the included documentation are great at providing a quick reference.

• Amount of Documentation: Nine pages of text and a Web site.
• Quality of Documentation: The documentation for this library is written for programmers, but it does include examples for every class basically.
• Commercial License Required/Price: No.
• Actively Maintained: Yes. This library is updated periodically by Alex Chachanashvili.
• Level of Support: E-mail support.
• Ease of Use: Moderately easy.
• Number of sample programs: Three.

The following describes the compatibility information for AHTML:

• Cross-Platform Compatibility: Should run on any platform that has an ANSI C++ compiler.

If you would like more information about AHTML, you can find it at the following places:

• Author's e-mail address: achacha@panix.com.
• Author's Web Page: http://www.serve.com/adc/acgi.

Kelly Black's CGI C++ Classes

This C++ class library appears to have been created in someone's spare time, given the fact that the docs don't exist and it is missing some features. The thing it does have going for it, though, is the fact that it supports the creation of forms.

The author does not provide a list of features in the documentation, and it is not possible to tell just from looking at the code, mainly because the code is not documented well enough.

As for a list of functions and procedures, some of the procedures have comments, but not enough to make a quick reference out of.

The following describes documentation and support available for these CGI classes:

• Amount of Documentation: Nonexistent as of yet.
• Quality of Documentation: N/A.
• Commercial License Required/Price: No.
• Actively Maintained: Not that I can tell. Last update was 12/20/95.
• Level of Support: Unknown.
• Ease of Use: Fairly difficult.
• Number of sample programs: Two.

The following contains a summary of each sample program:

• cgiform.cpp: Shows how to create forms using the library.
• cgimap.cpp: Imagemapping.

The following describes the compatibility of the CGI classes.

• Cross-Platform Compatibility: Should run on any platform that has an ANSI C++ compiler.

If you would like more information about the CGI classes, you can find it at the following places:

• Author's e-mail address: black@vidalia.unh.edu.
• Author's Web page: http://www.math.unh.edu/~black/cgi.

Perl Libraries

Unlike the other languages, there is a basically standard library for CGI programming in Perl: CGI-Lib.

CGI-Lib

The following lists the features of CGI-Lib:

• Standard.
• Supports form processing.
• Has basic error handling.

The following contains the CGI-Lib procedures and functions and a short synopsis of each. For more information, see the documentation.

• ReadParse. This subroutine reads and parses the CGI data and places it in a usable format.
• PrintHeader. Prints out the Content Type required for an HTML document.
• HtmlTop. Returns the proper tags for the beginning of an HTML document.
• HtmlBot. Returns the proper tags for the end of an HTML document.
• MethGet. True if the GET method was used.
• MethPost. True if the POST method was used.
• MyBaseURL. Returns the base URL of the script.
• MyFullURL. Returns the full URL of the script.
• CgiError. Prints out an error message with the proper headers.
• CgiDie. CgiError that quits after printing out the info on the error.
• PrintVariables. Prints out the CGI variables.
• PrintEnv. Nicely prints out the environment variables.

The following describes documentation and support available for CGI-Lib:

• Amount of Documentation: Web page, various tutorials, and the library itself has a lot of comments in it.
• Quality of Documentation: Depends on the documentation used. Most of it is written well.
• Commercial License Required/Price: No, but credit is needed.
• Actively Maintained: Yes. This library is updated periodically by Steven E. Brenner.
• Level of Support: Listservs, e-mail, and so on.
• Ease of Use: Moderately easy.
• Number of sample programs: None included in library; hundreds available on the Web.

The following describes the compatibility information on CGI-Lib:

• Cross-Platform Compatibility: Runs on any platform that has a Perl Interpreter. Compatible with versions 4 and 5 of Perl.

If you would like more information about CGI-Lib, you can find it in the following places:

• Author's e-mail address: S.E.Brenner@bioc.cam.ac.uk.
• Author's Web page: http://www.bio.cam.ac.uk/cgi-lib/.

Summary

That just about does it for our look at the various CGI libraries that are available to developers. The next chapter explores designing your CGI application.