Back in Visual C++, put your cursor in the source code at the start of the LAPI_MAIN line and select Build->Start Debug->Run to Cursor, as shown in Figure B.

FIGURE B

To start the program running, you select Start Debug->Run to Cursor from the Build menu. Click picture for a larger image.

A DOS box should appear briefly, and a new section becomes visible in the VC++ IDE to show you (on the left) what the values of variables currently defined (select the "locals" tab) and (on the right) a blank display giving you a facility to watch the value of any variable you define. You just type in the name of the variable.

Since you're at the start of the program, the only two variables are argc and argv, as you can see in Figure C. If you're not a programmer, this sort of display can be baffling, but if you're a programmer, it'll warm your heart. Basically, this thing is a debugger, a device for walking through program code to see, line-by-line, exactly how the code operates. Sometimes the only way to find a bug is to watch every single line of code interact with every data object in the program.

FIGURE C

The debug run has started. Click picture for a larger image.

The yellow arrow on the left shows the line of source code reached so far, and in the context window shown below the arrow, the values of program variables appear. Argc is set to 4, as this is the number of arguments (argc is short for "argument count") the program received when it started. The four are aclhelp, test.nsf, Mickey, and Mouse. Since argv (i.e., argument vector or argument variables, depending on who's religion you believe) is an array, all you can see is the address in memory of the array. If you press the F10 key, you can watch the program execute a line at a time. F10 allows you to step through the code and "step over" any function calls. If the function call is a Lotus one that you don't have the source code to, you'll have to step over it. If the function call is yours, you can use the F11 key to "step into" the function and execute that a line at a time too.

When you get to the line that checks the number of parameters to see if there were enough, you should see the cursor skip over the bracketed code since there were enough parameters entered at the start to avoid the error message. Now press F10 to move past the lines that copy the strings (strcpy) from the argv array into our variables pathname and entryname. Once those lines have been executed, you should be able to check their content. In mine, the pathname is now "test.nsf" and entryname is "Mickey".

Now we have our first design problem. The user didn't put the entryname inside double quotes. If they had, entryname would contain Mickey Mouse, not just Mickey, as seen in Figure D.

FIGURE D

As the run continues more parameters appear. Click picture for a larger image.

Since a space separated "Mickey" from "Mouse," the C program thought it was a new parameter. So, since most user names contain spaces, I added a loop to the code to read these extra parameters and add them on to entryname with a space between them. Of course, the same applies to pathname since paths can have spaces too, but since it's not the last parameter, we can't do much about this except to tell users to put double quotes around pathnames that include spaces. As you F10 down to the first "for" loop, you'll see the program add "Mouse" to the end of the entryname using the "strcat" string concatenation function. This is pictured in Figure E.