AppNote: "How to Create a Custom Installation Script" (WC1046)Last reviewed: October 27, 1997Article ID: Q119357 |
The information in this article applies to:
The Application Note "How to Create a Custom Installation Script" (WC1046) is now available from Microsoft Product Support Services (PSS). This Application Note tells how to modify setup table files (STFs) to automate custom installations of applications. It includes a description of the various sections within the STF and defines the modifications that are supported by PSS. You can obtain this Application Note from the following sources:
THE TEXT OF WC1046
Microsoft(R) Product Support Services Application Note (Text File)
WC1046: HOW TO CREATE A CUSTOM INSTALLATION SCRIPT
Revision Date: 8/94
No Disk Included
The following information applies to Microsoft Office, versions 4.2
and later.
| INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY |
| ACCOMPANY THIS DOCUMENT (collectively referred to as an Application |
| Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER |
| EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED |
| WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR |
| PURPOSE. The user assumes the entire risk as to the accuracy and |
| the use of this Application Note. This Application Note may be |
| copied and distributed subject to the following conditions: 1) All |
| text must be copied without modification and all pages must be |
| included; 2) If software is included, all files on the disk(s) must |
| be copied without modification (the MS-DOS(R) utility diskcopy is |
| appropriate for this purpose); 3) All components of this |
| Application Note must be distributed together; and 4) This |
| Application Note may not be distributed for profit. |
| |
| Copyright (C) 1994 Microsoft Corporation. All Rights Reserved. |
| Microsoft and MS-DOS are registered trademarks and Windows is a |
| trademark of Microsoft Corporation. |
|---------------------------------------------------------------------|
OVERVIEW
========
This Application Note tells how to modify setup table files (STFs) to
automate custom installations of applications. It includes a
description of the various sections within the STF and defines the
modifications that are supported by Microsoft Product Support Services
(PSS).
TABLE OF CONTENTS
=================
Introduction: What Is a Setup Script?
What Modifications to the Backup Copy of the STF Will PSS Support?
Overview of the Setup Table File (STF)
What Are the Different Sections of the STF?
Description of the Header Section
Description of the Object Section
Editing the Backup Copy of the STF
General Procedure for Editing the Backup Copy of the STF
To open the STF in Microsoft Excel 5.0
To edit the STF
Editing Specific Portions of the Backup Copy of the STF
To specify the type of installation that you want the script to
perform
To specify the default components or modules for a custom
installation
To specify the default directory
To specify the default Program Manager group
Using Shorthand Notation to Specify a Destination Directory
How to Distribute and Run a Setup Script
Examples of Command Lines You Can Use to Run Setup Scripts
INTRODUCTION: WHAT IS A SETUP SCRIPT?
=====================================
A setup script is a set of instructions you can use to control
elements of a program's setup such as the installation type, the
default directory, the location of a program's components, and the
Program Manager group where the program's icons will appear. These
instructions are contained in a special file known as a setup table
file (STF). When used in conjunction with a quiet mode installation
(SETUP /Q), setup scripts give network administrators the ability to
automate a custom installation of an application.
CAUTION: Due to the complex nature of our applications, Microsoft will support only limited modification of the setup table file. We cannot guarantee that our applications will function properly if setup is altered beyond those modifications outlined below.
WHAT MODIFICATIONS TO THE BACKUP COPY OF THE STF WILL PSS SUPPORT? ==================================================================As a general rule, support is limited to options that can normally be changed by a user during a standard installation of the application. Specifically, Microsoft Product Support Services (PSS) will support the following modifications to a BACKUP copy of the SETUP.STF file:
OVERVIEW OF THE SETUP TABLE FILE (STF)
======================================
The STF is the primary tool for customizing the Setup program. The STF
specifies the installation process for each of the modes and
determines the nature, sequence, and extent of all user input. In
addition, the STF determines which options are installed, and where
they are installed.
The STF is a text file that you can edit using Microsoft Excel or any other spreadsheet, database, or word processing program. The data fields in this text file are delimited by tabs, and subfields are delimited by different characters (depending on the data format).
WHAT ARE THE DIFFERENT SECTIONS OF THE STF?The STF contains two basic sections: the header section and the object section. Although the Setup program ignores blank lines, you should leave one blank line between the end of the header section and the beginning of the object section to make the STF easier to read.
Description of the Header SectionThe header section of the STF contains the basic information of the setup script--for example, this section contains the location of the .INF file, dialog box text strings, and references to the object section of the table. The header section contains two columns: one for the parameter name and one for the parameter data. The following table describes these parameters and the data that is associated with them.
Parameter name Parameter data
App Name The name of the executable file for the
application.
App Version The version number of the application.
Frame Bitmap Reference to the .DLL file containing the
bitmap to be displayed in the setup frame
window.
Frame Caption The text string that will appear at the top
of the setup frame window.
Dialog Caption Base The text string that will appear as the
standard part of the title for most of the
dialog boxes. Other strings are concatenated
to this string.
Usage String The text string that will appear when the
user types /? at the command line.
About Box String The text string that will appear in the About
box.
Check Modules Applications that the Setup program will
check for (if these applications are running
they could interfere with the Setup program).
Source Directory The directory from which the Setup program is
being run.
MSAPPS Mode Indicates whether the shared applications will
be installed locally or run from the server, or
if the choice will be made during the workstation
installation.
MSAPPS Network Contains the server and volume name of the
Server location for the shared applications. This
information should be in the universal naming
convention (UNC) format. For example:
\\SERVER\VOLUME.
If the network does not support UNC format, you
can substitute a logical drive letter for the
UNC path. However, if you do not use UNC paths,
shared applications will always be installed
locally regardless of the value in the MSAPPS
Mode field.
MSAPPS Network Path Contains the path to the shared applications.
This entry should be in UNC format. For example:
\\SUBDIR1\SUBDIR2.
If the network does not support UNC, you can
substitute a logical drive letter for the UNC
path. However, if you do not use UNC paths,
shared applications will always be installed
locally regardless of the value in the MSAPPS
Mode field.
INF File Name The name of the relevant INF file.
Setup Status Contains the copy disincentive information
collected from Setup during installation.
Maximum This field must contain a number only
Object ID slightly larger than the largest number of
entries (ObjID) in the STF. Setup uses this
number to operate more efficiently.
Admin Mode Root This field indicates the point on the object
Object ID section at which an administrative mode
installation begins.
Floppy Mode Root This field indicates the point on the object
Object ID section at which Setup begins. (The default
mode is a floppy disk installation.)
Network Mode Root This field indicates the point on the object
Object ID section at which a network installation
begins.
Maintenance Mode Root Indicates the point on the object section at
Object ID which a maintenance mode is run.
Batch Mode Root A batch mode installation (with minimal user
Object ID interaction).
Setup Version Version number of the current Setup toolkit.
Used to identify the version of the Setup
tool for which the current table file is
being generated.
Description of the Object SectionThe object section of the STF contains the sequence and options of the installation process as well as specific configuration information on a line-by-line, object-by-object basis. Each line designates an object and is made up of 15 columns. Each line provides specific data and instructions for the Setup installation. This information is arranged in a hierarchical fashion--that is, a given object can be a specific installation action, an object branching to other objects and groups of objects, or both. Of the 15 columns, only the first 12 are columns you can edit, the remaining 3 columns are for internal use by Setup.
Column Object field Description of entry type
A ObjID A unique number, greater than 0 (zero),
that identifies the object. Should be in
increasing sequence. Valid ObjID numbers
depend on the object in use.
B Install During Specifies whether the application at
Batch Mode this object line should be installed
during a batch mode installation. This
option applies only to network
installations and to options that are
normally selected by a user.
C Title A text string that you want to associate
with an object.
D Description A text string describing this object to
the user.
E Object Type The type of object. Examples of an
object type are the following (note that
these entries are case sensitive):
AppMainDlg
CustomDlg
OptionDlg
Group
CopyFile
CopySection
AddPathToAutoexec
CustomAction
F Object Data The content of this field is specific to
the Object Type. Setup uses this
information to define and run the
various automated and user-selectable
options. This field will either call
other objects (by referencing their
object IDs) or specify an installation
action.
G Bitmap ID Resource ID number for button bitmap. A
second number may be specified for use
with an EGA driver.
H Vital Attribute Indicates whether a portion of an
application is vital to the proper
functioning of the application. An empty
field indicates a value of "not vital."
If the user fails to select a vital
portion of the application, Setup
displays a warning.
I Shared Attribute Indicates whether this item is shared or
private. An empty field indicates a
value of "private." If the user attempts
to remove a "shared" item, the Setup
program displays a warning.
J Configurable Indicates whether the user can edit a
Directory directory field (yes) or is blocked from
editing a directory field (no). An empty
field indicates a <no> value.
K Destination Identifies the destination directory for
Directory the files controlled by this object.
Each time you specify a destination
directory, the directory applies to all
objects lower on the table's
hierarchical structure. This entry is
useful because you only have to specify
the destination directory once for each
change in directory.
L Check Directory Indicates whether to check a user-
selectable directory for earlier
versions of the files specified at this
line.
M Installed By Leave this field blank. Setup inserts
the following information when you run
Setup in maintenance mode:
se--Somebody else, more recent
us--Setup
nyi or blank--Not yet installed
N Install Data Leave this field blank. Setup provides
necessary data for this field. Used
during maintenance mode.
O Install Directory Leave this field blank. Setup provides
necessary data for this field. Used
during maintenance mode.
EDITING THE BACKUP COPY OF THE STF
==================================
GENERAL PROCEDURE FOR EDITING THE BACKUP COPY OF THE STFThe STF is a 15-column table (for more information about the columns in the table, see the "Description of the Header Section" and the "Description of the Object Section" sections earlier in this Application Note. When you edit this table, you must keep these columns intact. We recommend that you edit the STF in a spreadsheet program such as Microsoft Excel. This type of program opens the STF in a table format with the appropriate columns in place--having the data in columns makes it easy to edit. However, if you do choose to edit the STF in a text editor (such as Microsoft Write), the STF is opened in text format (as opposed to a table format). If you edit the file in this format, be sure to display all fields so that you can see the tabs that separate the columns of data in the table (these tabs are the column delimiters): being able to see these delimiters will help you avoid deleting them. If you delete any of the tabs, your STF will not function properly. NOTE: Do not use MS-DOS Editor to modify the STF; this program will make the file unusable because it will replace tabs with spaces.
To open the STF in Microsoft Excel 5.0
To edit the STF
"Type the word ""Yes"" here."This text string will appear in the Setup program in the following form:
Type the word "Yes" here.Note that a data field in the STF cannot contain more than 255 characters, and a line cannot contain more than 1024 characters.
EDITING SPECIFIC PORTIONS OF THE BACKUP COPY OF THE STFThere are four basic aspects of the Setup program that you can alter by editing the STF:
that you want the script to perform
| Install During | | ObjID | Batch Mode | Title | Description 33 | yes | &Typical | Microsoft Office will be
| | | installed with the most
| | | common options.
34 | no | &Complete/Custom | You can either install all
| | | of the files for a program
| | | or just the files you
| | | choose.
35 | no | &Laptop (Minimum)| The minimum set of files
| | | needed to run the Microsoft
| | | Office applications will be
| | | installed.
36 | no | &Workstation | The Microsoft Office will
| | | be installed to run from
| | | the server.
NOTE: The Object ID numbers in the first column will vary among
applications. Note also that the column headings have been added to
make the table easier to read (normally these headings appear
around row 22 of the STF).
To specify the default components or modules for a custom installation
A | B | C | D | Install During | | ObjID | Batch Mode | Title | Description 20 | yes | Microsoft | The complete set of Microsoft
| | Excel | Excel program files.
| | |
21 | yes | Online Help | Detailed, step-by-step
| | and Lessons | instructions and reference
| | | information about Microsoft
| | | Excel and a collection of
| | | lessons and example files.
| | |
22 | yes | Data Access | A data access application that
| | | lets you connect to and use
| | | external data. Also, Microsoft
| | | Excel add-ins that let you
| | | return your data to Microsoft
| | | Excel.
| | |
23 | yes | Graphics | Filters that allow you to
| | Filters | import graphics data into
| | | Microsoft Excel.
| | |
24 | yes | Add-ins | A collection of Microsoft
| | | Excel macros that can assist
| | | you in common spreadsheet
| | | tasks.
| | |
25 | yes | Tools | A collection of utilities you
| | | can use with Microsoft Excel.
NOTE: The Object ID numbers in the first column will vary among
applications. Note also that the column headings have been added to
make the table easier to read (normally these headings appear
around row 22 of the STF).
If, for example, you don't want to install the Data Access components
in Microsoft Excel, you can do either of the following:
To specify the default directory
ObjID |Install |Title |Description |Object |Object Data
|During | | |Type |
|Batch | | | |
|Mode | | | |
3 |yes |Microsoft | |AppSearch |"C:\EXCEL",
| |Excel | | |"EXCEL.EXE",
| | | | |"5.0.0.2414",
| | | | |2, no, yes, 5 6
NOTE: You can change drives only if you are running under a quiet mode Setup (setup /q). If you try to perform an interactive setup with the above example, Setup will default to the installation directory C:\WINAPPS\XL5.
To specify the default Program Manager group
A | B | C | D | E | F ObjID |Install |Title|Description|Object Type | Object Data
|During | | | |
|Batch | | | |
|Mode | | | |
1730 |yes | | |AddProgmanItem | Microsoft Office,
| | | | | Microsoft Excel,
| | | | | %s\EXCEL.EXE,
1731 |yes | | |AddProgmanItem | Microsoft Office,
| | | | | Microsoft Query,
| | | | | %s\MSQUERY.EXE,
1732 |yes | | |AddProgmanItem | Microsoft Office,
| | | | | MS Excel Readme,
| | | | | %s\XLREADME.HLP,
1733 |yes | | |AddProgmanItem | Microsoft Office,
| | | | | MS Excel Setup,
| | | | | %s\SETUP.EXE,
In the above table, column F contains the information that you would
change. Currently, the Program Manager Group is set to <Microsoft
Office>. If you wanted to change it, you would replace <Microsoft
Office> with the group name of your choice--<XL5>, for example.
USING SHORTHAND NOTATION TO SPECIFY A DESTINATION DIRECTORYThe STF supports use of shorthand notation to accommodate the variety of directory names in which users may store an application or operating system. For example, User A may install Microsoft Windows in a directory called C:\WINDOWS, while User B may install Windows in C:\MS_WINDOWS. You can use the shorthand notation %w to allow Setup to determine the Windows directory for either of these two users, thus eliminating the need for specifying exact directory locations. For example, in the following table from the Office STF, note the use of %w and %d in the Destination Directory column (column K).
A | B* | E | F* | K ObjID |Install | Object Type | Object Data | Destination
|During | | | Directory
|Batch | | |
|Mode | | |
38 |yes | DetectOlderFile | "excel.ini" | %w 39 |yes | DetectOlderFile | "excel4.ini" | %w 40 |yes | DetectOlderFile | "excel.exe", "5.0" | 41 |yes | Depend | 40 ? 42 | 42 |yes | Group | 43 59 | 43 |yes | Group | 46 47 44 45 57 | 44 |yes | Group | 48 50 51 52 53 54 | %d\LIBRARY 45 |yes | Group | 55 56 | %d\EXAMPLES 46 |yes | RemoveSection | "XL4 Files" | %d 47 |yes | RemoveSection | "XL4 CBT Files" | %d\EXCELCBT 48 |yes | RemoveSection | "XL4 Add-ins" | %dNOTE: * Due to a lack of space, columns C, D and G-J have been deleted from the text version of this Application Note.In this example, EXCEL.INI is listed Under Object Data, and %w is listed under Destination Directory. From the following combination of these entries, you can get an idea of what the Setup program will do at this line of the table:
Object Type | Object Data | Destination Directory DetectOlderFile | "excel.ini" | %wThe Setup program interprets the above information as the following:
Look for EXCEL.INI in this user's Windows directory.The other shorthand notation in this example is %d, which is shorthand for the destination directory. If you specify C:\MS_EXCEL in the Object Data field (making it the directory to which Microsoft Excel is installed), line 64 of the example reads
Object Type | Object Data | Destination Directory RemoveSection | "XL4 Files" | %dwhich the Setup program interprets as:
Remove Microsoft Excel 4.0 Files from C:\MS_EXCEL.If C:\MS_EXCEL is a new directory, this line would not need to be executed. However, if you are installing Microsoft Excel 5.0 over Microsoft Excel 4.0, this line is important. The following line is also an important one:
Object Type | Object Data | Destination Directory RemoveSection | "XL4 CBT Files" | %d\EXCELCBTThis line is interpreted by the Setup program to mean the following:
Remove Excel 4 CBT files from C:\MS_EXCEL\ EXCELCBT.The following table lists the shorthand notations you can use in the STF.
Value Meaning
%obj_id Use the destination directory of a specified
object (for example, %1).
%d or null Use the destination directory of the parent.
%m Use the Windows SYSTEM subdirectory.
%s Use the source directory.
%w Use the Windows directory.
%obj_id\<subdir> Use a subdirectory of the specified object.
%d\<subdir> Use a subdirectory of the parent (for example
%d\WINWORD).
%m<\subdir> Use a subdirectory of the Windows SYSTEM
subdirectory.
%s\<subdir> Use a subdirectory of the source directory.
%w\<subdir> Use a subdirectory of the Windows directory.
NOTE: The values %w and %m are necessary for an administrative mode
Setup. In other modes, the values can be implied by action, and
Setup automatically determines the correct directory.
HOW TO DISTRIBUTE AND RUN A SETUP SCRIPT
========================================
After you have created the STF, there are two basic ways you can
distribute it:
To distribute Setup scripts using Microsoft Mail
------------------------------------------------
1. In Microsoft Mail, compose your message and then choose Insert
Object from the Edit menu.
2. Under Object Type, select Package, and then choose the OK
button.
3. In the Object Packager, choose Command Line from the Edit menu.
4. Type the full path to SETUP.EXE on the network server, and then
choose the OK button. For example, you might type:
\\dragon\public\msoffice\setup.exe /t myscript.stf /q
NOTE: For information about the switches you can use in this
command line, see the table below.
5. To attach a Setup icon, choose the Insert Icon button.
6. Choose the Browse button, locate SETUP.EXE in the network
directory where your edited STF file is located, and then choose
the OK button. Choose the OK button again.
7. In Object Packager, choose Update from the File menu, and then
choose Exit.
If the network supports UNC path names, users who receive the message
can double-click the Setup script icon to install Office over the
network. If the network does not support UNC path names, users must
connect to the network using the same drive letter you used for Setup
before they double-click the icon.
Switch What the switch does
/t <filename>.STF Forces Setup to use a table file other
than the default table file (where
<filename> is your product's filename
without the extension).
/q Specifies Batch Mode installation.
Installs predetermined application files
with minimal user participation. Minimal
user interface is displayed. NOTE: This
switch is required for running custom setup
scripts.
/n "user name" Uses WIN.INI user name if it exists;
otherwise, uses the name value. Cannot be
used with /a.
/o "organization name" Uses the WIN.INI copy disincentive
organization name if it exists; otherwise,
uses the organization value. Cannot be
used with /a.
Examples of Command Lines You Can Use to Run Setup ScriptsThe following are some examples of command lines that could be used to run setup scripts. If you have not renamed the .EXE file and your setup script is named NEWSETUP.STF, you could use a command line similar to the following
<path>\setup /t newsetup.stf /qwhere <path> is the complete path to the .EXE file. If you have renamed the .EXE file to NEWSETUP.EXE and your setup script is named NEWSETUP.STF, you could use a command line similar to the following
<path>\newsetup /qwhere <path> is the complete path to the .EXE file.
TO OBTAIN THIS APPLICATION NOTEThe following file(s) are available for download from the Microsoft Software Library:
~ WC1046.EXE (size: 26748 bytes)For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:
ARTICLE-ID: Q119591 TITLE : How to Obtain Microsoft Support Files from Online Services
http://www.microsoft.com/worldwide/default.htm |
Additional query words: word6
© 1998 Microsoft Corporation. All rights reserved. Terms of Use. |