Migrating from InstallShield Professional 5.x
InstallShield 2020
Project:This information applies to InstallScript Object projects.
Script Changes
The basic structure of an InstallShield Professional 5.x script is supported in the InstallScript project type in InstallShield 2020. To compile a Professional 5.x script in InstallShield, you must first make the following changes:
Preprocessor Directives
| • | Include the following statement at the beginning of your script: |
#include "ifx.h"
| • | Remove any #define statements for SD_SINGLE_DIALOGS and its associated SD_<dialog name> constants. |
| • | You may need to remove some #define statements that define Windows constants if those statements result in compiler errors. Many Windows constants are defined in Ifx.h (which is in the InstallShield Program Files Folder\Script\Isrt\Include subfolder) or its included files. |
Built-In Functions
| • | Remove the following functions, which were supported in Professional 5.x but are not supported in InstallShield 2020. Some of these functions will compile, but they will not give the expected results. Where possible, supported alternatives are suggested. |
|
Professional 5.x Function |
Suggested Alternative |
|
AppCommand |
None. (Appropriate only for platforms using the Program Manager shell, which are no longer supported.) |
|
AddProgItemEx |
AddFolderIcon |
|
CmdGetMsg |
Windows API function GetMessage (call CmdGetHwndDlg to get the dialog handle) |
|
CmdGetParam1 |
Windows API function GetMessage (call CmdGetHwndDlg to get the dialog handle) |
|
CmdGetParam2 |
Windows API function GetMessage (call CmdGetHwndDlg to get the dialog handle) |
|
CommitSharedFiles |
The actions performed by this function in Professional 5.x are done automatically in InstallShield 2020. |
|
CreateProgGroupEx |
AddFolderIcon |
|
DeleteGroup |
DeleteProgramFolder |
|
DeleteProgItem |
DeleteFolderIcon |
|
ExitProgMan |
None. (Appropriate only for platforms using the Program Manager shell, which are no longer supported.) |
|
GetGroupNameList |
GetFolderNameList |
|
GetItemNameList |
None. (Appropriate only for platforms using the Program Manager shell, which are no longer supported.) |
|
QueryProgGroup |
None. (Appropriate only for platforms using the Program Manager shell, which are no longer supported.) |
|
RegDBCreateKey |
RegDBCreateKeyEx |
|
RegDBCreateKeyValue |
RegDBCreateKeyValueEx |
|
RegDBGetKeyValue |
RegDBGetKeyValueEx |
|
RegDBSetKeyValue |
RegDBSetKeyValueEx |
|
ReloadProgGroup |
None. (Appropriate only for platforms using the Program Manager shell, which are no longer supported.) |
|
ReplaceProgItem |
None. (Appropriate only for platforms using the Program Manager shell, which are no longer supported.) |
|
ShowGroup |
None. (Appropriate only for platforms using the Program Manager shell, which are no longer supported.) |
| • | Call Disable(LOGGING) before any code that makes changes to the target system that you do not want logged for uninstallation, and call Enable(LOGGING) after that code. This is necessary because logging of changes for uninstallation is automatically enabled before any script code is executed. |
Note that this is different from Professional 5.x installations in which logging did not begin until DeInstallStart was called. If you have any installation actions that previously were not logged because they occurred before DeInstallStart, you will need to add an additional Disable(LOGGING) call before these installation actions to disable logging manually.
If you want your installation to display a background, you must call Enable(BACKGROUND). In InstallShield 2020, the background is disabled by default, whereas in Professional 5.x it was enabled by default. (In event-based scripts, code for customizing and displaying a background exists in comment lines at the beginning of the default code for OnFirstUIBefore. To activate this code, remove the slash characters at the beginnings of the desired lines.)
Note that some user-interface functions, such as PlaceBitmap, will not work properly (nor return a negative value to let you know they failed) if the installation background is not enabled.
| • | It is no longer necessary to call RegDBSetItem with the argument REGDB_UNINSTALL_NAME to set the value of [DisplayName] under the uninstallation key. This is now done when MaintenanceStart or DeinstallStart is called. |
| • | Calling SetColor with STATUSBAR as its argument will not have any effect in InstallShield 2020; status bars are drawn using system colors. |
| • | When you call StrGetTokens, if the first (or last) character of szString matches a character in szDelimiterSet, a null string ("") is not inserted in the list as the first (or last) element. Instead, the characters between the first and second (or last and next to last) delimiters are inserted in the list as the first (or last) element. |
| • | When you call StrGetTokens, if a wildcard character is included in the filename specified by szSrcFile, the filename part of szTargetFile is not ignored as in previous versions of InstallShield Professional; instead, all of szTargetFile is treated as the target path to which each source file is copied to with its existing name. For example, CopyFile( "C:\\*.*", "D:\\File.txt" ) copies files to a folder named File.txt on the D drive. |
| • | WaitOnDialog now returns IDCANCEL when the end user selects the system menu’s Close command or clicks the title bar’s Close button from a custom dialog. In previous versions, DLG_CLOSE was returned in these cases. |
| • | If you pass GetSystemInfo a first argument of DRIVE and a third argument that is a UNC path, the function correctly returns a negative value. Previously it returned zero, falsely indicating success, although due to operating system limitations UNC paths are not supported in that case. |
| • | When you call ParsePath with its third argument set to PATH and its second argument set to a UNC path that includes only a server name without a trailing backslash (for example, "\\\\TheServer"), the function correctly sets the first argument equal to a double backslash ("\\\\"). In Professional 5.x, the function would set the first argument equal to a single backslash ("\\"). |
| • | The Professional 5.x Help Library listed specific numeric return values, other than 0 (zero) for success, for some functions. Some of these numeric values have changed for InstallShield 2020; a script used in InstallShield 2020 should compare a function’s return value only to the constants that are currently listed in that function’s help. |
| • | In order for the end-user interface to flow smoothly, by default the installation initialization dialog remains displayed until the script displays a dialog. To close the installation initialization dialog, call Disable(DIALOGCACHE) or any dialog function. |
| • | ComponentMoveData’s second argument no longer returns useful data. |
| • | Passing a pointer to a string as the fourth argument of SendMessageTimeout no longer gives the expected result. To pass string data to SendMessageTimeout, see the Additional Information section of the SendMessageTimeout topic. |
Predefined Constants
| • | Remove the following constants, which were supported in Professional 5.x but are not supported in InstallShield 2020: |
COMPONENT_VALUE_ALWAYSOVERWRITE
COMPONENT_VALUE_NEVEROVERWRITE
COMPONENT_VALUE_NEWERDATE
COMPONENT_VALUE_NEWERVERSION
COMPONENT_VALUE_OLDERDATE
COMPONENT_VALUE_OLDERVERSION
COMPONENT_VALUE_SAMEORNEWDATE
COMPONENT_VALUE_SAMEORNEWERVERSION
COMPONENT_FIELD_DESTINATION
COMPONENT_FIELD_OVERWRITE
| • | Remove statements that assign values to the following predefined variables (for example, TARGETDISK="C:\\";). Such statements will not compile in InstallShield 2020; these constants are now read-only. |
CMDLINE
COMMONFILES
ERRORFILENAME
FOLDER_DESKTOP
FOLDER_PROGRAMS
FOLDER_STARTMENU
FOLDER_STARTUP
ISRES
ISUSER
ISVERSION
MODE
PROGRAMFILES
SUPPORTDIR
TARGETDISK (The value of this variable is automatically updated when TARGETDIR is changed.)
UNINST
WINDIR
WINDISK
WINSYSDIR
WINSYSDISK
DLLs
| • | When you called a DLL function in Professional 5.x, all string arguments were passed by reference; in InstallShield 2020, you can pass a string argument by value. To specify the method for passing an argument, in the function prototype, precede the argument’s data type with the BYREF or BYVAL keyword; for example, MyDLL.MyFunc(BYREF NUMBER, BYVAL STRING). The InstallShield 2020 compiler includes the following compiler warnings to encourage the use of the appropriate keyword. |
| • | If your script includes DLL function calls where neither BYREF nor BYVAL has been specified, you receive compiler warning W7507. To eliminate this warning, add the appropriate keyword to the function prototype. |
| • | If you specify a literal string for a string argument that is passed by reference, you receive compiler warning W7511. To eliminate this warning, add the BYVAL keyword to the function prototype. |
When you call a function in an external DLL, make sure the same calling convention is used in the script and the DLL. In Professional 5.x, the installation engine always used the stdcall convention but would sometimes overlook an inconsistent DLL convention. The InstallShield 2020 engine does not; it generates an error (exception 0x80040704) when the wrong calling convention is used.
In your script, you can declare a calling convention, either cdecl or stdcall, when declaring a DLL function. For example:
prototype cdecl MyDLL.MyFunction (INT, INT);
If you do not explicitly declare a calling convention, InstallShield uses stdcall.
| • | In InstallShield 2020, InstallScript arrays are internally formatted as OLE Automation safe arrays, not native C or C++ arrays. To pass an InstallScript array to a DLL function that expects a C or C++ array, you must place the array data in the expected format by calling GetCArrayFromISArray. |
| • | In InstallShield 2020, a string variable whose address is stored in a pointer variable cannot be changed by passing the pointer to a DLL function. To allow a DLL function to change the value of a string variable, pass the variable itself as an argument to the function, after declaring the data type of that argument specifying the BYREF operator. |
| • | You no longer need to call the UseDLL function before calling a DLL that is located on Windows’ DLL search path. The DLL search path is the following: |
| 1. | The folder from which the application loaded. |
| 2. | The current folder. |
| 3. | The 32-bit Windows system folder. |
| 4. | The 16-bit Windows system folder. |
| 5. | The Windows folder. |
| 6. | The folders that are listed in the PATH environment variable. |
Use this feature with caution; the values of the current folder and PATH environment variable on an end user’s machine are not predictable.
Miscellaneous
| • | The undocumented array syntax ArrayName[nArrayIndex] is no longer supported. In InstallShield 2020, the syntax for all arrays is ArrayName(nArrayIndex). |
| • | If you explicitly declare a return type for a script-defined function, you must specify the same return type in the function definition, after the keyword "function", or the script will not compile. (If you do not explicitly declare a return type, the return type is assumed to be NUMBER.) In previous versions of InstallShield Professional, return types were assumed to be NUMBER regardless of explicit specifications of other return types, so this issue did not arise. |
| • | To place uninstall information under HKEY_CURRENT_USER, set the value of the ALLUSERS system variable to FALSE. |
| • | To pass a literal character as an argument to a built-in or user-defined function, you must pass its numeric ASCII value. |
| • | When processing the system variable CMDLINE, be aware that the following command line switches are no longer used by Setup.exe and so are included in CMDLINE: -SMS, -z, -c, -e, -q, -t, and -x. The -SMS switch is obsolete because now Setup.exe always stays in memory until the installation is complete. The -z switch is obsolete because now Setup.exe initializes correctly even on systems with more than 256 megabytes of memory. |
| • | Remove Professional 5.x’s ODBC Template code, which will not compile in InstallShield 2020. This is because the following function call is nested within the code: |
ComponentGetData ( szMedia, szCompName,
COMPONENT_FIELD_DESTINATION, nvData, svDest );
In InstallShield 2020 this function call does not compile because the Destination property is a file group property, not a component property.
Other Changes
| • | Pressing F3 no longer works to exit an installation. |
| • | Setup.exe no longer supports the -f switch for using a renamed Setup.inx. |
| • | InstallShield 2020 installations do not support including special billboards for low-resolution systems. |
| • | If neither a source file nor the already-existing target file has a version number, and the source file’s file group’s Overwrite property is "Newer Version", "Same or Newer Version", or "Older Version", then the file on the target system is not overwritten. In Professional 5.x installations, the target file would be overwritten. |
| • | InstallShield 2020 does not support displaying Windows 95-style dialogs. |
| • | The Lang key in a silent installation’s response (.iss) file’s [Application] section no longer has any effect. |
| • | In Professional 5.x installations, any registry key logged by the installer would be removed during uninstallation in any case. In InstallShield 2020, keys created by RegDBCreateKeyEx and non-shared keys in registry sets are removed only if the installer created the key, that is, the key did not exist when the installation was run. |