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 Microsoft
Developer Network (MSDN) Library at: http://msdn.microsoft.com/library/en-us/msi/cact_6a05.asp?frame=true
- The callback function must reside in the folder that is returned by the
GetTempPath Win32 call. Generally, this path is same
as 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, see the MSDN Library at: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/fileio/filesio_78fc.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 into the location defined
by the environment variables, <%TMP%> or <%TEMP%>. To get the environment
variable values on a specific computer for the user who is currently logged
on, open a command prompt and type this command: " SET " (without
the quotation marks). This command displays all the environment variables including
<TMP> and <TEMP>.
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 |
The information in this article applies to:
-
Microsoft SQL Server 2000 Desktop Engine (MSDE)
© 2003 Microsoft