5. USING THE DEBUGGING FACILITIES
One of the most difficult steps in writing form processing software with traditional CGI scripts is debugging. When the script does not complete successfully, it exits with an error code; in such a case the Web server merely reports an internal error occurred, which is not much help.
EiffelWeb makes the debugging process much more convenient through features of class CGI_INTERFACE.
Besides make, CGI_INTERFACE provides another procedure that can be used as creation procedure: make_debug, which extends make. Using make_debug you can perform extra operations, for example set environment variables to special values, and you can parse the input before starting any processing.
A piece of methodological advice: once you are done with debugging, remember to set the creation procedure back to the normal make, just in case make_debug sets environment variables to values which are not appropriate for normal processing, or generates output that is intended for you and not for your visitors.
To recreate the context in which the application is called by the WWW server, you need to set the corresponding environment variables. This can lead to one of the most annoying aspects of traditional CGI script creation and debugging. You must have exit the working environment, set the variables, and restart the environment; or you could set the variables from the script, but this is just as inconvenient.
EiffelWeb provides a better solution: set the variables on-the-fly by passing them as argument to the script. You will for example call the application as:
your_script REQUEST_METHOD=GET QUERY_STRING="name=foo"
setting the variables REQUEST_METHOD and QUERY_STRING to GET and to name=foo.
To set the default values, make_debug calls the procedure set_environment; in its version inherited from CGI_INTERFACE, set_environment does nothing, but you can redefine it to set environment variables to specific values. To set an individual environment variable, use set_environment_variable. The defaults will be overriden by the scripts arguments if any.
Here is an example class using these facilities:
Of course, you can still test your script manually and set the environment variables from the command line as follows (here expressed in C-shell syntax):
setenv REQUEST_METHOD "GET"
The creation procedure, whether make or make_debug, will catch any exception occurring during the execution of the script and will handle it according to the choosen option which set_environment can set by calling one of the three following procedures:
In all cases the application will not return an error code but keep control of the execution, therefore preventing the Web server from displaying its own message.
If you detect an irrecoverable error during processing, you can stop execution using procedure raise_error. This will display an error message, which you can set through an earlier call to set_error.
All the features listed in this section belong to class CGI_INTERFACE, whose complete specification appears in Appendix A.
Let's use again the basic example. Employing make_debug instead of make as creation procedure will allow us to change the debug level - e.g. to get the exception trace if an exception occurs. This will also allow us to set default values for some environment variables. This time instead of an indented list the results will be displayed in a bulleted list.