Part 9. Defining the Remaining User Functions

In this section you will implement the ShowAdd and Add functions of the Reviewer class, which respectively display a form for adding a comment, and add that comment. You will also implement the Complete function of the Author class, which marks a comment as completed.

This section should take you approximately 30 minutes to complete. It does not introduce any new IDE concepts or tasks. You can use it to strengthen your understanding of the IDE, and you can complete it if you want to have a working web-based review tool which you can later refine and enhance to suit your needs. If you do not need such a tool, you can proceed directly to Develop a Graphical User Interface from a Visual Part.

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.

Complete the Function Implementations

Implementation Details: The Reviewer::View function already does most of what you need for the ShowAdd function. You will begin by copying code from that function into Reviewer::ShowAdd. The only change you will make will be to insert the comment form at the appropriate location in the file. The Author::Complete function is also very similar to Reviewer::View; it finds the incomplete comment in the comment file, changes its status to completed, then shows a new view of the requested file with its comments.

Follow these steps to complete the function implementations, within user.cpp:

  1. Copy the body of the Reviewer::View function and paste it into Reviewer::ShowAdd. The Reviewer::ShowAdd function should now read as follows:
    IString Reviewer::ShowAdd() {
        // 1. Get the file contents
        IString Result=LinkFix();
        if (Result=="")
          return Error("Could Not Read File",
             "The file you requested, "+Req->GetFilename()
            +", could not be read, or was empty.");
        // 2. Initialize the CommentSection Array.
        CreateSections(Result, false);
        // 3. Print the CommentSections
        Result="";
        for (int cs=0;cs<CurCs;cs++) Result+=Section[cs].Print();
        return Result;
     }
  2. Add a statement before the call to LinkFix to determine the line number where the user wants to add a comment. Use the Request::GetValue function to determine this value:
    int LineNum=Req->GetValue("line").asInt();
  3. Add the following after the call to CreateSections:
    if (CurCs<LineNum)
       return Error("Cannot Insert Comment",
          "A section for inserting comment "
          +IString(LineNum)
          +" cannot be found.");
    Section[LineNum].SetShowInsert();
  4. To insert the Add Comment form, add the following to CommentSection::Print() in comment.cpp immediately before "Result+=Text;"
       if (ShowInsert) {
           Result+="<table border=1><tr><td>Add a Comment<br>\n";
           Result+="<form method=post action=\""+EXE+"\">\n";
           Result+="<input type=hidden name=key value="+Req->GetKey()+">\n";
           Result+="<input type=hidden name=file value="+Req->GetFilename()+">\n";
           Result+="<input type=hidden name=op value=add>\n";
           Result+="<input type=hidden name=line value="+SNumber+">\n";
           Result+="<textarea name=text rows=10 cols=60>\n</textarea><br>\n";
           Result+="<input type=submit name=Submit value=Submit></form></td></tr></table>";
       }
  5. Rebuild your project. Access the HTML file by clicking on the following link, or entering its text in your browser's URL field:

    http://localhost:49213/cgi-bin/review.exe?op=View+key=reviewer+file=index.html

    Try adding a comment in this file, by clicking on a numbered hypertext link. A form for adding your comment should appear. Enter some text in the comment form and click Submit. You should get an error message saying that the Reviewer version of the Add function is not yet implemented.

  6. Next, redefine the Add function by deleting the existing definition from user.cpp and entering the definition below.
    Implementation Details: The Add function first tries to open the comment file in append mode. It tries up to 50 times to do so, waiting 50 milliseconds after each try, in case another process is also trying to modify the comment file at the same time (for example, two users adding comments at once). If the comment file still cannot be opened, an error is returned. If it can be opened, the required markup and information for the comment are appended, including the current date (created from the IDate static member function today()) and time (created from ITime::now).
    IString Reviewer::Add() {
       // Open file in append mode
       ofstream CmtFile(Req->GetCommentFn(),ios::app);
       int tries=50;
       while (!CmtFile && tries>0) { // Try up to 50 times
          CmtFile.close();
          IThread::current().sleep(50);
          tries--;
          CmtFile.open(Req->GetCommentFn(),ios::app);
       }
       if (!CmtFile)
          return Error ("Comment File Locked",
       "The comment could not be added. The comment file may be locked by another process.");
       // Write out the markup and comment information
       CmtFile << "<cmt> "
               << Req->GetValue("line")
               << " u "
               << GetUserId() << " "
               << IDate::today().asString("%m/%d/%Y ") << " "
               << ITime::now().asString("%H:%M\n");
       // Read the entire request string, then cut it down to contain only the text
       // of the comment, which spans from "text=" to "Submit=Submit"
       // Submit=Submit comes from the user pressing the Submit button.
       IString Text=Req->GetReqString();
       int texteq=Text.indexOf("text=");
       // Exclude up to and including "text="
       Text=Text.subString(texteq+5);
       int sub=Text.indexOf("Submit=Submit");
       // Exclude from Submit=Submit to end
       if (sub>0) Text=Text.subString(1,sub-1);
       if (Text=="") Text="No text in comment";
       CmtFile << Text << "\n" << "</cmt>" << endl;
       CmtFile.close();
       // Finally, call View.
       return View();
    }
  7. Add the following three header files, either to a source directive in your configuration, or using #include <iheader.hpp> directives at the top of user.cpp:
  8. Rebuild the project. You will probably encounter one error: a reference to an undefined function, GetUserId(). Add the following as a public function inside the declaration for the Reviewer class:
    IString GetUserId() { return UserId; }

    Currently, UserId is a private member of the User class, so if you rebuilt now you would get an access error. Move the declaration for UserId from the private to the protected section of the User class declaration (right after the Request* object).

    You also need to set the value of UserId, which is currently not set anywhere. Add a SetUserId() function to the public section of the User class:

    void SetUserId(IString u) {UserId=u;}

    Then set the user ID by adding the following in your main function (in main.cpp), after the switch block:

    U->SetUserId(UserLine.word(3));

    The GetUserId function is defined in Reviewer, because it is only called from Reviewer::Add (a default user does not have a user ID). The SetUserId function is defined in User, because it is called by the polymorphic User* object in main.

  9. Rebuild the project. Before you try out the CGI, you need to modify the users.dat file by adding a user ID or name after each user's key and authority level. Edit the file and change it, for example, to the following. The file is located in the path specified by the UserFilepath macro.
    reader 1 Arthur_Green
    reviewer 2 Roland_Burgess
    author 3 Kay_Smith
  10. Try adding a comment again. This time, you should see the text of your comment along with a user name, the date, and time, imbedded in the text of the document. The URL to view your file is:

    http://localhost:49213/cgi-bin/review.exe?op=View+key=reviewer+file=index.html

  11. Implement the Author::View function. It is almost identical to Reviewer::View. The only difference is that the second argument to the call to CreateSections is set to true instead of false. This argument to CreateSections is then passed on to each CommentSection and CommentType object, so that the CommentType::Print function prints a link to allow the author to complete the comment. Mark the body of the Reviewer::View function (use Alt+L at the top and bottom lines of the body) and copy it into Author::View (use Alt+C); change the call to CreateSections as noted.
  12. The final function to implement is Author::Complete.
    Implementation Details: A request to complete a comment should contain the file, line, and comment number of the comment to complete. These arguments can be parsed out by the Request::GetValue function. The Complete function then opens the file in binary mode, reads in characters until it finds the byte whose value of 'u' (for "Unhandled") needs to be changed to 'c' (for "Completed"), writes out only that byte, and closes the file. This approach minimizes file I/O by reading only the bytes than required to locate the comment to complete, and by writing only a single byte of output.

    Change the definition of Author::Complete to the following:

    IString Author::Complete() {
    // Open the file in binary read-write mode. If the file doesn't exist,
    // there are no comments.
       FILE* stream=fopen(Req->GetCommentFn(),"rb+");
       if (!stream)
          return Error("Could Not Complete Comment",
            "The comment could not be completed because the comment file, "
            +Req->GetCommentFn()
            +", could not be found.");
       char* Buffer=new char[256];
       IString CommentFile="";
       int CommentNum=Req->GetValue("cmt").asInt();
       int LineNum=Req->GetValue("line").asInt();
       IString ThisCmt="<cmt> "+IString(LineNum)+" ";
       int bytesread=fread(Buffer,sizeof(char),256,stream);
       CommentFile+=Buffer;
       // Read in the file 256 bytes at a time. 
       // Continue reading until the number of comments for this line
       // is at least equal to the comment number the Complete applies to
       while (bytesread>0 && CommentFile.occurrencesOf(ThisCmt)<CommentNum) {
          bytesread=fread(Buffer,sizeof(char),256,stream);
          CommentFile+=Buffer;
       }
       // Find the comment position of the nth comment for this line
       int lastpos=0;
       int thispos=CommentFile.indexOf(ThisCmt);
       for (int i=1;i<CommentNum;i++) {
          lastpos=thispos;
          thispos=CommentFile.indexOf(ThisCmt,thispos+1);
       }
       // If that comment's completion code is 'u' change it to 'c'
       if (CommentFile[thispos+ThisCmt.length()]=='u') {
          fseek(stream, thispos+ThisCmt.length()-1,SEEK_SET);
          fputc('c',stream);
          fclose(stream);
       }
       // If you like, add an error return here that returns a
       // message stating that the comment was already completed.
       return View();
    }
  13. Rebuild the application. You may find that SEEK_SET is undefined. If so, add the directive #include <stdio.h> at the top of user.cpp and rebuild again.
  14. Try completing a comment. You will need to use an author user ID to do so; try accessing the file from this link:

    http://localhost:49213/cgi-bin/review.exe?op=View+key=authorr+file=index.html

The CGI portion of your program is now complete. You can now review your own web documents by adding the documents to your WebRoot directory tree; you can let others review them by adding their user IDs, passwords, and authority levels to your users file. This program is still only a prototype. You may want to enhance the error handling and the types of HTML markup to which it allows comments to be added, and you may want to enable it to work with first and last names.

If you wanted to ship this program to customers now, you would first need to change the configuration so that the version produced used the static version of the run-time libraries. If you completed Part 6. Managing Configuration Files, you have an easy way of doing so - change the value of ReadyToShip to "true" and rebuild. However, there is still some work to do before you have a program you can present to users who will be installing the CGI to run from their web servers. Your users probably do not want to edit a user management file directly; you need to create a graphical user interface (GUI) program that runs locally, not through a browser, so that the administrator of the machine running the CGI can create and manage user IDs. In the next sections, you will learn to use the Visual Builder component of VisualAge C++, along with the IDE, to create the GUI interface and the user management code.

You have now completed the CGI portion of the VisualAge C++ tutorial.

You can proceed from here to: