Customizing Desktop Engine Setup.exe

Desktop Engine Setup.exe installs an instance of MSDE 2000. It can be executed in two ways:

• Running it in a command prompt window.
  
  
• Running it from within a wrapper application, such as a Microsoft® Windows® application that calls the Win32® CreateProcess() function. For information about using CreateProcess() to execute Setup.exe, see Desktop Engine Installation Samples. Additional information and samples are available on this MSDE 2000 Web site.

The behavior of Setup is controlled by switches and parameters. Switches can be specified in these locations:

• On the command prompt, when Setup is run in the command prompt window.
  
  
• In a character string using the lpCommandLine parameter, when Setup is run from a program calling CreateProcess().

Parameters can be specified in the same manner as switches, either on the command prompt or in an lpCommandLine parameter. Parameters can also be specified in an .ini file specified in a /settings switch.

The Setup.exe switches are: /?, /i, /settings, /L*V, /upgradesp, /qn, /qb, and /x.

The Setup.exe parameters are: ALLOWXDBCHAINING, BLANKSAPWD, CALLBACK, COLLATION, DATADIR, DISABLENETWORKPROTOCOLS, INSTANCENAME, SAPWD, SECURITYMODE, TARGETDIR, UPGRADE, UPGRADEUSER, and UPGRADEPWD.

Before running Desktop Engine Setup.exe, ensure that your computer meets the hardware and software requirements for SQL Server 2000 database software. For more information about these requirements, see Hardware and Software Requirements for Installing SQL Server 2000. In addition, file and print sharing must be enabled for you to run the Desktop Engine Setup.exe, except on Windows 98 and Windows Millennium Edition. In Control Panel, select Network Connections. Select the Advanced/Advanced Settings menu item. Ensure File and Print Sharing for Microsoft Networks is enabled on the Adaptors and Bindings tab.

New MSDE 2000 users who are attempting to run the Desktop Engine Setup.exe from the command prompt can view the examples later in this topic to find out how to run Setup.exe in typical installation scenarios.

Security Note  The version of the Desktop Engine included in SQL Server 2000 SP3a includes fixes to address the issues raised by the Slammer worm. You should always install the version of Desktop Engine from SQL Server 2000 SP3a or later. This topic describes the behavior of the SP3a Setup.exe file.

Security Note  Installation with a blank sa password is strongly discouraged. The Installer's default behavior is to require that an sa password be set using the SAPWD parameter. This requirement can be overridden by setting BLANKSAPWD=1, but that should only be done if you have an application that requires that the sa login have a null password.

Syntax

setup [/?]

   [

      [   /i package_file

          [ /settings ini_file ]

          |   [   [ ALLOWXDBCHAINING=1 ]

                   [ BLANKSAPWD=1 ]

                   [ CALLBACK=Dllname!CallbackFunctionName ]

                   [ COLLATION="collation_name" ]

                   [ DATADIR="data_folder_path" ]

                   [ DISABLENETWORKPROTOCOLS=n ]

                   [ INSTANCENAME="instance_name" ]

                   [ SAPWD="sa_password" ]

                   [ SECURITYMODE=SQL ]

                   [ TARGETDIR="executable_folder_path" ]

                   [ UPGRADE=1 ]

                   [ UPGRADEUSER=admin_login ]

                   [ UPGRADEPWD=admin_password ]

              ]

      ]

   [ /L*v [filename] ]

   [ /upgradesp { SQLRUN

                           | <MSIPath>SQLRunnn.msi }

   ]

   [ /qn | /qb ]

   [ /x package_name ]

   ]

Arguments

/?

Displays a syntax summary of the setup options.

Important  Because setup displays more options than it accepts, use only the options documented in this topic.

/i package_file

Specifies the name of the Windows Installer installation package file (an .msi file) to be used to install an instance of the Microsoft SQL Server™ 2000 Desktop Engine (MSDE 2000). The package file specified must be one of the .msi files (Sqlrun01.msi through Sqlrun16.msi) distributed in the /MSDE/Setup folder. Place the .msi file in the same folder as Setup.exe. If /i is not specified, copy all 16 of the .msi files from the /MSDE/Setup folder on the SQL Server 2000 compact disc to the folder in which Setup.exe is located.

For SP3 or later, the preferred approach is to specify the INSTANCENAME parameter instead of the /i option. If all of the .msi package files are present, then Setup will dynamically select which package file to use for the installation. If neither /i nor INSTANCENAME are specified, Setup will dynamically select the package file and install a default instance.

Caution  It is possible to overwrite an instance by mistake. You must check for instances that are already present, including instances installed by other vendors' software.

/settings ini_file_name

Specifies the name of an .ini file containing settings for the Setup parameters ALLOWXDBCHAINING, DISABLENETWORKPROTOCOLS, TARGETDIR, DATADIR, INSTANCENAME, COLLATION, and SECURITYMODE. If /settings is specified, these parameters should be set in the .ini file, not on the command prompt. Place the .ini file in the folder where Setup.exe is located.

ALLOWXDBCHAINING=1

In SQL Server 2000 Service Pack 3 (SP3) or later, overrides the default behavior of the Installer and enables cross database ownership chains for the instance. For more information about cross database chaining, see Cross DB Ownership Chaining. You should not use this parameter unless you are running an application that requires cross database ownership chains.

BLANKSAPWD=1

Overrides the Installer's default behavior, which is to require that you specify a strong sa password. If you specify BLANKSAPWD=1, the Installer assigns a null password to the sa login

Security Note  Assigning a null, blank, simple, or well-known password to the sa login can allow unauthorized people access to your data.

CALLBACK=Dllname!CallbackFunctionName

Specifies the name of the DLL containing the Desktop Engine Windows Installer callback function, and the name of the callback function. For more information, see Windows Installer Callback Functions for Desktop Engine.

COLLATION="collation_name"

Specifies the SQL Server collation that will be used as the default collation for this instance of the Desktop Engine. For information about collation names, see Windows Collation Name and SQL Collation Name.

DATADIR="data_folder_path"

Specifies the folder where the SQL Server system databases are built. Assuming that the system default for program files is C:/Program Files:

• The default value for default instances is: C:/Program Files/Microsoft SQL Server/MSSQL/Data/.
  
  
• The default value for named instances is C:/Program Files/Microsoft SQL Server/MSSQL$<instance_name>/Data/, where instance_name is the name specified in the INSTANCENAME option.

  The file path for this parameter must end with a backslash (/). When installing a default instance, setup appends mssql/data to the end of the path specified in DATADIR. When installing a named instance, setup appends mssql$<instance_name>/data, where instance_name is the value specified in the INSTANCENAME option.

  Setup builds two other folders at the same location as the Data folder, a Log folder for the database engine error logs, and an Install folder containing installation scripts.

Note  Settings that contain spaces should be enclosed with quotation marks.

DISABLENETWORKPROTOCOLS=n

In SQL Server 2000 SP3 or later, specifies how the Installer configures the network protocol support for the instance of the Desktop Engine being installed or upgraded. n is an integer number, and should be set to either 0 or 1.

These are the behaviors of DISABLNETWORKPROTOCOLS in SP3a or later:

Value Specified for nUpgrading Existing InstanceInstalling New Instance1Instance is configured with all server Net-Libraries disabled.Instance is configured with all server Net-Libraries disabled.0The existing server Net-Library configuration is retained.Instance is configured with default server Net-Libraries and addresses enabled.Parameter not specified, or is any value other than 0 or 1The existing server Net-Library configuration is retained.Instance is configured with all server Net-Libraries disabled.

In SP3, DISABLENETWORKPROTOCOLS has two differences in behavior compared to SP3a:

• When installing a new instance using SP3, and DISABLENETWORKPROTOCOLS is either not specified or set to a value other than 0 or 1, then the instance is installed with the default Net-Libraries and addresses enabled. In SP3a, the Net-Libraries are disabled.
  
  
• Whenever all Net-Libraries are disabled for an instance of MSDE 2000 SP3, the instance will still use User Datagram Protocol (UDP) port 1434. In SP3a, the instance will not use UDP port 1434 in that configuration. For more information, see Controlling Net-Libraries and Communications Addresses.

