INFORMIX-ESQL/C CGI Interface Kit Documentation

Version 1.00.UE1 Mar. 6, 1996

Back to TOC = back to this Table of Contents

Source code references are listed between brackets [ sourcefile.c ]

Porting Considerations

Informix has certified the INFORMIX-ESQL/C CGI Interface Kit for the Sun Solaris, Hewlett Packard HP-UX, Silicon Graphics IRIX and IBM AIX platforms. Where possible, standard Unix commands were used so chances are the kit will also compile on your Unix platform.

In the spirit of making our products as open as possible, we will continue to certify this kit for additional platforms in the near future.

Installing the Interface Kit Source Code

Select a working directory to install the kit's source code (the installation and finished library will take less than 1MB of disk space, the compiled examples will take additional space). The following directories will be created:

esqlcgi (top directory)
esqlcgi/src (source code)
esqlcgi/examples (top example directory)
esqlcgi/examples/example1 (customer example)
esqlcgi/examples/example2 (getcatpic example)
esqlcgi/examples/example3 (catalog example)
esqlcgi/examples/loadgif (GIF images, GIF loading utility)
esqlcgi/examples/lib (installed library)

Once you have downloaded the kit (esqlcgi.tar), change to your working directory and use tar to install the files:

cd /myworkdir
tar xvf /tmp/esqlcgi.tar

Generating Make Files

The kit includes the source code and make file template (libcgiusr.std) to build the library yourself.

The make files for building the library can be generated from the libcgiusr.std templates:

cd /myworkdir/esqlcgi/src
make

You will see the message:

Making makefile libcgiusr.mak from libcgiusr.std

If you are not developing on one of the 4 certified platforms (Sun Solaris, Hewlett Packard HP-UX, Silicon Graphics IRIX or IBM AIX), you may have to make modifications to the generated make files to get them to work. Refer to the documentation on the make utility provided with your C development software.

[ libcgiusr.std ]

Making the Library libcgiusr.a

Change to the source directory and run the make command that builds the CGI library after you have completed the Generating the Make Files step:

cd /myworkdir/esqlcgi/src
make -f libcgiusr.mak all

The library will be installed into the the library directory for the examples to facilitate building the examples yourself. When you begin development on your own appliation, you will want to copy the library into the application's working directory:

cp /myworkdir/esqlcgi/examples/lib/libcgiusr.a /myappdir

When you compile your application, include the library on the link line:

cd /myappdir
esql -o myapp myapp.ec libcgiusr.a

The Header file cgiusr.h

The header file cgiusr.h must be included at the top of each ESQL/C CGI application source code file. Copy this file to the working directory of your CGI application:

cp /myworkdir/esqlcgi/src/cgiusr.h /myappdir

Include the header in every source file in the application -- for example:

/* File: myapp.ec */
#include "cgiusr.h"
$include sqltypes.h;
$include locator.h;
void main() 
{ /* etc ...

Besides declaring the the function prototypes for the interface, the cgiusr.h header define 2 structures you'll need for your CGI application:

cgi_env

The cgi_env structure stores pointers to the environment variables specfic to CGI:

typedef struct cgienvstruct
{
   char *server_software;
   char *server_name;
   char *gateway_interface;
   char *server_protocol;
   char *server_port;
   char *request_method;
   char *path_translated;
   char *script_name;
   char *query_string;
   char *remote_host;
   char *remote_addr;
   char *auth_type;
   char *remote_user;
   char *remote_ident;
   char *content_type;
   char *content_length;
   char *http_accept;
   char *http_user_agent;
   char *http_referer;
   char *path_info;
} t_cgi_env;
GLOBAL t_cgi_env cgi_env;

t_cgi_entry

The structure template t_cgi_entry is used to store the form entries retrieved from the HTML form:

typedef struct cgiformstruct
{
   char *name;
   char *value;
   struct cgiformstruct *next;
} t_cgi_entry;

A pointer to a form entry (t_cgi_entry *) is returned from the function cgi_get_form_entry(), for example:

t_cgi_entry *myfield;
myfield = cgi_get_form_entry("myfield");

A null form entry (NULLENTRY) is defined to test for a valid form entry:

if ( myfield == NULLENTRY )
{ /* handle error ...

[ cgiusr.h ]

Reading the CGI Environment and Form Values

The interface kit includes 3 functions to read and interpret the information passed from an HTML form via CGI to your ESQL/C application.

int cgi_start()

The function cgi_start() does the 3 tasks required to receive and interpret the data passed from CGI:

Populate the cgi_env structure with pointers to the CGI specific environment variables:
Read the URL-encoded query string and decode it.
Parse the query string into a list of form entries that can be accessed from the function cgi_get_form_entry().

This function will return zero upon successful completion and non-zero upon failure:

if ( cgi_start != 0 )
{ /* error handler ...

[ cgistart.c ]

t_cgi_entry cgi_get_form_entry(char fieldname)

The function cgi_get_form_entry() is used to access the list of form entries. It searches through the list looking for a form entry matching the field name passed and returns a pointer to a form entry structure (t_cgi_entry *). If a form entry matching the field name is not found, cgi_get_form_entry() returns a null form entry (NULLENTRY). For example:

t_cgi_entry *field_one;
field_one = cgi_get_form_entry("field_one");
if ( field_one == NULLENTRY )
{ /* handle null entry ...

The t_cgi_entry structure and the NULLENTRY constant are defined in the cgiusr.h header file.

[ cgigetfrment.c ]

void cgi_free()

The function cgi_free() frees the memory that was allocated to the form entry list. For good housekeeping, call this at the end your application:

void main()
{
    if ( cgi_start() != 0 )
    /* continue CGI application ... */
  main_exit:
    cgi_free();
    return;
}

