http://www.informix.com/informix/dbweb/grail/4gldoc.htm (PC Press Internet CD, 03/1996)

INFORMIX-4GL 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-4GL 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:

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

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

cd /myworkdir
tar xvf /tmp/4glcgi.tar

Generating Make Files

The kit includes the source code and make file templates (lib4glcgi.std and cgi_rds.std) to build the library and customized runners yourself.

The 2 make files for building the library and the customized runners can be generated from lib4glcgi.std and cgi_rds.std templates:

cd /myworkdir/informix/dbweb/grail/4glcgi/src
make

You will see the message:

Making makefile lib4glcgi.mak from lib4glcgi.std
Making makefile cgi_rds.mak from cgi_rds.std

White Ball If you are not developing on one of the 3 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.

White Ball If you are not using the INFORMIX-4GL Rapid Development System or the INFORMIX-4GL Interactive Debugger, you can skip the step Making Customized Runners (you will not require the cgi_rds.mak file).

[ lib4glcgi.std ] [ cgi_rds.std ]

Making the Library lib4glcgi.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/4glcgi/src
make -f lib4glcgi.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/4glcgi/examples/lib/lib4glcgi.a /myappdir

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

cd /myappdir
c4gl -o myapp.4ge myapp.4gl lib4glcgi.a

Making Customized Runners

If you are using the INFORMIX-4GL Rapid Developement System and/or the INFORMIX-4GL Interactive Debugger, you will need to create a customized P-Code runner and a customized Debugger that include the CGI function library. The cgi_rds.mak file will have been generated in the Generating Make Files step and can be used to build both runners.

First, copy the the fgicfunc.h file into your CGI directory:

cp $INFORMIXDIR/incl/tools/fgicfunc.h /myworkdir/4glcgi/src

Then, use the make file to build the runners:

make -f cgi_rds.mak all

The runners, cgi_runner and cgi_debug are ready to be used for your CGI development.

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 4GL application.

FUNCTION icgi_start()

    DEFINE return_value INTEGER
    LET return_value = cgi_start()

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

Read and stores the information from CGI specific environment variables.
Read the URL-encoded query string and decode it.
Parse the query string into a list of form entries.

The values of the CGI environment variables and the form entries from the application's HTML form are accessed from the function icgi_get_value().

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

IF ( icgi_start != 0 ) THEN
    # error handling code here
END IF

[ icgistart.c ]

FUNCTION icgi_getvalue()

    DEFINE field_name CHAR(30),
           field_value CHAR(30)
    LET field_name = "myfield"
    LET field_value = icgi_getvalue(field_name)

Retrieving a value from the CGI environment

The function icgi_getvalue() can be used to get the value of a variable from the CGI environment:

DEFINE request_method CHAR(4)
LET request_method = icgi_getvalue("REQUEST_METHOD")

Retrieve a value from an HTML form entry

The same function can be used to get the value of an entry from the application's HTML form:

DEFINE customer_num_field CHAR(15)
LET customer_num_field = icgi_getvalue("customer_num_field")

In either case, icgi_getvalue() will return a NULL string if the field or variable is non-existent or is existent but does not have a corresponding value:

DEFINE business_sic_fld CHAR(40)
LET business_sic_fld = icgi_getvalue("business_sic_fld")
IF ( business_sic_fld IS NULL ) THEN
   # handle empty field
END IF

[ icgigetvalue.ec ]

FUNCTION icgi_free()

    CALL icgi_free()

The function icgi_free() frees the memory that was allocated to storing variables and form entries:

MAIN
IF ( cgi_start() != 0 ) THEN
    # handle error
END IF
# continue CGI application
LABEL main_exit:
    CALL cgi_free()
    
END MAIN

[ icgifree.c ]

Printing to CGI

The 4GL interface kit includes 3 functions to facilitate printing to the Web Browser via CGI.

FUNCTION icgi_mimetype()

    DEFINE mime_type CHAR(30)
    LET mime_type = "text/plain"
    CALL icgi_mimetype(mime_type)

Web browsers require the MIME-type (also known as "Content Type") be sent first. The function icgi_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:

FORMAT
FIRST PAGE HEADER
    CALL icgi_mimetype("text/html")

icgimimetype.ec

FUNCTION icgi_print_text()

    DEFINE page_title CHAR(60)
    LET page_title = "<TITLE>My HTML Page</TITLE>"
    CALL icgi_print_text(page_title)

The function icgi_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 append a new-line to the output.

The following 4GL statements ...

DEFINE html_string CHAR(1024)
LET html_string = "Bolded Text"
CALL icgi_print_text("<B>")
CALL icgi_print_text(html_string)
CALL icgi_print_text("</B>")

... will result in the following HTML source at the Web browser:

<B>
Bolded Text
</B>

[ icgiprinttext.c ]

FUNCTION icgi_print_blob()

    DEFINE mime_type CHAR(30),
           image_blob BYTE
    LOCATE image_blob IN MEMORY  # can also be located in file
    SELECT image_blob_col
      FROM image_table
      INTO image_blob
     WHERE primary_key = 1000
    LET mime_type = "image/gif"
    CALL icgi_print_blob(mime_type, image_blob)
    FREE image_blob

The function icgi_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 variable (TEXT or BYTE). The function will handle either type of BLOB which can be located in memory or a file.

The 4GL programmer must LOCATE the BLOB correctly prior to fetching it from the database. For more information about accessing BLOB data from 4GL, refer to the BYTE and TEXT data types in the "Data Types of 4GL" section and the LOCATE command in the "INFORMIX-4GL Statements" section of the INFORMIX-4GL Reference 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:

CALL icgi_print_blob("image/gif", my_gif_blob)

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

LET mime_type = NULL
CALL icgi_print_blob(mime_type, my_text_blob)

[ icgiprintblob.ec ]

Other CGI Utility Functions

FUNCTION icgi_decode()

    DEFINE decoded_str CHAR(2048),
           encoded_str CHAR(2048)
    LET decoded_str = icgi_decode(encoded_str)

The function icgi_decode() decodes a string that has been URL-encoded.

[ icgidecode.ec ]

FUNCTION icgi_encode()

DEFINE decoded_str CHAR(2048),
encoded_str CHAR(2048)
LET encoded_str = icgi_encode(decoded_str)

The function icgi_encode() encodes a plain text string using URL-encoding rules.

[ icgiencode.ec ]

Other 4GL Utility Functions

The following functions are utilities to facilitate setting the environment and handling files on your Web server.

FUNCTION i4gl_setenv()

    DEFINE env_str CHAR(256),
           return_value INTEGER
    LET env_str = "INFORMIXSERVER=grimmy_ol1"
    LET return_value = i4gl_setenv(env_str)

The function i4gl_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.

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 NCSAserver 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."
To install the Informix products in the /usr/informix directory. If the INFORMIXDIR variable is not set at runtime, this is the default directory the executable will use. If you have already installed the Informix products in another directory, this can be accomplished by creating a symbolic link to /usr/informix:
```
ln -s /usr/infmx7.10 /usr/informix
```

INFORMIX-4GL development and runtime packages require that at least the correct INFORMIXDIR variable be set before running a compiled executable. If you are using a Web server that does reset the environment, then you will be forced to use the 2nd or 3rd approaches. A shell wrapper which sets INFORMIXDIR before running your CGI executable might be:

#!/bin/sh
# set Informix environment
INFORMIXDIR=/usr/infmx7.10
export INFORMIXDIR
# execute CGI application
/usr/local/www/cgi-bin/fgl_cust.4ge

If you do choose to set other Informix environment variables from within the 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).

[ i4glsetenv.c ]

FUNCTION i4gl_access()

    DEFINE return_value INTEGER,
           access CHAR(3),
           file_name CHAR(250)
    LET access = "w"
    LET file_name = "myfile.htm"
    LET return_value = i4gl_access(file_name, access)

The function i4gl_access() allows the 4GL application to query the accessability of a file. The first parameter is a string containing the file name. The second parameter is a string containing one, some or all of the following characters:

"r" to check whether the file is readable
"w" to check whether the file is writable
"x" to check whether the file is executable

The function will return a zero if all the access levels queried are valid for the file, -1 otherwise.

[ i4glaccess.c ]

FUNCTION i4gl_cd()

    DEFINE return_value INTEGER,
           directory CHAR(256)
    LET directory = "/www/html"
    LET return_value = i4gl_cd(directory)

The function i4gl_cd() allows the 4GL application to change the current working directory. It returns zero if successful, non-zero if unsuccessful.

[ i4glcd.c ] ]

FUNCTION i4gl_chmod()

    DEFINE return_value INTEGER,
           file_name CHAR(60),
    mode CHAR(4)
    LET file_name = "myfile.htm"
    LET mode = "664"
    LET return_value = i4gl_chmod(file_name, mode)

The function i4gl_chmod() allows the 4GL application to change the permissions of a file. The mode is the same numeric permissions (read/write/execute by owner/group/other) that can be passed to the Unix utility chmod. It returns zero if successful, non-zero if unsuccessful.

[ i4glchmod.c ]

FUNCTION i4gl_getpid()

    DEFINE pid INTEGER,
    LET pid = i4gl_getpid()

The function i4gl_getpid() allows the 4GL application to query the current process ID.

[ i4glpid.c ]

FUNCTION i4gl_pwd()

    DEFINE directory CHAR(256)
    LET directory = i4gl_pwd()

The function i4gl_pwd() allows the 4GL application to query the current working directory.

[ i4glpwd.c ]

FUNCTION i4gl_rm()

    DEFINE filename CHAR(60)
    DEFINE return_value INTEGER
    LET filename = "/mydir/tmpfile.htm"
    LET return_value = i4gl_rm(filename)

The function i4gl_rm() allows the 4GL application to delete a file from the filesystem. It returns zero if successful, non-zero if unsuccessful.

[ i4glrm.c ]

FUNCTION i4gl_tmpfile()

    DEFINE path CHAR(256)
    LET path = i4gl_tmpfile()

The function i4gl_tmpfile() generates a filename with a fully qualified path that can be used as a temporary file.

[ i4gltmpfile.c ]

A CGI Template

The following is a basic template for a 4GL application:

MAIN
    DEFINE myfield CHAR(50)
### send the MIME-type first ###
CALL icgi_mimetype("text/html")
 
IF ( icgi_start() != 0 ) THEN
    #### send error message in HTML ####
    RETURN
END IF
 
### get the form entries ###
LET myfield = icgi_getvalue("myfield")
 
### construct SQL ###
 
### execute SQL ###
 
### print HTML ####
CALL icgi_print_text("<TITLE>My HTML Page</TITLE>")
CALL icgi_print_text("etc ... <P>")
 
### clean-up and return ###
CALL icgi_free()
RETURN
END MAIN

Complete Index of Source Code

Examples

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