Migration Extension Interface Reference

[This is preliminary documentation and subject to change.]

Many applications work identically under Microsoft® Windows® 95, Microsoft® Windows® 98, and Microsoft® Windows NT® 5.0. Your application may operate differently under the different versions. If so, if your users decide to move from Windows 95 or Windows 98 to Windows NT, they will be unable to use your application. To prevent this, Microsoft provides the Migration Extension Interface.

If applications do not work properly, users have to reinstall them. Individual reinstallation of applications is an irritation at any level. In corporate environments, where large-scale deployments are automated, reinstalling applications is prohibitive since it increases deployment costs. For most non-corporate environments, users may not have the original installation media readily available to reinstall their applications.

The Migration Extension Interface is an extension to the Setup API that enables you to ensure that your application will operate correctly after Windows NT is installed over Windows 95 or Windows 98. To make use of the Migration Extension Interface, you must write a migration DLL (MIGRATE.DLL) that the Setup program can use to make the changes that will enable your application to work correctly under the new operating system.

This reference is divided into the following sections:

Overview
Provides more details on why you would implement a migration DLL for your application.
How the Migration Process Works
An overview of how the migration functionality fits in with the Windows 95 and Windows 98 to Windows NT upgrade process.
About MIGRATE.DLL
Describes the overall structure and processing order of the essential DLL functions.
Migration DLL Development Issues
Details a number of important issues you must consider when you choose to implement a migration DLL
Testing a Migration DLL
Outlines the steps you should take to determine if you need a migration DLL
Migration DLL Function Reference
Details the MIGRATE.DLL functions.
The MIGRATE.INF File
Details the information file your DLL will use to pass information to the Windows NT Setup program.


Overview

Most users expect that all their installed applications will function properly after they decide to upgrade from Microsoft® Windows® 95 or Windows 98 to Windows NT®. However, it is almost impossible to guarantee that an existing application will work properly after Windows NT Setup completes installation of the new operating system. While Windows NT Setup attempts to adhere to the ideal behavior, there are certain problems with some applications that it cannot resolve. These include problems caused by applications that do the following.

  • Write to different registry locations on Windows 95 and Windows 98 than on Windows NT
  • Write different registry values to the same registry locations
  • Install different run-time files (.dll, .exe, and so on) on the two operating systems
  • Install different versions of files that are common to Windows 95, Windows 98, and Windows NT
  • Make operating-system-specific calls on Windows 95 and Windows 98 that are not available on Windows NT

As the developer of your application, you are the only one who can resolve these issues. You can use the Migration Extension Interface to interact with the upgrade process and correct inconsistencies like these before they become problems.


How the Migration Process Works

The Migration Extension Interface is designed to fit into the upgrade process as follows:

  1. A user installs your application on a Windows® 95- or Windows 98-based system. You place your MIGRATE.DLL file (and other associated files) on your distribution media or on the World Wide Web site where the user installed the application.
  2. Sometime later, the user runs the Windows NT® 5.0 Setup program, which prompts the user for the location of the migration DLLs.
  3. Setup locates (via user input) and activates your MIGRATE.DLL, passing it its MIGRATE.INF file.
  4. Your MIGRATE.DLL modifies the MIGRATE.INF file with the relevant information and passes it back to Windows NT Setup.
  5. Windows NT Setup continues its installation process. When it begins the Windows NT portion of the installation, it again contacts your MIGRATE.DLL and passes it the MIGRATE.INF file.
  6. Your MIGRATE.DLL uses the information it wrote into the MIGRATE.INF file and takes the appropriate actions to enable your application to run under Windows NT.


MIGRATE.DLL

About MIGRATE.DLL

The migration DLL is a standard Win32®-based DLL you create. It is called by Windows NT 5.0 Setup at different times during the upgrade process to perform a custom migration of your otherwise incompatible application. Setup relies on migration DLLs to identify unknown software components and to either migrate their settings to Windows NT or remove the components that will never work properly after an upgrade.

At a minimum, a migration DLL must have the following Setup-defined exported functions.

  • QueryVersion
  • Initialize9x
  • MigrateUser9x
  • MigrateSystem9x
  • InitializeNT
  • MigrateUserNT
  • MigrateSystemNT

Your migration DLL can contain additional functions. But if any of these seven functions is missing from a migration DLL, Setup will not load and process it, and your application will not migrate.


How Migration DLLs are Processed

This section provides the order in which the functions in the migration DLL are called and a brief description of each function. Note that if any of the required seven functions is not present, Setup will skip your MIGRAGE.DLL, and your application will not be migrated to the new system.

During the initial portion of Windows NT Setup (that is, while Windows 95 or Windows 98 is still running), the following MIGRATE.DLL functions are called in the order listed.

Function | Caller | Reason for Call
DllMain (DLL_PROCESS_ATTACH) | Windows 95 and Windows 98 | Standard call to load the migration DLL from the installation media.
QueryVersion | Setup | Obtain application ID information (such as the product ID and version number) and determine if further processing is necessary. After successful processing, the relevant files are copied to the user's hard disk.
DllMain (DLL_PROCESS_DETACH) | Windows 95 and Windows 98 | The system unloads the migration DLL.
DllMain (DLL_PROCESS_ATTACH) | Windows 95 and Windows 98 | The system loads the migration DLL from its new location on the local hard disk.
Initialize9x | Setup | MIGRATE.DLL prepares itself for the migration process. It detects its target application component locations. Then it provides the working and source directories to Windows NT Setup.
MigrateUser9x | Setup | Setup calls the MigrateUser9x function once for each Windows 95 and Windows 98 user account on the computer being upgraded as well as for the Windows NT Administrator account (that is, the active user account becomes the Windows NT Administrator account after migration). The migration DLL detects the users that have installed its target application. Setup also calls MigrateUser9x for the default user account if necessary. If the application is installed for the given user name, the DLL gathers user-specific application information to be used during the MigrateUserNT function call.
MigrateSystem9x | Setup | The DLL gathers system-wide information concerning its target application and saves private data to be used during the MigrateSystemNT function call.
DllMain (DLL_PROCESS_DETACH) | Windows 95 and Windows 98 | The system unloads the migration DLL.

During the second portion of Windows NT Setup (that is, when the newly installed Windows NT is running), the following MIGRATE.DLL functions are called in the order listed.

Function | Caller | Reason for Call
DllMain (DLL_PROCESS_ATTACH) | Windows NT | The system loads the migration DLL.
InitializeNT | Setup | Windows NT Setup provides the migration DLL with its working directory, specified during the earlier call to Initialize9x.
MigrateUserNT | Setup | Setup calls MigrateUserNT once per user. It enables the migration DLL to make changes to a user's application settings. Note that the number of calls may be less than the number made to MigrateUser9x since some user accounts may not migrate. For example, the default user account may not migrate if that account has never been accessed. As such, a DLL must store its private data on a per-user basis.
MigrateSystemNT | Setup | The migration DLL makes changes to the system application settings based on the information obtained during the call to MigrateSystem9x.
DllMain (DLL_PROCESS_DETACH) | Windows NT | The system unloads the migration DLL.

By the time the system calls the DllMain (DLL_PROCESS_ATTACH) function, Setup has done the following:

  1. Copied all 32-bit executables from %windir%\system to %windir%\system32.
  2. Adjusted Window 95 or Windows 98 registry key values within HKU\User\Software and HKLM\Software that contain full paths to files that exist in a new location on Windows NT.
  3. Migrated all system settings, including the registry, program menu items, desktop, recent documents, and other shell settings.
  4. Deleted Windows 95- and Windows 98-specific OLE system objects (not application objects).
  5. Migrated the user shell folders (such as c:\windows\desktop) to the Windows NT equivalent (that is, c:\windows\profiles\<user>\desktop).
  6. Adjusted the paths in .STF files (part of ACME Setup) if necessary (for Beta 2).
  7. Adjusted links and PIFs that point to moved files.

Note In the Windows NT phase of the upgrade process, each DLL function has 60 seconds to complete its processing. If it takes longer, Setup will terminate it.


Migration DLL Development Issues

Since a migration DLL is a standard Win32® DLL, writing one should be fairly straightforward. However, the following sections describe some specific development issues to consider.

