3.2.1 Parameter Validation

Windows 3.1 contains code to validate parameters passed to Windows functions and messages. These features are included in both the retail and debugging versions of the system. The debugging version of the system includes some additional features and parameter checking that is not included in the retail product.

3.2.1.1 Invalid Parameter Error Messages

The system validates handles, pointers, structures, indices, and flags. In most cases, an invalid parameter causes a function to return an error value. In other cases, such as when a flag is invalid, the function executes as usual, but an appropriate warning message is displayed.

When Windows encounters an invalid parameter error, it displays the message on your debugging terminal or window. The message has the following form:

err AppName function:address: message:parameter-value

Following are the message parameters:

AppName

Identifies the application or DLL that caused the error.

function

Identifies the number of the function that was passed the invalid parameter.

address

Identifies the address of the function that was passed the invalid parameter.

message

Specifies the string identifying the error.

parameter-value

Specifies the value of the invalid parameter.

For example, a message could have the following form:

err FONTSAMP 011F:056A: Invalid local handle: 1D50

If the address is not near the address of a Windows function you recognize, the window message parameter is probably invalid. Functions that take messages, such as SendMessage, DispatchMessage and SendDlgItemMsg, show an address within the message validation code. Parameter values for invalid parameters begin with the PV prefix (for example, PV_WM_COMMAND).

By default, invalid parameter messages display a stack trace and an “Abort, Break, or Ignore?” prompt. You can change the default by setting options in the System Debug Options box of the Systems Debugging Log Application (DBWIN.EXE). This dialog box is displayed when you choose the Settings command on the Options menu. (For more information about DBWIN.EXE, see Section 3.3.2, “Using the System Debugging Log Application.”)

You can also log invalid parameter errors by using Dr. Watson, just as you would log general-protection (GP) faults by using Dr. Watson. By default, this feature is turned off. For more information on invalid parameter error logging, see Microsoft Windows Programming Tools.

3.2.1.2 Buffer Overflow Errors

A common application error is to allocate too little space for a buffer that is passed to and filled by Windows. These errors are especially difficult to track if the buffers are allocated on the stack. Windows can help you find these errors by filling buffers before information is copied into them. If the operation overflows the buffer, Windows detects and reports the error.

By default, this feature is disabled. You can enable the feature by choosing the Settings command on the Options menu of DBWIN.EXE and then selecting the Fill Buffers check box. When you select this check box, Windows displays a stack trace and an “Abort, Break, or Ignore?” prompt with some warning messages.

This feature is available in the Windows debugging version only.

3.2.1.3 Interpreting Invalid Parameters

Possible reasons for getting invalid parameter errors follow.

Invalid Handles

A handle is invalid under the following circumstances:

Using NULL or –1 when it is not allowed

Reusing a destroyed or deleted handle

Using an uninitialized stack variable

Using a device context handle created by the CreateIC or CreateMetaFile function in a function that does not allow the handle

Passing one type of handle in place of another, such as passing a device-context handle in place of an window handle

Invalid Pointers

A pointer is invalid under the following circumstances:

Using a NULL pointer when it is not allowed

Pointing to a buffer that is too small

Using a function pointer without properly exporting it or properly creating a procedure-instance address

Pointing to a string that does not have a null-terminating character

Pointing to a structure that contains an invalid member (for example, if you call the RegisterClass function with a invalid window procedure in the CREATESTRUCT structure, Windows reports an invalid pointer)

Using an uninitialized stack variable

Passing a read-only pointer when a read-write pointer is required

Invalid Flags or Value

A flag or value is invalid under the following circumstances:

Passing meaningless flags

Passing an out-of-range index

Using a value that is otherwise illegal

You can use pointer-validation functions (such as IsBadCodePtr) to help you check for and debug your application's use of pointers.