INSTANCENAME="instance_name"

Specifies the name for the instance. If no instance name is specified, the instance is installed as a default instance.

SAPWD="sa_password"

Specifies the password to be assigned to the sa login when installing a new instance of MSDE 2000. SAPWD is ignored when you upgrade an existing instance of MSDE 2000, so you should ensure the sa login has a strong password before upgrading. You should always specify a strong sa password, even when using Windows Authentication Mode. While the SAPWD parameter is not written to the installation log file when running Setup.exe, it is if you install using merge modules.

SECURITYMODE=SQL

Specifies that the instance be configured in Mixed Mode, where the instance supports both SQL Server Authentication and Windows Authentication connections.

In Microsoft Windows NT® 4.0 or Windows 2000, if SECURITYMODE=SQL is not specified, the instance will be configured in Windows Authentication Mode. The instance will only support Windows Authentication connections, and the Windows local administrator's group will be added to the SQL Server sysadmin role. If SECURITYMODE=SQL is specified, Setup configures the instance in Mixed Mode.

Security Note  When possible, use Windows Authentication.

In Microsoft Windows 98 or Windows ME, the instance is always configured to use Mixed Mode, regardless of whether SECURITYMODE=SQL is specified. On these operating systems, MSDE 2000 can only support SQL Server Authentication connections.

TARGETDIR="executable_folder_path"

Specifies the folder where the Desktop Engine executable files are to be installed. Assuming that your system default for program files is C:/Program Files:

• The default value for default instances is: C:/Program Files/Microsoft SQL Server/MSSQL/Binn/.
  
  
• The default value for named instances is:  C:/Program Files/Microsoft SQL Server/MSSQL$<instance_name>/Binn/ for named instances, where instance_name is the name specified in the INSTANCENAME option.

  The file path for this parameter must end with a backslash (/). When installing a default instance, setup appends mssql/binn to the end of the path specified in TARGETDIR. When installing a named instance, setup appends mssql$<instance_name>/binn.

Note  Settings that contain spaces should be enclosed with quotation marks.

UPGRADE=1

Specifies that Desktop Engine Setup or Windows Installer is upgrading an instance of Microsoft Desktop Engine (MSDE) version 1.0 to SQL Server 2000 Desktop Engine. The only value supported is 1. MSDE 1.0 operates in the same fashion as a default instance of MSDE 2000, and is always upgraded to a default instance of MSDE 2000.

UPGRADEUSER=admin_login

Specifies the login to be used when you upgrade an instance of either MSDE 1.0 or MSDE 2000 using SQL Server Authentication. The login must be a member of the sysadmin fixed server role. This parameter is only used when you specify SECURITYMODE=SQL when upgrading an instance of MSDE.

UPGRADEPWD=admin_password

Specifies the password for the login specified in UPGRADEUSER when you upgrade Desktop Engine using SQL Server Authentication.

/L*v [filename]

Specifies that a verbose log be created. If filename is specified, the log is stored in the file specified.

/upgradesp { SQLRUN | <MSIPath>SQLRunnn.msi }

Specifies that Setup will upgrade an existing instance of MSDE 2000. For SP3 and later, this option replaces the /p option supported by earlier versions of Setup. Do not use the /p option with SP3 or later. When upgrading to SP3 or later, you are no longer required to specify the .msi file used to install the existing instance of MSDE 2000.

Many users simply specify SQLRUN, in which case the MSDE 2000 SP3 or later setup utility determines which .msi file to use. When you specify SQLRUN without specifying an INSTANCENAME, Setup will upgrade the default instance of MSDE 2000. If you specify both SQLRUN and an INSTANCENAME, Setup will upgrade the instance you specified using the INSTANCENAME parameter.