Where to Place Migration DLLs

Migration Function Processing Order

Run-Time DLLs Included with Windows NT 5.0

Manipulating a User's Registry Settings

Checking Network Availability

Avoiding User Interfaces

Storing Private Data

Handling Special String Characters

Using the Setup Answer File

Deferring Application Migration

Logging Errors

Using the Win32 Profile APIs

Restarting Setup


Where to Place Migration DLLs

You can place your migration DLL in a network location, on a floppy disc, or on a compact disc.

Network Location of MIGRATE.DLL

Floppy or Compact Disc-Based MIGRATE.DLL


Network Location of MIGRATE.DLL

A user may place migration DLLs on a network share and specify the location during Setup. Or, if Setup is running in unattended mode, the user may specify the location in the Setup answer file. Each migration DLL must be placed in its own subdirectory (along with any other files required for migrating the target application).

Note If the Win95upg subdirectory exists before Setup runs, Setup will delete it and create a new one into which the specified files will be copied.


Floppy or Compact Disc-Based MIGRATE.DLL

Setup provides users with the option to supply a floppy or compact disc that contains migration DLLs for their target applications. Setup searches the provided media for MIGRATE.DLL files. For each DLL it finds, it copies the directory containing the DLL and all other files and subdirectories in that directory to a unique subdirectory.

Note The Windows NT 5.0 compact disc also contains migration DLLs.


Migration Function Processing Order

There is no guaranteed processing order for migration DLLs. Therefore, do not allow one of your migration DLLs to be dependent on the migration DLL for another application.


Run-Time DLLs Included with Windows NT 5.0

Before running any migration extensions on the Windows 95 or Windows 98 system, Setup will copy the following files from the Windows NT compact disc to the Windows 95 or Windows 98 System directory.

SETUPAPI.DLL
Setup
MSVCRT.DLL
Run-time shipped with Microsoft® Visual C++® 5.0
MSVCRT40.DLL
Run-time shipped with Microsoft Visual C++ 4.0
MFC40.DLL
Microsoft Foundation Class Library 4.0
MFC42.DLL
Microsoft Foundation Class Library 4.2

For international environments, Setup copies the appropriate localized DLLs. For example, Setup copies MFC40JPN.DLL and MFC42JPN.DLL for a Japanese installation.

Debug versions of the run-time DLLs are not copied, nor can Setup guarantee that other run-time versions of an application will migrate correctly.

This list of files is not final. Setup may also install newer versions if they become available. However, if your migration extension needs a run-time DLL that is not installed by Windows NT, you must ship it with your migration DLL, and use the migration DLLs functionality to ensure the run-time DLL is installed.


Manipulating a User's Registry Settings

Setup runs in a logged-on user context on Windows 95 and Windows 98, but does not run in a logged-on user context under Windows NT. Rather, it runs in the local system account context. As such, your migration DLL should not try to query or modify the HKEY_CURRENT_USER registry key directly. Instead, it should query the UserRegKey handles passed to it through the MigrateUser9x and MigrateUserNT functions.


Determining Application Registry Differences

You can use SYSDIFF.EXE to determine registry entry differences between an application on a computer with Windows NT 5.0 newly installed and a computer upgraded from Windows 95 or Windows 98. SYSDIFF.EXE is available from the Microsoft Windows NT Workstation 4.0 Resource Kit. This utility is useful when you are not familiar with the application registry differences between the two versions of your application.

To use SYSDIFF.EXE to determine the registry entries made by an application on a computer using Windows NT:
  1. Install Windows NT 5.0 on a computer.
  2. Log on to the system under the administrator account.
  3. Copy SYSDIFF.EXE and SYSDIFF.INF into a temporary directory.
  4. Modify SYSDIFF.INF as necessary.
  5. From the Command Prompt, run
    sysdiff /snap [/log:<logfile1>] <snap_file>

    logfile1 and snap_file are valid file names. The /log parameter is optional. SYSDIFF.EXE will create both files.

  6. Install your application.

    Note SYSDIFF.EXE records all system changes. Install your application only.

  7. From the Command Prompt, run
    sysdiff /diff [/log:<logfile2>] <snap_file> <diff_file>

    logfile2 and diff_file are valid file names. The /log parameter is optional. SYSDIFF.EXE will create both files. snap_file is the file name you specified in the previous call to SYSDIFF.EXE.

  8. From the Command Prompt, run
    sysdiff /dump <diff_file> <dump_file>

    dump_file is a valid file name. SYSDIFF.EXE will create it. diff_file is the file name you specified in the previous call to SYSDIFF.EXE.

    When SYSDIFF.EXE completes, dump_file is a plain text file containing a list of file, .INI file, and registry changes made to the system by the target application. Now you are ready to get the upgrade registry entries.

To determine registry entry differences between an upgraded computer (from Windows 95 or Windows 98 to Windows NT 5.0) and a computer with Windows NT 5.0 newly installed:
  1. Install Windows 95 or Windows 98 on a computer.
  2. Install your application.
  3. Upgrade the computer using WINNT32.EXE.
  4. Log on to the Windows NT 5.0 computer.
  5. Run REGEDIT32.EXE or REGEDIT.EXE.
  6. Compare the registry values listed in dump_file obtained during the final call to SYSDIFF.EXE and those listed in the registry. The differences are those you need to resolve.

Note This procedure is different because SYSDIFF does not work across platforms.


Check Network Availability

Checking Network Availability

The network is available to Setup during the Windows 95 and Windows 98 phase of the upgrade process, but it will not be available during the Windows NT phase. Your migration DLL must not try to access the network during the Windows NT portion of the migration.


Avoid User Interfaces

Avoiding User Interfaces

Your migration DLL should not have a user interface. A parent window handle is provided only for the extreme case where a user interface is unavoidable. If Setup provides a NULL parent window handle, the DLL must never display any windows, dialog boxes, drop-down list boxes, or message boxes. The migration DLL must never display a user interface during the Windows NT phase of Setup.

This is extremely important when Setup is running in unattended mode. You can determine the Setup mode by testing the value of the ParentWnd parameter in either MigrateUser9x or MigrateSystem9x.

The installation process should be as hassle free as possible. If the user interface is required at any point during an attended installation, consider the usability implications when someone must load multiple migration DLLs.


Storing Private Data

Each migration DLL is copied to a unique working directory. Your migration DLL may store private Windows 95 and Windows 98 configuration information in this directory as well as other run-time or data files required for the migration.

This directory is the only location to which your migration DLL should write when it is running on Windows 95 and Windows 98. Setup deletes this working directory after all migration DLLs have completed and after Windows NT is successfully installed.


Handling Special String Characters

When writing messages, paths, and registry locations to an INF file, your migration DLL may need to pass certain characters that have special meanings to Setup and to the operating system. When writing messages or paths, the string must be enclosed in double-quotes if it contains any of the following:

    "

    %

    ,

    ;

    [

    ]

In addition, embedded percent and double-quote characters must be formatted properly before the string is written to the INF file. For example,

This "example" illustrates how to escape the percent (%) symbol

Must appear in an INF file as

"This ""example"" illustrates how to escape the percent (%%) symbol"

When writing registry locations to an INF file, you must replace the characters listed below as well as all characters with ASCII values greater than 127 (including double-byte characters) with their hexadecimal values enclosed in tilde (~).

Character | Hex value
" | 0x22
% | 0x25
, | 0x2C
; | 0x3B
[ | 0x5B
] | 0x5D
~ | 0x7E

For example, replace a semicolon (;) with the string ~3B~ .


Using the Setup Answer File

Setup passes the location of its answer file (UNATTEND.TXT) to your migration DLL in the MigrateUser9x, MigrateSystem9x, MigrateUserNT, and MigrateSystemNT functions.

Your migration DLL can modify this answer file during the Windows 95 and Windows 98 portion of the upgrade process by using the Win32 profile APIs (such as WritePrivateProfileString). Your DLL is permitted to change standard answer file settings and create private sections for its own use. Note that it may not modify the following sections of the UNATTEND.TXT file.

