Part 5. Debugging and Revising Your Application

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.

Prerequisites If You Are Starting Here

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.

Remove Unneeded Workbook Sections

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:

  1. Select the Workbook section, Overview page. This page shows a Table of Contents view, which is a list of the current sections and pages of the workbook.
  2. Scroll down the view to the first File section.
  3. Select that section by clicking mouse button 1 on the section entry.
  4. Hold down the Ctrl key, and click each other workbook section you want to remove.
  5. Click mouse button 2 while over one of the selected entries, and select Remove This Object's Workbook Section from the pop-up menu.

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.

Change the main Function to Accept Command Line Arguments

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);
      }

Define the ReadFile Function in funcs.cpp

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);
}

Redefine the Reader::View Function in user.cpp

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:

  • Retrieves the contents of the requested file, using the ReadFile function you just defined.
  • Changes all <a href=...> links in the document to calls to the CGI with the correct op=, file=, and key= values. When the link is followed, the CGI is invoked to display the new file.

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.

  1. Obtain a Source view for the declaration for the User class.
  2. Select the line in the Source view containing Request* Req;.
  3. Press Alt+L. This keystroke shortcut highlights a line for moving, copying, or deleting.
  4. Move the cursor down to the line before the public access specifier.
  5. Press Alt+M. This keystroke shortcut moves the currently selected text below the current line.
  6. Press Alt+U to remove the highlight.
  7. Insert the protected access specifier above the Request declaration. The class declaration should now look like this:
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:

  1. Select Project Workbook - Open File from the titlebar menu or press Ctrl+O.
  2. Enter the new file name, index.html.
  3. Select Open as a Workbook Section.
  4. Make sure that the Add to Project check box is not checked. Click Open.
  5. After you enter the text, remember to save the file. (Files that are not part of your project are not automatically saved when you build.) Press Ctrl+S, click the Save File button from the toolbar, or select Source - Save File from the titlebar menu.

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:
  • Some links are offsite
  • Some links are to nonexistent files
  • Some links are to different frames
  • Some links have uppercase attributes
  • Some links are syntactically invalid
  • <a href="review.exe?Op=View+Key=reader+file=

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:

  • The first link, to an offsite location (one starting with http://) should not have been modified by the CGI.
  • The second and third links point to files not found in the WebRoot directory. These two problems are easily solved by creating the necessary files. The second link points to a frame that does not exist, so a new browser window opens to display the error message.
  • The fourth link has its href= attribute in uppercase (HREF=) and so this was not found by the CGI. However, because the browser considers the referring document (your CGI) to be stored in the cgi-bin directory, it adds "cgi-bin" to the path of the link.
  • The fifth link was syntactically invalid (the href= attribute began with a space).

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.

Set and Disable Some Breakpoints before You Start Debugging

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.

  1. Locate the Reader::View function in any view that displays the function and shows an object to its left, for example the Members view of the Reader class (from the Classes page).
  2. Position the mouse pointer over this symbol, and click mouse button 2. From the pop-up menu, select Set function breakpoint or Set virtual function breakpoint (since the Reader class is the class whose View function you want to debug, either breakpoint type will do).

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.

Start the Debug Session

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:

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.

Debug the String Concatenation

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.

  1. Find the statement last=href+5 (use the Live Find entry field, or scroll down the Source view until you find it).
  2. Position the mouse pointer over this statement in the source view and click the right mouse button.
  3. Select the object, and from the cascading menu select Run to This Statement.

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.

  1. Select the Storage page of the Process section.
  2. Increase the height of the Threads view by moving the mouse over the line dividing the threads pane from the panes below it, then dragging the line down until you can view at least five lines of the Threads view.
  3. Expand the Thread object, and the Stack object of the thread. The current stack frame for the thread is displayed in an expanded state. Select this stack frame; it should be the stack frame for Reader::View.
  4. Scroll down through the local variables of the stack frame to the Result variable. Expand this variable as you did earlier, and expand its pBuffer member to display the contents of the Result string. Select the contents; notice that the Storage view at bottom right updates to show the start of storage for that string.
  5. Scroll down further to the NewResult variable and expand it, then click the text contents shown for it; the Storage view now shows the contents for that string.

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:

  1. Click the arrow to the right of the int column header, then select Destroy from the pop-up menu. This removes the column from the Storage view.
  2. Remove the Single byte character column as well. You now see only the void* column and the Addresses column.
  3. Click the arrow to the right of the void* column, and expand the Choose a built-in type choice. Change the built-in type to Single byte character. When you have made this change, click the arrow to the right of the void* column again to minimize the pop-up list.
  4. Expand the Storage Options entry at the top of the storage view.
  5. Expand the Number of bytes per line entry beneath this, and change the number of bytes to 32.
  6. If you want, you can increase the number of lines of storage displayed, also from the Storage Options.
  7. Collapse the storage options. If you cannot see all 32 characters of each line of text, drag the left edge of the pane farther to the left, or change the number of bytes per line to a smaller number.

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:

  1. Hold down the Ctrl key and position the mouse pointer over the right edge of the Threads view.
  2. When the pointer icon changes to an arrow, drag the new pane left until it takes up half the top portion of the window.
  3. Click the arrow to the right of the object shown on the title bar of the view.
  4. Select Opened Objects from the pop-up menu.
  5. Select the object for the current process from the menu below that to set the object type of the new pane to the process object for this process.

  6. A Help Tip appears warning you that changing the object type of the pane will detach the pane from other panes that link to it. Click OK.
  7. Change the View type to a Source view, by clicking the arrow to the right of the Details entry in the view's title bar, and choosing Source.

  8. Another Help Tip appears; click OK again.
  9. If you cannot see enough of the Source view (at least four or five lines of source code), slide the bottom edge of the Source view's frame down. This also resizes the adjacent view. You can obtain even more screen space for the views by maximizing the screen with the Maximize button above the project toolbar, on the far right. This hides the workbook sections. To display them again, click the restore button that has replaced the maximize button.

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:
  • Some links are offsite
  • Some links are to nonexistent files
  • Some links are to different frames
  • Some links have uppercase attributes
  • Some links are syntactically invalid
  • Some links are fine but fail in the CGI

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.