When you specify the name of an MSDE 2000 .msi installation package file, Setup will upgrade whichever instance on the computer was originally installed with a merge module of the same name. For example, if you specify SqlRun01.msi, Setup will upgrade whichever instance of MSDE 2000 was originally installed using SqlRun01.msi. MSIPath is the path to the folder holding the .msi file. MSIPath defaults to Setup/.

/qn

Specifies that Setup run with no user interface.

/qb

Specifies that Setup show only the basic user interface. Only dialog boxes displaying progress information are displayed. Other dialog boxes, such as the dialog box that asks users whether they want to restart at the end of the setup process, are not displayed.

If neither /qn nor /qb is specified, Setup displays all user interface dialog boxes.

/x package_name

Specifies the name of the Windows Installer installation package file (an .msi file) to use when uninstalling an instance of SQL Server 2000 Desktop Engine. You must specify the name of the same installation package file that was used to install the instance of the Desktop Engine. Place the .msi file in the same folder as Setup.exe.

Remarks

Setup.exe is a tool designed to be:

• Called directly by installation wrapper programs and batch files.
  
  
• Users can also execute it from the command prompt to install or upgrade instances of MSDE. New users running Setup.exe from the command prompt can find examples of the switches to use for typical installation and upgrade scenarios later in this topic.

By default, the MSDE 2000 SP3 or later Setup utility will not install a new instance of MSDE 2000 unless you use the SAPWD parameter to specify a strong sa password. By default, the MSDE 2000 SP3 or later setup will not upgrade an existing instance of MSDE 2000 unless you have assigned a strong password to the sa login before attempting the upgrade. You should assign a strong password to the sa login, even when upgrading an existing instance, unless the application using your instance of MSDE depends in some way on a null sa password. Even if the instance of MSDE 2000 is running in Windows Authentication mode, the sa login becomes immediately active if the instance is ever switched to Mixed Mode. A null, blank, simple, or well-known sa password could be used for unauthorized access. If you need to assign a strong sa password before upgrading your instance of MSDE 2000, use the sp_password system stored procedure to assign a strong password to the sa login.

All Desktop Engine SP3a installation files and folders are located in the /MSDE folder:

• On the SQL Server 2000 SP3a CD-ROM
  
  
• In the directory containing the extracted service pack files from SQL2KDeskSP3.exe downloaded from the SQL Server 2000 service pack Web page.

The /MSDE folder holds the SP3areadme.htm file, the readme.txt file, the license.txt file, and the executable files for the Setup utility. It also has the following subfolders:

• /Msi: contains the executable files needed to install Windows Installer, or upgrade Windows Installer if it is earlier than 2.0.2600.0.
  
  
• /MSM: Contains the merge modules needed for a merge module setup.
  
  
• /Setup: Contains the .msi installation package files required by the MSDE 2000 setup to install a new instance of MSDE 2000 SP3a, or the msp patch package files to upgrade existing instances of MSDE 2000 to SP3a, and the sqlrun.cab cabinet file containing the files installed by Setup.

For a description of using the Desktop Engine merge modules, see Using the SQL Server Desktop Engine Merge Modules.

If your application setup calls MSDE 2000 Setup, build a folder with this structure and sets of files (where MSDEInstallFolder represents an example folder name):

MSDEInstallFolder

Copy in these files from the Desktop Engine SP3a /MSDE folder: Setup.exe, Setup.ini, Setup.rll, and sqlresld.dll.

MSDEInstallFolder/Msi

Copy in all of the files from the Desktop Engine SP3a /MSDE/Msi folder.

MSDEInstallFolder/Setup

Copy in all of the files from the Desktop Engine SP3a /MSDE/Setup folder.

You can then execute Setup.exe to install or upgrade instances of MSDE 2000 SP3a.

If Windows Installer has not been installed on the computer, or is a version earlier than the version tested with MSDE 2000 SP3a Setup, Setup will use the files in the MSDEInstallFolder/Msi folder to upgrade Windows Installer.

When an application needs to uninstall an instance of the Desktop Engine, it must call Setup.exe using the /x option to specify the same .msi file that was used to install that instance. For example, to uninstall a named instance installed with a custom installation package file named MyCustom.msi, execute:

setup /x MyCustom.msi

The following example shows the format of a typical .ini file:

[Options]TARGETDIR="C:/Program Files/Microsoft SQL Server/Mssql$MyInstance/Binn/"DATADIR="C:/Program Files/Microsoft SQL Server/Mssql$MyInstance/Data/"INSTANCENAME=MyInstance

Using the /L*v switch to enable verbose logging improves your ability to diagnose problems you might encounter when running Setup.exe. You should especially consider turning on verbose logging in new environments, such as during the development and testing of a new application that embeds the Desktop Engine Setup.exe.

Using TARGETDIR and DATADIR

When installing MSDE 2000 SP3a or later, you should usually not specify TARGETDIR and DATADIR. The MSDE 2000 files should be in their default locations.

When you run Setup on an existing instance of MSDE 2000 to either apply a service pack or uninstall the instance, Setup will automatically locate the data and executable files, even if you had used TARGETDIR and DATADIR to specify a non-default location on the original installation.

These settings for TARGETDIR and DATADIR are the same as taking the defaults for either a default or named instance, assuming the default location for your system program files folder is C:/Program Files:

TARGETDIR="C:/Program Files/Microsoft SQL Server/"DATADIR="C:/Program Files/Microsoft SQL Server/"

Note  Settings that contain spaces should be enclosed with quotation marks.

Implementation Guidelines

If you combine Setup.exe with your own installer, consider these factors:

• Desktop Engine supports a maximum of 16 named instances on a given computer. Setup.exe implements a very simple system of numbered instances, using numbered files in the MSDE/Setup directory. If you alter the default behavior of Setup.exe, you must implement logic in your installer to avoid name conflicts and to ensure that this limit is not exceeded. For more information, see Installation API for Desktop Engine.
  
  
• Desktop Engine does not support nested installations. You must not call an .msi file from within another .msi file.

Using Setup.exe to Apply a Service Pack

Depending on how your instance of MSDE 2000 was originally installed, you may not be able to use Setup to apply a service pack from Microsoft. Service packs cannot be used to patch an instance of MSDE 2000 that was installed using either a customized MSDE 2000 installation package file or a Windows Installer-based application setup program that consumed the MSDE 2000 merge modules. The readme file for MSDE 2000 Service Pack 3a or later has instructions on how to determine if a Microsoft service pack can be applied to an instance of MSDE 2000. If it cannot, you must obtain a patch file from the vendor who supplied the application that installed that instance.

Examples

A. INSTALL A NEW INSTANCE OF MSDE 2000

These examples will install a new instance of MSDE 2000 SP3a that has been configured with its network connectivity disabled. If the instance must accept connections from applications running on other computers, also specify DISABLENETWORKPROTOCOLS=0.

These examples install instances using the defaults for all configuration items such as collation and file locations. The configurations can be controlled by setup parameters, such as COLLATION, DATADIR, and TARGETDIR.

1. Open a command prompt window.
   
   
2. From the command prompt, use the cd command to navigate to the folder containing the MSDE 2000 SP3a setup utility:

   cd c:/MSDESP3aFolder/MSDE

   where c:/MSDESP3aFolder is either the path to the folder into which you extracted the MSDE 2000 SP3a files, or the Desktop Engine SP3a folder on the SQL Server 2000 SP3a CD.

3. Execute one of the following commands:
   • To install a default instance configured to use Windows Authentication Mode, execute:

     setup SAPWD="AStrongSAPwd"

     where AStrongSAPwd is a strong password to be assigned to the sa login.

   • To install a named instance configured to use Windows Authentication Mode, execute:

     setup INSTANCENAME="InstanceName" SAPWD="AStrongSAPwd"

     where AStrongSAPwd is a strong password to be assigned to the sa login and InstanceName is the name to be assigned to the instance.

   • To install a default instance configured to use Mixed Mode, execute:

     setup SAPWD="AStrongSAPwd" SECURITYMODE=SQL

     where AStrongSAPwd is a strong password to be assigned to the sa login.

   • To install a named instance configured to use Mixed Mode, execute:

     setup INSTANCENAME="InstanceName" SECURITYMODE=SQL SAPWD="AStrongSAPwd"

     where AStrongSAPwd is a strong password to be assigned to the sa login and InstanceName is the name to be assigned to the instance.