[Unattended]]
[MassStorageDrivers]
[DisplayDrivers]
[KeyboardDrivers]
[PointingDeviceDrivers]
[OemBootFiles]
[OEM_Ads]
[GuiUnattended]
[UserData]
[LicenseFilePrintData]
[Display]
[Modem]

Note This list will change before Beta 2. Refer the reader to Win95upg.inf, [Answer File Restrictions] on the Windows NT compact disc.

For a detailed description of answer file parameters, search the Microsoft Knowledge Base at http://www.microsoft.com/kb/.

If you require a private section, your DLL should build the section name from the working directory passed to it by the Initialize9x function. The private section name may only contain alphanumeric characters (A-Z and 0-9). Spaces and other characters are not permitted because they prevent Windows NT Setup from starting the text-only portion of the installation.

During the Windows NT portion of the upgrade, your migration DLL must treat the UNATTEND.TXT file as a read-only file. You must not modify the answer file in any way.


Windows 95 and Windows 98 Upgrade Answer File Parameters

To support the Migration Extension Interface, the Win9x Upgrade section has been added to the UNATTEND.TXT answer file. (Note that this is subject to change before Beta 2.)

[Win9x Upgrade]

Attended = [Yes|No]
Default value is Yes. Attended specifies if the upgrade is running in attended mode or not. When set to No, Setup assumes default values for the rest of the Win9x Upgrade section parameters:
MigrationDllPath = <path>
Specifies a local or UNC path to migration DLLs. Setup will search this directory and its subdirectories for migration DLLs.
ReportOnly = [No|Yes]
Default value is No. This parameter forces Setup to generate a compatibility report and then terminate without upgrading the computer.
SaveReportTo = <path>
Default is the local computer system drive (generally C:\). Specifies a local or UNC path (not a file name) to the desired location of Setup compatibility report files (HARDWARE.TXT and SOFTWARE.TXT). HARDWARE.TXT contains the hardware compatibility report. SOFTWARE.TXT contains the software compatibility report.
AppendComputerNameToPaths = [No|Yes]
Default value is No. This key is used to specify whether the computer name should be appended to the path to which the compatibility reports are to be saved. The directory is created if it does not already exist. For example, if SaveReportTo = C:\reports and the computer name is Testcomp, the reports would be saved to C:\reports\Testcomp.


Deferring Application Migration

If your application is network-based, it may not be practical for your migration DLL to copy your migration files from a network location to every local computer that has Windows 95 or Windows 98 installed.

Instead, your migration DLL can redirect the application shell links to a new executable. This way, when a user launches the application, the new executable runs instead. This executable is responsible for completing the migration from the network location to that user's local machine in the user's logged-on, network-accessible context on Windows NT. If you choose this approach, all your migration DLL needs to do is to copy the new executable to the local hard disk and redirect all shell links from the original target application to this new executable. (You accomplish this through an entry in the [Moved] section of MIGRATE.INF.)

The new executable must complete the migration when a user runs it on Windows NT. It must restore the original shell links, delete itself, and then run the newly migrated application. For more details on how to replace links, see the Shell Link documentation in the Win32 SDK.

See Also

[Moved] Section


Logging Errors

Windows NT Setup automatically logs errors returned by your migration DLL code. To log the errors your migration DLL detects, you must use the new Setup API SetupLogError function.

BOOL
SetupLogError(
    IN LPCTSTR MessageString,
    IN LogSeverity ErrorSeverity
    );

Parameters

MessageString
Error message string to be saved to the Windows NT Setup action log (saved to %Windir%SETUPACT.LOG).
ErrorSeverity
Specifies the severity of the error to be logged, and it can have one of the following values. The values are listed from lowest to highest severity.
  • LogSevInformation
  • LogSevWarning
  • LogSevError
  • LogSevFatalError (reserved for use by Windows NT Setup)

Remarks

If ErrorSeverity level is LogSevWarning, LogSevError, or LogSevFatalError, a copy of the error message will also be saved to the %Windir%SETUPERR.LOG file.

Before logging an error, the log file must be opened using SetupOpenLog. SetupCloseLog must be used to close it after the error is written.

Note Opening and closing a log file can be done in the DLLMain function of a migration DLL. See sample source code for example.


Using the Win32 Profile APIs

The Win32 Profile APIs (GetPrivateProfileString and WritePrivateProfileString) use a separate cache than the one used by SetupOpenInfFile. Therefore, if you open MIGRATE.INF using SetupOpenInfFile, and then (before closing it) modify the file using WritePrivateProfileString, your changes will not appear in SetupOpenInfFile cache.

As such, care must be taken when using both the Win32 Profile APIs and the Setup APIs. Ideally, their use must be separated.

If you modify MIGRATE.INF using WritePrivateProfileString, you must call WritePrivateProfileString again with all NULL parameters to force the file to be written to disk before you open it again using SetupOpenInfFile.

If a file has already been opened with SetupOpenInfFile, do not call WritePrivateProfileString to modify the same file.


Restarting Setup

The GUI-mode portion of Windows NT Setup may be restarted in case of a critical interruption (such as a power failure) during the upgrade. Your migration DLL should be prepared to handle this scenario. For example, before moving files, the DLL must check to see if the file has already been moved. Of course, this is standard programming practice, and the extent of your fail-safe functionality is mostly determined by the complexity of your migration process.


Testing a Migration DLL

Applications that do not survive migration from one version of Microsoft® Windows® to another will not comply with Windows logo requirements. Your migration DLL can help to preserve your logo compliance.

The Setup program attempts to detect conflicts that arise from implementing your application under the new operating system. It may or may not succeed in identifying inconsistencies. Because of this, you should test your application extensively under various migration scenarios.

The migration functionality is provided to enable you to ensure that your customer base can use your application under the new operating system. You should test how your application behaves under different versions of Windows. Ideally, it behaves the same under different versions.

If conflicts exist, you have two options. You can either correct the intrinsic problem so that no problems occur during migration, or you can create a migration DLL. If you do not take advantage of the Migration Extension Interface, your customers will need to reinstall your application for it to run correctly under the newly installed system.

Migration DLLs must be thoroughly tested before being distributed to end users by means of the World Wide Web or other media. The following procedures outline the minimal process you should undertake during your test. Note that you should repeat the tests for multiple user account scenarios (that is, default, roaming, workgroup, and domain users). The scenarios should also cover combinations of these user accounts.

To test your migration DLL under an attended upgrade:
  1. Install Windows 95 or Windows 98 on a computer.
  2. Install the target application on the computer.
  3. Start Windows NT Setup, and select the Upgrade option on the Welcome page.
  4. When prompted, insert the media containing the migration DLL.
  5. Complete Windows NT Setup.
  6. Launch the migrated application on Windows NT.
  7. Run any test suites to determine if the application is fully functional.
To test your migration DLL under an unattended upgrade:
  1. Install Windows 95 or Windows 98 on a computer.
  2. Install the target application on the computer.
  3. Place the migration DLL in a subdirectory of %windir%\setup\win95upg.
  4. Start Windows NT Setup in unattended mode with the "Win95Upgrade = Yes" key set in the answer file.
  5. Complete Windows NT Setup.
  6. Launch the migrated application on Windows NT.
  7. Run any test suites to determine if the application is fully functional.


Migration DLL Function Reference

You call the MIGRATE.DLL functions in order as you migrate your application from Windows® 95 and Windows 98 to Windows NT®.

  • QueryVersion
  • Initialize9x
  • MigrateUser9x
  • MigrateSystem9x
  • InitializeNT
  • MigrateUserNT
  • MigrateSystemNT


QueryVersion

Setup uses QueryVersion to determine if further processing of the DLL is necessary.

LONG
CALLBACK
QueryVersion(
    OUT LPCSTR *ProductID,
    OUT LPUINT DllVersion,
    OUT LPINT *CodePageArray,    OPTIONAL
    OUT LPCSTR *ExeNamesBuf,    OPTIONAL
    LPVOID Reserved
    );

Parameters

*ProductID
Points to a string that identifies the DLL and its target application. To ensure uniqueness, the string must contain the name of the manufacturer, the product name, and the version number of the application the DLL will migrate. The length of the string must not exceed MAX_PATH bytes (as defined within your migration DLL). Setup ignores excess characters. The ProductID string is also used for error messages generated during DLL processing.

