Microsoft Visual Basic 3.00                              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 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 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 the 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 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.  Since 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, the usVersion field
of the control's MODEL structure must be set to VB300_VERSION or greater
(or simply use VB_VERSION defined in a Visual Basic 3.0 VBAPI.H).  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,
then 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.
