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 IncludedThe 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 SectionEditing 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 DirectoryHow 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. |