Note Your migration DLL is responsible for allocating and freeing the ProductID string buffer.

DllVersion
Points to a non-zero unsigned integer that specifies the version number of your migration DLL. Setup looks for duplications by comparing ProductID strings from other migration DLLs. If two or more DLLs have identical ProductID strings, Setup uses the DLL with the highest DllVersion number and ignores the other duplicates.

Note DllVersion is not intended to be the DLL binary version number.

CodePageArray
Points to an array of integers containing all the code pages supported by the migration DLL. The last element of the array must be -1. If your migration DLL does not support the system code page, Setup skips your migration DLL and your application will not migrate to the new operating system.

If this pointer is NULL, Setup processes all the required functions in the DLL regardless of the installed Windows 95 and Windows 98 code pages. Set this pointer to NULL if the DLL has no language dependencies.

Note Your DLL is responsible for the allocating and freeing memory used by this array.

ExeNamesBuf
Points to a multi-sz string buffer containing a list of file names (not paths) that your migration DLL wants Setup to locate. Setup locates all instances of the listed files and returns the list of full file paths to your migration DLL via the MIGRATE.INF file. Paths to files located on network, substituted, or compressed drives will not be returned to the DLL because Setup does not search those drives. Other directories on the computer not related to the active Windows 95 or Windows 98 installation may also be excluded.

Set this parameter to NULL if you do not want Setup to search for any particular files.

Note Your migration DLL is responsible for allocating and freeing the ExeNamesBuf string buffer.

Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS if your migration DLL found one or more installed components for its target application. This guarantees that Setup will call your migration DLL for later processing.

ERROR_NOT_INSTALLED if your migration DLL initializes properly but did not find any of its components installed on the active Windows 95 or Windows 98 installation. Note that Setup will not call your DLL again if it returns ERROR_NOT_INSTALLED.

Your migration DLL must also return ERROR_SUCCESS if it does not attempt to detect installed components in QueryVersion.

All other return values (Win32 error values) are considered initialization errors. Setup will report the error to the user, clean up your migration DLL files, and ask the user to continue or cancel the Windows NT installation process.

An exception generated by a migration DLL causes Setup to report RPC error messages. Setup will provide more information in SETUPERR.LOG.

Remarks

Setup uses QueryVersion to determine if further processing of the DLL is necessary. During this call, your migration DLL (located on a floppy, compact disc, or network share) must provide Setup with the ProductID, DllVersion, CodePageArray, and ExeNamesBuf information. At this point, your migration DLL cannot make any changes to the system.

Your migration DLL should try to determine if the target application is installed on the computer, and then return the appropriate result from QueryVersion. The system unloads the migration DLL after QueryVersion returns. Setup copies it to the local hard disk and calls Initialize9x only if QueryVersion returns ERROR_SUCCESS.

During the call to QueryVersion, Setup finds all occurrences of files listed in the ExeNamesBuf string (if not NULL) and writes their locations to the [Migration Paths] section of MIGRATE.INF. These paths are then available to the other functions in your migration DLL.

Setup detects duplicate migration DLLs by comparing the ProductID strings of supplied DLLs. It only processes the DLL with the highest DllVersion number. The user is not notified of duplicates found.

Important DllVersion number zero (0) is reserved for Windows NT Setup-provided migration DLLs. DLLs not supplied by Microsoft Windows NT with the Windows NT 5.0 compact disc must not use this value.


Initialize9x

Setup calls Initialize9x after relocating the migration DLL to the local hard disk.

LONG
CALLBACK
Initialize9x(
    IN LPCSTR WorkingDirectory,
    IN LPCSTR SourceDirectories,
    LPVOID Reserved
    );

Parameters

WorkingDirectory
Points to the path of a Setup-supplied directory your migration DLL can use to store its private temporary data. This directory will contain MIGRATE.DLL and all associated files. Your migration DLL must write to this directory if it needs temporary data storage. Setup provides this directory again during the Windows NT phase of the upgrade process and automatically deletes it after the upgrade is complete.
SourceDirectories
Points to the path of the Windows NT installation files. This path is a multi-sz string to enable you to specify multiple source directories. Normally, this directory is D:\I386 where D:\ is the CD-ROM drive on the computer.

Note Compressed files on the Windows NT installation compact disc can be decompressed by using the Setup API functions SetupGetFileCompressionInfo and SetupDecompressOrCopyFile.

Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS if your migration DLL found one or more installed components for the target application. If your DLL does not attempt to detect installed components in Initialize9x, it must also return ERROR_SUCCESS.

ERROR_NOT_INSTALLED if the migration DLL initializes properly but does not find any of its components installed on the active Windows 95 or Windows 98 installation. Note that Setup will not call your DLL again if it returns ERROR_NOT_INSTALLED.

All other return values (Win32 error values) are considered initialization errors. Setup reports the error to the user, cleans up your migration DLL files, and asks the user to abort or continue the Windows NT installation process.

Exceptions generated by your migration DLL cause Setup to report RPC error messages. Setup provides more information in SETUPERR.LOG.

Remarks

Setup calls Initialize9x after relocating your migration DLL to the local hard disk. During this call, your DLL should try to detect its new installation. It should return ERROR_SUCCESS if it is ready to be called by Setup during the Windows NT portion of the upgrade. If the DLL returns ERROR_NOT_INSTALLED, Setup will stop processing it.

The current directory is set to the working directory and will not be changed by Setup during the processing of a migration DLL.


MigrateUser9x

Gather information concerning the users, and save private data to be used during the later call to MigrateUserNT.

LONG
CALLBACK
MigrateUser9x(
    IN HWND ParentWnd,
    IN LPCSTR AnswerFile,
    IN HKEY UserRegKey,
    IN LPCSTR UserName,
    LPVOID Reserved
    );

Parameters

ParentWnd
Specifies a handle to the parent window for any dialog boxes or windows that you may want your migration DLL to display.

Note You should not display a user interface unless absolutely necessary.

If this parameter is NULL, Setup is running in an unattended mode and your DLL must not display user interface elements or prompt the user for input.

AnswerFile
Points to a copy of the Windows NT Setup answer file (typically UNATTEND.TXT), which is used to automate the installation of Windows NT. You can access this file using the Win32 profile APIs (for example, GetPrivateProfileString and WritePrivateProfileString). Some sections of this answer file cannot be modified by your DLL. For more information, see Using the Setup Answer File.
UserRegKey
Provides a registry handle to the user hive of the Windows 95 or Windows 98 user specified in the UserName parameter. This user hive is equivalent to the user's HKEY_CURRENT_USER (HKCU) when that user logs on. This handle is valid only within the scope of MigrateUser9x and is provided for user-specific information gathering purposes.
UserName
Provides the user name (for example, "username") for the Windows 95 or Windows 98 user whose registry information is supplied through the UserRegKey parameter. A value of NULL refers to the default Windows 95 or Windows 98 user account (that is, the account used when a user accesses the system by skipping the log on process). UserName may also be "Administrator" even though Windows 95 and Windows 98 do not have an administrator account. This allows a migration DLL to collect information for the Windows NT Administrator account to be created later.
Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS if the target application is installed for the specified user. Also return ERROR_SUCCESS if your migration DLL needs further processing during the Windows NT phase.

ERROR_NOT_INSTALLED if your target application is not installed for the specified user account and that user's registry does not require any processing. However, Setup will continue to call MigrateUser9x for the rest of the users and MigrateSystem9x if this function returns ERROR_NOT_INSTALLED.

ERROR_CANCELLED if the user wants to exit Setup. You should specify this return value only if ParentWnd is not set to NULL.

All other return values (Win32 error values) are considered initialization errors. Setup reports the error to the user and prompts to abort or continue the upgrade.

Exceptions generated by your migration DLL cause Setup to report RPC error messages. Setup provides more information in SETUPERR.LOG.

Remarks

A DLL must always check for the value of ParentWnd in MigrateUser9x before proceeding since its value determines whether UI can be displayed to the user.

Do not use the MigrateUser9x function for user account modification. Use it only for information gathering about user accounts. To modify user-specific settings, save the data collected to your provided working directory and then use the MigrateUserNT function to perform the modifications.