Important  If you are using an .ini file during setup, avoid storing credentials in the .ini file.

Important  Always specify a strong password for the sa login, even when the instance is configured to use Windows Authentication Mode.

B. UPGRADE AN EXISTING INSTANCE OF MSDE 2000

These examples will upgrade an existing instance of MSDE 2000 to SP3a, and also disable the network connectivity for that instance of MSDE 2000. If the instance must accept connections from applications running on other computers, do not specify the DISABLENETWORKPROTOCOLS parameter.

1. Open a command prompt window.
   
   
2. From the command prompt, use the cd command to navigate to the folder containing the MSDE 2000 SP3a setup utility:

   cd c:/MSDESP3aFolder/MSDE

   where c:/MSDESP3aFolder is either the path to the folder into which you extracted the MSDE 2000 SP3a files, or the Desktop Engine SP3a folder on the SQL Server 2000 SP3a CD.

3. Execute one of the following commands:
   • For a default instance using Windows Authentication Mode, execute:

     setup /upgradesp sqlrun DISABLENETWORKPROTOCOLS=1

   • For a named instance using Windows Authentication Mode, execute:

     setup /upgradesp sqlrun INSTANCENAME=InstanceName DISABLENETWORKPROTOCOLS=1

   • For a default instance using Mixed Mode (where AnAdminLogin is a member of the sysadmin fixed server role), execute:

     setup /upgradesp sqlrun SECURITYMODE=SQL UPGRADEUSER=AnAdminLogin UPGRADEPWD=AdminPassword DISABLENETWORKPROTOCOLS=1

   • For a named instance using Mixed Mode (where AnAdminLogin is a member of the sysadmin fixed server role), execute:

     setup /upgradesp sqlrun INSTANCENAME= InstanceName SECURITYMODE=SQL UPGRADEUSER=AnAdminLogin UPGRADEPWD=AdminPassword DISABLENETWORKPROTOCOLS=1

Important  If you use an .ini file during setup, avoid storing credentials in the .ini file.

Note  When upgrading Desktop Engine on a computer running Windows 98 or Windows Millennium Edition, the instance of Desktop Engine that you are upgrading must be stopped before starting Setup.

C. UPGRADE AN EXISTING INSTANCE OF MSDE 1.0 TO MSDE 2000

These examples will upgrade an existing instance of MSDE 1.0 to MSDE 2000 SP3a, and also disable the network connectivity for the instance. If the instance must accept connections from applications running on other computers, do not specify the DISABLENETWORKPROTOCOLS parameter.

MSDE 1.0 operates in the same fashion as a default instance of MSDE 2000, and is always upgraded to a default instance of MSDE 2000.

1. Open a command prompt window.
   
   
2. From the command prompt, use the cd command to navigate to the folder containing the MSDE 2000 SP3a setup utility:

   cd c:/MSDESP3aFolder/MSDE

   where c:/MSDESP3aFolder is either the path to the folder into which you extracted the MSDE 2000 SP3a files, or the Desktop Engine SP3a folder on the SQL Server 2000 SP3 CD.

3. Execute one of the following commands:
   • When using Windows Authentication Mode, execute:

     setup UPGRADE=1 DISABLENETWORKPROTOCOLS=1

   • When using Mixed Mode (where AnAdminLogin is a member of the sysadmin fixed server role), execute:

     setup UPGRADE=1 SECURITYMODE=SQL UPGRADEUSER=AnAdminLogin UPGRADEPWD=AdminPassword DISABLENETWORKPROTOCOLS=1

Caution  The use of blank passwords is strongly discouraged.

Important  If you use an .ini file during setup, avoid storing credentials in the .ini file.

See Also

Reinstalling SQL Server 2000 Desktop Engine