How to implement a SQL Server 2000 Desktop Engine callback function and example (315463)

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.

back to the top

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
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
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.

back to the top

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.

In the Microsoft Visual C++ 6.0 IDE, click File, and then click New. On the Projects tab, click the Extended Stored Proc wizard.
Specify a project name. For example, MyCallback. You can also specify the location in which you want to create the project. Click OK.
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.

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

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.
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.
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
					
```