Use the DLL working directory provided by the Initialize9x WorkingDirectory parameter to store any user-specific configuration information you may want to keep track of. Remember to use the UserName parameter to differentiate the information about the various users.


MigrateSystem9x

Gather system-wide information concerning the target application, and save private data to be used during the later call to MigrateSystemNT.

LONG
CALLBACK
MigrateSystem9x(
    IN HWND ParentWnd,
    IN LPCSTR AnswerFile,
    LPVOID Reserved
    );

Parameters

ParentWnd
Specifies a handle to the parent window for any dialog boxes or windows that your migration DLL may want to display.

Note You should not display a user interface unless absolutely necessary.

If this parameter value is NULL, Setup is running in an unattended mode and your DLL must not prompt the user for input. Therefore, the ParentWnd value determines whether ERROR_CANCELLED can be returned from this function.

AnswerFile
Points to a copy of the Windows NT Setup answer file, UNATTEND.TXT. This file is used to automate the installation of Windows NT and can be accessed using the Win32 profile APIs, such as GetPrivateProfileString and WritePrivateProfileString. For more information, see Using the Setup Answer File.
Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS if your target application is installed on the system. Also, return ERROR_SUCCESS if system-wide changes need to be made for the target application during the Windows NT phase of the upgrade.

ERROR_NOT_INSTALLED if your migration DLL detects no application components common to the entire system or if your DLL requires no further processing. Note that Setup will continue to call MigrateUser9x for the rest of the users and MigrateSystem9x if this function returns ERROR_NOT_INSTALLED.

ERROR_CANCELLED if the user elects to exit the Setup program. Use this return value only if ParentWnd is not NULL.

All other return values (Win32 error values) are considered initialization errors. Setup reports the error to the user and asks to abort or continue the upgrade.

Exceptions generated by your migration DLL cause Setup to report RPC error messages. Setup provides more information in SETUPERR.LOG.

Remarks

Your DLL must always check for the value in ParentWnd before proceeding since its value determines whether user interface elements can be displayed to the user.

Do not use this function to modify the system. Use it for system-wide information gathering only. To modify system-wide settings, save any private data collected in your migration DLLs working directory (specified in an earlier call to Initialize9x). Use MigrateSystemNT to perform the modifications during the Windows NT portion of the upgrade.


InitializeNT

This function is called during Windows NT GUI Mode Setup when the Windows NT phase of the upgrade is ready to start.

LONG
CALLBACK
InitializeNT(
    IN LPCWSTR WorkingDirectory,
    IN LPCWSTR SourceDirectories,
    LPVOID Reserved
    );

Parameters

WorkingDirectory
Points to the path of the Setup-supplied working directory. This value is the value that your migration DLL used for storing its private temporary data and files during the Windows 95 or Windows 98 phase of the upgrade.
SourceDirectories
Points to the path of the Windows NT installation files. This path is a multi-sz because multiple source directories can be provided. Normally this directory is D:\I386 or C:\$WIN_NT$.~LS\I386 where D:\ is the CD-ROM drive on the computer and C:\$WIN_NT$.~LS\I386 is the Setup temporary source directory.
Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS if your migration DLL initializes properly within the Windows NT environment.

All other return values (Win32 error values) are considered critical errors. Setup reports the error to the user and then cancels processing your migration DLL. However, Setup will not continue the upgrade. Any errors or logs generated will include the ProductID string specified in QueryVersion to identify your DLL.

Exceptions generated by your migration DLL cause Setup to report RPC error messages. Setup provides more information in SETUPERR.LOG.

Remarks

InitializeNT is called during Windows NT GUI Mode Setup when the Windows NT phase of application migration is ready to start. When this function is called, the current directory is set to the DLL working directory.

Your migration DLL must not display user messages in its InitializeNT function.


MigrateUserNT

Migrate the user accounts that port from Windows 95 or Windows 98 to Windows NT.

LONG
CALLBACK
MigrateUserNT(
    IN HINF AnswerFileHandle,
    IN HKEY UserRegKey,
    IN LPCWSTR UserName,
    LPVOID Reserved
    );

Parameters

AnswerFileHandle
INF handle to the answer file being used for the upgrade process. This file contains settings generated by Setup, the attending user, and all migration DLLs. You can access the file referenced by this handle using the Setup functions. Do not close this handle at any time.
UserRegKey
A registry handle to the private registry settings of the Windows 95 or Windows 98 user specified in UserName. This handle is equivalent to HKEY_CURRENT_USER (HKCU) when that user is logged on. The handle is only valid within the scope of MigrateUserNT. Do not close this handle at any time.
UserName
The user name for the user whose registry information is supplied through the UserRegKey parameter. If this value is NULL, Setup is referring to the Windows NT logon account. The Windows NT logon account is used for creating the desktop settings for the Windows NT logon prompt and as a template for creating new Windows NT users.
Reserved
Reserved for future use.

Return Value

ERROR_SUCCESS if the migration of user-specific settings is successful.

Other error codes will terminate the processing of your migration DLL. However, Windows NT Setup will proceed. Ideally, only critical problems (such as a hardware failure) should generate terminating error codes.

Exceptions generated by your migration DLL cause Setup to report RPC error messages. Setup provides more information in SETUPERR.LOG.

Remarks

The order in which user names are passed to your migration DLL during the call to MigrateUserNT may be different than the order in which they were passed during the call to MigrateUser9x.

Setup may disable migration of one or more user accounts if errors occur. For this reason, the number of user names passed to MigrateUserNT may be less than the number passed to MigrateUser9x.

Your migration DLL is responsible for managing its private data created and stored during MigrateUser9x and processed during MigrateUserNT.

Your migration DLL must not display user messages within its MigrateUserNT function.


MigrateSystemNT

LONG
CALLBACK
MigrateSystemNT(
    IN HINF AnswerFileHandle,
    LPVOID Reserved
    );

Parameters

AnswerFileHandle
INF handle to the answer file being used for the upgrade process. This file contains settings generated by Setup, the attending user, and all migration DLLs. You can access the file referenced by this handle using the Setup functions. Do not close this handle at any time.
Reserved
Reserved for future use.

Return Values

ERROR_SUCCESS if the migration of system-wide settings is successful.

Other error codes will terminate the processing of your migration DLL. However, Windows NT Setup will proceed. Ideally, only critical problems (such as a hardware failure) should generate terminating error codes.

Exceptions generated by your migration DLL cause Setup to report RPC error messages. Setup provides more information in SETUPERR.LOG.

Remarks

Your migration DLL is responsible for managing its private data created and stored during MigrateSystem9x and processed during MigrateSystemNT.

Your migration DLL must not display user messages in its MigrateSystemNT function.


The MIGRATE.INF File

During the Windows 95 or Windows 98 phase of the upgrade, Windows NT Setup creates and uses MIGRATE.INF files to collect file information from all migration DLLs. During the Windows NT portion of the upgrade, Setup uses this same file to provide that information back to the submitting migration DLL.

Each working directory passed to a migration DLL has a MIGRATE.INF file in it. The sections are:

Section | Description
[Version] | This is a generic section required for every Windows 95- and Windows 98-style INF. It contains information about the version of Windows NT being used for the upgrade. Setup writes to this section.
[Migration Paths] | This section contains a list of Win32 paths to files requested by your migration DLL through the QueryVersion function ExeNamesBuf parameter. Each line represents the full path to a file. Setup writes to this section.
[Excluded Paths] | This section contains a list of paths not part of the active Windows 95 or Windows 98 system configuration. Setup does not search through any of these paths or their subdirectories. Excluded paths include directories on the system drive used by other operating systems, network drives, and substituted or compressed drives. Setup writes to this section.
[Handled] | You use this section to inform Windows NT Setup about files, directories, and registry entries in the active Windows 95 or Windows 98 installation you intend to migrate using your migration DLL. Setup assumes that files, directories, and registry entries listed here are compatible with Windows NT 5.0. Therefore, users will not be warned about incompatibilities associated with these components. All file names, directories, and registry entries listed in this section must be valid on the active Windows 95 or Windows 98 system. You can use the WritePrivateProfileString function for adding lines to this section.
[Moved] | You use this section to inform Windows NT Setup about files and directories you plan to move, rename, or delete during the migration. This enables Setup to adjust the relevant Windows NT Explorer shell links. You can use the WritePrivateProfileString function for adding lines to this section.
[Incompatible Messages] | You use this section to present messages to a user through the Setup incompatibility report (displayed during the Windows 95 or Windows 98 phase of the upgrade process). The report is presented to the user before any changes are made to the computer and is useful when you intend to change the behavior of an application or when you plan to remove application components.
[<Message Object Section>] | A message object section provides a mechanism for you to associate one or more message objects (file, directory, and registry location) with a message specified in the [Incompatible Messages] section.
[Windows NT Disk Space Requirements] | You use this section to specify the amount of disk space (on a per drive basis) your migration DLL requires during the Windows NT phase of the upgrade. Setup uses this information to calculate the total amount of space required for the upgrade. If sufficient space is unavailable, Setup informs the user accordingly during the Windows 95 or Windows 98 phase of the upgrade.


[Version] Section

This is a generic section required for every Windows 95- and Windows 98-style INF. It contains information about the version of Windows NT being used for the upgrade. Your DLL cannot modify it.

Signature = <File Signature>
The signature of the file. For example, $Windows NT$. This is the default.
SetupOS = <OS Identifier>
OS Identifier specifies the operating system. For the upgrade, this value is Microsoft® Windows NT® Operating System.
SetupPlatform = <Platform Identifier>
Platform Identifier specifies the object Windows NT platform upgrade. The value can be either Workstation or Server.
SetupBuild = <Build Identifier>
Build Identifier specifies the object Windows NT build upgrade. This value will be 1382 or higher (depending on the build).

See the Win32 SDK for details on the non-migration information that may be contained in the [Version] section of Windows 95- and Windows 98-style INFs.


[Migration Paths] Section

This section contains a list of Win32 paths to files requested by your migration DLL through the QueryVersion function ExeNamesBuf parameter. Each line represents the full path to a file. Setup writes to this section.

Your migration DLL can read the file paths listed here using the Setup API functions SetupGetLineCount and SetupGetLineText.

If multiple copies of a particular file name are found (such as versions installed by other applications), multiple paths to the file name will be listed in this section. When this happens, it is up to your migration DLL to determine that executables are valid for migrating your application.

If a file is not found in the active Windows 95 or Windows 98 system, it will not be listed.


[Excluded Paths] Section

This section contains a list of paths that are not part of the active Windows 95 or Windows 98 system configuration. Setup does not search through any of these paths or their subdirectories. Excluded paths include directories on the system drive used by other operating systems, network drives, and substituted or compressed drives. Setup writes to this section.

If your application is installed in any one of the paths listed in this section, your DLL must consider the application as not installed and must return ERROR_NOT_INSTALLED when initializing.

Your migration DLL can read the paths listed in this section using the Setup API SetupGetLineCount and SetupGetLineText functions. You can then use string matching to determine if a path you need is excluded. Your DLL must never make changes to the directories listed in this section.


[Handled] Section

You use this section to inform Windows NT Setup about files, directories, and registry entries in the active Windows 95 or Windows 98 installation you intend to migrate using your migration DLL.

Setup assumes that files, directories, and registry entries listed here are compatible with Windows NT 5.0. Therefore, it shall not warn users about incompatibilities associated with these components, nor will any processing be performed. For example, specifying a file path to a file in the system directory will cause it not to be moved to system32. Similarly, "handled" registry entries will not be copied to Windows NT.

All file names, directories, and registry entries listed in this section must be valid on the active Windows 95 or Windows 98 system.

You can use the WritePrivateProfileString function to add lines to this section.

The syntax for lines in this section is:

<Identifier Object> = <Identifier Type>

Identifier Object
Specifies the name or path to a Windows 95 or Windows 98 file, directory, or registry location. Files and directories are in long file name format. Registry paths are of the form:

<Root>\<SubKey>\<SubKey>\<…> [<Value Name>]

where:

Root
Specifies the registry root. It can be any one of HKEY_LOCAL_MACHINE, HKLM, HKEY_ROOT or HKR (migration DLLs can only handle a registry key for ALL users, not for individual users)
SubKey
Specifies one or more registry keys separated by back slashes (\)
Value Name
(Optional) Specifies a registry value name enclosed in square brackets. An empty square bracket ([ ]) specifies the default value for the specified key name.

Registry keys or value names themselves may contain square brackets ([ ]), tildes (~), or characters with values greater than 127. You must enclose hexadecimal value for these characters in tildes (~) when writing them as registry values to the [Handled] section. For more information, see Handling Special String Characters.

Identifier Type
Identifies the type of <Identifier Object> to be handled. It must be one of the following three values:
File
The object specified refers to a long file name (including the full path to the file). This must be a full path, without environment variables, and without short versions of long file names.
Directory
The object specified refers to a directory (including the full path to the directory).
Registry
The object specified refers to a registry key (including the full path to that key).


[Moved] Section

You use this section to inform Windows NT Setup about files and directories you plan to move, rename, or delete during the migration. This enables Setup to adjust the relevant Windows NT Explorer shell links.

You can use the WritePrivateProfileString function for adding lines to this section. Listing a file here will cause it not to be processed in any other way, just like it was in the [Handled] section.

The syntax for this section is:

<OldPath> = <NewPath>

OldPath
Specifies the file name or path of a Windows 95 or Windows 98 file or directory to be moved or deleted. File names and paths are in long file name format.
NewPath
Specifies the new file name or path, again in long file name format. If NewPath is empty or not specified, Setup will delete OldPath.


[Incompatible Messages] Section

You use this section to present messages to a user through the Setup incompatibility report (displayed during the Windows 95 or Windows 98 phase of the upgrade process). The report is presented to the user before any changes are made to the computer and is useful when you intend to change the behavior of an application or when you plan to remove application components.

The syntax for this section is:

<Message Object Section> = <Message>

Message Object Section
Specifies the name of a custom section (defined by your migration DLL) that contains a list of message objects such as files, directories, and registry entries. The name may be any combination of uppercase and lowercase letters, numbers, and spaces. It may not start or end with a space. By listing one or more message objects in a separate section, your DLL can associate several message objects with a single message. The value for Message Object Section is used as the component string in the compatibility report presented to the end user.
Message
Is a string describing the details of the incompatibility or message to be displayed to the user. The user will see the text in a multiline, scrollable, read-only edit control.

For example, this incompatibility section may contain the following line:

MyAppMsg = "The DOS and Real-mode portions of Myapp.exe are not supported on Windows NT"

Where MyAppMsg refers to another section containing the list of files, directories, and registry entries associated with the message string.

Notes When you write an entry to the [Incompatible Messages] section, a Message Object Section must provide one or more objects associated with the message.

Your migration DLL is responsible for managing the code page and language dependencies of the messages listed in this section. In particular, the text in the [Incompatible Messages] section must be in the same language as the active Windows 95 or Windows 98 system. Your DLL must not write messages to this section if it does not support the active operating system language.

The user has an option to view, print, or save the incompatibility report generated. This report will associate the ProductID with each Message.


[<Message Object Section>] Section

A message object section provides a mechanism for you to associate one or more message objects (such as file, directory, and registry location) with a message specified in the [Incompatible Messages] section. The [Handled] section describes how to specify a message object.

The section name is defined by your migration DLL. Each line has the following syntax:

<Message Object> = <Identifier Type>

