Microsoft KB Archive/107873

= VB ver 3.0 CDK TN002.TXT: Custom Control Version Management =

Article ID: 107873

Article Last Modified on 1/8/2003

-

APPLIES TO


 * Microsoft Visual Basic 3.0 Professional Edition

-



This article was previously published under Q107873



SUMMARY
The following article contains the complete contents of the TN002.TXT file installed in the CDK directory of the Professional Edition of Visual Basic version 3.0 for Windows.



TN002.TXT
Microsoft Visual Basic version 3.00 for Windows

Microsoft Corporation Technical Notes

TN002.TXT: Custom Control Version Management

This note describes how to use the version management functionality for custom controls.

Introduction
Visual Basic provides upward compatibility for custom controls. This means that a custom control created for Visual Basic version 1.0 will run in Visual Basic versions 2.0 and 3.0. If a custom control uses version- specific features, a custom control can always explicitly test for a specific version during initialization and thereby determine whether or not to load.

There are cases, however, when a Visual Basic application created with a new version of a custom control runs on a system with an older version of the custom control. Depending on the features and implementation of the custom control, the application may not work correctly -- or worse, may cause VB.EXE or VBRUNx00.DLL to crash.

The following sections describe Visual Basic version 3.0's custom control version management system, which can help avoid potential application failure.

MODEL Structure
This is the definition of the MODEL structure used in Visual Basic version 3.0. Note the addition of the last field (USHORT usCtlVersion). typedef struct tagMODEL {   USHORT      usVersion;           // VB version used by control FLONG      fl;                  // Bitfield structure PCTLPROC   pctlproc;            // The control procedure FSHORT     fsClassStyle;        // Window class style FLONG      flWndStyle;          // Default window style USHORT     cbCtlExtra;          // Number of bytes allocated // for control structure USHORT     idBmpPalette;        // BITMAP ID for tool palette PSTR       npszDefCtlName;      // Default control name prefix PSTR       npszClassName;       // Visual Basic class name PSTR       npszParentClassName; // Parent window class, if subclassed NPPROPLIST npproplist;          // Property list NPEVENTLIST npeventlist;        // Event list BYTE       nDefProp;            // Index of default property BYTE       nDefEvent;           // Index of default event BYTE       nValueProp;          // Index of control value property USHORT     usCtlVersion;        // Identifies current version of the // custom control. The values 1 and // 2 are reserved for custom controls // created with VB1.0 and VB2.0 } MODEL;

Control Version
A custom control developer who wants to take advantage of the version management feature in Visual Basic version 3.0 needs to provide a valid version number in the usCtlVersion field. This value must be an unsigned integer (USHORT), and it should be changed any time the custom control changes its backward compatibility with previous versions.

Although any nonzero value is valid, the values 1 and 2 should not be used. Because Visual Basic versions 1.0 and 2.0 do not support version management, Visual Basic automatically assigns values 1 and 2 to any custom control that has the usVersion field in the control's MODEL structure set to VB100_VERSION and VB200_VERSION, respectively.

In order to take advantage of version management, you must set the usVersion field of the control's MODEL structure to VB300_VERSION or greater, or use VB_VERSION defined in a Visual Basic version 3.0 VBAPI.H file. This allows Visual Basic to determine whether the usCtlVersion field is defined in the MODEL structure of a given custom control.

If the custom control contains a value of 0 in the usCtlVersion field, no version control checks are made on this custom control.

How the System Works
When you create a Visual Basic executable (.EXE) file that uses a custom control, Visual Basic retrieves the control version number (usCtlVersion) for that control and stores it in a special section of the .EXE file.

When you execute the application, the Visual Basic run-time support file (VBRUN300.DLL or greater) checks the control version number recorded in the .EXE file against the version number found in the custom control when it is loaded into the system. If the version found in the .EXE file is greater than the version of the control loaded into the system, Visual Basic displays a notification that the particular custom control (.VBX file) is out of date and will not load, consequently forcing the application to terminate.

Additional query words: 3.00

Keywords: KB107873

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.