Is That Valid?

by Matt Smith

''Have you ever been in the situation where your application just wasn't doing what it was supposed to be doing on a target machine and you wanted to see the error return codes? What about the times when you have a user on the other side of the building (or the world for that matter) and he or she is running into problems? Don't you wish that you had a way of logging the error returns provided by the operating system? Or what about the times when you can't figure out why your window wasn't created?''

Well, now you can through a new tool, Validator for OS/2, that was introduced for Beta on the last issue of The Developer Connection for OS/2 CD-ROM. This tool that can help you solve life's little programming mysteries, as well as help make your applications run efficiently when finally released.

What is Validator for OS/2?
Validator for OS/2 is a set of DLLs that step in-between your application and the OS/2 APIs. Each call that you make to an OS/2 API is rigorously checked to make sure that each parameter passed to the OS/2 API is valid. When an invalid parameter is detected, an enhanced return error code specifically indicates which parameter is in error and why.

You may be asking "Why would Validator for OS/2 be needed when the OS/2 APIs already provide parameter validation?" Valid question that can best be answered by looking at how the operating system validates certain parameters versus the mechanism used within Validator for OS/2.

Let's look at the DosOpen API to see what happens. Two of the parameters are bit flags. OS/2 validates these flags by AND'ing the passed parameter with the invalid bits. If any bits remain, an invalid bit flag was passed to the API and usually the ERROR_INVALID_FLAG will be returned. But, which of the flag parameter is in error?

Validator does basically the same thing, but when it checks the bit flags, it tells you which area of the bit flags you have used incorrectly along with the parameter number.

Why doesn't OS/2 do this? Simple, it will slow down the call. Applications using the Validator for OS/2 support can experience up to a 10% decrease in speed.

Getting this information from Validator for OS/2 is very useful, especially when you are monitoring the return values through the debugger. But the validation support doesn't stop there. You can request through the ValInitialize API, provided by Validator for OS/2, to have this error information logged to an error file.

Even further, you can ask the same API to monitor the errors in real-time through a tool called ViewPort that is also provide with Validator for OS/2. ViewPort will show the error information and depending on how you compiled your application, will show the name of the file along with the line number where the error was detected.

Validator for OS/2, not only rigorously validates the parameters of an API, it monitors the return codes such that when an error is detected, the error information is logged or passed to ViewPort. This lets you see even the errors that you might be expecting.

These different levels of support within Validator for OS/2 let you use it through almost all of the stages of your application development.

What Am I Doing Wrong?
To give you an idea of what Validator for OS/2 does, consider the following:

HPS  hPS;          /* Presentation Space Handle        */ RECTL rcl;         /* Window Rectangle                 */ WinQueryWindowRect(hWnd, &rcl); /* Assume window size is 25 x 50 */ rcl.xLeft += 50L; WinFillRect(hPS = WinGetPS(hWnd), &rcl, CLR_CYAN); WinReleasePS(hPS); ''Figure 1. Sample Source Code''

The problem in the source code doesn't seem very apparent and appears quite valid. The actual error is that the xLeft field of the rcl structure will be larger than the xRight field.

When the updated rcl structure is used within the WillFillRect API, the validation routines will check the range of the fields within the rcl</tt> structure and return an error stating that the xLeft</tt> field is greater than the xRight</tt> field.

So how is this manifested through Validator for OS/2? Well, depending on the level of support requested through the ValInitialize</tt> API and how you prepare your source code, you will see a variety of reporting mechanisms. On the simplest level, you could perform a WinGetLastError</tt> after the WinFillRect</tt> and through the high byte of the error return, you would see a value of 0x0b</tt>. This is defined as being PERR_WFR02_XRIGHTLTXLEFT</tt> for the API in the validation errors.

The second level is where you have requested through the validation API's to log the error information to a specified error file. You would see the following: ''Figure 2. Error file''

The third level is where you have requested through the validation API's to have the error information passed directly to the ViewPort utility that will, in turn, display the error within a monitoring window. When you select the error within the ViewPort monitor window by double clicking on the entry, you will see the following window:



''Figure 3. Error Info window''

Each level has its purpose within the development cycle. Basically, the first and third levels are used during the development of the application and the second level is used both for internal and external testing. Most often, you will use the third level in the development process because you will be able to monitor the errors as you test the application after adding new features or enhance its operation.

When placing your application within a Beta cycle, you can include the validation DLLs with your distribution files such that the application is monitored and the error information is either logged to an ASCII file like that in Figure 2 or to a file that is readable through ViewPort producing information like that in Figure 3. Depending on the logging type, the ASCII file will only contain basic information on the error, whereas the ViewPort logging file will contain much more detailed information.

You can than either have the Beta user fax you the output of the ASCII file or email the ASCII or ViewPort format logging file.

The Next Release of OS/2
With the pending release of a new version of OS/2, Validator for OS/2 plays even a larger role within the development process. Validator for OS/2 does not depend on the DosDebug</tt> API, so you can run applications prepared for Validator for OS/2 and ViewPort on machines that are running the next version of OS/2. You will still be able to see the errors that occur - such that Validator for OS/2 almost becomes a tool for spying.