|
|||||||||
|
|||||||||
Functions | Platforms | ||||||||
omcgi (test version) - CGI testing |
The OmniMark CGI testing library is provided as a companion to the OmniMark CGI library. This library uses a simulated CGI program environment: rather than retrieving input data from environment variables or through standard input, it retrieves the data from a file generated by the "capture.xom" CGI program. The file that the capture utility generates is a simple XML-like file in which the environment variable and query string information is stored. The functions in the CGI testing library use the contents of this file to simulate a CGI program retrieving input from the web server.
The CGI testing library allows you to develop and debug your OmniMark CGI programs using the OmniMark Integrated Development Environment (IDE). When you run your CGI program in the OmniMark IDE using the CGI testing library, you can see the input your CGI program is receiving through the simulated environment, and see the output of your CGI program displayed in the IDE log window. Additionally, you can use all of the editing and debugging tools in the IDE to develop and debug your OmniMark CGI programs.
For more information about writing CGI programs with OmniMark, please see CGI programming with OmniMark.
The CGI testing library consists of a single include file, "omcgi.xin", and a companion OmniMark utility program called "capture.xom". Note that these files are in a subdirectory of the OmniMark samples directory, not in the samples directory itself. This allows you to change which "omcgi.xin" library file you are using in your CGI program simply by changing the include directory paths in your arguments file or on the command line. You do not have to change any code in your CGI program when you are finished debugging your CGI program in the IDE because the library filenames and function calls are exactly the same.
You can see how this library works by opening and running the "newcgilib.xop" project in the OmniMark IDE. This project is included with the other sample programs that are part of the IDE package.
Using the capture.xom utility
The capture.xom program is an OmniMark CGI program that captures the environment variable and query string data and stores that data in the XML-like file.
Use capture.xom instead of your CGI program to retrieve and process the input data sent by the web server. For example, if you are creating a guestbook CGI application that includes the files "guestbook.xar" (an arguments file) and "guestbook.xom" (the main program file), the "action" attribute in your "<form>" tag would look something like this:
action="c:\inetpub\scripts\guestbook\guestbook.xar"
To use the capture.xom utility, you would create an arguments file called "capture.xar" and you would change the "action" attribute to point at this new arguments file:
action="c:\inetpub\scripts\cgitest\capture.xar"
You also need to tell the capture utility what file you want the input data stored in. You can do this by adding a "-d" option to your "capture.xar" arguments file to define the value of the cgiTestFile variable declared in the "omcgi.xin" file (CGI testing library version). For example:
-s "c:\inetpub\scripts\cgitest\capture.xom" -i "d:\programs\omnimark\samples\cgi\" -i "d:\programs\omnimark\xin\" -x "d:\programs\omnimark\lib\=L.dll" -alog "c:\inetpub\wwwroot\logfiles\capture.log" -d cgiTestFile "c:\inetpub\scripts\cgitest\captured-file.xml"
When you submit the form, the capture utility captures the CGI input data and stores it in the file you name in the cgiTestFile variable. When the capture utility has successfully captured, processed, and stored the CGI input data, it sends a message to your browser informing you that the capture was successful.
When the input data is captured into the XML-like file, you can use the file along with the OmniMark CGI testing library to develop and test your CGI programs in the OmniMark IDE.
Using the OmniMark CGI testing library
You use the OmniMark CGI testing library in almost the same way you use the OmniMark CGI library. The only differences are these:
-d cgiTestFile c:\inetpub\scripts\cgitest\captured-file.xml
.
The "omcgi.xin" file for this library contains the CGI testing function and macro declarations.
As with the OmniMark CGI library, you must declare the #process-input
stream as unbuffered
. If you do not, on some systems your CGI program will hang.
Note that when using the CGI testing library, you must specify the "samples/cgi/" directory as well as the "xin/" directory in your list of include directories. The "samples/cgi/" directory must be specified first. When using the IDE, you specify your include directories in the project configuration dialog box.
After you're finished debugging your CGI program
When you've finished developing and debugging your OmniMark CGI program in the IDE, you only have to make a couple of minor changes to turn it into a "live" CGI program that interacts directly with your web server:
For further information about CGI programming with OmniMark, please see CGI programming with OmniMark.
Include the following code for the test version of omcgi at the beginning of your OmniMark CGI programs, and note the one difference from the CGI library: you include "\Samples\omcgi.xin":
declare #process-input has unbuffered declare #process-output has binary-mode declare #process-output has unbuffered include "builtins.xin" include "omutil.xin" include "\Samples\omcgi.xin"
Functions cgiGetEnv (CGI Testing library) cgiGetQuery (CGI Testing library) |
Platforms Digital UNIX (Alpha) HP/UX IBM AIX Linux (Intel) MS Windows 95/98 MS Windows NT SGI IRIX SINIX Sun Solaris |
---- |