Message Object
Specifies a Windows 95 or Windows 98 file, path, or registry entry. A file or path must be specified in long file name format.
Identifier Type
Identifies the type of <Message Object>. It can only have one of the following three values:
File
The object specified refers to a long file name (including the full path to the file).
Directory
The object specified refers to a directory (including the full path to the directory).
Registry
The object specified refers to a registry key (including the full path to that key).
  • Setup uses the value for Message Object Section to develop a hierarchy for incompatibility messages. The use of the section name enables your migration DLL to organize multiple incompatibility messages in the same format that Setup uses. Setup processes the section name in one of two ways:
    1. If the name of the section matches ProductID, Setup displays the message at the root level of the incompatibility message tree. The ProductID itself is listed in a tree control, and when the user clicks on the root item, the incompatibility message is shown in an edit control.
    2. If the name of the section contains one or more backslashes, Setup separates the string at the backslashes to create the hierarchy. Setup limits the number levels in the tree to 10. Optimally, you should organize your messages into 3 levels.

    Using the section name in this way achieves unique children for each migration DLL, organized under a single item at the root. Because ObjectSection is used for display purposes, your DLL must provide localized strings.

  • Setup treats all objects in a section as a set. If every object in the set is found in any [Handled] section (including ones provided by other vendors), no incompatibility message will be displayed for the particular object, even if the message is listed in [Incompatible Messages]. If only some or none of the objects are handled, the message will be displayed.


[Windows NT Disk Space Requirements]

[Windows NT Disk Space Requirements] Section

You use this section to specify the amount of disk space (on a per-drive basis) your migration DLL requires during the Windows NT phase of the upgrade. Setup uses this information to calculate the total amount of space required for the upgrade. If sufficient space is unavailable, Setup informs the user accordingly during the Windows 95 or Windows 98 phase of the upgrade.

The syntax for this section is:

<DriveLetter> = <Space Required>

DriveLetter
Specifies the drive/partition (single letter without a colon or backslash) in which a migration DLL requires space for its private data. Setup will ignore drives/partitions that are also listed in the [Excluded Paths] section.
Space Required
Is an integer that indicates the amount of disk space in (bytes) required by a migration DLL during the Windows NT phase of Setup. When calculating space requirements, the amount of space lost from directory and cluster use must be taken into account. The number does not include the files copied into the working directory during the Windows 95 or Windows 98 phase.

If this section is not present, or if no drives or partitions are specified, Setup assumes that the migration DLL requires no additional hard disk space to migrate the target application.

Important Be sure to specify the correct disk space requirement data. If you cannot calculate disk space requirements accurately, you should provide a liberal estimate of the space required.


Sample Migrate.inf file

;
; Sample migrate.inf file
;
[Version]
Signature = $Windows NT$
SetupOS = Microsoft(R) Windows NT(R) Operating System
SetupPlatform = Workstation
SetupBuild = 1610

[Migration Paths]
"c:\windows\foo.exe"
"c:\temp\foo.exe"
"C:\program files\foo\bar.exe"
"C:\foofiles\bar.exe"

[Excluded Paths]
"c:\winnt40"
"f:\"

[Handled]
"C:\windows\foo.exe"=File
"C:\windows\foo.dll"=File
"c:\Program Files\foo"=Path
"HKLM\Software\Foo-Bar, Inc."=Registry

[Moved]
;moved
"c:\dir\boo.exe"="c:\dir\nt\boo.exe"

;moved and replaced
"c:\Windows\foo.exe"="c:\Windows\foo\foo_nt.exe"

;deleted
"c:\Windows\foo\Win9x"=""

[Incompatible Messages]
;the message must be on one line, but can be long
Foo-Bar ="The application Foo-Bar does not support the DOS component 'boo' on Windows NT."

[Foo-Bar]
"C:\dir\boo.exe"=File
"C:\dir\boo.dll"=File

[NT Disk Space Requirements]
c=104096
d=16384


Integrating with Setup Computer Wizard

You can simplify the details of installing your application on Microsoft® Small Business Server by integrating your Setup program with the Setup Computer Wizard (SCW). By integrating with SCW, you can have your application available for deployment and installation on client computers throughout the Small Business Server Network.

This section details the following information about integrating with SCW.

  • Overview
  • Requirements for Your Application
  • Requirements If You Use a Response File
  • Modifying CLIOC.INF
  • Modifying SCW.INI
  • Creating your Application .INF
  • Other Considerations


Overview

To integrate, you need to do the following:

  • Configure your Setup program for unattended installation, and reboot delay (this enables the entire installation to be automated).
  • Create an information (INF) file that details how to install your application. SCW will use this INF file to run your Setup program on the client computer.
  • Modify the existing SCW client setup process to include your application.
  • Create a preinstallation application that installs your Setup program and your application files to the correct server location.

When the network administrator installs your application to its network location, it is your preinstallation program that runs. Your preinstallation program performs the following:

  1. Copies the INF file for your application to the %sbs%\SmallBusiness\Template directory.
  2. Copies all the files needed by your actual client Setup program to the server location specified in the INF file for your application.
  3. Modifies the Setup Computer Wizard initialization file, SCW.INI.
  4. Modifies the client optional component file, CLIOC.INF.

When users elect to install your application, the Setup Computer Wizard uses the information specified in your application's INF file to install your application on the client computer.


Requirements for Your Application

To make use of SCW integration functionality, your application Setup program must comply with the following requirements:

  • It must provide an unattended or automated installation mode. This enables Small Business Server to automate all application installations on Small Business Server clients.
  • The option to eliminate prompt for reboot. Since more than one application will likely be installed on the client workstation during Setup, SCW postpones machine reboot until after all queued applications have been installed.


Requirements If You Use a Response File

If your Setup program uses a response file during its unattended mode, it must:

  • Create a master copy (template) of this file that will be used for all installations. It exists on the server as the response file used for all client installations of your application.
  • Within this master copy, use SCW variable names for fields that must be substituted during installation.

    For example, HomeDir=%SBSServer%

Note At present, %SBSServer% is the only SCW variable name defined. Future versions of SCW will provide others.


Modifying Clioc.inf

The client optional component file (Clioc.inf) is used exclusively by applications using the integration features of the Setup Computer Wizard (SCW).

Your preinstallation program will find the Clioc.inf file in the %sbs%\SmallBusiness\Template directory. The name and identifier of your application setup .inf file must be added to this file.

Your preinstallation program must add your application setup .inf information to the [Components] section of Clioc.inf.

Entries in the [Components] section have the following format:

"","",<inf-file-name>

where

inf-file-name
The name of the information file that you supply with your Setup program.

Note The first two quote-enclosed null fields in the line are required.

Do not place your application entry after the client entry. In addition, do not change the order of any of the applications already listed.

If your preinstallation program places the entry for your application setup INF file in another location within Clioc.inf, SCW will ignore that entry. Users will not be able to install your application.

The following shows the content of the default Clioc.inf file.

[Components.w95]
proxy = "","",cliproxy.inf
outlook = "","",clioutl.inf
clifax = "","",clifax.inf
mshare = "","",climshr.inf
ie3 = "","",cliie3.inf
client = ..\..\setup\win95\ocsam.dll,OcEntry,client.inf

[Components.x86]
proxy = "","",cliproxy.inf
outlook = "","",clioutl.inf
clifax = "","",ntfax.inf
mshare = "","",ntmshr.inf
ie3 = "","",cliie3.inf
client = ..\..\setup\i386\ocsam.dll,OcEntry,client.inf

You must add the line describing your application to both the Components.w95 and Components.x86 blocks if it runs on both the Microsoft® Windows NT® and Microsoft® Windows® 95 platforms. If it runs only on Windows 95, then add your application to the components.w95 section only.

In addition, you must also add a register key and value so SCW can detect whether your application is already installed. You do this by adding a section to the end of the CLIOC.INF file in the format:

HKLM="<register key>","<value>"

For example:

[client]
HKLM="SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\Client","DisplayName"


Modifying Scw.ini

Before your preinstallation application can modify the Scw.ini file, it must determine the available application number.

The available application number is identified under the [SCW_OptionalApplications] with the SCW_NumberOfApps entry. For example, if, before you modify it, the Scw.ini file contains the following lines

[SCW_OptionalApplications]
SCW_NumberOfApps=6

then the identification number for your application will be 6. Your preinstallation program must increment this to the next greatest number (in this case, to 7) before it adds the information about your application.

Once it determines the available application number, your preinstallation program needs to add the following information to the [SCW_OptionalApplications] section of the Scw.ini file. Note you must append the number of your application to each key name (represented in the example below by x).

