Your CGI now handles GET and POST requests, the two types of requests that would be received from a user's browser calling the CGI. In this section, you will add a third request method that uses command line parameters as the source of the CGI arguments, so that you can start a debug session for the project within the IDE, and supply the request you want to debug as the program's command line parameters. This change will allow you to debug new methods as you implement them later, using the debugging features of the IDE.
You will also implement the Reader::View function and an auxiliary function, ReadFile. The Reader::View function will have a bug in it that you will try to find and fix.
This section should take you approximately 45 minutes to complete. In it you will learn to perform the following IDE tasks:
If you are interested only in learning the IDE, and do not need to understand the details of the CGI application, you can skip paragraphs or sections titled Implementation Details.
You should have the following source files in a directory on your system. Click on the link to see the file's contents. Any changes you may need to make for your environment are indicated in the files.
If you have not yet exited the IDE, started it up again, and reloaded your project, the workbook sections may appear very crowded, because you have a workbook section for each of your source files.
Once your project has built successfully, the contents of all the source files will be represented in the codestore. You no longer need to have separate workbook sections for each file. You may find it easier to navigate the source files, functions, classes, declarations etc. through the Project section of the workbook You can remove each source file workbook section by clicking mouse button 2 over the section's tab and choosing Remove This Object's Workbook Section. However, if you want to remove a large number in one action, you can follow these steps instead:
You can open a series of workbook sections for different files by selecting each desired file in a Source Files view (for example, on the Overview page of the Project), clicking mouse-button 2, and choosing Open as a Workbook Section.
| Implementation Details: A CGI is never invoked with command line arguments from a user's web browser, but for debugging purposes it is useful to allow the arguments to be specified by the command line instead of environment variables. The lines you add below set the necessary environment variables so that the arguments provided at the command line can be treated as a regular GET request coming from a web browser. |
Add the following lines to the start of the main function, right after the opening brace:
if (argc>1) {
IString Args="";
for (int i=1;i<argc;i++) Args+=IString(argv[i])+"+";
Args.stripTrailing('+');
putenv("REQUEST_METHOD=GET");
char*TArgs=strdup("QUERY_STRING="+Args);
putenv(TArgs);
}
The ReadFile function returns the contents of a specified file. This is an auxiliary function, so you should add it to the source file funcs.cpp. You also need to include the fstream.h header file at the top of funcs.cpp. Although the file already has access to the fstream class (because fstream.h is included elsewhere in the program), it does not have access to the EOF macro that is defined when fstream.h is included, because macros do not have global scope by default.
To the top of funcs.cpp, add:
#include <fstream.h>
At the bottom of funcs.cpp, type or paste the following:
//... Previously defined functions
IString ReadFile(IString Path) {
ifstream In(Path);
if (!In) return "";
return IString::lineFrom(In,EOF);
}
| Implementation Details Currently, this function displays a message indicating that it is still unimplemented. You will change it to a function that does the following:
|
Before you start, you should first define the macro EXE in macros.hpp, so that it contains the full filename (but not the path) of the CGI executable file. Type or paste the following in macros.hpp:
#define EXE IString("review.exe")
Next, replace the current definition of Reader::View in user.cpp with the following code:
| Implementation Details: Note that a char* array is used to store the modified version of the requested file's contents; although the IString class supports a concatenation operator (+=), it reallocates storage for the target string after each allocation, which is less efficient than anticipating the total length required, and declaring a char* array sufficiently large to hold the final output string. |
// In user.cpp
IString Reader::View() {
// Call ReadFile to read the file pointed to by Request::FilePath
IString Result=ReadFile(Req->GetFilepath());
if (Result=="")
return Error("Could Not Read File",
"The file you requested, "
+Req->GetFilename()
+", was empty, or could not be read.");
// Find the first "href=" attribute.
int href=Result.indexOf("href=");
// Return if there are no href= tags to fix
if (href==0) return Result;
// Substitute the executable name and necessary arguments
// in all href= calls. EXE must be defined in macros.hpp
IString LinkInsert=EXE+"?Op=View+Key="+Req->GetKey()+"+file=";
// Allocate a new IString large enough to contain the new string,
// by determining the number of inserts to do.
int NewLength=Result.occurrencesOf("href=")
*LinkInsert.length()
+Result.length()+1;
char* NewResult=new char[NewLength];
NewResult[0]='\0';
int last=0;
while (href>0) {
// Write from last position written up to past the href=,
// and add the link insertion text
strcat(NewResult,
Result.subString(last+1,href+5-last)+
LinkInsert);
last=href+5;
href=Result.indexOf("href=",last);
}
return NewResult; // Automatically converted to an IString
}
Rebuild the project. You should see three identical errors, stating that the private member User::Req cannot be accessed. Because the Reader, Reviewer, and Author classes will often need to access information from the Request object, this member should be declared protected.
class User {
IString UserId;
virtual IString View() {return Unauthorized("View");}
virtual IString ShowAdd() {return Unauthorized("ShowAdd");}
virtual IString Add() {return Unauthorized("Add");}
virtual IString Complete() {return Unauthorized("Complete");}
protected:
Request* Req;
public:
User(Request* req) : Req(req),UserId("") {}
User(): Req(0), UserId("") {}
IString Action();
};
Rebuild the project. Before you try the Reader::View function, create a file with some links in it and save it as index.html in the directory to which the WebRoot macro points. (Use the file shown below even if you already copied a file to index.html in a previous part of the tutorial.)
You can create a file in the IDE that is not associated with the project by following these steps:
The index.html file should contain the following:
<html><head><title>Problems with Links</title></head> <body><p>Here are some common problems:</p> <ul> <li><a href="http://elsewhere.com/other.htm">Some links are offsite</a></li> <li><a href="nothere.htm">Some links are to nonexistent files</a></li> <li><a href="here.htm" target="elsewhere">Some links are to different frames</a></li> <li><a HREF="upper.htm">Some links have uppercase attributes</a></li> <li><a href=" there.htm">Some links are syntactically invalid</a></li> <li><a href="there.htm">Some links are fine but fail in the CGI</a></li> </ul> </body></html>
Save this file, then try out the following link to see how the Reader::View function works. This link uses a target attribute that causes a new browser window to open, so that you can view this tutorial and the file the CGI is displaying at the same time.
http://localhost:49213/cgi-bin/review.exe?op=View+key=reader+file=index.html
If you get an "unauthorized" error message, you did not create the user file defining access levels for Reader, which the UserFilepath macro in macros. hpp will point to. This is described in Source for macros.hpp. Once you have done this, try the link again.
When the index.html file is displayed, it should look something like the following:
Here are some common problems:
|
The last link got messed up by the CGI. You will correct this problem by debugging your program. If another browser window opened when you tried the third link, close the extra browser window now.
| Implementation Details None of the other links actually work, because:
If you intend to use this tutorial to create a working review tool, you can fix problems with these links yourself later, by adding additional code to the View function to anticipate offsite locations, href attributes in uppercase, and syntactically invalid links. |
The VisualAge IDE allows you to set breakpoints before you start a debugging session, and supports a wide range of breakpoints, including these breakpoint types:
Before you start debugging, it would be useful to set a function breakpoint in Reader::View, so that execution stops at the first statement in the Reader::View function.
Next, select the Debug page of the Project section. This page, which you will use to start a debugging session, is divided into the following panes:
Before you start the debug session, you need to provide the request to the CGI. Enter the following string in the Arguments field of the run specification:
Op=View+Key=reader+File=index.html
If you were to start debugging now, execution would stop on entry to main, because of
the entry point breakpoint. You have already set a function breakpoint for the function
you want to start debugging in, so you should disable the entry point breakpoint. Click
the
red octagon beside the Entry Point main of *
breakpoint; the red octagon turns green, indicating that the breakpoint is disabled.
If you try expanding different entries in the Breakpoints view of the project, you will see that all but the All Breakpoints breakpoint are childless. Each time you start a debugging session for the project, a child breakpoint specific to the new debugging process is added to each existing breakpoint, and that child breakpoint's state (enabled or disabled) is inherited from its parent. The IDE allows you to debug several copies of the project executable file as separate processes at the same time; you can disable or enable individual breakpoints at a project level by clicking the octagon beside a parent breakpoint, or at a process level by expanding the parent breakpoint and clicking the octagon beside the appropriate child. If you want to disable or enable all breakpoints, you can click the octagon beside All Breakpoints, until the breakpoint's state has overridden all child breakpoint states.
You are now ready to start debugging.
From the Debug page of the Project section, click the Debug button to start the debugging session.
When you start debugging a program, the IDE creates a process for that program, and a Process section in the workbook corresponding to that process. It also adds buttons to the toolbar; these buttons allow you to step through the process and perform other debugging actions. If the program is a console (non-windowed) program, such as this CGI, a console window opens so that console input can be obtained and output can be displayed. The IDE automatically regains focus after the console window is opened.
Normally you do your debugging from pages within a Process section. You can debug several versions of the same program by starting debug processes several times for the same executable file, using the same or different sets of arguments. To switch from debugging one process to another, select the Process section for the process you want to debug next.
The program should run until the first executable statement of Reader::View. (If execution stops at the start of the main function you did not disable the entry point breakpoint; press Ctrl+Shift+U to run to the next breakpoint.) The current page of the Process section is the Source page, which is divided into four panes:
The IDE provides hierarchical views so that you can view the same type of information for more than one object. For example, in the Threads view you can expand the stack entry for each of several threads, then expand the topmost stack frame for each thread to view the settings of local variables within each thread.
In the Local Variables view, expand the Result variable, then the
pBuffer member of Result. The data member pBuffer points to Istring's storage. The value
of pBuffer may be null, or the string may contain random data, indicating that no buffer
has been allocated. Step over the call to ReadFile by clicking the
toolbar button or by pressing Ctrl+Shift+O.
The contents of the buffer should change to show the start of an HTML file. Expand
NewResult to show its contents; this char array also appears to contain random data, as it
has not yet had storage allocated to it.
Since you are trying to debug the eventual contents of NewResult, you should run the program up to the point where NewResult has a first substring concatenated to it.
You can also click the gray square in the left margin beside the statement to set a
breakpoint on the first statement of the line, then click the run button
in the toolbar to run to the first breakpoint.
It would be easier to debug the concatenations of source string parts to the target string if the target string were displayed in a flowed view, so that you did not have to keep scrolling to the right. Follow these steps to obtain a Storage view of the target string; this will help you learn to use the Storage view of the debugger portion of the IDE.
The default storage view is not suitable for viewing the contents of long text strings. To change this view to something more suitable, follow these steps:
It would also be useful if the start of the string were at the top of the Storage view.
You can move it up by clicking the single down-arrow (
)
to the left of the Addresses column.
The Source view of the process is not visible on the Storage page, but this is the view you need, so you can step through your code while watching how each statement affects the contents of the NewResult character array. Follow these steps to add a Source view:


You can now step through the source code and watch the NewResult string grow. The
debugger provides several types of step commands. The Step Over command (
or Ctrl+Shift+O) lets you step over source
code statements without stepping through any code that may be called by them. Other step
commands include Step Debug, Step Into, and Step Return. If you are interested in the
types of breakpoints available, see Types
of Breakpoints.
Step over the statements in the while block one by one. Notice, each time the NewResult string is concatenated to, that the storage view updates to show the changed contents in red. On the next step command, the red changes to black. Continue stepping until the while loop ends. Suddenly the bug becomes clear: you have not concatenated the remainder of the file after the last reference you processed.
Add the following code in the current source view, before the return statement:
if (last>0) strcat(NewResult,Result.subString(last+1));
Before you rebuild the project, click the Run toolbar button to run to the end of the program. If you do not run to the end of the program, when you rebuild you will be warned that all currently running processes will be terminated. The IDE prompts you for this because you cannot change the object code in an executable file while that executable is running, and you may need to run your executable to the end if you have any writable files open, otherwise their data may be lost. Since you are not accessing any files in write mode, click OK. Once the program is rebuilt, try running it again from your web browser, at:
http://localhost:49213/cgi-bin/review.exe?op=View+key=reader+file=index.html
The last link in the HTML document should display correctly:
Here are some common problems:
|
Notice that you have just made a source code correction in the middle of a debugging session. The source code change does not affect the current process being debugged; you could have continued stepping through the old version of your executable file, and the source code change would be remembered. Even if you terminate a debuggee process after changing code in a Source view from the Process section, your changes are remembered.
You can now go straight to Part 8, or work through Part 6, Part 7, or both.
If you feel you have already learned enough about the VisualAge IDE to start doing your own coding, and you do not plan to use the web-based review tool, you can stop doing the CGI tutorial now, and proceed to the next section on creating a GUI.