[ cgifree.c ]

Printing to CGI

The ESQL/C interface kit includes 3 functions to facilitate printing to the Web Browser via CGI.

void cgi_mimetype(char *mimetype)

Web browsers require the MIME-type (also known as "Content Type") be sent first. The function cgi_mimetype() should be called with a valid MIME-type before attempting to print anything else to CGI. Typical HTML output would require the MIME-type "text/html", for instance:

cgi_mimetype("text/html");

[ cgimimetype.c ]

void cgi_print_text(char *string)

The function cgi_print_text() is used to print text from a string to CGI. This is the typical way to send your HTML formatted text to the Web browser. The function will not append a new-line to the output, so use the escaped new-line character ('\n') if needed, for example:

cgi_print_text("<TITLE>My HTML Page</TITLE>\n");

[ cgiprinttext.c ]

void cgi_print_blob(char mimetype, loc_t blob_locator)

The function cgi_print_blob() is used to print Informix BLOB data to CGI (BLOB data types are available with the OnLine engine). The function is passed a string containing a valid MIME-type and a BLOB locator pointer (loc_t *) describing where the BLOB is being stored. The function will handle either TEXT or BYTE BLOB's which can be located in either memory or a file.

The ESQL/C developer is reponsible for including the locator header, declaring the locator correctly, initializing it correctly, fetching the BLOB data from the database correctly and cleaning up any temporary files if used. For a complete discussion of handling Informix BLOB data in ESQL/C, refer to the "Programming with Blobs" chapter of the INFORMIX-ESQL/C Programmer's Manual.

If the ouput is a BYTE BLOB, this function is typically called "stand-alone" without prior or subsequent HTML text, therefore a valid MIME-type should be used. For example, if the data were a GIF image:

cgi_print_blob("image/gif", &mygif_locator);

If the output is a TEXT BLOB, this function might be called amongst other HTML text (using calls to cgi_print_text() ), therefore the MIME-type has already been sent using cgi_mimetype(). In this case, pass an empty string. For example:

cgi_print_blob("", &mytext_locator);

[ cgiprintblob.ec ]

Other CGI Utility Functions

int cgi_setenv(char *env_str)

The function cgi_setenv() allows the developer to change environment variables from within the CGI executable. A non-zero value will be returned if the function is unable to alter the environment:

char *informix_server = "INFORMIXSERVER=grimmy_ol1";
if ( cgi_setenv(informix_server) != 0 ) {
    /* handle error */
}

If you do not "hard code" and set the Informix environment from within the compiled executable, your alternatives would be:

To set the Informix environment for the user that will run the Web server process (usually httpd) before starting it. This approach is not available for all HTTP servers as some will reset the environment upon start-up. (We found the CERN server does not reset the environment while the NCSA server does.)
To provide a shell script "wrapper" that sets the Informix environment then runs your CGI executable. This method has 2 disadvantages -- slower performance because an extra process is required for the shell script, and a possible security hole because the shell script could be "hacked into."

If you do choose to set the Informix environment from within the compiled executable, all the variables required to connect to your Informix server must be set before issuing a CONNECT or DATABASE command. The combination of Informix variables required to connect to a server depends on the version of the server, whether it is local or remote and whether it is INFORMIX-OnLine or INFORMIX-SE (refer to the Administrator's Guide).

The cgi_setenv() function provides a "leak proof" alternative to the standard Unix putenv() function which has known memory leak problems on some platforms.

[ cgisetenv.c ]

int cgi_decode(char decoded_str, char encoded_str)

The function cgi_decode() decodes a string that has been URL-encoded. The developer is responsible for allocating enough space in the string to receive the decoding (the first parameter). The function returns the number of characters in the decoded string.

char decoded[2048];
int decoded_len;
decoded_len = cgi_decode(decoded, encoded);

[ cgidecode.c ]

int cgi_encode(char encoded_str, char decoded_str)

The function cgi_encode() encodes a plain text string using URL-encoding rules. The developer is responsible for allocating enough space in the string to receive the encoding (the first parameter). The function returns the number of characters in the encoded string.

char encoded[2048];
int encoded_len;
encoded_len = cgi_encode(encoded, decoded);

[ cgiencode.c ]

char trim(char string)

The function trim is a convenience utility to trim trailing blanks off strings. The function returns a pointer to the same string.

cgi_print_text( trim(myfield->value) );

[ cgitrim.c ]

A CGI Template

The following is a basic template for an ESQL/C CGI application:

#include "cgiusr.h"
$include sqltypes.h;
$include locator.h;
/* other ESQL/C includes here */
 
/* pointers to your HTML form entries */
t_cgi_entry *myfield;
 
void main(argc, argv)
int argc;
char *argv[];
{
    /* send the MIME-type first */
    cgi_mimetype("text/html");
 
    if ( cgi_start() != 0 ) {
        /* send error message in HTML */
        exit(0);
    }
 
    /* get the form entries */
    myfield = cgi_get_form_entry("myfield");
 
    /* construct SQL */
 
    /* execute SQL */
 
    /* print HTML */
    cgi_print_text("<TITLE>My HTML Page</TITLE>\n");
    cgi_print_text("etc ... <P>");
 
    /* clean-up and return */
    cgi_free();
    return;
}

A Complete Index of Source Code

Examples

[ Home ] [ Search ] [ Comments ] [ WWW Databases ] [ Download Free Software ] [ CGI Kit FAQ ]