DetailPage-MSS-KB

Microsoft small business knowledge base

Article ID: 315463 - Last Review: November 2, 2013 - Revision: 4.0

This article was previously published under Q315463
This article has been archived. It is offered "as is" and will no longer be updated.

On This Page

Summary

This article describes how to implement a callback function during the installation of the SQL Server 2000 Desktop Engine (MSDE 2000) and also discusses all the conditions that must be met to make sure the callback function runs properly.

The SQL Server 2000 Desktop Engine (MSDE 2000) is a redistributable version of the relational database engine in Microsoft SQL Server 2000. It permits an application that uses the SQL Server relational database engine to install the engine as a part of the application setup process.

The MSDE 2000 installation package permits you to use a callback function to track progress or to perform custom actions during the setup.

Conditions for Use of the Callback Function

For the callback function to run normally, the following conditions must be met:
  • You must implement the callback function as a Windows Installer Custom Action Type 1 Dynamic Linked Library (DLL). For example, you can use the Microsoft Visual C++ Extended Stored Procedure Wizard to create a callback DLL.

    For more information about the Windows Installer library types, visit the following Microsoft Developer Network (MSDN) Web site:
    http://msdn.microsoft.com/library/en-us/msi/cact_6a05.asp?frame=true (http://msdn.microsoft.com/library/en-us/msi/cact_6a05.asp?frame=true)
  • The callback function must reside in any one of the following folders:
    • The folder that is returned by the GetTempPath Win32 call.
    • The {Product code} folder that is present in the folder that is returned by the GetTempPath Win32 call.

      Note {Product code} is a placeholder for the product code of the MSDE 2000 instance that is installed on your computer.
    Typically, the folder that is returned by the GetTempPath Win32 call is the %TMP% environment variable. If the %TMP% environment variable is not available, it is the %TEMP% environment variable.

    For more information about the GetTempPath Win32 function, visit the following Microsoft Developer Network (MSDN) Web site:
    http://msdn.microsoft.com/library/en-us/fileio/base/gettemppath.asp (http://msdn.microsoft.com/library/en-us/fileio/base/gettemppath.asp)

  • The Desktop Engine callback function must take an additional UINT parameter that contains the Desktop Engine exit code, or return code. The definition of a callback function looks similar to
    UINT __stdcall MyCallbackFunction(MSIHANDLE hinstall, UINT uExitCode)
    						
    where uExitCode contains the Desktop Engine setup exit code, or return code.

Sample Steps and Code to Implement a Callback Function

The following steps describe the implementation of a sample callback function by using Microsoft Visual Studio 6.0.

  1. In the Microsoft Visual C++ 6.0 IDE, click File, and then click New. On the Projects tab, click the Extended Stored Proc wizard.
  2. Specify a project name. For example, MyCallback. You can also specify the location in which you want to create the project. Click OK.
  3. Specify a name to the callback function. For example, MyCallbackFunction. Note that the example uses the Extended Stored Proc wizard to create a callback DLL. The wizard recommends that you specify a name starting with "XP_". However, you can ignore the recommendation and specify the callback function name of your choice. Click Finish.
  4. This will create the classes and the cpp files needed. In the workspace pane, you will see the workspace for this project. Select the ClassView, and then expand the Globals folder in the MyCallback classes tree. There you will see the definition of the MyCallbackFunction function.

    The sample code for the callback function is in the following Sample Code heading. You can test the project by copying the following code into the MyCallbackFunction function.

    Sample Code

    #include <stdafx.h>
    
    #define XP_NOERROR 0
    #define XP_ERROR 1
    #define MAXCOLNAME 25
    #define MAXNAME 25
    #define MAXTEXT 255
    
    #ifdef __cplusplus
    extern "C" {
    #endif
    
    UINT __declspec(dllexport) MyCallbackFunction(HANDLE hinstall, UINT uExitCode);
    
    #ifdef __cplusplus
    }
    #endif
    
    UINT __declspec(dllexport) MyCallbackFunction(HANDLE hinstall, UINT uExitCode)
    {
    
         TCHAR buffer[1024];
    
         wsprintf(buffer, TEXT("**Callback** Return code is %d"), uExitCode);
    
         MessageBox(NULL, buffer, TEXT("MyCallbackFunction Dialog"), MB_OK);
    
         return 0;
    }
    					
    This callback function sample displays a message box with this text on every call:
    **Callback** Return code is 0
    					
  5. Build the MyCallback.dll file by using the Build menu. The DLL is built and saved to a subfolder named Debug, in the same location that you specified in step 2.
  6. After the DLL is built, you must copy the DLL to a location that depends on the version of MSDE 2000 that is installed on your computer.
    • If you are using Microsoft SQL Server 2000 Desktop Engine SP2, you must copy the DLL to the location that is defined by one of the following environment variables:
      • %TMP%
      • %TEMP%.
      To obtain the environment variable values on a specific computer for the user who is currently logged on, type the following command at a command prompt:
      SET
      This command displays all the environment variables, including TMP and TEMP.
    • If you are using Microsoft SQL Server 2000 Desktop Engine SP3a, you must copy the DLL to one of the following locations:
      • %TMP%\{Product code}
      • %TEMP%\{Product code}
      Note {Product code} is a placeholder for the product code of the MSDE 2000 instance that is installed on your computer.

      For example, if your MSDE 2000 instance has a product code of E09B48B5-E141-427A-AB0C-D3605127224A, you must copy the DLL to the %TMP%\{E09B48B5-E141-427A-AB0C-D3605127224A} or %TEMP%\{E09B48B5-E141-427A-AB0C-D3605127224A} folder.
  7. Use the Desktop Engine Windows Installer CALLBACK option to invoke the callback function during setup. For example:
    CALLBACK=Dllname!CallbackFunctionName
    For this example the syntax is:
    setup.exe /L*v c:\msde_setup.log CALLBACK=MyCallback!MyCallbackFunction
    					

References

For additional information, click the following article number to view the article in the Microsoft Knowledge Base:
299795  (http://support.microsoft.com/kb/299795/ ) How to author MSDE 2000 setup packages with Microsoft Visual Studio Installer 1.1


Windows Installer SDK is part of the Microsoft Platform Software Development Kit (SDK). For more information about the Platform SDK, visit the following Microsoft Web site:
http://www.microsoft.com/msdownload/platformsdk/sdkupdate/ (http://www.microsoft.com/msdownload/platformsdk/sdkupdate/)
SQL Server 2000 Books Online; topics: "Building SQL Server Applications"; "Distributing SQL Server Applications"; "Distributing SQL Server with Applications"; "Desktop Engine Windows Installer Return Codes"; "Desktop Engine Windows Installer Callback Functions"
Keywords: 
kbnosurvey kbarchive kbhowtomaster KB315463
Share
Additional support options
Ask The Microsoft Small Business Support Community
Contact Microsoft Small Business Support
Find Microsoft Small Business Support Certified Partner
Find a Microsoft Store For In-Person Small Business Support