SCW_AppNamex=<application symbol name>
Internal name SCW uses to identify your application. Do not use spaces in the application symbol name. This value is required.
SCW_AppDisplayStringx=<message display name>
This is the string SCW displays in message boxes and log files. You can use spaces in the message display name. This value is required.
SCW_AppSelectedByDefaultx=[NO|YES]
If Yes, SCW will enable the check box to set up your application. If No, SCW will clear the check box. Either Yes or No is required.
SCW_AppRequiresUnattendedTextFilex=[NO|YES]
If Yes, your application requires a response file for unattended mode. (You must also provide the response file). If No, your application requires no response file. Either Yes or No is required.
SCW_AppTemplatePathx=<appTemplatePath>
Path and name of application's .inf file. This path must be relative to the %SBSServer%\SmallBusiness directory. The Template directory is the preferred location.
SCW_AppTemplateSourceNamex=<appTemplateSourceName>
Initial name of the unattend/response file template at the location specified in SCW_AppTemplatePathx.
SCW_AppTemplateDestNamex=<appTemplateDestName>
The name to which the SCW_AppTemplateSourceNamex file must be changed after it is installed.
SCW_AppSetupInfPathx=Template
Path to the .inf file that describes how to install your application (that is, the .inf file you created for preinstallation). This path must be relative to the %SBSServer%\SmallBusiness directory. The Template directory is the preferred location.
SCW_AppSetupInfSourceNamex=<appSetupInfSource>
This is the name of the INF file you created for preinstallation (not the INF file used by your application Setup program).
SCW_AppSetupInfDestNamex=<appSetupInfDest>
The name to which the SCW_AppSetupInfSourceNamex file must be changed after it is installed.
SCW_ArchitectureListx=[win95|i386]
If your application runs on Microsoft® Windows® 95 only, specify win95. If your application runs on both Windows 95 and Microsoft® Windows NT®, specify i386.

Example Scw.ini Modification

The following excerpt details how "Bob's Time Card Application" would be defined in the Scw.ini file [SCW_OptionalApplications] section.

[SCW_OptionalApplications]

; The value for SCW_NumberOfApps is available for the *next* application
SCW_NumberOfApps=6
;
;The following lines reflect the new fields that need to be created when
; adding an application to SCW.

SCW_AppName5=BOB_TIMECARD
SCW_AppDisplayString5=Bob's Time Card Application
SCW_AppSelectedByDefault5=NO
SCW_AppRequiresUnattendedTextFile5=NO
;
;three unused options follow
SCW_AppTemplatePath5=
SCW_AppTemplateSourceName5=
SCW_AppTemplateDestName5=
;
SCW_AppSetupInfPath5=Template
SCW_AppSetupInfSourceName5=timecard.inf
SCW_AppSetupInfDestName5=timecard.inf
SCW_AppArchitectureList5=win95

SCW detects the end of your entry when it encounters the next SCW_AppNamex= entry.


Creating Your Application .INF

Your application requires a standard Setup .inf file. This section details only those modifications required to integrate with the Setup Computer Wizard (SCW). For more information on the .inf file required for setting up your application, see the documentation that accompanied your Setup management software.

Along with the other information you must place in your application .inf file, you must provide the following information to SCW:

  • The name of the .inf section that contains information about your setup application.
  • The symbol number of the icon to associate with your application.
  • The command line text to install your application on the client workstation.
  • The command line text to remove (uninstall) your application from the client workstation.
  • The amount of disk space in megabytes that your application needs during installation. This includes temporary files and directories.
  • Message strings your application may need to display during installation.
To create the .inf file for your setup application
  1. Include the required [Version] section.
  2. Under the [Version] section, include the Signature parameter with the value $WINDOWS NT$.
  3. Include the [Optional Components] section.
  4. Under the [Optional Components] section, include the name of the section that contains the information about your Setup application. Only one application per .inf file is allowed.
  5. Under your [application] section, you can use the optional OptionDesc and Tip parameters to provide explanatory text about your application to SCW. The values for these optional parameters must be string parameters defined in the [Strings] section.
  6. Under your [application] section, add the IconIndex parameter with the index number of the icon you plan to use for your application Setup program. Legal values for IconIndex are defined in Icon Indices.
  7. Under your [application] section, add the InstallCmd parameter with the actual quoted text required to run your Setup program in unattended mode. Do not use a value from the [String] section.

    Use the %SBSServer% environment variable for the path to the server, and construct the install command from that location. Small Business Server shares the %SBSServer%\CLIENTS directory that you can use for this purpose. If you don't use the %SBSServer%\CLIENTS directory, then you will have to make sure that users who install your application has permission to run programs in the directory.

  8. Under your [application] section, add the UninstallCmd parameter with the actual quoted text required to remove your application from the client computer in unattended mode. Do not use a value from the [String] section.
  9. Under your [application] section, add the DiskSpaceEstimate parameter with the number of megabytes your setup application needs on the client computer during installation. This includes temporary directories.
  10. Under the [Strings] section, add the string parameters for optional messages you need.

Example INF File

The following example depicts the INF provided by the developer of the fictional Bob's Time Card Application.

;
; timecard.inf
;
; Component INF for installing Bob's Time Card Application
;
; Note the use of the variable $SAMSERVERNAME$ in the
;  InstallCmd parameter value, which is substituted by SCW
;
; Required section for all INF files. See the SDK for
;  other legal values
[Version]
Signature = "$Windows NT$"
;
; You add this section and the name of the section that
;  contains your application setup information
[Optional Components]
timecard
;
; Here's the actual application section
[timecard]
; Optional 'application description' and 'tip' section.
;  The timecard_desc string is defined in the [Strings] section.
OptionDesc = %timecard_desc%
Tip = %timecard_tip%
;
; Required icon definition for the application Setup program
;  (This is NOT your application's icon)
IconIndex = 0
;
; Required value for the command-prompt unattended installation.
;  The %SBSServer% variable is the location of the Small Business Server
;  software.
InstallCmd = "\\%SBSServer%\clients\timecard\setup /auto $SAMSERVERNAME$"
;
; Required value to run an unattended program from the command prompt
;  to remove your application from the client computer
UninstallCmd = "\\%SBSServer%\clients\timecard\setup /uninstall"
;
; This application requires 7 megabytes of disk space on the client
;  computer during installation.
DiskSpaceEstimate = 7
;
; Standard section. Required when you use string parameters.
[Strings]
; This value is used in the OptionDesc parameter
timecard_desc = "Bob's Time Card Application"
;
; This value is used in the Tip parameter
timecard_tip = "Lets users log their hours"


Icon Indices

This section lists icon indices for use with the IconIndex field in .Inf files that are created for installing applications using the Small Business Server client setup process. These icons are defined within SCW, and will be available during your application setup.

Index | Icon
0 | computer
1 | chip
2 | display
3 | network
4 | windows
5 | mouse
6 | keyboard
7 | phone
8 | sound
9 | drives
10 | plugs
11 | generic
12 | checked box
13 | unchecked box
14 | printer
15 | nettrans
16 | netclient
17 | netservice
18 | question mark
19 | fax
20 | grayed check
21 | dial-up networking
22 | direct cable connection
23 | briefcase (filesync)
25 | partial check
26 | Start menu program group
27 | multimedia
28 | drive and magnifying glass
30 | Calculator
32 | generic document
33 | pie graphs
34 | solitaire cards
35 | computer and modem
36 | artists tools
37 | paint bucket
38 | terminal
39 | pad and pen
40 | Clipboard
41 | accessibility
42 | hard drive to floppy
43 | paint
45 | arrow and hourglass
47 | hand dialing phone
48 | shaded graph
49 | help (book)
50 | globe
51 | .wav file
52 | music compact disc
53 | director's cue
54 | computer speaker
55 | AVI
56 | AVI


Other Considerations

Detect if a user has run your Setup program from a client computer connected to a Microsoft® Small Business Server and give the user the option to integrate with client setup.

Provide tools that integrate with the client setup process automatically to automate this process. This could include copying files and making the modifications to the Scw.ini file.

Test your applications to verify they install and work successfully. Some applications may not integrate well with the SCW installation model.

Work with your customers to ensure they have the required software licenses. SCW provides a deployment mechanism for installing applications. It doesn't implement licensing. If your application requires licenses for each computer, you must configure.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.