InstallShield 2012 InstallScript

Reference Guide

InstallShield 2012 InstallScript Reference Guide

Part Number: ISP-1800-RG00 Product Release Date: August 2011

Copyright Notice
Copyright 19962011 Flexera Software, Inc. and/or InstallShield Co. Inc. All Rights Reserved. This product contains proprietary and confidential technology, information and creative works owned by Flexera Software, Inc. and/or InstallShield Co. Inc. and their respective licensors, if any. Any use, copying, publication, distribution, display, modification, or transmission of such technology in whole or in part in any form or by any means without the prior express written permission of Flexera Software, Inc. and/or InstallShield Co. Inc. is strictly prohibited. Except where expressly provided by Flexera Software, Inc. and/or InstallShield Co. Inc. in writing, possession of this technology shall not be construed to confer any license or rights under any Flexera Software, Inc. and/or InstallShield Co. Inc. intellectual property rights, whether by estoppel, implication, or otherwise. All copies of the technology and related information, if allowed by Flexera Software, Inc. and/or InstallShield Co. Inc., must display this notice of copyright and ownership in full.

Trademarks
Flexera Software, AdminStudio, FlexNet Connect, InstallShield, InstallShield Developer, InstallShield DevStudio, InstallShield Professional, OneClick Install, and QuickPatch are registered trademarks or trademarks of Flexera Software, Inc. and/or InstallShield Co. Inc. in the United States of America and/or other countries. All other brand and product names mentioned herein are the trademarks and registered trademarks of their respective owners.

Restricted Rights Legend

The software and documentation are commercial items, as that term is defined at 48 C.F.R. 2.101, consisting of commercial computer software and commercial computer software documentation, as such terms are used in 48 C.F.R. 12.212 or 48 C.F.R. 227.2702, as applicable. Consistent with 48 C.F.R. 12.212 or 48 C.F.R. 227.2702-1 through 227.7202-4, as applicable, the commercial computer software and commercial computer software documentation are being licensed to U.S. government end users (A) only as commercial items and (B) with only those rights as are granted to all other end users pursuant to the terms and conditions set forth in the Flexera Software standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States of America.

Contents

InstallScript Language Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Integrated Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Command-Line Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Setup Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
InstallScript Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Structure of a Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Declarations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Program Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Function Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Identifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Syntax Punctuation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Writing Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Using White Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Hungarian Notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Escape Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Embedding Quotation Marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Format Specifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Language Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
abort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 BOOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 cdecl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 external . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 for...endfor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

iii

Contents

goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 if Structure with goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 if-then Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 if-then-else Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Nested if-then-else Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 elseif Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 property(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 prototype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 repeat...until . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 return . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 stdcall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 switch...endswitch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 try, catch, and endcatch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 while...endwhile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Nested while Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Predefined Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
AFTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 ALLCONTENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 ALLCONTROLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 APPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 ASKDESTPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 ASKOPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 ASKPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 ASKTEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 BACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 BACKBUTTON. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 BACKGROUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 BACKGROUNDCAPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 BASEMEMORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 BEFORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 BIF_BROWSEFORCOMPUTER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 BIF_BROWSEFORPRINTER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 BIF_DONTGOBELOWDOMAIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 BIF_EDITBOX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 BIF_RETURNFSANCESTORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 BIF_RETURNONLYFSDIRS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 BIF_STATUSTEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 BILLBOARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

iv

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

BITMAPICON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 BK_BLUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 BK_GREEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 BK_MAGENTA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 BK_ORANGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 BK_PINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 BK_RED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 BK_SMOOTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 BK_SOLIDBLACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 BK_SOLIDBLUE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 BK_SOLIDGREEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 BK_SOLIDMAGENTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 BK_SOLIDORANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 BK_SOLIDPINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 BK_SOLIDRED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 BK_SOLIDWHITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 BK_SOLIDYELLOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 BK_YELLOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 BLACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 BLUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 BOOTUPDRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 BUTTON_CHECKED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 BUTTON_UNCHECKED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 BYTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 CANCEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 CANCELBUTTON. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 CDROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 CDROM_DRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 CENTERED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 CHECKBOX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 CHECKBOX95 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 CHECKLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 CHECKMARK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 CLEAR_FILE_ATTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 COLORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 COMMAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 COMMON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 COMPACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 COMPARE_DATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 COMPARE_MD5_SIGNATURE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 COMPARE_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 COMPARE_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 COMP_NORMAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 COMP_UPDATE_DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

Contents

COMP_UPDATE_SAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 COMP_UPDATE_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 COPY_ERR_CREATEDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 COPY_ERR_MEMORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 COPY_ERR_NODISKSPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 COPY_ERR_OPENINPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 COPY_ERR_OPENOUTPUT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 COPY_ERR_TARGETREADONLY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 CURRENTROOTKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 CUSTOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 DATA_COMPONENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 DATA_LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 DATA_NUMBER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 DATA_STRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 DEFAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 DEFWINDOWMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 DELETE_EOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 DIALOGCACHE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 DIFXAPI_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 DIFXAPI_INFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 DIFXAPI_SUCCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 DIFXAPI_WARNING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 DIR_WRITEABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 DISABLE_ALLUSERBTN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 DISABLE_PERUSERBTN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 DISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 DISK1FEATURE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 DISK_INFO_QUERY_ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 DISK_INFO_QUERY_BYTES_PER_CLUSTER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 DISK_INFO_QUERY_DISK_FREE_SPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 DISK_INFO_QUERY_DISK_TOTAL_SPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 DISK_INFO_QUERY_DRIVE_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 DISK_TOTALSPACE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 DISK_TOTALSPACE_EX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 DLG_ASK_OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 DLG_ASK_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 DLG_ASK_TEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 DLG_ASK_YESNO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 DLG_CENTERED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

vi

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

DLG_CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 DLG_DIR_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 DLG_DIR_DRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 DLG_DIR_FILE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 DLG_ENTER_DISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 DLG_ERR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 DLG_ERR_ALREADY_EXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 DLG_ERR_ENDDLG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 DLG_INFO_ALTIMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 DLG_INFO_ALTIMAGE_REVERT_IMAGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 DLG_INFO_ALTIMAGE_VERIFY_BMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 DLG_INFO_CHECKSELECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 DLG_INFO_KUNITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 DLG_INFO_USEDECIMAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 DLG_INIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 DLG_MSG_ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 DLG_MSG_INFORMATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 DLG_MSG_SEVERE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 DLG_MSG_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 DLG_MSG_WARNING. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 DLG_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 DLG_USER_CAPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 DOINSTALL_OPTION_NOHIDEPROGRESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 DOINSTALL_OPTION_NOHIDESPLASH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 DOINSTALL_OPTION_NOLANGSWITCH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 DOINSTALL_OPTION_NOSETBATCHINSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 DOTNETFRAMEWORKINSTALLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 DOTNETSERVICEPACKINSTALLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 DRIVE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 DRIVE_CDROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 DRIVE_FIXED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 DRIVE_NO_ROOT_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 DRIVE_RAMDISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 DRIVE_REMOTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 DRIVE_REMOVABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 DRIVE_UNKNOWN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 DRIVER_PACKAGE_DELETE_FILES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 DRIVER_PACKAGE_FORCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 DRIVER_PACKAGE_LEGACY_MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 DRIVER_PACKAGE_REPAIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 DRIVER_PACKAGE_SILENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 EDITBOX_CHANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 EFF_BOXSTRIPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

vii

Contents

EFF_FADE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 EFF_HORZREVEAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 EFF_HORZSTRIPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 EFF_NONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 EFF_REVEAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 EFF_VERTSTRIPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 END_OF_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 END_OF_LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 ENTERDISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 EQUALS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 ERROR_ACCESS_DENIED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 ERROR_CIRCULAR_DEPENDENCY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 ERROR_DATABASE_DOES_NOT_EXIST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 ERROR_DEPENDENT_SERVICES_RUNNING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 ERROR_DUP_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 ERROR_FILE_NOT_FOUND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 ERROR_INVALID_HANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 ERROR_INVALID_PARAMETER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 ERROR_INVALID_SERVICE_ACCOUNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 ERROR_INVALID_SERVICE_CONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 ERROR_PATH_NOT_FOUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 ERROR_SERVICE_ALREADY_RUNNING. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 ERROR_SERVICE_CANNOT_ACCEPT_CTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 ERROR_SERVICE_DATABASE_LOCKED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 ERROR_SERVICE_DEPENDENCY_DELETED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 ERROR_SERVICE_DEPENDENCY_FAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 ERROR_SERVICE_DISABLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 ERROR_SERVICE_DOES_NOT_EXIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 ERROR_SERVICE_EXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 ERROR_SERVICE_LOGON_FAILED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 ERROR_SERVICE_NOT_ACTIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 ERROR_SERVICE_NO_THREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 ERROR_SERVICE_REQUEST_TIMEOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 ERROR_TIMEOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 ERR_ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 ERR_BOX_BADPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 ERR_BOX_BADTAGFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 ERR_BOX_DISKID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 ERR_BOX_DRIVEOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 ERR_IGNORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 ERR_NO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 ERR_PERFORM_AFTER_REBOOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 ERR_RETRY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 ERR_YES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

viii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

EXCLUDE_SUBDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 EXCLUSIVE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 EXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 EXTENDEDMEMORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 EXTENSION_ONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 FALSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 FEATURE_FIELD_CDROM_FOLDER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 FEATURE_FIELD_DESCRIPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 FEATURE_FIELD_DISPLAYNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 FEATURE_FIELD_ENCRYPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 FEATURE_FIELD_FILENEED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 FEATURE_FIELD_FLAGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 FEATURE_FIELD_FTPLOCATION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 FEATURE_FIELD_GUID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 FEATURE_FIELD_HANDLER_ONINSTALLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 FEATURE_FIELD_HANDLER_ONINSTALLING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 FEATURE_FIELD_HANDLER_ONUNINSTALLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 FEATURE_FIELD_HANDLER_ONUNINSTALLING. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 FEATURE_FIELD_HTTPLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 FEATURE_FIELD_IMAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 FEATURE_FIELD_MISC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 FEATURE_FIELD_PASSWORD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 FEATURE_FIELD_SELECTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 FEATURE_FIELD_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 FEATURE_FIELD_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 FEATURE_FIELD_VISIBLE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 FEATURE_INFO_ATTRIBUTE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 FEATURE_INFO_COMPONENT_FLAGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 FEATURE_INFO_COMPSIZE_HIGH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 FEATURE_INFO_COMPSIZE_LOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 FEATURE_INFO_DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 FEATURE_INFO_DATE_EX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 FEATURE_INFO_DESTINATION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 FEATURE_INFO_FTPLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 FEATURE_INFO_HTTPLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 FEATURE_INFO_LANGUAGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FEATURE_INFO_MD5_SIGNATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FEATURE_INFO_MISC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FEATURE_INFO_ORIGSIZE_HIGH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 FEATURE_INFO_ORIGSIZE_LOW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 FEATURE_INFO_OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 FEATURE_INFO_OVERWRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 FEATURE_INFO_PLATFORM_SUITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

ix

Contents

FEATURE_INFO_TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 FEATURE_INFO_VERSIONLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 FEATURE_INFO_VERSIONMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 FEATURE_INFO_VERSIONSTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 FEATURE_OPCOST_UNINSTALL_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 FEATURE_OPCOST_UNINSTALL_REGORINI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 FEATURE_OPCOST_UNINSTALL_UNREGFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 FEATURE_VALUE_CRITICAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 FEATURE_VALUE_HIGHLYRECOMMENDED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 FEATURE_VALUE_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 File Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 FILE_ADD_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 FILE_ADD_SUBDIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 FILE_ALL_ACCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 FILE_APPEND_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 FILE_ATTR_ARCHIVED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 FILE_ATTR_HIDDEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 FILE_ATTR_NORMAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 FILE_ATTR_READONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 FILE_ATTR_SYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 FILE_ATTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 FILE_BIN_CUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 FILE_BIN_END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 FILE_BIN_START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 FILE_DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 FILE_DELETE_CHILD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 FILE_EXECUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 FILE_EXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 FILE_INSTALLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 FILE_IS_LOCKED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 FILE_LINE_LENGTH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 FILE_LIST_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 FILE_LOCKED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 FILE_MD5_SIGNATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 FILE_MODE_APPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 FILE_MODE_APPEND_UNICODE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 FILE_MODE_BINARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 FILE_MODE_BINARYREADONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 FILE_MODE_NORMAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 FILE_NOT_FOUND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 FILE_NO_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 FILE_RD_ONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 FILE_READ_ATTRIBUTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 FILE_READ_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

FILE_READ_EA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 FILE_SHARED_COUNT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 FILE_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 FILE_SIZE_HIGH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 FILE_SIZE_LOW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 FILE_SRC_OLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 FILE_TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 FILE_TRAVERSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 FILE_WRITE_ATTRIBUTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 FILE_WRITE_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 FILE_WRITE_EA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 FILE_WRITEABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 FILENAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 FILENAME_ONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 FIXED_DRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 FONT_AVAILABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 FULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 FULLSCREEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 FULLSCREENSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 FULLWINDOWMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 FUNCTION_EXPORTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 GBYTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 GENERIC_ALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 GENERIC_EXECUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 GENERIC_READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 GENERIC_WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 GREATER_THAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 GREEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 GTFIS_OPTION_DELETE_TEMP_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 GTFIS_OPTION_DONT_CREATE_DIR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 GTFIS_OPTION_DONT_RESOLVE_TEXTSUBS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 GTFIS_OPTION_NONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 HIDE_DISABLED_BTNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 HKEY_CLASSES_ROOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 HKEY_CURRENT_USER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 HKEY_LOCAL_MACHINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 HKEY_USERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 HKEY_USER_SELECTABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 HOURGLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 HWND_DESKTOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 HWND_INSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 IDCANCEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 IDOK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xi

Contents

IDS_IFX_ERROR_INVALID_MEDIA_PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 IFX_ONNEXTDISK_PACKAGE_CAPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 IFX_ONNEXTDISK_PACKAGE_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 INCLUDE_SUBDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 INDVFILESTATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 INFORMATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 IS_PERMISSIONS_OPTION_ALLOW_ACCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 IS_PERMISSIONS_OPTION_DENY_ACCESS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 IS_PERMISSIONS_OPTION_NO_APPLYDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 IS_PERMISSIONS_TYPE_FILE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 IS_PERMISSIONS_TYPE_FOLDER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 IS_PERMISSIONS_TYPE_REGISTRY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 ISDIFX_OPTION_DONT_ASSOCIATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 ISDIFX_OPTION_DONT_RESOLVE_TEXTSUBS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 ISDIFX_OPTION_LOG_IN_DRIVER_PACKAGE_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 ISDIFX_OPTION_NO_REPAIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 ISERR_GEN_FAILURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 ISERR_SUCCESS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 ISLANG_AFRIKAANS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 ISLANG_AFRIKAANS_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 ISLANG_ALBANIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 ISLANG_ALBANIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 ISLANG_ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 ISLANG_ARABIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 ISLANG_ARABIC_ALGERIA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 ISLANG_ARABIC_BAHRAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 ISLANG_ARABIC_EGYPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 ISLANG_ARABIC_IRAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 ISLANG_ARABIC_JORDAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 ISLANG_ARABIC_KUWAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 ISLANG_ARABIC_LEBANON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 ISLANG_ARABIC_LIBYA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 ISLANG_ARABIC_MOROCCO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ISLANG_ARABIC_OMAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ISLANG_ARABIC_QATAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ISLANG_ARABIC_SAUDIARABIA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ISLANG_ARABIC_SYRIA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ISLANG_ARABIC_TUNISIA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ISLANG_ARABIC_UAE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ISLANG_ARABIC_YEMEN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ISLANG_BASQUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 ISLANG_BASQUE_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 ISLANG_BELARUSIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 ISLANG_BELARUSIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

xii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

ISLANG_BULGARIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 ISLANG_BULGARIAN_STANDARD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 ISLANG_CATALAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 ISLANG_CATALAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 ISLANG_CHINESE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 ISLANG_CHINESE_HONGKONG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 ISLANG_CHINESE_PRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 ISLANG_CHINESE_SINGAPORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 ISLANG_CHINESE_TAIWAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 ISLANG_CROATIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 ISLANG_CROATIAN_STANDARD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 ISLANG_CZECH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 ISLANG_CZECH_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 ISLANG_DANISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 ISLANG_DANISH_STANDARD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 ISLANG_DUTCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 ISLANG_DUTCH_BELGIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 ISLANG_DUTCH_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 ISLANG_ENGLISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 ISLANG_ENGLISH_AUSTRALIAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 ISLANG_ENGLISH_BELIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 ISLANG_ENGLISH_CANADIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 ISLANG_ENGLISH_CARIBBEAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 ISLANG_ENGLISH_IRELAND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 ISLANG_ENGLISH_JAMAICA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 ISLANG_ENGLISH_NEWZEALAND. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 ISLANG_ENGLISH_SOUTHAFRICA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 ISLANG_ENGLISH_TRINIDAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 ISLANG_ENGLISH_UNITEDKINGDOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 ISLANG_ENGLISH_UNITEDSTATES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 ISLANG_ESTONIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 ISLANG_ESTONIAN_STANDARD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 ISLANG_FAEROESE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 ISLANG_FAEROESE_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 ISLANG_FARSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 ISLANG_FARSI_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 ISLANG_FINNISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 ISLANG_FINNISH_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 ISLANG_FRENCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 ISLANG_FRENCH_BELGIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 ISLANG_FRENCH_CANADIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 ISLANG_FRENCH_LUXEMBOURG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 ISLANG_FRENCH_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 ISLANG_FRENCH_SWISS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xiii

Contents

ISLANG_GERMAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 ISLANG_GERMAN_AUSTRIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 ISLANG_GERMAN_LIECHTENSTEIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 ISLANG_GERMAN_LUXEMBOURG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 ISLANG_GERMAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 ISLANG_GERMAN_SWISS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 ISLANG_GREEK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 ISLANG_GREEK_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 ISLANG_HEBREW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 ISLANG_HEBREW_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 ISLANG_HUNGARIAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 ISLANG_HUNGARIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 ISLANG_ICELANDIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 ISLANG_ICELANDIC_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 ISLANG_INDONESIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 ISLANG_INDONESIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 ISLANG_ITALIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ISLANG_ITALIAN_STANDARD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ISLANG_ITALIAN_SWISS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ISLANG_JAPANESE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ISLANG_JAPANESE_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ISLANG_KOREAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ISLANG_KOREAN_JOHAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ISLANG_KOREAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 ISLANG_LATVIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 ISLANG_LATVIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 ISLANG_LITHUANIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 ISLANG_LITHUANIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 ISLANG_NORWEGIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 ISLANG_NORWEGIAN_BOKMAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 ISLANG_NORWEGIAN_NYNORSK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 ISLANG_POLISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 ISLANG_POLISH_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 ISLANG_PORTUGUESE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 ISLANG_PORTUGUESE_BRAZILIAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 ISLANG_PORTUGUESE_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 ISLANG_ROMANIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 ISLANG_ROMANIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 ISLANG_RUSSIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 ISLANG_RUSSIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 ISLANG_SERBIAN_CYRILLIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 ISLANG_SERBIAN_LATIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 ISLANG_SLOVAK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 ISLANG_SLOVAK_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

xiv

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

ISLANG_SLOVENIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 ISLANG_SLOVENIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 ISLANG_SPANISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 ISLANG_SPANISH_ARGENTINA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 ISLANG_SPANISH_BOLIVIA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 ISLANG_SPANISH_CHILE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 ISLANG_SPANISH_COLOMBIA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 ISLANG_SPANISH_COSTARICA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 ISLANG_SPANISH_DOMINICANREPUBLIC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 ISLANG_SPANISH_ECUADOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 ISLANG_SPANISH_ELSALVADOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 ISLANG_SPANISH_GUATEMALA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 ISLANG_SPANISH_HONDURAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 ISLANG_SPANISH_MEXICAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 ISLANG_SPANISH_MODERNSORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 ISLANG_SPANISH_NICARAGUA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 ISLANG_SPANISH_PANAMA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 ISLANG_SPANISH_PARAGUAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 ISLANG_SPANISH_PERU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 ISLANG_SPANISH_PUERTORICO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 ISLANG_SPANISH_TRADITIONALSORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 ISLANG_SPANISH_URUGUAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 ISLANG_SPANISH_VENEZUELA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 ISLANG_SWEDISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 ISLANG_SWEDISH_FINLAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 ISLANG_SWEDISH_STANDARD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 ISLANG_THAI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 ISLANG_THAI_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 ISLANG_TURKISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 ISLANG_TURKISH_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 ISLANG_UKRAINIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 ISLANG_UKRAINIAN_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 ISLANG_VIETNAMESE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 ISLANG_VIETNAMESE_STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 ISOSL_ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 ISOSL_SUPPORTED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 ISOSL_WIN2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 ISOSL_WIN7_SERVER2008R2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 ISOSL_WINSERVER2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 ISOSL_WINVISTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 ISOSL_WINVISTA_SERVER2008 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 ISOSL_WINXP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 ISOS_ST_ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 ISOS_ST_BACKOFFICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xv

Contents

ISOS_ST_DATACENTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 ISOS_ST_ENTERPRISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 ISOS_ST_PROC_ARCH_32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 ISOS_ST_PROC_ARCH_AMD64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 ISOS_ST_PROC_ARCH_IA64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 ISOS_ST_SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 ISOS_ST_SERVER2003_R2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 ISOS_ST_SMALLBUSINESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 ISOS_ST_SMALLBUSINESS_RESTRICTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 ISOS_ST_TERMINAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 ISOS_ST_WORKSTATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 ISOS_ST_XP_HOME. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 ISOS_ST_XP_PRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 ISUS_AGENT_FEATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 ISUS_MAIN_FEATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 ISUS_TEXTSUB_HOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 ISUS_TEXTSUB_INTERVAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 ISUS_TEXTSUB_LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 ISUS_TEXTSUB_LOGO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 ISUS_TEXTSUB_MANAGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 ISUS_TEXTSUB_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 ISUS_UPDATEMANAGER_FEATURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 IS_386 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 IS_486 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 IS_ALPHA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 IS_CDROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 IS_EGA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 IS_FIXED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 IS_FOLDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 IS_ITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 IS_PENTIUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 IS_REMOTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 IS_REMOVABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 IS_SVGA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 IS_UNKNOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 IS_UVGA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 IS_VGA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 IS_WINDOWS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 IS_WINDOWS9X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 IS_WINDOWSNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 IS_XVGA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 KBYTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 KEY_CREATE_LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 KEY_CREATE_SUB_KEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

xvi

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

KEY_ENUMERATE_SUB_KEYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 KEY_NOTIFY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 KEY_QUERY_VALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 KEY_SET_VALUE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 LAAW_OPTION_CHANGEDIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 LAAW_OPTION_FIXUP_PROGRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 LAAW_0PTION_HIDDEN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 LAAW_OPTION_MAXIMIZED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 LAAW_OPTION_MINIMIZED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 LAAW_OPTION_NO_CHANGEDIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 LAAW_OPTION_NOWAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 LAAW_OPTION_SET_BATCH_INSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 LAAW_OPTION_SHOW_HOURGLASS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 LAAW_OPTION_USE_CALLBACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 LAAW_OPTION_USE_SHELLEXECUTE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 LAAW_OPTION_WAIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 LAAW_OPTION_WAIT_INCL_CHILD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 LANGUAGE_SUPPORTED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 LESS_THAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 LINE_NUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 LISTBOX_ENTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 LISTBOX_SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 LISTFIRST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 LISTLAST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 LISTNEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 LISTPREV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 LIST_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 LOCKEDFILE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 LOGGING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 LOWER_LEFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 LOWER_RIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 LWTF_OPTION_APPEND_TO_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 LWTF_OPTION_WRITE_AS_ANSI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 LWTF_OPTION_WRITE_AS_UNICODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 MAGENTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 MATH_COPROCESSOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 MBYTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 MEDIA_FIELD_ADDREMOVE_NOMODIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 MEDIA_FIELD_ADDREMOVE_NOREMOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 MEDIA_FIELD_COMPANY_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 MEDIA_FIELD_MEDIA_FLAGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 MEDIA_FIELD_PREVIOUS_VERSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 MEDIA_FIELD_PRODUCT_COMMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xvii

Contents

MEDIA_FIELD_PRODUCT_EXE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 MEDIA_FIELD_PRODUCT_ICON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 MEDIA_FIELD_PRODUCT_NAME. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 MEDIA_FIELD_PRODUCT_README. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 MEDIA_FIELD_PRODUCT_SUPPORT_CONTACT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 MEDIA_FIELD_PRODUCT_SUPPORT_PHONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 MEDIA_FIELD_PRODUCT_SUPPORT_URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 MEDIA_FIELD_PRODUCT_UPDATE_URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 MEDIA_FIELD_PRODUCT_URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 MEDIA_FIELD_PRODUCT_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 MEDIA_FIELD_TARGETDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 MEDIA_FLAG_FORMAT_DIFFERENTIAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 MEDIA_FLAG_FORMAT_PATCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 MEDIA_FLAG_UPDATEMODE_SUPPORTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 MEDIA_PASSWORD_KEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 METAFILE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 MMEDIA_AVI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 MMEDIA_MIDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 MMEDIA_PLAYASYNCH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 MMEDIA_PLAYCONTINUOUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 MMEDIA_PLAYSYNCH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 MMEDIA_STOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 MMEDIA_SWF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 MMEDIA_WAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 MODIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 NEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 NEXTBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 NO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 NONEXCLUSIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 NORMALMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 NORMAL_PRIORITY_CLASS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 NOSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 NOTEXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 NO_SUBDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 NUMBERLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 OFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 OK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 ON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 ONLYDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 OTHER_FAILURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 OUT_OF_DISK_SPACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 PARALLEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 PARTIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

xviii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 PATH_EXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 PCRESTORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 PERSONAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 READ_CONTROL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 REBOOTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 RECORDMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 RED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 REGDBREMOTEREGCONNECTED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 REGDB_APPPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 REGDB_APPPATH_DEFAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 REGDB_BINARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 REGDB_ERR_CONNECTIONEXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 REGDB_ERR_CORRUPTEDREGISTRY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 REGDB_ERR_INITIALIZATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 REGDB_ERR_INVALIDHANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 REGDB_ERR_INVALIDNAME. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 REGDB_KEYPATH_APPPATHS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 REGDB_KEYPATH_DOTNET_10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 REGDB_KEYPATH_DOTNET_11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 REGDB_KEYPATH_DOTNET_20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 REGDB_KEYPATH_DOTNET_30 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 REGDB_KEYPATH_DOTNET_30_SP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 REGDB_KEYPATH_DOTNET_35 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 REGDB_KEYPATH_DOTNET_40_CLIENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 REGDB_KEYPATH_DOTNET_40_FULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 REGDB_KEYPATH_ISUNINSTINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 REGDB_KEYPATH_RUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 REGDB_KEYPATH_RUNONCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 REGDB_KEYPATH_RUNONCEEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 REGDB_KEYPATH_SHAREDDLLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 REGDB_KEYPATH_UNINSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 REGDB_KEYPATH_WINCURRVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 REGDB_KEYPATH_WINCURRVER_AUTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 REGDB_KEYPATH_WINNTCURRVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 REGDB_KEYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 REGDB_NAMES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 REGDB_NUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 REGDB_STRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 REGDB_STRING_EXPAND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 REGDB_STRING_MULTI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 REGDB_UNINSTALL_COMMENTS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 REGDB_UNINSTALL_CONTACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 REGDB_UNINSTALL_DISPLAYICON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xix

Contents

REGDB_UNINSTALL_DISPLAY_VERSION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 REGDB_UNINSTALL_HELPLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 REGDB_UNINSTALL_HELPTELEPHONE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 REGDB_UNINSTALL_INSTALLDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 REGDB_UNINSTALL_INSTALLLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 REGDB_UNINSTALL_INSTALLSOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 REGDB_UNINSTALL_LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 REGDB_UNINSTALL_LOGFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 REGDB_UNINSTALL_MAINT_OPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 REGDB_UNINSTALL_MAJOR_VERSION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 REGDB_UNINSTALL_MAJOR_VERSION_OLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 REGDB_UNINSTALL_MINOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 REGDB_UNINSTALL_MINOR_VERSION_OLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 REGDB_UNINSTALL_MODIFYPATH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 REGDB_UNINSTALL_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 REGDB_UNINSTALL_NOMODIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 REGDB_UNINSTALL_NOREMOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 REGDB_UNINSTALL_NOREPAIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 REGDB_UNINSTALL_PRODUCTGUID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 REGDB_UNINSTALL_PRODUCTID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 REGDB_UNINSTALL_PUBLISHER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 REGDB_UNINSTALL_README . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 REGDB_UNINSTALL_REGCOMPANY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 REGDB_UNINSTALL_REGOWNER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 REGDB_UNINSTALL_STRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 REGDB_UNINSTALL_SYSTEMCOMPONENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 REGDB_UNINSTALL_URLINFOABOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 REGDB_UNINSTALL_URLUPDATEINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 REGDB_UNINSTALL_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 REGDB_VALUENAME_APPPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 REGDB_VALUENAME_APPPATHDEFAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 REGDB_VALUENAME_INSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 REGDB_VALUENAME_INSTALLSUCCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 REGDB_VALUENAME_SP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 REGDB_VALUENAME_UNINSTALL_COMMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 REGDB_VALUENAME_UNINSTALL_CONTACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 REGDB_VALUENAME_UNINSTALL_DISPLAYICON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 REGDB_VALUENAME_UNINSTALL_DISPLAYNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 REGDB_VALUENAME_UNINSTALL_DISPLAYVERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 REGDB_VALUENAME_UNINSTALL_HELPLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 REGDB_VALUENAME_UNINSTALL_HELPTELEPHONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 REGDB_VALUENAME_UNINSTALL_INSTALLDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 REGDB_VALUENAME_UNINSTALL_INSTALLLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 REGDB_VALUENAME_UNINSTALL_INSTALLSOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

xx

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

REGDB_VALUENAME_UNINSTALL_LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 REGDB_VALUENAME_UNINSTALL_LOGFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 REGDB_VALUENAME_UNINSTALL_LOGMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 REGDB_VALUENAME_UNINSTALL_MAJORVERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 REGDB_VALUENAME_UNINSTALL_MAJORVERSION_OLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 REGDB_VALUENAME_UNINSTALL_MINORVERSION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 REGDB_VALUENAME_UNINSTALL_MINORVERSION_OLD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 REGDB_VALUENAME_UNINSTALL_MODIFYPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 REGDB_VALUENAME_UNINSTALL_NOMODIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 REGDB_VALUENAME_UNINSTALL_NOREMOVE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 REGDB_VALUENAME_UNINSTALL_NOREPAIR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 REGDB_VALUENAME_UNINSTALL_PRODUCTGUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 REGDB_VALUENAME_UNINSTALL_PRODUCTID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 REGDB_VALUENAME_UNINSTALL_PUBLISHER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 REGDB_VALUENAME_UNINSTALL_README . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 REGDB_VALUENAME_UNINSTALL_REGCOMPANY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 REGDB_VALUENAME_UNINSTALL_REGOWNER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 REGDB_VALUENAME_UNINSTALL_SYSTEMCOMPONENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 REGDB_VALUENAME_UNINSTALL_UNINSTALLSTRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 REGDB_VALUENAME_UNINSTALL_URLINFOABOUT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 REGDB_VALUENAME_UNINSTALL_URLUPDATEINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 REGDB_VALUENAME_UNINSTALL_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 REGDB_VALUENAME_UNINSTALLKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 REGDB_VALUENAME_WINCURRVER_REGORGANIZATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 REGDB_VALUENAME_WINCURRVER_REGOWNER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 REGDB_WINCURRVER_REGORGANIZATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 REGDB_WINCURRVER_REGOWNER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 REGFONT_OPTION_DEFAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 REGFONT_OPTION_DONTBROADCASTFONTCHANGEMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 REGFONT_OPTION_DONTUPDATEREGISTRY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 REGISTRYFUNCTIONS_USETEXTSUBS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 REMOTE_DRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 REMOVE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 REMOVEABLE_DRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 REMOVEALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 REPAIR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 REPLACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 RESET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 RESTART . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 ROOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 RUN_MAXIMIZED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 RUN_MINIMIZED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 SELECTFOLDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 SELFREGISTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxi

Contents

SELFREGISTERBATCH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 SELFREGISTRATIONPROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 SERIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 SERVICE_ADAPTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 SERVICE_ALL_ACCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 SERVICE_AUTO_START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 SERVICE_BOOT_START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 SERVICE_CHANGE_CONFIG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 SERVICE_CONTINUE_PENDING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 SERVICE_DEMAND_START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 SERVICE_DISABLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 SERVICE_ENUMERATE_DEPENDENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 SERVICE_ERROR_CRITICAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 SERVICE_ERROR_IGNORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 SERVICE_ERROR_NORMAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 SERVICE_ERROR_SEVERE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 SERVICE_FILE_SYSTEM_DRIVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 SERVICE_FLAG_DIFX_32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 SERVICE_FLAG_DIFX_AMD64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 SERVICE_FLAG_DIFX_IA64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 SERVICE_FLAG_ISFONTREG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 SERVICE_INTERACTIVE_PROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 SERVICE_INTERROGATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 SERVICE_ISFONTREG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 SERVICE_ISUPDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 SERVICE_KERNEL_DRIVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 SERVICE_PAUSED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 SERVICE_PAUSE_CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 SERVICE_PAUSE_PENDING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 SERVICE_QUERY_CONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 SERVICE_QUERY_STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 SERVICE_RECOGNIZER_DRIVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 SERVICE_RUNNING. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 SERVICE_START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 SERVICE_START_PENDING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 SERVICE_STOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 SERVICE_STOPPED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 SERVICE_STOP_PENDING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 SERVICE_SYSTEM_START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 SERVICE_USER_DEFINED_CONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 SERVICE_WIN32_OWN_PROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 SERVICE_WIN32_SHARE_PROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 SETUPTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 SETUPTYPE_INFO_DESCRIPTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

xxii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

SETUPTYPE_INFO_DISPLAYNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 SETUPTYPE_STR_COMPACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 SETUPTYPE_STR_COMPLETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 SETUPTYPE_STR_CUSTOM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 SETUPTYPE_STR_TYPICAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 SETUP_PACKAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 SEVERE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 SHAREDFILE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 SILENTMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 SKIN_LOADED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 SQL_BATCH_INSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 SQL_BATCH_UNINSTALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 SQL_BROWSE_ALIAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 SQL_BROWSE_ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 SQL_BROWSE_LOCAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 SQL_BROWSE_REMOTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 SQL_ERROR_GET_SCHEMA_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 SQL_ERROR_SCRIPT_COMMAND_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 SQL_ERROR_SCRIPT_CONNECTION_NOT_OPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 SQL_ERROR_SCRIPT_UNABLE_OPEN_FILE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 SQL_ERROR_SET_SCHEMA_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 SRCINSTALLDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 SRCTARGETDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 STANDARD_RIGHTS_ALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 STANDARD_RIGHTS_EXECUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 STANDARD_RIGHTS_READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 STANDARD_RIGHTS_REQUIRED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 STANDARD_RIGHTS_WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 STATUSBAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 STATUSBBRD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 STATUSDLG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 STATUSEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 STATUSOLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 STRINGLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 STYLE_BOLD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 STYLE_ITALIC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 STYLE_NORMAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 STYLE_SHADOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 STYLE_UNDERLINE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 SW_MAXIMIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 SW_MINIMIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 SW_RESTORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 SW_SHOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxiii

Contents

SYNCHRONIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 SYS_BOOTMACHINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 TBYTES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 TILED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 TRUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 TTFONTFILEINFO_FONTTITLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 TYPICAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 UPDATE_SERVICE_INSTALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 UPDATESERVICECOMPONENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 UPPER_LEFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 UPPER_RIGHT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 USER_ADMINISTRATOR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 USER_INADMINGROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 USER_POWERUSER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 USE_LOADED_SKIN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 VALID_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 VERSION_COMPARE_RESULT_NEWER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 VERSION_COMPARE_RESULT_NEWER_NOT_SUPPORTED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 VERSION_COMPARE_RESULT_NOT_INSTALLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 VERSION_COMPARE_RESULT_OLDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 VERSION_COMPARE_RESULT_SAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 VERSION_PREVIOUS_VERSION_DELIMITER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 VER_DLL_NOT_FOUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 VER_UPDATE_ALWAYS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 VER_UPDATE_COND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 VIDEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 VIRTUAL_MACHINE_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 VOLUMELABEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 WARNING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 WEB_BASED_SETUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 WELCOME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 WHITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 WILL_REBOOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 WINDOWS_SHARED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 WINMAJOR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 WINMINOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 WOW64FSREDIRECTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 WRITE_DAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 WRITE_OWNER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 YELLOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 YES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 _MAX_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

xxiv

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

Predefined Script Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

__FILE__. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 __LINE__ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 BASICMSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 INSTALLSCRIPTMSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 INSTALLSCRIPTMSIEEUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 ISUS_PRODUCT_CODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 SERVICE_IS_PARAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 SERVICE_IS_STATUS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Data Types and Predefined Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 Constant Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Language IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Variable Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Global vs. Local Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 String Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 String Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 String Size and Autosize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 System Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 ADDREMOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 ADDREMOVE_COMBINEDBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 ADDREMOVE_HIDECHANGEOPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 ADDREMOVE_HIDEREMOVEOPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 ADDREMOVE_STRING_REMOVEONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 ADDREMOVE_SYSTEMCOMPONENT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 ALLUSERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 How an InstallScript Installation Works by Default Depending on ALLUSERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 BATCH_INSTALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 CMDLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 COMMONFILES. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 COMMONFILES64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 DISK1SETUPEXENAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 DISK1TARGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 ENABLED_ISERVICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 ENGINECOMMONDIR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 ENGINEDIR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 ERRORFILENAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 FOLDER_APPDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 FOLDER_APPLICATIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxv

Contents

FOLDER_APPLICATIONS64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 FOLDER_COMMON_APPDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 FOLDER_DESKTOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 FOLDER_DOTNET_10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 FOLDER_DOTNET_11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 FOLDER_DOTNET_20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 FOLDER_DOTNET_30 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 FOLDER_DOTNET_35 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 FOLDER_DOTNET_40 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 FOLDER_FONTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 FOLDER_LOCAL_APPDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 FOLDER_PERSONAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 FOLDER_PROGRAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 FOLDER_STARTMENU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 FOLDER_STARTUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 FOLDER_TEMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 HKEYCURRENTROOTKEY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 HKEY_USER_SELECTABLE_AUTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 IFX_COMPANY_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 IFX_DISK1INSTALLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 IFX_INITIALIZED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 IFX_INSTALLED_DISPLAY_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 IFX_INSTALLED_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 IFX_KEYPATH_PRODUCT_INFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 IFX_MULTI_INSTANCE_SUFFIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 IFX_PRODUCT_COMMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 IFX_PRODUCT_DISPLAY_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 IFX_PRODUCT_DISPLAY_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 IFX_PRODUCT_ICON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 IFX_PRODUCT_KEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 IFX_PRODUCT_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 IFX_PRODUCT_README . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 IFX_PRODUCT_REGISTEREDCOMPANY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 IFX_PRODUCT_REGISTEREDOWNER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 IFX_PRODUCT_REGISTEREDSERIALNUM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 IFX_PRODUCT_SUPPORT_CONTACT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 IFX_PRODUCT_SUPPORT_PHONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 IFX_PRODUCT_SUPPORT_URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 IFX_PRODUCT_UPDATE_URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 IFX_PRODUCT_URL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 IFX_PRODUCT_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 IFX_SETUP_TITLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 IFX_SUPPORTED_VERSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 INFOFILENAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

xxvi

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

INSTALLDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 INSTANCE_GUID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 ISDIFXAPPID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 ISMSI_HANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 IS_NULLSTR_PTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 ISRES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 ISUSER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 ISVERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 LAAW_PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 LAAW_PROCESS_INFORMATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 LAAW_SHELLEXECUTEINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 LAAW_SHELLEXECUTEVERB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 LAAW_STARTUPINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 MAINTENANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 MAINT_OPTION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 MEDIA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 MSI_TARGETDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 MULTI_INSTANCE_COUNT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 PACKAGE_LOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 PRODUCT_GUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 PRODUCT_INSTALLED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 PROGRAMFILES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 PROGRAMFILES64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 REGDB_OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 REINSTALLMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 REMOVEALLMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 REMOVEONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 SELECTED_LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 SHAREDSUPPORTDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 SHELL_OBJECT_FOLDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 SHOW_PASSWORD_DIALOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 SRCDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 SRCDISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 SUPPORTDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 SYSINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 SYSPROCESSORINFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 TARGETDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 TARGETDISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 UNINST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 UNINSTALLKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 UNINSTALL_DISPLAYNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 UNINSTALL_STRING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 UPDATEMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxvii

Contents

WINDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 WINDISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 WINSYSDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 WINSYSDIR64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 WINSYSDISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Preprocessor Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

#define . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 #elif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 #error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 #if. . .#else. . .#endif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 #ifdef and #ifndef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 #include. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 #undef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 #warning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Event Handlers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Event Handler Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 Component Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Global Event Handlers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Initialization Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 OnCheckMediaPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 OnFilterComponents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 OnSetTARGETDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 OnSetUpdateMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 Before Move Data Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 OnAppSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 OnBegin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 OnCCPSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 OnFirstUIBefore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 OnIISInitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 OnMaintUIBefore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 OnSQLComponentInstalled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 OnSQLComponentUninstalled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 OnSQLLogin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 OnSQLServerInitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 OnSQLServerInitializeMaint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 OnUpdateUIBefore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 OnXMLInitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 Move Data Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 OnCustomizeUninstInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 OnGeneratedMSIScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 OnGeneratingMSIScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 OnIISComponentInstalled. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

xxviii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

OnIISVRootUninstalling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 OnInstalledFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 OnInstalledFontFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 OnInstallFilesActionBefore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 OnInstallFilesActionAfter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 OnInstallingFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 OnMoved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 OnMoveData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 OnMoving. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 OnNetApiCreateUserAccount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 OnSQLBatchScripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 OnSQLComponentInstalled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 OnSQLComponentUninstalled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 OnUninstalledFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 OnUninstallingFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 OnUninstallingDIFxDriverFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 OnUninstallingFontFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 OnXMLComponentInstalled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 OnXMLComponentUninstalling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 After Data Move Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 OnIISUninitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 OnXMLUninitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 OnFirstUIAfter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 OnMaintUIAfter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 OnUpdateUIAfter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 OnEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 Feature Event Handlers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 OnInstalled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 OnInstalling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 OnUnInstalled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 OnUnInstalling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 Miscellaneous Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 OnAbort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 OnAdminInstallUIAfter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 OnAdminInstallUIBefore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 OnAdminPatchUIAfter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 OnAdminPatchUIBefore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 OnAdvertisementAfter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 OnAdvertisementBefore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 OnCanceling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 OnComponentError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 OnDIFxLogCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 OnError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 OnException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxix

Contents

OnFileError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 OnFileLocked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 OnFileReadOnly. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 OnFilesInUse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 OnHelp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 OnInternetError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 OnLaunchAppAndWaitCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 OnLogonUserSetMsiProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 OnMD5Error. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 OnMsiSilentInstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 OnNextDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 OnOutOfDiskSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 OnPatchUIAfter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 OnPatchUIBefore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 OnRebooted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 OnRemovingSharedFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 OnResumeUIAfter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 OnResumeUIBefore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 OnRMFilesInUse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 OnSelfRegistrationError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 OnWarning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Advanced Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 OnShowUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 OnUninstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

10

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Using Built-In Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Built-In Functions by Category. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Batch File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 Ez Batch File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 Advanced Batch File Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 Component Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 Configuration File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Ez Config.sys File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Advanced Configuration File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Device Driver Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Dialog Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 Dialog Customization Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 Extensibility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Feature Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 Script-Created Feature Set vs. File Media Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 File Media Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 File and Folder Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 FlexNet Connect Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

xxx

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

Information Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 Initialization File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 List Processing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Log File Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 Long File Name Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 Object Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 Path Buffer Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 Registry Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 Shared and Locked File Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 Shell Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Special Registry-Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 SQL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 String Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 Text Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Uninstallation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 User Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Version-Checking Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 Windows Installer Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Windows Installer API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Windows Installer API Functions Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

11

Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Address Operator (&) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 Append to Path Operator (^) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 Arithmetic Operators (+, -, *, /) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Arithmetic Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Binary Arithmetic Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Unary Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Assignment Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 Bit Operators (&, |, ^, ~, <<, >>) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 BYREF Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 BYVAL Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 Concatenate Operator (+) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 Indirection Operator (*) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 Logical Operators (&&, ||, !) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 Member Operator (.). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 Relational Operators (<, >, =, <=, >=, !=) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 Relational Operator Precedence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445 String Operators (^, +, %) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 String Constant Operator (@) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 Structure Pointer Operator (->) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 Find String Operator (%) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxxi

Contents

12

Objects and Object Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 Err Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 Objects Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 Reboot Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 TextSub Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 Object Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 InitProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 ReadProperties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 WriteProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 Exception Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

Built-In Functions (A-D) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

AddFolderIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 AddFolderIcon Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 AddFolderIcon Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 AddFolderIcon Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 AddFolderIcon Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 AddProfString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 AddProfString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 AdminAskPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 AdminAskPath Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 AskDestPath. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 AskDestPath Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 AskOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 AskOptions Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 AskPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 AskPath Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 AskText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 AskText Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 AskYesNo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 AskYesNo Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 BatchAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 BatchAdd Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486 BatchDeleteEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 BatchDeleteEx Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 BatchFileLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 BatchFileLoad Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 BatchFileSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 BatchFileSave Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 BatchFind. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 BatchFind Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 BatchGetFileName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 BatchGetFileName Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501

xxxii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

BatchMoveEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502 BatchMoveEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 BatchSetFileName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 BatchSetFileName Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506 CalculateAndAddFileCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 CallDLLFx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 CallDLLFx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 ChangeDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 ChangeDirectory Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 CharReplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 CharReplace Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 CloseFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 CloseFile Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 CmdGetHwndDlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 CmdGetHwndDlg Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 CoCreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 CoCreateObjectDotNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 CoGetObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 CoGetObject Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 ConfigAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 ConfigAdd Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 ConfigDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 ConfigDelete Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 ConfigFileLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 ConfigFileLoad Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 ConfigFileSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529 ConfigFileSave Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 ConfigFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 ConfigFind Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 ConfigGetFileName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 ConfigGetFileName Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 ConfigGetInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 ConfigGetInt Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 ConfigMove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 ConfigMove Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 ConfigSetFileName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 ConfigSetFileName Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 ConfigSetInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 ConfigSetInt Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 ConvertSizeToUnits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 ConvertWinHighLowSizeToISHighLowSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 CopyBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 CopyBytes Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 CopyCHARArrayToISStringArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxxiii

Contents

CopyFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 CopyFile Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 CreateDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 CreateDir Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 CreateFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 CreateFile Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 CreateInstallationInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 CreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 CreateProgramFolder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 CreateProgramFolder Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 CreateRegistrySet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 CreateRegistrySet Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 CreateShellObjects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 CreateShellObjects Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 570 CtrlClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 CtrlClear Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572 CtrlDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 CtrlDir Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 CtrlGetCurSel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 CtrlGetCurSel Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 CtrlGetDlgItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 CtrlGetMLEText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 CtrlGetMLEText Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 CtrlGetMultCurSel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 CtrlGetMultCurSel Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 CtrlGetState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 CtrlGetState Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 CtrlGetSubCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 CtrlGetSubCommand Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 CtrlGetText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 CtrlGetText Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 CtrlGetUrlForLinkClicked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 CtrlGetUrlForLinkClicked Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 CtrlPGroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 CtrlPGroups Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 CtrlSelectText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 CtrlSelectText Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 CtrlSetCurSel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 CtrlSetCurSel Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 CtrlSetFont. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 CtrlSetFont Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 CtrlSetList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 CtrlSetList Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 CtrlSetMLEText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619

xxxiv

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

CtrlSetMLEText Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 CtrlSetMultCurSel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 CtrlSetMultCurSel Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 CtrlSetState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 CtrlSetState Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 CtrlSetText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 CtrlSetText Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 DefineDialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 DefineDialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 DeinstallSetReference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 DeinstallStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 Delay Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 DeleteCHARArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 DeleteDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 DeleteDir Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642 DeleteFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 DeleteFile Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 DeleteFolderIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645 DeleteFolderIcon Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646 DeleteProgramFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 DeleteProgramFolder Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648 DeleteWCHARArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649 DialogSetFont. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 DialogSetInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651 DialogSetInfo Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655 Dialog Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656 CHECKBOX Dialog Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656 CHECKBOX95 Dialog Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 CHECKMARK Dialog Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658 CHECKLINE Dialog Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659 DIFxDriverPackageGetPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659 DIFxDriverPackageInstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660 DIFxDriverPackagePreinstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664 DIFxDriverPackageUninstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 Disable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668 Disable Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672 Do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 Do Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674 DoInstall. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675 DoInstall Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678 DotNetCoCreateObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679 DotNetUnloadAppDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxxv

Contents

Built-In Functions (E-G) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683

Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683 Enable Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686 EndCurrentDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687 EndDialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688 EndDialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689 EnterDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691 EnterDisk Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692 EnterDiskError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693 EnterLoginInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694 EnterPassword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696 ExistsDir. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697 ExistsDir Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697 ExistsDisk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698 ExistsDisk Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 EzBatchAddPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700 EzBatchAddPath Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701 EzBatchAddString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703 EzBatchAddString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705 EzBatchReplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706 EzBatchReplace Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 EzConfigAddDriver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709 EzConfigAddDriver Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710 EzConfigAddString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712 EzConfigAddString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713 EzConfigGetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715 EzConfigGetValue Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 EzConfigSetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717 EzConfigSetValue Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 EzDefineDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719 EzDefineDialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 FeatureAddCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723 FeatureAddItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 FeatureAddItem Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726 FeatureAddUninstallCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727 FeatureCompareSizeRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728 FeatureCompareSizeRequired Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730 FeatureDialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732 FeatureDialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734 FeatureError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735 FeatureError Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 FeatureErrorInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739 FeatureErrorInfo Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740 FeatureFileEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741

xxxvi

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

FeatureFileEnum Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743 FeatureFileInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745 FeatureFileInfo Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751 FeatureFilterLanguage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754 FeatureFilterLanguage Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 FeatureFilterOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757 FeatureFilterOS Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760 FeatureGetCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763 FeatureGetCost Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 764 FeatureGetCostEx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765 FeatureGetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766 FeatureGetData Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770 FeatureGetItemSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 FeatureGetItemSize Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 FeatureGetTotalCost. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773 FeatureInitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774 FeatureInitialize Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775 FeatureIsItemSelected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777 FeatureIsItemSelected Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778 FeatureListItems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 779 FeatureListItems Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780 FeatureLoadTarget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781 FeatureMoveData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782 FeatureMoveData Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783 FeaturePatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787 FeatureReinstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788 FeatureRemoveAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788 FeatureRemoveAllInLogOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789 FeatureRemoveAllInMedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790 FeatureRemoveAllInMediaAndLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791 FeatureSaveTarget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792 FeatureSelectItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793 FeatureSelectItem Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794 FeatureSelectNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795 FeatureSetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796 FeatureSetData Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799 FeatureSetTarget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800 FeatureSetTarget Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801 FeatureSetupTypeEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 FeatureSetupTypeEnum Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802 FeatureSetupTypeGetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803 FeatureSetupTypeGetData Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804 FeatureSetupTypeSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807 FeatureSetupTypeSet Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxxvii

Contents

FeatureSpendCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809 FeatureSpendUninstallCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810 FeatureStandardSetupTypeSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811 FeatureTotalSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 813 FeatureTotalSize Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814 FeatureTransferData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816 FeatureUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 817 FeatureValidate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819 FeatureValidate Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819 FileCompare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821 FileCompare Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823 FileDeleteLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 825 FileDeleteLine Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826 FileGrep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828 FileGrep Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 829 FileInsertLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831 FileInsertLine Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832 FindAllDirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834 FindAllDirs Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835 FindAllFiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836 FindAllFiles Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 838 FindFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 840 FindFile Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841 FindWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842 FindWindow Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 843 FormatMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844 FormatMessage Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845 GetAndAddAllFilesCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845 GetAndAddFileCost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847 GetCArrayFromISArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848 GetCHARArrayFromISStringArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849 GetCurrentDialogName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850 GetCurrentDir. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851 GetDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852 GetDir Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853 GetDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854 GetDisk Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854 GetDiskInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855 GetDiskInfo Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857 GetDiskSpace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858 GetDiskSpace Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858 GetDiskSpaceEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860 GetDiskSpaceEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861 GetEnvVar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862

xxxviii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

GetEnvVar Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863 GetExtendedErrInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 GetExtents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865 GetExtents Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866 GetFileInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867 GetFileInfo Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869 GetFolderNameList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871 GetFolderNameList Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873 GetFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874 GetFont Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875 GetLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 878 GetLine Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879 GetMemFree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880 GetObject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 880 GetObjectByIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881 GetObjectCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882 GetProfInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883 GetProfInt Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884 GetProfSectionKeyCount. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884 GetProfString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885 GetProfString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887 GetProfStringList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888 GetProfStringList Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 888 GetStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 GetSystemInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891 GetSystemInfo Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895 GetTempFileNameIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 898 GetTrueTypeFontFileInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900 GetUpdateStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900 GetUpdateStatusReboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901 GetValidDrivesList. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901 GetValidDrivesList Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902 GetWCHARArrayFromISStringArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904 GetWindowHandle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 904 GetWindowHandle Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905

Built-In Functions (H-P) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907

Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907 HandlerEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907 HandlerEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909 HIBYTE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910 HIWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911 HIWORD Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 911 InstallationInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xxxix

Contents

Is . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912 Is Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 919 ISCompareServicePack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920 ISCompareServicePack Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921 ISDeterminePlatform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922 IsEmpty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922 IsEmpty Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923 IsObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 LaunchApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 LaunchApp Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 LaunchAppAndWait. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925 LaunchAppAndWait Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 925 LaunchAppAndWaitInitStartupInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927 LaunchApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929 LaunchApplicationInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935 ListAddItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937 ListAddItem Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938 ListAddList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940 ListAddString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941 ListAddString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942 ListAppendFromArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943 ListAppendToArray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944 ListConvertNumToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 ListConvertStrToNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946 ListCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947 ListCount Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948 ListCreate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949 ListCreate Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950 ListCurrentItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951 ListCurrentItem Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952 ListCurrentString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953 ListCurrentString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954 ListDeleteAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955 ListDeleteItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956 ListDeleteItem Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957 ListDeleteString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959 ListDeleteString Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959 ListDestroy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961 ListDestroy Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962 ListFindItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963 ListFindItem Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964 ListFindKeyValueString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965 ListFindString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967 ListFindString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968

xl

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

ListGetFirstItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970 ListGetFirstItem Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970 ListGetFirstString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972 ListGetFirstString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972 ListGetIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974 ListGetNextItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974 ListGetNextItem Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 975 ListGetNextString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977 ListGetNextString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977 ListGetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979 ListGetType Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979 ListReadFromFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980 ListReadFromFile Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981 ListSetCurrentItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982 ListSetCurrentItem Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 983 ListSetCurrentString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985 ListSetCurrentString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986 ListSetIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987 ListSetIndex Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989 ListValid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991 ListValid Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991 ListValidType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992 ListValidType Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993 ListWriteToFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994 ListWriteToFile Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995 ListWriteToFileEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996 LoadStringFromStringTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997 LOBYTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998 LogReadCustomNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999 LogReadCustomNumber Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000 LogReadCustomString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001 LogReadCustomString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003 LogWriteCustomNumber. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004 LogWriteCustomNumber Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005 LogWriteCustomString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1006 LogWriteCustomString Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007 LongPathFromShortPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008 LongPathFromShortPath Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008 LongPathToQuote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009 LongPathToQuote Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010 LongPathToShortPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011 LongPathToShortPath Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012 LOWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013 LOWORD Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xli

Contents

MaintenanceStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015 MediaGetData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017 MediaGetDataEx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018 MessageBeep. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020 MessageBeep Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1021 MessageBox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022 MessageBox Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023 MessageBoxEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024 NumToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026 NumToStr Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026 OpenFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027 OpenFile Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028 OpenFileMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029 OpenFileMode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030 ParsePath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1032 ParsePath Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033 ParseUrl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035 ParseUrl Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035 PathAdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036 PathAdd Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037 PathDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039 PathDelete Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040 PathFind. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042 PathFind Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043 PathGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045 PathGet Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045 PathMove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047 PathMove Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048 PathSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050 PathSet Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1051 PlaceBitmap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052 PlaceBitmap Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1056 PlaceWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1057 PlaceWindow Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1060 PlayMMedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061 PlayMMedia Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063 PostShowComponentDlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064 PreShowComponentDlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065 ProgDefGroupType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066

Built-In Functions (Q-R) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067

QueryProgItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067 QueryProgItem Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069 QueryShellMgr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1071

xlii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

QueryShellMgr Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072 ReadArrayProperty. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072 ReadBoolProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073 ReadBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074 ReadBytes Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075 ReadNumberProperty. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076 ReadStringProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077 RebootDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078 RebootDialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079 RegDBConnectRegistry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1080 RegDBConnectRegistry Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083 RegDBCopyKeys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1084 RegDBCopyValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087 RegDBCreateKeyEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1089 RegDBCreateKeyEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091 RegDBDeleteItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1092 RegDBDeleteKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095 RegDBDeleteKey Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1096 RegDBDeleteValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1097 RegDBDeleteValue Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098 RegDBDisConnectRegistry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099 RegDBDisConnectRegistry Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1100 RegDBGetAppInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1102 RegDBGetAppInfo Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103 RegDBGetDefaultRoot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1105 RegDBGetItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1106 RegDBGetItem Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110 RegDBGetKeyValueEx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111 RegDBGetKeyValueEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1113 RegDBGetUninstCmdLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1115 RegDBKeyExist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1116 RegDBKeyExist Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117 RegDBQueryKey. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119 RegDBQueryKey Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1120 RegDBQueryKeyCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122 RegDBQueryStringMultiStringCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123 RegDBSetAppInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125 RegDBSetAppInfo Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1126 RegDBSetDefaultRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1128 RegDBSetDefaultRoot Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1129 RegDBSetItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1131 RegDBSetItem Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1134 RegDBSetKeyValueEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1136 RegDBSetKeyValueEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1139

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xliii

Contents

RegDBSetVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1140 RegisterFontResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1141 RegisterFontResource Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144 ReleaseDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1144 ReleaseDialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1145 RenameFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1147 RenameFile Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148 ReplaceFolderIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1150 ReplaceFolderIcon Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1152 ReplaceProfString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153 ReplaceProfString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155 Resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156 RGB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1156 RGB Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1157

Built-In Functions (S-T) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159

SdAskDestPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159 SdAskDestPath Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161 SdAskDestPath2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1161 SdAskDestPath2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163 SdAskOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1164 SdAskOptions Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1166 SdAskOptionsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1167 SdAskOptionsList Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1169 SdBitmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1170 SdBitmap Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1172 SdConfirmNewDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173 SdConfirmNewDir Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1174 SdConfirmRegistration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1175 SdConfirmRegistration Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1176 SdCustomerInformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1177 SdCustomerInformation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1180 SdCustomerInformationEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1181 SdCustomerInformationEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1184 SdDiskSpace2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1185 SdDiskSpace2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1186 SdDiskSpaceRequirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1187 SdDisplayTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1188 SdDisplayTopics Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1189 SdExceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1191 SdExceptions Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1192 SdFeatureDialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1193 SdFeatureDialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1195 SdFeatureDialog2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1196

xliv

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

SdFeatureDialog2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198 SdFeatureDialogAdv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1199 SdFeatureDialogAdv Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1201 SdFeatureMult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1202 SdFeatureMult Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204 SdFeatureTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205 SdFeatureTree Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1207 SdFilesInUse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208 SdFilesInUse Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1210 SdFinish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211 SdFinish Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1212 SdFinishEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1214 SdFinishEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215 SdFinishReboot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215 SdFinishReboot Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1217 SdFinishUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1218 SdFinishUpdateEx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1218 SdFinishUpdateReboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1220 SdFinishUpdateReboot Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1222 SdGeneralInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1222 SdGeneralInit Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223 SdInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225 SdInit Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1225 SdLicense . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226 SdLicense Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1227 SdLicense2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1228 SdLicense2 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1231 SdLicense2Ex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1231 SdLicense2Rtf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1234 SdLicense2Rtf Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236 SdLicenseEx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1236 SdLicenseRtf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1239 SdLicenseRtf Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1240 SdLoadString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1241 SdLoadString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1242 SdLogonUserBrowse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1243 SdLogonUserCreateUser. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1243 SdLogonUserInformation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1243 SdLogonUserListGroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1244 SdLogonUserListServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245 SdLogonUserListUsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245 SdMakeName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1245 SdMakeName Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1246 SdOptionsButtons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1250

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xlv

Contents

SdOptionsButtons Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1252 SdOutOfDiskSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1254 SdPatchWelcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255 SdPatchWelcome Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256 SdProductName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1256 SdProductName Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1257 SdRegisterUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1258 SdRegisterUser Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1260 SdRegisterUserEx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1260 SdRegisterUserEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263 SdRMFilesInUse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1264 SdSelectFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1266 SdSelectFolder Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1267 SdSetupCompleteError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1268 SdSetupCompleteError Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269 SdSetupType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1270 SdSetupType Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1271 SdSetupType2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1272 SdSetupType2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1274 SdSetupTypeEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1275 SdSetupTypeEx Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1276 SdShowAnyDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1277 SdShowAnyDialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1278 SdShowDlgEdit1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1279 SdShowDlgEdit1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1280 SdShowDlgEdit2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1281 SdShowDlgEdit2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1282 SdShowDlgEdit3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1283 SdShowDlgEdit3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1285 SdShowFileMods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1286 SdShowFileMods Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1287 SdShowInfoList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1289 SdShowInfoList Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1290 SdShowMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291 SdShowMsg Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1293 SdStartCopy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1293 SdStartCopy Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1295 SdStartCopy2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296 SdStartCopy2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1297 SdSubstituteProductInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299 SdWelcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299 SdWelcome Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1300 SdWelcomeMaint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1301 SdWelcomeMaint Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1302

xlvi

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

SeekBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1303 SeekBytes Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1304 SelectDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1306 SelectDir Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1308 SelectDirEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309 SelectDirEx Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311 SelectFolder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1312 SelectFolder Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313 SendMessage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1314 SendMessage Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315 ServiceAddService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1317 ServiceExistsService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1318 ServiceGetServiceState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1319 ServiceInitParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1320 ServiceRemoveService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1321 ServiceStartService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322 ServiceStopService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323 SetColor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1324 SetColor Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1326 SetDialogTitle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1327 SetDialogTitle Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1328 SetDisplayEffect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1329 SetDisplayEffect Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330 SetErrorMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1332 SetErrorMsg Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333 SetErrorTitle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1334 SetErrorTitle Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1335 SetExtendedErrInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336 SetFileInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1337 SetFileInfo Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1339 SetFont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1340 SetFont Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341 SetInstallationInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342 SetObjectPermissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343 SetObjectPermissions Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1346 SetStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1347 SetStatusEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1348 SetStatusExStaticText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1349 SetStatusWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1350 SetStatusWindow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1351 SetTitle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1352 SetTitle Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355 SetUpdateStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356 SetUpdateStatusReboot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xlvii

Contents

SetupType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1356 SetupType Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1359 SetupType2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1361 SetupType2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363 ShowObjWizardPages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365 ShowProgramFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365 ShowProgramFolder Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366 ShowWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367 SilentReadData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369 SilentReadData Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371 SilentWriteData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1374 SilentWriteData Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1376 SizeOf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1379 SizeWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380 SizeWindow Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1381 Sprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1382 Sprintf Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1383 SprintfBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1384 SprintfBox Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387 SprintfMsiLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1388 SQLBrowse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1389 SQLBrowse2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1390 SQLDatabaseBrowse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1391 SQLRTComponentInstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1392 SQLRTComponentUninstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393 SQLRTConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394 SQLRTConnect2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395 SQLRTConnectDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397 SQLRTDoRollbackAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1398 SQLRTGetBatchList. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1399 SQLRTGetBatchMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1400 SQLRTGetBrowseOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1401 SQLRTGetComponentScriptError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1402 SQLRTGetComponentScriptError2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1404 SQLRTGetConnectionAuthentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1406 SQLRTGetConnectionInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407 SQLRTGetConnections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1408 SQLRTGetDatabases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1409 SQLRTGetErrorMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1410 SQLRTGetLastError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1411 SQLRTGetLastError2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1412 SQLRTGetScriptErrorMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1412 SQLRTGetServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1413 SQLRTGetServers2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1414

xlviii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

SQLRTInitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1415 SQLRTInitialize2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416 SQLRTPutConnectionAuthentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417 SQLRTPutConnectionInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417 SQLRTPutConnectionInfo2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418 SQLRTServerValidate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1419 SQLRTSetBrowseOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1421 SQLRTTestConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1422 SQLRTTestConnection2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1424 SQLServerLogin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426 SQLServerSelect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1427 SQLServerSelectLogin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1428 SQLServerSelectLogin2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429 SQLServerSelectLoginEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432 StatusUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433 StatusUpdate Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1435 StrAddLastSlash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1436 StrCompare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1437 StrCompare Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1438 StrConvertSizeUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1439 StreamFileFromBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1440 StrFind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1441 StrFind Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1441 StrFindEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1442 StrGetTokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1443 StrGetTokens Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1444 StrLength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446 StrLength Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446 StrLengthChars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1447 StrLengthChars Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1448 StrPutTokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1449 StrRemoveLastSlash. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1450 StrRemoveLastSlash Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1451 StrReplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1452 StrSub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453 StrSub Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1454 STRTOCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1455 StrToLower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456 StrToLower Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1457 StrToNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1458 StrToNum Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1459 StrToNumHex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1460 StrToUpper. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1461 StrToUpper Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1462

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

xlix

Contents

StrTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1463 System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1464 System Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1465 TextSubGetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1465 TextSubGetValue Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1466 TextSubParseTextSub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1467 TextSubParseTextSub Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1468 TextSubSetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1469 TextSubSetValue Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1469 TextSubSubstitute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1470 TextSubSubstitute Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1471

Built-In Functions (U-Z) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1473

UninstallApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1473 UnUseDLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1474 UnUseDLL Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1475 UpdateServiceCheckForUpdates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1477 UpdateServiceCreateShortcut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1477 UpdateServiceEnableUpdateManagerInstall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1477 UpdateServiceGetAgentTarget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478 UpdateServiceOnEnabledStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478 UpdateServiceRegisterProduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1478 UpdateServiceRegisterProductEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1479 UpdateServiceSetHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1479 UpdateServiceSetLanguage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1479 UseDLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1479 UseDLL Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1482 VarInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1484 VarRestore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1485 VarRestore Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1488 VarSave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1489 VarSave Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1491 VarSave Stack Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1492 VerCompare. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1493 VerCompare Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494 VerFindFileVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1496 VerFindFileVersion Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1497 VerGetFileLanguages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1499 VerGetFileLanguages Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1500 VerGetFileVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1501 VerGetFileVersion Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1502 VerProductCompareVersions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1503 VerProductGetInstalledVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1504 VerProductIsVersionSupported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1505

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Contents

VerProductNumToStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1506 VerProductStrToNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1507 VerProductVerFromVerParts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1508 VerProductVerPartsFromVer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1509 VerSearchAndUpdateFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1510 VerSearchAndUpdateFile Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1512 VerUpdateFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1514 VerUpdateFile Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1518 WaitForApplication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1519 WaitOnDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1522 WaitOnDialog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1523 Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1525 Welcome Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526 WizardDirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1527 WriteArrayProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1528 WriteBoolProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1529 WriteBytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1530 WriteBytes Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1531 WriteLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1532 WriteLine Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1533 WriteNumberProperty. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535 WriteProfInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1535 WriteProfInt Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1537 WriteProfString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1538 WriteProfString Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1539 WriteStringProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1540 XCopyFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1541 XCopyFile Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1545

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1547

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

li

Contents

lii

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

1
InstallScript Language Reference
InstallShield makes designing your installation easy with InstallScript, a simple but powerful programming language. InstallScript is similar to the C language. It has a defined format and regulated syntax. It uses certain data types, each with specific properties. It also allows you to create custom functions. InstallScript, however, does not provide the full range of programming functionality that C does. InstallScript was designed to do one thingcreate installations. And it does so better than any programming language in the world. Regardless of your programming background, you can quickly learn to build an installation with InstallScript.

Project: Some InstallScript functions, events, and variables are limited to specific project types. Table 1-1: InstallScript Language Reference Section Integrated Compiler Command-Line Compiler Description Provides general information about the InstallScript integrated compiler. Contains details about the InstallScript command-line compiler that can be invoked from the DOS prompt or from a DOS batch file. Introduces you to the InstallScript language and the structure of a script. Presents background about language keywords, which are words InstallScript uses as commands in the script. Language keywords are interpreted by the InstallScript compiler to perform some action, or are considered part of a statement. Identifies and describes each of the predefined constants reserved by InstallScript. These constants represent specific literal values that are passed to and returned by built-in functions. Contains information about script variables that you can use with InstallScript.

Setup Scripts Language Keywords

Predefined Constants

Predefined Script Variables

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

Chapter 1: InstallScript Language Reference Integrated Compiler

Table 1-1: InstallScript Language Reference (cont.) Section Data Types and Predefined Structures Description Contains content about the data types and predefined structures supported in InstallScript. Discusses preprocessor directives, which are instructions to the InstallScript compiler that are executed as the script is compiled. Preprocessor directives can instruct the compiler to include other source files in the compilation, to define constants, to include or exclude statements based on compile-time conditions, and to display a user-defined error message. Contains information on how to control the flow of execution within scripts. InstallScript project installation programs are driven by the InstallScript engine, which generates a series of events in a specific order. Describes the different types of functions that you can use in your installation scripts; also includes details aboutand examples ofeach of the built-in functions available in InstallScript. Contains information about supported operators in InstallScript. Contains information about the objects that InstallScript supports and how to separate error handling from the rest of your script code.

Preprocessor Directives

Flow Control

Event Handlers

Functions

Operators Objects and Object Handlers

Note: Some of the functions that were available in InstallShield Professional are deprecated in later versions of InstallShield. To view a list of the functions, see Unsupported Functions. Because the InstallShield Help Library is designed to interact with InstallShield, it is recommended that you open the help from within InstallShield. Copying the help files to another folder or system causes many of its features to work incorrectly.

Integrated Compiler
If you want to compile your script without building a release, you can use the integrated InstallScript compiler in InstallShield.

Task

To compile your script:

On the Build menu, click Compile. InstallShield displays compiler messages in the Output window.

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 1: InstallScript Language Reference Command-Line Compiler

Command-Line Compiler
In addition to the integrated compiler, which you can launch from within InstallShield, InstallShield includes a command-line compiler that you can invoke from the DOS prompt or from a DOS batch file. This program, called Compile.exe, is in the following folder:
InstallShield Program Files Folder/System

After you have completed the design of an installation project, you can use Compile.exe to compile the installation script using different options than those that are used when you compile the script from within InstallShield. For the syntax and available command-line parameters and switches for Compile.exe, see Compile.exe.

Note: When you build a release from the command line using ISCmdBld.exe, the build engine automatically compiles your script; therefore, you do not need to use Compile.exe directly unless you want to use compiler options that are different from those specified for the project in InstallShield. For more information, see ISCmdBld.exe.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

Chapter 1: InstallScript Language Reference Command-Line Compiler

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

2
Setup Scripts
A setup script is a collection of event handlers, functions called by those event handlers, and data used by the event handlers and functions. These elements are expressed in the InstallScript Language, a simple but powerful programming language. InstallScript is similar to the C language. It has a defined format and regulated syntax. It uses certain data types, each with specific properties. It also allows you to create custom functions. InstallScript, however, does not provide the full range of programming functionality that C does. InstallScript was designed to do one thingcreate setups. And it does this effectively and efficiently. Regardless of your programming background, you can learn quickly to build your setup with InstallScript.

InstallScript Limits
Following are limits for the compiled script file (setup.inx):

Maximum number of statements: about 4,294,967,295 (If this limit is exceeded, error -5009 may occur during setup initialization.) Maximum number of global variables: about 196,605 (65,535 numbers, 65,535 variants, 65,535 strings) Maximum number of typedefs: about 65,535 Maximum number of prototypes: about 65,535 Maximum number of functions: about 65,535 Maximum number of statements per function: about 65,535 Maximum local variables per function: about 196,605 (65,535 numbers, 65,535 variants, 65,535 strings)

Following are limits for script files (.rul):

Maximum line width: 1,024 characters

ISP-1800-RG00 5

InstallShield 2012 InstallScript Reference Guide

Chapter 2: Setup Scripts Structure of a Script

Maximum number of nested include files: 80 Maximum number of include files: 2,048 Maximum identifier length: 63 characters Maximum number of macro expansions: 100 Maximum macro expansion text length: 256 characters Maximum file name length: 256 characters Maximum number of nested #if statements: 10 Maximum number of parameters per function: 16

Compile errors occur if one or more of these .rul limits are exceeded.

Tip: If you encounter any of the aforementioned limits, consider reducing the size of your installation script by removing code, or by splitting up your installation script into multiple projects, creating separate installations, and calling the child installations from your main installation (parent installation).

Structure of a Script
Every script includes declarations and function blocks. Declarations can precede function declarations or appear between a function statement and the begin statement for that function. The general outline of a script is shown below:
// Constant definitions, global data declarations, and function declarations // Function blocks

Declarations
Every script begins with global data declarations. Here, you define constants and declare each of the global variables and user-defined functions that you will be using. Declarations instruct the InstallScript compiler that the script will be using the listed items at a later time. Declarations also build an association between a function and its attributes or values. You do not need to declare any of the built-in functions, since the InstallScript compiler already recognizes the function names. Below are some examples of constant definitions, data declarations, and function declarations:
// Constant definitions #define PRODUCT "InstallShield" #define LIMIT 100 // Variable declarations CHAR cVal; NUMBER nVal; STRING szName; // Function declarations prototype DisplayMsg (NUMBER, STRING);
6 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 2: Setup Scripts Program Block

prototype GetName (BYREF STRING);

Program Block
Program blocks are used in scripts written using InstallShield Professional 5.5 or earlier. A program block cannot be used for an InstallScript custom action or in an event-driven script. The only code that is executed is found in event handlers and entry-point functions.
program // In an event-driven script, the program block is optional and remains empty. endprogram

Function Block
Project: This information applies to InstallScript projects.

All functions that have been declared with a prototype statement must be defined in the function block, which follows the keyword endprogram in a setup script. Additional global data declarations may be made in the function block, either between the endprogram statement and the first function declaration or between function declarations. However, data declared in the function block is visible only to functions that are defined after the data declaration.

Identifiers
Identifiers are the names that you create to denote constants, variables, and functions in your script. Observe the following syntax rules when creating identifiers:

An identifier may be of any length, but only the first 63 characters are significant. The first character of an identifier must be alphabetic (a-z, A-Z) or an underscore. The remaining characters may be alphabetic (a-z, A-Z), numeric (0-9), or an underscore. Each identifier must be unique. Be careful not to create an identifier that is a reserved word in InstallScript.

Syntax Punctuation Rules

Like any programming language, InstallScript has syntax rules that regulate its usage. The basic syntax of InstallScript is similar to that of the C programming language. The following punctuation reminders apply to all sections of the script:

Most statements end with a semicolon (;). This includes many one-word statements, such as end;, exit;, and return;. Preprocessor statementssuch as #define and #includenever end with a semicolon.
ISP-1800-RG00 7

InstallShield 2012 InstallScript Reference Guide

Chapter 2: Setup Scripts Writing Comments

The keywords program, endprogram, and begin are placed on separate lines by themselves and receive no punctuation. The function line that begins each function block receives no punctuation. End a label, such as start: or starthere:, with a colon (:). Enclose parameter lists within parentheses. Separate multiple parameters with commas.

Writing Comments
InstallScript gives you two ways to create comments in a script. You can use either method to add explanatory text to your script or to exclude or comment out certain parts of your script for testing and debugging purposes.

Caution: You can begin comments anywhere in a scriptwith one exception: Comments cannot be placed on the same line as an #ifdef or #ifndef statement. You must write comments before or after these statements, if necessary. Otherwise, the compiler returns an error.

Block of Text
One way to create a comment is to enclose a block of text between the character pairs /* and */. This method makes it easy to write a comment over multiple lines:
/* This is a line of sample code that shows you * how to use the InstallScript function PlaceBitmap. */

Line by Line
The second way is to insert the characters // into a line. The compiler ignores everything to the right of the double slashes on that line only.
// This is a line of sample code showing the // InstallScript function PlaceBitmap.

Using White Space

Like C and other programming languages, InstallScript does not recognize white space (spaces and tabs, carriage returns) except in a string literal. It is recommended that you use white space to make your script easier to follow.

Code Without White Space

For example, the following section of code is dense and difficult to decipher:
#define DISK_DRIVE "C:\\" STRING szDrive, svString; NUMBER nSpace, nResult; szDrive = DISK_DRIVE; nSpace = GetDiskSpace(szDrive); nResult = NumToStr(svString, nSpace); if (nResult < 0) then MessageBox("NumToStr failed.", SEVERE); abort; endif;
8 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 2: Setup Scripts Hungarian Notation

SprintfBox(INFORMATION, "Info", "Disk Space: %s", svString);

Code With White Space

Adding white space with indentation makes the same code much easier to read:
#define DISK_DRIVE "C:\\" STRING NUMBER szDrive, svString; nSpace, nResult;

szDrive = DISK_DRIVE; nSpace = GetDiskSpace(szDrive); nResult = NumToStr(svString, nSpace); if (nResult < 0) then MessageBox("NumToStr failed.", SEVERE); abort; endif; SprintfBox(INFORMATION, "Info", "Disk Space: %s", svString);

Hungarian Notation
InstallShield help topics employ an extended form of Hungarian notationa naming convention that uses short, lowercase prefixes to indicate the data type. For example, iPointSize denotes an integer variable, while szFileName indicates a string variable. Hungarian notation is used in example scripts to indicate the data type of all variables. In function syntax descriptions, Hungarian notation is used for parameter names to indicate the type of data that may be passed in a parameter. For example, the syntax description of BatchDeleteEx shows that it takes two parameters:
BatchDeleteEx ( szKey, nOptions );

The first parameter, identified as szKey, could be a string variable or constant. The second, identified as nOptions, could be a number variable or constant.

Variable Parameters
In those cases where a variable parameter is required, the Language reference employs a special set of two-letter prefixes:

The first letter indicates the data type. The second character is the letter v, for variable.

In the syntax description for GetDir, the first parameter can be a string variable or constant, but the second parameter must be a variable.
GetDir ( szPath, svDir );

Functions that require variable parameters generally return data to the caller in those parameters.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

Chapter 2: Setup Scripts Hungarian Notation

Prefix Table
Because Hungarian notation makes it easy to recognize a variables type, it is strongly recommended that you use Hungarian notation when you create variable names in your own scripts. The table below describes each of the prefixes used in InstallShield.
Table 2-1: Prefix Table Prefix b bv Data Type Boolean (BOOL) Boolean (BOOL) When Used in Function Syntax Boolean constant, literal, or variable. Boolean variable only. Constants and literals not allowed. Character constant, literal, or variable. Constant or literal. Variables not allowed. Handle variable. Integer constant, literal, or variable. Long integer constant, literal, or variable. Long integer variable only. Constants and literals not allowed. List variable. Number constant, literal, or variable. Number variable only. Constants and literals not allowed. Pointer variable. Not used. Short integer constant, literal, or variable. String constant, literal, or variable. String variable only. Constants and literals not allowed. Not used.

c const h i l lv

Character (CHAR) Constant Handle (HWND) Integer (INT) Long integer (LONG) Long integer (LONG)

list n nv

List (LIST) Number (NUMBER) Number (NUMBER)

p pstruct s sz sv

Pointer (POINTER) Pointer to a defined structure type Short integer (SHORT) String (STRING) String (STRING)

struct

Defined structure type

10

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 2: Setup Scripts Escape Sequences

Escape Sequences
An escape sequence is a set of characters used to insert into a string certain special characterssuch as tabs, carriage returns and quotation marks. Escape sequences in InstallScript are very much like those in C. They begin with a backslash, called an escape character, and the backslash is followed by one or more characters that have special meaning. If the backslash is followed by characters other than those used in an escape sequence, the backslash is ignored.

Inserting a Newline Character Into a String

A commonly used escape sequence is \n, which inserts a newline character into a string. The string This is line one, This is line two. is displayed or printed on a single line. However, the string This is line one,\nThis is line two. is displayed or printed as shown below:
This is line one, This is line two.

The \n escape sequence works only in multiline static text fields. For example, you can insert \n in the szQuestion argument of AskText to manually format the string. You can also use \n with MessageBox and SprintfBox. The newline escape sequence is case sensitive; that is, \N does not insert a newline character. The percent sign (%) also has a special function in InstallScript; it is used as the first character of a format specifier, which is a sequence of characters that is used with functions such as Sprintf and SprintBox to indicate how the value stored in a variable should be displayed on screen.

Supported Escape Sequences

The following table lists the escape sequences that are supported by InstallScript:
Table 2-2: Supported Escape Sequences Escape Sequence \n \' \" \r \t \ooo \\ Performs the Following Action Inserts a carriage return and a line feed. Inserts a single quotation mark in the string. Inserts a double quotation mark in the string. Inserts a carriage return only. Does not insert a line feed. Inserts a tab character. Indicates an ASCII characternot an integerin octal notation. Inserts a backslash.

Specifying a Universal Naming Convention Path

To specify a Universal Naming Convention (UNC) path in an InstallScript string, you must use two backslash escape sequences (that is, four backslashes\\\\), to create the double backslash at the start of the path. For example, the path \\MyServer\Public\Readme.txt must be specified as follows:
"\\\\MyServer\\Public\\Readme.txt"
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 11

Chapter 2: Setup Scripts Embedding Quotation Marks

Embedding Quotation Marks

You can insert double quotation marks as part of a string literal using one of two methods. If you begin the string literal with double quotation marks, you must use the \" escape character to embed double quotation marks. You can, however, begin the literal with a single quotation mark and then type the double quotation mark:
//These two statements will both yield embedded double quotation marks szQuote1 = "Who said, \"Quitters never win\"?"; szQuote2 = 'The same guy who said, "I quit. "';

To embed a single quotation mark, either use the \' escape sequence or open the string literal with double quotation marks:
//These two statements will both yield embedded single quotation marks szQuote1 = 'Who said, \'Nice guys finish last\'?'; szQuote2 = "The same guy who said, 'I win.'";

Note: Your setup scripts must use the standard quotation marks (" and ') found to the right of the semicolon (;) key on the standard U.S. keyboard. Do not use open or closed typographer's quotation marks (), such as this help files uses outside of example scripts.

Format Specifiers
Format specifiers are used with the functions Sprintf and SprintfBox to control the display of values that are stored in variables. A format specifier begins with a percent sign (%) and is followed by at least one or two characters. Format specifications follow the format shown below:
% [-] [#] [0] [width] [.precision] type

Each field of a format specification is a single character or number that represents a particular format option. The type field, for example, determines whether Sprintf or SprintfBox interprets the associated argument as a character, a string, or a number. The initial character % and the type field are both required. Items enclosed within brackets are optional. The simplest format specification contains only the percent sign and a type character, for example %s. In the following example, the value of svString is displayed in a message box. The format specifier %s, which is assigned to svFormat, indicates to SprintfBox that the value of svString should be displayed as a string of characters.
STRING szTitle, szFormat, szString; szTitle = "Demonstrate format specifiers"; szFormat = "%s"; szString = "This is a string."; SprintfBox(INFORMATION, szTitle, szFormat, szString);

The value assigned to svFormat may contain literal characters (including escape sequences) that are to be displayed along with the value of a variable. In the following example, an identifying label is displayed to the left of a number variable: nNumber = 100;.
STRING szTitle, szFormat; NUMBER nNumber;

12

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 2: Setup Scripts Format Specifiers

szTitle = "Demonstrate format specifiers"; szFormat = "nNumber = %d."; nNumber = 100; SprintfBox(INFORMATION, szTitle, szFormat, nNumber);

Note: To print a percent sign, you must insert two percent signs in the string assigned to svFormat. Assuming that the number to be printed is 100, the following format specification string displays nNumber = 100%:
svFormat = "nNumber = %d%%."

Table 2-3: Format Specifier Fields Field Meaning If you include a hyphen after the percent character, the output value is aligned left and padded on the right to the width of the field with blanks or zeros. If you omit this field, the output value is right aligned and padded on the left. Use this symbol to prefix hexadecimal values with 0x (lowercase) or 0X (uppercase). Pads the output value with zeros to fill the field width. If you omit this field, the output value is padded with blanks. Enter the minimum number of characters you want to place in this field. Type the width field as a non-negative integer. When you enter a width specification, the value is never truncated. If the number of characters in the output value is greater than the width specified, or if you omit the width field, every character of the value is displayed, subject to the value of the precision field. Enter the minimum number of digits you want in this field. If the number of digits in the argument is less than the precision value you enter, the output value on the left is padded with zeros. When the number of digits exceeds the precision value, the value is not truncated. If you enter a precision value of zero or omit it entirely, or if the period (.) appears without a number following it, the precision is set to 1. For strings, convert the maximum number of characters. Format the corresponding argument as a character, a string, or a number. When two format specifier letter combinations are shown, you can use one or the other, but not both at the same time. This is a required field. In this field you must enter one of the following characters:

# 0

width

precision

type

cFormats a single character of type CHAR. The Sprintf function ignores a character with a numeric value of zero. d, iFormats a single integer of type INT or of type NUMBER. ld, liFormats a single signed decimal integer of type LONG. lx, lXFormats a single unsigned hexadecimal integer of type LONG. sFormats a string (type STRING).

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

13

Chapter 2: Setup Scripts Reserved Words

Each format specifier has a matching variable. The variables are listed from left to right after the string, with the first variable matching the first format specifier in the string, the second variable matching the second format specifier in the string, and so on. At run time, InstallShield inserts each variable's contents into the string at the location of its matching format specifier.

Reserved Words
Reserved words and characters have special meaning in InstallScript and cannot be used except for their intended purposes. InstallScript has the following classes of reserved words:

Functions Language Keywords Predefined Constants System Variables Event Handlers Predefined Script Variables

14

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

3
Language Keywords
Language keywords are words InstallScript uses as commands in the script. Language keywords are interpreted by the InstallScript compiler to perform some action, or are considered part of a statement. You cannot use these following keywords for any reason other than their predefined purpose (for example, these keywords cannot be used as variable names).

abort
When the script encounters an abort statement, the setup terminates. The abort statement is also encountered in the InstallShield default exit handler (OnCanceling) when the end user exits the installation before it has completed by pressing the Esc key or the Cancel button of an InstallScript dialog.

Note: The abort statement exits the installation and runs the uninstaller in silent mode to clean up the aborted installation. The exit statement aborts the installation, but does not remove anything from the target system. The abort statement does not call a rollback if initiated after the OnFirstUIAfter event.

BOOL
Boolean data: either TRUE (1) or FALSE (0). Variables of this type should not be used to store any other values. Like C++, InstallScript evaluates non-zero values as TRUE; only the value of zero is evaluated as FALSE. Normally, the value of 1 is used to indicate TRUE.

cdecl
Project: This information applies to InstallScript projects.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 15

Chapter 3: Language Keywords exit

The cdecl keyword is used when declaring an external DLL function that uses the cdecl calling convention. For example:
prototype cdecl POINTER Msvcrt.memcpy( byref string, pointer, long );

In previous versions of InstallShield Professional, the setup engine always used the stdcall convention but would sometimes overlook an inconsistent DLL convention. Most Windows API functions use the stdcall (WINAPI) calling convention. Consult Microsoft documentation for more information about calling conventions.

exit
When the setup program encounters an exit statement in the script it is executing, the setup process terminates. Each setup script containsat mostone exit statement. If your script includes conditional expressions that might cause it to exit before the installation has completed, you should use abort instead of exit.

export
The prototype of any function that is called directly by the setup engine must be marked as export. An example is shown below:
export prototype NewFeature1_Installing();

external
The keyword external is reserved and may not be used.

for...endfor
The for statement is designed to execute one or more statements a fixed number of times. It begins with the keyword for and an expression that specifies the number of times statements within the for structure are to be executed. The for structure ends with the keyword endfor.

Note: The for statement itself is not terminated with a semicolon; however, a semicolon is required after the endfor statement.

Using for...endfor
In the following example, the function MessageBox is called 10 times. On the first pass, iCount is set to 1. Because 1 is in the specified range (1 to 10), the message box is displayed. Then iCount is incremented by 1 and the for statement is resolved again. This time, iCount = 2 (still in the specified range) and the message box is displayed a second time. When iCount is incremented after the tenth pass, its value becomes 11. Because this value is outside the specified range, the for statement ends.
16 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 3: Language Keywords goto

for iCount = 1 to 10 MessageBox ("This appears ten times.", INFORMATION); endfor;

Adjusting the Increment

The default increment in a for statement is one (1), but you can use the keyword step to adjust the increment. In the example below, step increases the value of iCount by 10 each time loop is executed. On the first pass, iCount = 10; on the second pass, iCount = 20; on the third pass, iCount = 30, and so on.
for iCount = 10 to 100 step 10 MessageBox ("This appears ten times.", INFORMATION); endfor; Counting Down from a Higher Number to a Lower Number

You can count down from a higher number to a lower number by using the keyword downto in place of the keyword to. In the following example, a message box is displayed three times. The first time the loop is entered, j is set to 20. Because downto specifies that the controlling variable be decremented and step 5 sets a decrement of 5 per loop, j is equal to 15 the second time the loop is entered. The third time, j is equal to 10.
for j = 20 downto 10 step 5 MessageBox ("This appears three times.", INFORMATION); endfor;

Note: You cannot define a label within a for statement.

goto
The goto keyword is used to branch directly to the statement immediately following a specified label. In the following code fragment, the goto statement causes execution to continue with the AskText statement.
Name: AskText("Company name:", "", szSrc); if (szSrc = "") then MessageBox("Please enter the company name.", SEVERE); goto Name; endif;

A goto statement in the main program must specify a label that has been declared in the main program. A goto statement in a function must specify a label that has been declared in that function.

Note: You cannot use a goto statement within a try...catch...endcatch statement.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

17

Chapter 3: Language Keywords if

if
Use an if statement when you want your script to choose between two or more options. An if statement consists of the keyword if, a condition to be evaluated, the keyword then, and the keyword endif followed by a semicolon, as shown below:
if (condition) then // statements to be executed if condition is true endif;

The condition can be one of the following:

A Boolean or integer constant, variable or literal. An expression that produces a Boolean or integer result. A function that returns an integer result.

The parentheses around the condition are optional, but highly recommended for readability.

Tip: Many InstallScript functions return a negative value when they fail. When using the result of InstallScript functions as the condition in an if statement, test for failure by using a statement like the one below:
if (FunctionA (ParameterOne) < 0) then // Statements to handle the failure else // Statements when the function succeeds endif;

InstallScript provides the following if statement structures:

if Structure with goto if-then Structure if-then-else Structure Nested if-then-else Structure elseif Structure

if Structure with goto

InstallScript supports a special form of the if statement that can be used only with goto statements:
if condition goto labelname;

This special structure is has the following features:

The condition must be followed by a goto statement. The keyword then is not used. The keyword endif is not used.

In the following example, the user will be prompted to enter a company name as long as szSrc is a null string ().
18 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 3: Language Keywords if

Name: AskText("Company name:", "", szSrc); if (szSrc = "") goto Name;

if-then Structure
The simplest if statement evaluates an expression and performs a specified action if the expression is true. If the expression is not true, InstallShield ignores the entire statement. For example:
if (szStringA = "exit") then AskYesNo ( "Are you sure you want to exit?", NO ); endif;

If szStringA equals "exit", the test evaluates to TRUE (1) and the AskYesNo function is called. If szStringA contains anything else, the result is FALSE (0) and the entire statement is ignored. The sample code below compares the values of the variable nDialog and the constant DLG_ERR. If they are equivalent, InstallShield executes the MessageBox function:
if (nDialog = DLG_ERR) then MessageBox ("Error has occurred", WARNING); endif;

Tip: You may find that your if statement is easier to read when you place the expression to be evaluated in parentheses, but the parentheses are optional in InstallScript.

if-then-else Structure
An if statement can also specify one or more statements to be executed if the condition is false. This option is indicated with the keyword else, as shown below:
if (condition) then // statements to be executed if condition is true else // statements to be executed if condition is false endif;

In the example below, if szStringA equals "exit," the test evaluates to TRUE (1), and the AskYesNo function is called. If szStringA is not equal to "exit," the result is FALSE (0), and the MessageBox function is called following the else statement.
if szStringA = "exit" then AskYesNo ("Are you sure you want to exit?", NO ); else MessageBox ("Please wait... ", INFORMATION ); endif;

Nested if-then-else Structure

You can create nested if statements, in which one if statement is embedded in another:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

19

Chapter 3: Language Keywords if

if (first condition) then if (second condition) then // statements to be executed if // second conditions are true else // statements to be executed if // second condition is false endif; else if (third condition) then // statements to be executed if // false and third condition is else // statements to be executed if // false and third condition is endif; endif;

first and

first is true but

first condition is true first condition is false

In the following example, if the value of szStringA is "exit", AskYesNo is called. If the value of szStringA is "exit", the program displays a message box. if szStringA is not equal to either of those values, the execution proceeds to the label UserErrorHandler.
if szStringA = "exit" then AskYesNo ("Are you sure you want to exit?", NO); else if szStringA = "continue" then MessageBox ("Please wait...", INFORMATION); else UserErrorHandler; endif; endif;

elseif Structure
InstallScript provides the elseif statement to create if structures in which the else branch of one if statement leads to another if statement:
if (first condition) then // statements to be executed if first condition // is true elseif (second condition) then // statements to be executed if first condition // is false and second condition is true elseif (third condition) then // statements to be executed if first and second // conditions are false and third condition is // true endif;

In the following example, if szStringA equals exit, AskYesNo is called. If szStringA is not equal to exit, the program continues to the elseif statement to test if szStringA is equal to continue. If szStringA is equal to continue, the result is TRUE and MessageBox is called. If szStringA is not equal to continue, the program moves to the next elseif, and so on.
if szStringA = "exit" then AskYesNo ("Are you sure you want to exit?", NO ); elseif szStringA = "continue" then MessageBox ("Please wait...", INFORMATION ); elseif szStringA = "reboot" then

20

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 3: Language Keywords method

goto StartHere; endif;

Note: You cannot define a label within an if statement.

method
Project: This information applies to InstallScript projects.

The method keyword is used to declare a method in an object script with the following syntax:
method <return variable type> <method name> ( <argument variable type(s)> );

For example:
method STRING MyMethod ( STRING, NUMBER );

If you add a method to the object project by using the Add New Method dialog box, a method declaration is automatically placed in the object script.

property()
Project: This information applies to InstallScript projects.

The property() keyword is used to declare a property and its get and/or put procedures in an object script with the following syntax:
Table 3-1: Property() Keyword Declarations Access Read only Write only Read/write Declaration
property(get) <return variable type> <property name> ( <argument variable type(s)> ); property(put) <return variable type> <property name> ( <argument variable type(s)> ); property(get,put) <return variable type> <property name> ( <argument variable type(s)> );

For example:
property(get,put) STRING MyProperty ( NUMBER );

If you add a property to the object project by using the Add New Property dialog box, a property declaration is automatically placed in the object script.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

21

Chapter 3: Language Keywords prototype

prototype
The prototype keyword tells the InstallScript compiler that the line of code contains a function definition. To learn how to use this keyword, see Declaring Functions.

repeat...until
The repeat statement is analogous to the do...while loop in the C language. It also is very similar to the InstallScript while statement. There are two main differences between repeat and while in InstallScript:

The repeat statement must loop at least once. A while statement might not loop at all. A while statement terminates when the expression evaluates as false. A repeat statement terminates when the expression evaluates as true.

Task

To create a repeat loop: 1. 2. 3. 4. 5.

Set the variable you will be using in the conditional test as you would for a while loop. Type repeat on its own line with no punctuation. Build the operation(s) that you want repeated. Add the operation that changes the test variable (for example, nCount = nCount + 1, or nCount = SomeVariable). End the loop with an until statement containing the conditional test in parentheses.

The following example demonstrates repeat loop syntax:

nCount = 1; repeat MessageBox("Count is less than 5", INFORMATION); nCount = nCount + 1; until (nCount = 5);

Note: You cannot define a label within the repeat statement.

return
You can use the return statement to return a value from a user-defined function (if the function prototype does not specify a return type of void). When a return statement is encountered, program flow returns to the point at which the function was called. When used to return from a call to a user-defined function, the return statement can return a specified value to the caller.

22

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 3: Language Keywords set

The return value of most built-in functions will be either 0 (zero), indicating the success of the function, or a value less than zero (< 0), indicating failure. You can assign a number to the return value by using a return statement above the end statement in the function block, as shown below:
return -1; end;

This attribute allows you to return the value of a local variable to the caller, even though the local variable itself is destroyed:
function MyFunction(ParamOne, ParamTwo) NUMBER nNumber; begin nNumber = (ParamOne + ParamTwo); // . . . return nNumber; end;

set
The set keyword must precede the assignment of an OBJECT variable to a reference returned by the CreateObject function. For example:
function OnBegin( ) OBJECT oMSI; begin // create the object set oMSI = CreateObject("WindowsInstaller.Installer"); // use the object (display MSI version on user's system) MessageBox("Your MSI version is: " + oMSI.Version, INFORMATION); // free the object set oMSI = NOTHING; end;

Note: You can use the keywords trycatchendcatch for more control over exception handling for COM objects.

stdcall
Project: This information applies to InstallScript projects.The stdcall keyword is used when declaring an external DLL function that uses the stdcall calling convention. For example:
prototype stdcall POINTER kernel32.lstrcpy( byref string, byref string);

If no calling convention is specified, stdcall is assumed. Most Windows API functions use the stdcall (WINAPI) calling convention. Consult Microsoft documentation for more information about calling conventions.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

23

Chapter 3: Language Keywords switch...endswitch

switch...endswitch
The switch statement is similar to the elseif Structure statement. Use the switch statement to execute one of several different sections of code, depending on the value of an expression. The switch statement evaluates the expression and then branches to the case statement whose constant value matches the result of the expression. If no match is found among the case statements, control passes to a default statement, if one has been specified.

Creating Switch Statements

Task

To create a switch statement: 1.

Type the keyword switch, followed by the expression to be evaluated. The expressionwhich can be a constant, variable, arithmetic expression, logical expression, or function resultmust be enclosed within parentheses. Do not punctuate this line. For each option, type the keyword case and one or more constants followed by a colon. If more than one constant is specified, delimit them with commas. Note that only constants can be specified here. Specifying a variable name, string identifier, function result, or other type of expression after the keyword case results in an error. For each case, follow the colon with the statement or statements to be executed for that option. Terminate each statement with a semicolon. After all case statements have been specified, use the keyword default, followed by a colon (:), to control the program when the expression does not match any of the stated cases. Close the block with the keyword endswitch, followed by a semicolon (;).

2.

3. 4. 5.

Example Script
The following script segment displays the current video resolution of the computer on which it is executed:
STRING szMsg, svResult; NUMBER nvResult; GetSystemInfo (VIDEO, nvResult, svResult); switch (nvResult) case IS_UNKNOWN: szMsg = "The user's video is unknown."; case IS_EGA: szMsg = "EGA resolution."; case IS_VGA: szMsg = "VGA resolution."; case IS_SVGA: szMsg = "Super VGA (800 x 600) resolution."; case IS_XVGA: szMsg = "XVGA (1024 x 768) resolution."; case IS_UVGA: szMsg = "Greater than 1024 x 768 resolution."; default: szMsg = "Error"; endswitch;

24

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 3: Language Keywords try, catch, and endcatch

MessageBox (szMsg, INFORMATION);

Note: Only one case block is executed each time a switch statement is executed. After InstallShield executes a case block, it executes the next statement after the endswitch. A switch block can be quite useful inside of a while loop. By using the case statements as flags, you can create a loop with optional exit points.

try, catch, and endcatch

The keywords try, catch, and endcatch are used for exception handling. For more information on exception handling, see Exception Handling.

Note: You cannot use a goto statement within a try...catch...endcatch statement. In addition, you cannot define a label within a try...catch...endcatch statement.

void
Void is not a true data type, in the sense that a variable cannot be declared as type void. Void is only used in function prototypes to indicate that the function does not return a value, as in the following:
prototype void Subroutine(int); function void Subroutine(int); begin // perform operations, but // do not return a value end;

while...endwhile
Use the while statement when you want to execute one or more statements repeatedly, as long as a particular condition is true. If the condition is not true when the statement is first executed, the loop is not performed.

Task

To create a while loop: 1. 2. 3. 4. 5.

Set the variable you are using as the condition to an initial state. Type the keyword while, followed by the conditional test in parentheses. Do not punctuate this line. Build the operation(s) that you want repeated. Add the operation that changes the test variable (for example, nCount = nCount + 1, or nCount = SomeVariable). End the loop by typing endwhile, followed by a semicolon.
ISP-1800-RG00 25

InstallShield 2012 InstallScript Reference Guide

Chapter 3: Language Keywords while...endwhile

In the following example, the message box is displayed four times.

nCount = 1; while (nCount < 5) MessageBox ("This is still true.", INFORMATION); nCount = nCount + 1; endwhile;

Because nCount is assigned an initial value of 1, the while statement evaluates TRUE the first time it is executed; the message box is displayed and nCount is incremented by 1. After the fourth pass through the loop, nCount is equal to 5; the while statement evaluates FALSE and the program continues executing with the statement after endwhile.

Note: You cannot define a label within a while block. You can, however, nest while statements in InstallScript. You must end each while block with endwhile.

Nested while Example

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/* This script illustrates a nested while loop. * It searches for the specified type of files and * shows the number of lines in each file. */ #define SOURCEDIR "c:\\example"; // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_Nested while(HWND); function ExFn_Nested while(hMSI) LIST listID; STRING svTarget, svResult, filename, svLine, szPath, szFileName; NUMBER nResult, nOp,nFileHandle,count; begin count = 0; nOp = RESET; svTarget = SOURCEDIR; listID = ListCreate (STRINGLIST); while FindAllFiles (svTarget, "*.txt", svResult, nOp) = 0; // To get the name of the file in the fully specified path StrGetTokens(listID,svResult,"\\"); ListCurrentString(listID,filename); // Set the file mode to normal. OpenFileMode(FILE_MODE_NORMAL); szFileName = filename;
26 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 3: Language Keywords Flow Control

szPath

= svTarget;

// The following opens the file for editing. OpenFile(nFileHandle, szPath, szFileName); /*------------------------------------------------------------------*\ * * The following retrieves each line of text from the open file and increments * a count to find the number of lines. * \*------------------------------------------------------------------*/ while (GetLine (nFileHandle, svLine) = 0) count = count + 1; endwhile; SprintfBox(INFORMATION,"The Total lines in the file", "The No. of lines in the file %s is %d",filename,count); count = 0; // The following closes the file CloseFile(nFileHandle); // Continue searching files where last file was left off nOp = CONTINUE; if (FindAllFiles (svTarget, "*.txt", svResult, nOp) < 0) then abort; endif; endwhile; end;

Flow Control
Like most programming languages, InstallScript processes statements within a function block sequentially, starting with the first statement and ending with the last. The linear flow of execution within a function block can be controlled with conditional statements that perform branching and iteration. Branching is most commonly performed with an if statement that directs execution down one path or another. Iteration is performed with loop statements that execute one or more statements repeatedly, either for a set number of times or as long as a specified condition is met. To control the flow of execution within scripts, InstallShield provides the following keywords:

abort exit for...endfor goto if...then...else...endif

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

27

Chapter 3: Language Keywords Flow Control

repeat...until return switch...endswitch while...endwhile

28

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

4
Predefined Constants
A predefined constant is an identifier reserved by InstallScript to represent a specific literal value. InstallScript uses predefined constants to represent certain data values that are passed to and returned by built-in functions. By using these predefined constants rather than literal values, you can improve the readability of your setup scripts. You cannot change the value InstallShield assigns to a predefined constant. However, you can determine the value of a predefined constant by calling SprintfBox, as shown in the example below, which displays the value of the predefined constant FEATURE_FIELD_SELECTED:
SprintfBox (INFORMATION, "", "%d", FEATURE_FIELD_SELECTED);

Although you can use a literal value in place of a predefined constant, it is strongly recommended that you use predefined constants wherever indicated for a function. Following is a list of the predefined constants used by InstallScript.

AFTER
AFTER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
EzBatchAddString EzBatchAddPath ConfigAdd ConfigMove ListAddItem ListAddString PathAdd
ISP-1800-RG00 29

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ALLCONTENTS

PathMove BatchAdd PathMove BatchMoveEx FileInsertLine EzConfigAddDriver EzConfigAddString

ALLCONTENTS
ALLCONTENTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DeleteDir

ALLCONTROLS
ALLCONTROLS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CtrlSetFont

APPEND
APPEND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileInsertLine

ASKDESTPATH
ASKDESTPATH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

30

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ASKOPTIONS

Used With
AskDestPath

ASKOPTIONS
ASKOPTIONS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
AskOptions PlaceWindow

ASKPATH
ASKPATH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
AskPath PlaceWindow

ASKTEXT
ASKTEXT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
AskText PlaceWindow

BACK
BACK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
AskDestPath AskOptions

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

31

Chapter 4: Predefined Constants BACKBUTTON

AskPath AskText FeatureDialog SdAskDestPath SdAskOptions SdAskOptionsList SdBitmap SdDisplayTopics SdFeatureDialog SdFeatureDialog2 SdFeatureDialogAdv SdFeatureMult SdLicense SdOptionsButtons SdRegisterUser SdRegisterUserEx SdSelectFolder SdShowAnyDialog SdShowDlgEdit1 SdShowDlgEdit2 SdShowDlgEdit3 SdShowFileMods SdShowInfoList SdStartCopy SdWelcome SelectFolder Welcome

BACKBUTTON
BACKBUTTON is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
32 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants BACKGROUND

Used With
Disable Enable Is

BACKGROUND
BACKGROUND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceWindow SetColor Enable SizeWindow Disable

BACKGROUNDCAPTION
BACKGROUNDCAPTION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetTitle

BASEMEMORY
Project: This information applies to InstallScript projects.

BASEMEMORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

33

Chapter 4: Predefined Constants BEFORE

BEFORE
BEFORE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PathMove FileInsertLine EzBatchAddPath EzBatchAddString BatchAdd BatchMoveEx EzConfigAddDriver EzConfigAddString ConfigAdd ConfigMove ListAddItem ListAddString PathAdd

BIF_BROWSEFORCOMPUTER
Project: This information applies to InstallScript projects.

BIF_BROWSEFORCOMPUTER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDirEx

BIF_BROWSEFORPRINTER
Project: This information applies to InstallScript projects.

34

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants BIF_DONTGOBELOWDOMAIN

BIF_BROWSEFORPRINTER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDirEx

BIF_DONTGOBELOWDOMAIN
Project: This information applies to InstallScript projects.

BIF_DONTGOBELOWDOMAIN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDirEx

BIF_EDITBOX
Project: This information applies to InstallScript projects.

BIF_EDITBOX is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDirEx

BIF_RETURNFSANCESTORS
Project: This information applies to InstallScript projects.

BIF_RETURNFSANCESTORS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDirEx

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

35

Chapter 4: Predefined Constants BIF_RETURNONLYFSDIRS

BIF_RETURNONLYFSDIRS
Project: This information applies to InstallScript projects.

BIF_RETURNONLYFSDIRS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDirEx

BIF_STATUSTEXT
Project: This information applies to InstallScript projects.

BIF_STATUSTEXT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDirEx

BILLBOARD
BILLBOARD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Disable PlaceWindow

BITMAPICON
BITMAPICON is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceBitmap

36

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants BK_BLUE

BK_BLUE
BK_BLUE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_GREEN
BK_GREEN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_MAGENTA
BK_MAGENTA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_ORANGE
BK_ORANGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_PINK
BK_PINK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

37

Chapter 4: Predefined Constants BK_RED

BK_RED
BK_RED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_SMOOTH
BK_SMOOTH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_SOLIDBLACK
BK_SOLIDBLACK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_SOLIDBLUE
BK_SOLIDBLUE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_SOLIDGREEN
BK_SOLIDGREEN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

38

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants BK_SOLIDMAGENTA

BK_SOLIDMAGENTA
BK_SOLIDMAGENTA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_SOLIDORANGE
BK_SOLIDORANGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_SOLIDPINK
BK_SOLIDPINK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_SOLIDRED
BK_SOLIDRED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_SOLIDWHITE
BK_SOLIDWHITE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

39

Chapter 4: Predefined Constants BK_SOLIDYELLOW

BK_SOLIDYELLOW
BK_SOLIDYELLOW is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BK_YELLOW
BK_YELLOW is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

BLACK
BLACK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetTitle

BLUE
BLUE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor SetTitle

BOOTUPDRIVE
BOOTUPDRIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
40

GetSystemInfo
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants BUTTON_CHECKED

BUTTON_CHECKED
BUTTON_CHECKED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CtrlSetState CtrlGetState

BUTTON_UNCHECKED
BUTTON_UNCHECKED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CtrlSetState CtrlGetState

BYTES
BYTES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ConvertSizeToUnits StrConvertSizeUnit

CANCEL
CANCEL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDir

CANCELBUTTON
CANCELBUTTON is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

41

Chapter 4: Predefined Constants CDROM

Used With
Disable Enable Is

CDROM
CDROM is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

CDROM_DRIVE
CDROM_DRIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetValidDrivesList

CENTERED
CENTERED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceWindow PlaceBitmap

CHECKBOX
CHECKBOX is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DialogSetInfo

42

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants CHECKBOX95

CHECKBOX95
CHECKBOX95 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DialogSetInfo

CHECKLINE
CHECKLINE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DialogSetInfo

CHECKMARK
CHECKMARK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DialogSetInfo

CLEAR_FILE_ATTR
CLEAR_FILE_ATTR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
XCopyFile

COLORS
COLORS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

43

Chapter 4: Predefined Constants COMMAND

COMMAND
COMMAND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
BatchMoveEx ConfigFind EzBatchAddString BatchAdd BatchDeleteEx

COMMON
COMMON is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ProgDefGroupType

COMPACT
COMPACT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetupType SdSetupType

COMPARE_DATE
COMPARE_DATE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileCompare

44

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants COMPARE_MD5_SIGNATURE

COMPARE_MD5_SIGNATURE
COMPARE_MD5_SIGNATURE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileCompare

COMPARE_SIZE
COMPARE_SIZE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileCompare

COMPARE_VERSION
COMPARE_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileCompare

COMP_NORMAL
COMP_NORMAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
XCopyFile

COMP_UPDATE_DATE
COMP_UPDATE_DATE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
XCopyFile

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

45

Chapter 4: Predefined Constants COMP_UPDATE_SAME

COMP_UPDATE_SAME
COMP_UPDATE_SAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
XCopyFile

COMP_UPDATE_VERSION
COMP_UPDATE_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
XCopyFile

CONTINUE
CONTINUE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileGrep BatchFind FindFile ConfigFind PathFind

COPY_ERR_CREATEDIR
COPY_ERR_CREATEDIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CopyFile XCopyFile

46

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants COPY_ERR_MEMORY

COPY_ERR_MEMORY
COPY_ERR_MEMORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CopyFile XCopyFile

COPY_ERR_NODISKSPACE
COPY_ERR_NODISKSPACE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CopyFile XCopyFile

COPY_ERR_OPENINPUT
COPY_ERR_OPENINPUT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CopyFile XCopyFile

COPY_ERR_OPENOUTPUT
COPY_ERR_OPENOUTPUT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CopyFile XCopyFile

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

47

Chapter 4: Predefined Constants COPY_ERR_TARGETREADONLY

COPY_ERR_TARGETREADONLY
COPY_ERR_TARGETREADONLY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CopyFile XCopyFile

CPU
CPU is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

CURRENTROOTKEY
CURRENTROOTKEY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VarRestore VarSave

CUSTOM
CUSTOM is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetupType SdSetupType

DATA_COMPONENT
DATA_COMPONENT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
48 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DATA_LIST

Used With
SilentReadData SilentWriteData

DATA_LIST
DATA_LIST is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SilentWriteData

DATA_NUMBER
DATA_NUMBER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SilentReadData SilentWriteData

DATA_STRING
DATA_STRING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SilentReadData SilentWriteData

DATE
DATE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

49

Chapter 4: Predefined Constants DEFAULT

DEFAULT
DEFAULT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
switch...endswitch

DEFWINDOWMODE
DEFWINDOWMODE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Enable

DELETE
Project: This information applies to InstallScript projects.

DELETE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions SERVICE_IS_PARAMS

DELETE_EOF
DELETE_EOF is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileDeleteLine

50

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DIALOGCACHE

DIALOGCACHE
DIALOGCACHE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Disable Enable

DIFXAPI_ERROR
DIFXAPI_ERROR is a predefined constant that is used to represent a value that is available for use with one or more event handlers. You cannot change the value of a predefined constant.

Used With
OnDIFxLogCallback

DIFXAPI_INFO
DIFXAPI_INFO is a predefined constant that is used to represent a value that is available for use with one or more event handlers. You cannot change the value of a predefined constant.

Used With
OnDIFxLogCallback

DIFXAPI_SUCCESS
DIFXAPI_SUCCESS is a predefined constant that is used to represent a value that is available for use with one or more event handlers. You cannot change the value of a predefined constant.

Used With
OnDIFxLogCallback

DIFXAPI_WARNING
DIFXAPI_WARNING is a predefined constant that is used to represent a value that is available for use with one or more event handlers. You cannot change the value of a predefined constant.

Used With
OnDIFxLogCallback
ISP-1800-RG00 51

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DIRECTORY

DIRECTORY
DIRECTORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ParsePath

DIR_WRITEABLE
DIR_WRITEABLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

DISABLE_ALLUSERBTN
Project: This information applies to InstallScript projects.

DISABLE_ALLUSERBTN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant. The DISABLE_ALLUSERBTN constant indicates that the all-users option should be disabled (or hidden) in cases where it would normally be enabled. The default value of this variable is FALSE. Note that the all-users option is always hidden if the installation is being run without administrator or poweruser privileges, regardless of the value of this variable.

Used With
SdCustomerInformation SdCustomerInformationEx

DISABLE_PERUSERBTN
DISABLE_PERUSERBTN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant. The DISABLE_PERUSERBTN constant indicates that the per-user option should be disabled (or hidden if HIDE_DISABLED_BTNS is TRUE) in cases where it would normally be enabled. The default value of this variable is FALSE. Note that the per-user option is always hidden on Windows 9x platforms, regardless of the value of this variable.

52

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DISK

Used With
SdCustomerInformation SdCustomerInformationEx

DISK
DISK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ParsePath

DISK1FEATURE
Project: This information applies to InstallScript projects.

DISK1FEATURE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant. DISK1FEATURE specifies the feature with the files needed for maintenance setups and uninstallation. (Note that this feature is automatically placed in your .cab files by the media builder and is not displayed in the IDE.)

Used With
FeatureSelectItem FeatureIsItemSelected

DISK_INFO_QUERY_ALL
DISK_INFO_QUERY_ALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DISK_INFO_QUERY_BYTES_PER_CLUSTER
DISK_INFO_QUERY_BYTES_PER_CLUSTER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 53

Chapter 4: Predefined Constants DISK_INFO_QUERY_DISK_FREE_SPACE

Used With
GetDiskInfo

DISK_INFO_QUERY_DISK_FREE_SPACE
DISK_INFO_QUERY_DISK_FREE_SPACE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DISK_INFO_QUERY_DISK_TOTAL_SPACE
DISK_INFO_QUERY_DISK_TOTAL_SPACE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DISK_INFO_QUERY_DRIVE_TYPE
DISK_INFO_QUERY_DRIVE_TYPE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DISK_TOTALSPACE
DISK_TOTALSPACE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

54

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DISK_TOTALSPACE_EX

DISK_TOTALSPACE_EX
DISK_TOTALSPACE_EX is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

DLG_ASK_OPTIONS
DLG_ASK_OPTIONS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDialogTitle

DLG_ASK_PATH
DLG_ASK_PATH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDialogTitle

DLG_ASK_TEXT
DLG_ASK_TEXT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDialogTitle

DLG_ASK_YESNO
DLG_ASK_YESNO is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDialogTitle

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

55

Chapter 4: Predefined Constants DLG_CENTERED

DLG_CENTERED
DLG_CENTERED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DefineDialog

DLG_CLOSE
DLG_CLOSE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
WaitOnDialog

DLG_DIR_DIRECTORY
DLG_DIR_DIRECTORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CtrlDir

DLG_DIR_DRIVE
DLG_DIR_DRIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CtrlDir

DLG_DIR_FILE
DLG_DIR_FILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CtrlDir

56

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DLG_ENTER_DISK

DLG_ENTER_DISK
DLG_ENTER_DISK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDialogTitle

DLG_ERR
DLG_ERR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
WaitOnDialog EzDefineDialog ReleaseDialog CtrlGetState DefineDialog

DLG_ERR_ALREADY_EXISTS
DLG_ERR_ALREADY_EXISTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DefineDialog EzDefineDialog

DLG_ERR_ENDDLG
DLG_ERR_ENDDLG is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ReleaseDialog

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

57

Chapter 4: Predefined Constants DLG_INFO_ALTIMAGE

DLG_INFO_ALTIMAGE
DLG_INFO_ALTIMAGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DialogSetInfo

DLG_INFO_ALTIMAGE_REVERT_IMAGE
DLG_INFO_ALTIMAGE_REVERT_IMAGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DialogSetInfo

DLG_INFO_ALTIMAGE_VERIFY_BMP
DLG_INFO_ALTIMAGE_VERIFY_BMP is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DialogSetInfo

DLG_INFO_CHECKSELECTION
DLG_INFO_CHECKSELECTION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DialogSetInfo

DLG_INFO_KUNITS
DLG_INFO_KUNITS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

58

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DLG_INFO_USEDECIMAL

Used With
DialogSetInfo

DLG_INFO_USEDECIMAL
DLG_INFO_USEDECIMAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DialogSetInfo

DLG_INIT
DLG_INIT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
WaitOnDialog

DLG_MSG_ALL
DLG_MSG_ALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DefineDialog

DLG_MSG_INFORMATION
DLG_MSG_INFORMATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDialogTitle

DLG_MSG_SEVERE
DLG_MSG_SEVERE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

59

Chapter 4: Predefined Constants DLG_MSG_STANDARD

Used With
SetDialogTitle

DLG_MSG_STANDARD
DLG_MSG_STANDARD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DefineDialog

DLG_MSG_WARNING
DLG_MSG_WARNING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDialogTitle

DLG_STATUS
DLG_STATUS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDialogTitle

DLG_USER_CAPTION
DLG_USER_CAPTION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDialogTitle

DOINSTALL_OPTION_NOHIDEPROGRESS
DOINSTALL_OPTION_NOHIDEPROGRESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
60 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DOINSTALL_OPTION_NOHIDESPLASH

Used With
DoInstall

DOINSTALL_OPTION_NOHIDESPLASH
DOINSTALL_OPTION_NOHIDESPLASH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall

DOINSTALL_OPTION_NOLANGSWITCH
DOINSTALL_OPTION_NOLANGSWITCH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall

DOINSTALL_OPTION_NOSETBATCHINSTALL
DOINSTALL_OPTION_NOSETBATCHINSTALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall

DOTNETFRAMEWORKINSTALLED
DOTNETFRAMEWORKINSTALLED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

61

Chapter 4: Predefined Constants DOTNETSERVICEPACKINSTALLED

DOTNETSERVICEPACKINSTALLED
DOTNETSERVICEPACKINSTALLED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

DRIVE
DRIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

DRIVE_CDROM
DRIVE_CDROM is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DRIVE_FIXED
DRIVE_FIXED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DRIVE_NO_ROOT_DIR
DRIVE_NO_ROOT_DIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

62

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DRIVE_RAMDISK

DRIVE_RAMDISK
DRIVE_RAMDISK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DRIVE_REMOTE
DRIVE_REMOTE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DRIVE_REMOVABLE
DRIVE_REMOVABLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DRIVE_UNKNOWN
DRIVE_UNKNOWN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetDiskInfo

DRIVER_PACKAGE_DELETE_FILES
DRIVER_PACKAGE_DELETE_FILES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DIFxDriverPackageUninstall

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

63

Chapter 4: Predefined Constants DRIVER_PACKAGE_FORCE

DRIVER_PACKAGE_FORCE
DRIVER_PACKAGE_FORCE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DIFxDriverPackageInstall DIFxDriverPackagePreinstall DIFxDriverPackageUninstall

DRIVER_PACKAGE_LEGACY_MODE
DRIVER_PACKAGE_LEGACY_MODE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DIFxDriverPackageInstall DIFxDriverPackagePreinstall

DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT
DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DIFxDriverPackageInstall DIFxDriverPackagePreinstall

DRIVER_PACKAGE_REPAIR
DRIVER_PACKAGE_REPAIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
64

DIFxDriverPackageInstall DIFxDriverPackagePreinstall DIFxDriverPackageUninstall

ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants DRIVER_PACKAGE_SILENT

DRIVER_PACKAGE_SILENT
DRIVER_PACKAGE_SILENT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DIFxDriverPackageInstall DIFxDriverPackagePreinstall

EDITBOX_CHANGE
EDITBOX_CHANGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CtrlGetSubCommand

EFF_BOXSTRIPE
EFF_BOXSTRIPE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDisplayEffect

EFF_FADE
EFF_FADE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDisplayEffect

EFF_HORZREVEAL
EFF_HORZREVEAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDisplayEffect
ISP-1800-RG00 65

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants EFF_HORZSTRIPE

EFF_HORZSTRIPE
EFF_HORZSTRIPE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDisplayEffect

EFF_NONE
EFF_NONE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDisplayEffect

EFF_REVEAL
EFF_REVEAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDisplayEffect

EFF_VERTSTRIPE
EFF_VERTSTRIPE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetDisplayEffect

END_OF_FILE
END_OF_FILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileGrep

66

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants END_OF_LIST

END_OF_LIST
END_OF_LIST is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ListCurrentItem ListCurrentString ListGetFirstItem ListSetIndex ListDeleteItem ListDeleteString ListFindItem ListFindString ListCurrentString ListGetNextItem ListGetNextString ListSetCurrentItem ListSetCurrentString

ENTERDISK
ENTERDISK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
EnterDisk PlaceWindow

EQUALS
EQUALS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerCompare

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

67

Chapter 4: Predefined Constants ERROR_ACCESS_DENIED

FileCompare

ERROR_ACCESS_DENIED
Project: This information applies to InstallScript projects.

ERROR_ACCESS_DENIED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_CIRCULAR_DEPENDENCY
Project: This information applies to InstallScript projects.

ERROR_CIRCULAR_DEPENDENCY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_DATABASE_DOES_NOT_EXIST
Project: This information applies to InstallScript projects.

ERROR_DATABASE_DOES_NOT_EXIST is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

68

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ERROR_DEPENDENT_SERVICES_RUNNING

ERROR_DEPENDENT_SERVICES_RUNNING
Project: This information applies to InstallScript projects.

ERROR_DEPENDENT_SERVICES_RUNNING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_DUP_NAME
Project: This information applies to InstallScript projects.

ERROR_DUP_NAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_FILE_NOT_FOUND
Project: This information applies to InstallScript projects.

ERROR_FILE_NOT_FOUND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_INVALID_HANDLE
Project: This information applies to InstallScript projects.

ERROR_INVALID_HANDLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

69

Chapter 4: Predefined Constants ERROR_INVALID_PARAMETER

Used With
GetExtendedErrInfo

ERROR_INVALID_PARAMETER
Project: This information applies to InstallScript projects.

ERROR_INVALID_PARAMETER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_INVALID_SERVICE_ACCOUNT
Project: This information applies to InstallScript projects.

ERROR_INVALID_SERVICE_ACCOUNT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_INVALID_SERVICE_CONTROL
Project: This information applies to InstallScript projects.

ERROR_INVALID_SERVICE_CONTROL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

70

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ERROR_PATH_NOT_FOUND

ERROR_PATH_NOT_FOUND
Project: This information applies to InstallScript projects.

ERROR_PATH_NOT_FOUND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_ALREADY_RUNNING
Project: This information applies to InstallScript projects.

ERROR_SERVICE_ALREADY_RUNNING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_CANNOT_ACCEPT_CTRL
Project: This information applies to InstallScript projects.

ERROR_SERVICE_CANNOT_ACCEPT_CTRL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_DATABASE_LOCKED
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

71

Chapter 4: Predefined Constants ERROR_SERVICE_DEPENDENCY_DELETED

ERROR_SERVICE_DATABASE_LOCKED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_DEPENDENCY_DELETED
Project: This information applies to InstallScript projects.

ERROR_SERVICE_DEPENDENCY_DELETED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_DEPENDENCY_FAIL
Project: This information applies to InstallScript projects.

ERROR_SERVICE_DEPENDENCY_FAIL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_DISABLED
Project: This information applies to InstallScript projects.

ERROR_SERVICE_DISABLED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

72

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ERROR_SERVICE_DOES_NOT_EXIST

ERROR_SERVICE_DOES_NOT_EXIST
Project: This information applies to InstallScript projects.

ERROR_SERVICE_DOES_NOT_EXIST is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_EXISTS
Project: This information applies to InstallScript projects.

ERROR_SERVICE_EXISTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_LOGON_FAILED
Project: This information applies to InstallScript projects.

ERROR_SERVICE_LOGON_FAILED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_NOT_ACTIVE
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

73

Chapter 4: Predefined Constants ERROR_SERVICE_NO_THREAD

ERROR_SERVICE_NOT_ACTIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_NO_THREAD
Project: This information applies to InstallScript projects.

ERROR_SERVICE_NO_THREAD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_SERVICE_REQUEST_TIMEOUT
Project: This information applies to InstallScript projects.

ERROR_SERVICE_REQUEST_TIMEOUT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

ERROR_TIMEOUT
Project: This information applies to InstallScript projects.

ERROR_TIMEOUT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetExtendedErrInfo

74

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ERR_ABORT

ERR_ABORT
ERR_ABORT is a predefined constant that is used to represent a value that is passed to or returned by one or more event handlers. You cannot change the value of a predefined constant.

Used With
OnNextDisk

ERR_BOX_BADPATH
ERR_BOX_BADPATH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetErrorMsg SetErrorTitle

ERR_BOX_BADTAGFILE
ERR_BOX_BADTAGFILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetErrorMsg SetErrorTitle

ERR_BOX_DISKID
ERR_BOX_DISKID is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetErrorTitle SetErrorMsg

ERR_BOX_DRIVEOPEN
ERR_BOX_DRIVEOPEN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

75

Chapter 4: Predefined Constants ERR_IGNORE

Used With
SetErrorTitle SetErrorMsg

ERR_IGNORE
ERR_IGNORE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or event handlers. You cannot change the value of a predefined constant.

Used With
SdExceptions

ERR_NO
ERR_NO is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or event handlers. You cannot change the value of a predefined constant.

Used With
SdExceptions

ERR_PERFORM_AFTER_REBOOT
ERR_PERFORM_AFTER_REBOOT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or event handlers. You cannot change the value of a predefined constant.

Used With
SdExceptions

ERR_RETRY
ERR_RETRY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or event handlers. You cannot change the value of a predefined constant.

Used With
OnNextDisk SdExceptions

76

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ERR_YES

ERR_YES
ERR_YES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or event handlers. You cannot change the value of a predefined constant.

Used With
SdExceptions

EXCLUDE_SUBDIR
EXCLUDE_SUBDIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
XCopyFile FindAllDirs

EXCLUSIVE
EXCLUSIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SdAskOptionsList AskOptions SdAskOptions

EXISTS
EXISTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ExistsDir ExistsDisk

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

77

Chapter 4: Predefined Constants EXIT

EXIT
EXIT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Do HandlerEx

EXTENDEDMEMORY
EXTENDEDMEMORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

EXTENSION_ONLY
EXTENSION_ONLY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ParsePath

FALSE
FALSE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
78

AskOptions CtrlSetMultCurSel DialogSetInfo FeatureAddItem FeatureGetData FeatureIsItemSelected FeatureSelectItem

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FEATURE_FIELD_CDROM_FOLDER

FeatureTotalSize LongPathToQuote SdDiskSpace2 SelectDir SdShowMsg SQLDatabaseBrowse SQLRTConnect SQLRTConnect2 SQLRTConnectDB SQLRTGetDatabases SQLRTGetServers SQLRTGetServers2 SQLRTPutConnectionAuthentication SQLRTTestConnection SQLRTTestConnection2 SQLServerSelectLogin SQLServerSelectLogin2

FEATURE_FIELD_CDROM_FOLDER
Project: This information applies to InstallScript projects.

FEATURE_FIELD_CDROM_FOLDER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_DESCRIPTION
Project: This information applies to the following project types:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

79

Chapter 4: Predefined Constants FEATURE_FIELD_DISPLAYNAME

InstallScript InstallScript MSI

FEATURE_FIELD_DESCRIPTION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData FeatureSetData

FEATURE_FIELD_DISPLAYNAME
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_FIELD_DISPLAYNAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData FeatureSetData

FEATURE_FIELD_ENCRYPT
Project: This information applies to InstallScript projects.

FEATURE_FIELD_ENCRYPT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData FeatureSetData

80

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FEATURE_FIELD_FILENEED

FEATURE_FIELD_FILENEED
Project: This information applies to InstallScript projects.

FEATURE_FIELD_FILENEED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_FLAGS
Project: This information applies to InstallScript projects.

FEATURE_FIELD_FLAGS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_FTPLOCATION
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_FIELD_FTPLOCATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_GUID
Project: This information applies to InstallScript projects.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 81

Chapter 4: Predefined Constants FEATURE_FIELD_HANDLER_ONINSTALLED

FEATURE_FIELD_GUID is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_HANDLER_ONINSTALLED
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_FIELD_HANDLER_ONINSTALLED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_HANDLER_ONINSTALLING
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_FIELD_HANDLER_ONINSTALLING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_HANDLER_ONUNINSTALLED
Project: This information applies to the following project types:

82

InstallScript InstallScript MSI

ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FEATURE_FIELD_HANDLER_ONUNINSTALLING

FEATURE_FIELD_HANDLER_ONUNINSTALLED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_HANDLER_ONUNINSTALLING
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_FIELD_HANDLER_ONUNINSTALLING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_HTTPLOCATION
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_FIELD_HTTPLOCATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_IMAGE
Project: This information applies to the following project types:

InstallScript

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

83

Chapter 4: Predefined Constants FEATURE_FIELD_MISC

InstallScript MSI

FEATURE_FIELD_IMAGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureSetData

FEATURE_FIELD_MISC
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_FIELD_MISC is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData FeatureSetData

FEATURE_FIELD_PASSWORD
Project: This information applies to InstallScript projects.

FEATURE_FIELD_PASSWORD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_FIELD_SELECTED
Project: This information applies to the following project types:

InstallScript InstallScript MSI

84

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FEATURE_FIELD_SIZE

FEATURE_FIELD_SELECTED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData FeatureSetData

FEATURE_FIELD_SIZE
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_FIELD_SIZE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData FeatureSetData

FEATURE_FIELD_STATUS
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_FIELD_STATUS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData FeatureSetData

FEATURE_FIELD_VISIBLE
Project: This information applies to the following project types:
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 85

Chapter 4: Predefined Constants FEATURE_INFO_ATTRIBUTE

InstallScript InstallScript MSI

FEATURE_FIELD_VISIBLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData FeatureSetData

FEATURE_INFO_ATTRIBUTE
Project: This information applies to InstallScript MSI projects.

FEATURE_INFO_ATTRIBUTE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_COMPONENT_FLAGS
Project: This information applies to InstallScript projects.

FEATURE_INFO_COMPONENT_FLAGS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_COMPSIZE_HIGH
Project: This information applies to the following project types:

InstallScript InstallScript MSI

86

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FEATURE_INFO_COMPSIZE_LOW

FEATURE_INFO_COMPSIZE_HIGH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_COMPSIZE_LOW
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_INFO_COMPSIZE_LOW is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_DATE
Project: This information applies to InstallScript projects.

FEATURE_INFO_DATE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_DATE_EX
Project: This information applies to InstallScript projects.

FEATURE_INFO_DATE_EX is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

87

Chapter 4: Predefined Constants FEATURE_INFO_DESTINATION

Used With
FeatureFileInfo

FEATURE_INFO_DESTINATION
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_INFO_DESTINATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_FTPLOCATION
Project: This information applies to InstallScript projects.

FEATURE_INFO_FTPLOCATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_HTTPLOCATION
Project: This information applies to InstallScript projects.

FEATURE_INFO_HTTPLOCATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

88

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FEATURE_INFO_LANGUAGE

FEATURE_INFO_LANGUAGE
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_INFO_LANGUAGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_MD5_SIGNATURE
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_INFO_MD5_SIGNATURE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_MISC
Project: This information applies to InstallScript projects.

FEATURE_INFO_MISC is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

89

Chapter 4: Predefined Constants FEATURE_INFO_ORIGSIZE_HIGH

FEATURE_INFO_ORIGSIZE_HIGH
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_INFO_ORIGSIZE_HIGH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_ORIGSIZE_LOW
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_INFO_ORIGSIZE_LOW is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_OS
Project: This information applies to InstallScript projects.

FEATURE_INFO_OS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

90

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FEATURE_INFO_OVERWRITE

FEATURE_INFO_OVERWRITE
Project: This information applies to InstallScript projects.

FEATURE_INFO_OVERWRITE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_PLATFORM_SUITE
Project: This information applies to InstallScript projects.

FEATURE_INFO_PLATFORM_SUITE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_TIME
Project: This information applies to InstallScript projects.

FEATURE_INFO_TIME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_VERSIONLS
Project: This information applies to the following project types:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

91

Chapter 4: Predefined Constants FEATURE_INFO_VERSIONMS

InstallScript InstallScript MSI

FEATURE_INFO_VERSIONLS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_VERSIONMS
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_INFO_VERSIONMS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

FEATURE_INFO_VERSIONSTR
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FEATURE_INFO_VERSIONSTR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
FeatureFileInfo

92

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FEATURE_OPCOST_UNINSTALL_FILE

FEATURE_OPCOST_UNINSTALL_FILE
FEATURE_OPCOST_UNINSTALL_FILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureAddUninstallCost FeatureSpendUninstallCost

FEATURE_OPCOST_UNINSTALL_REGORINI
FEATURE_OPCOST_UNINSTALL_REGORINI is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureAddUninstallCost FeatureSpendUninstallCost

FEATURE_OPCOST_UNINSTALL_UNREGFILE
FEATURE_OPCOST_UNINSTALL_UNREGFILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureAddUninstallCost FeatureSpendUninstallCost

FEATURE_VALUE_CRITICAL
Project: This information applies to InstallScript projects.

FEATURE_VALUE_CRITICAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

93

Chapter 4: Predefined Constants FEATURE_VALUE_HIGHLYRECOMMENDED

FEATURE_VALUE_HIGHLYRECOMMENDED
Project: This information applies to InstallScript projects.

FEATURE_VALUE_HIGHLYRECOMMENDED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

FEATURE_VALUE_STANDARD
Project: This information applies to InstallScript projects.

FEATURE_VALUE_STANDARD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureGetData

File Attributes
Project: This information applies to InstallScript projects. Table 4-1: File Attributes Attribute FILE_ATTR_NORMAL FILE_ATTR_ARCHIVED FILE_ATTR_DIRECTORY FILE_ATTR_HIDDEN FILE_ATTR_READONLY FILE_ATTR_SYSTEM Description The file is a normal file. The file is archived. The file is a directory. The file is hidden. The file is read-only. The file is a system file.

94

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FILE_ADD_FILE

FILE_ADD_FILE
FILE_ADD_FILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_ADD_SUBDIRECTORY
FILE_ADD_SUBDIRECTORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_ALL_ACCESS
FILE_ALL_ACCESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_APPEND_DATA
FILE_APPEND_DATA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_ATTR_ARCHIVED
FILE_ATTR_ARCHIVED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetFileInfo

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

95

Chapter 4: Predefined Constants FILE_ATTR_HIDDEN

FILE_ATTR_HIDDEN
FILE_ATTR_HIDDEN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetFileInfo

FILE_ATTR_NORMAL
FILE_ATTR_NORMAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetFileInfo

FILE_ATTR_READONLY
FILE_ATTR_READONLY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetFileInfo

FILE_ATTR_SYSTEM
FILE_ATTR_SYSTEM is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetFileInfo

FILE_ATTRIBUTE
FILE_ATTRIBUTE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
96

GetFileInfo SetFileInfo
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FILE_BIN_CUR

FILE_BIN_CUR
FILE_BIN_CUR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SeekBytes

FILE_BIN_END
FILE_BIN_END is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SeekBytes

FILE_BIN_START
FILE_BIN_START is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SeekBytes

FILE_DATE
FILE_DATE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFileInfo SetFileInfo

FILE_DELETE_CHILD
FILE_DELETE_CHILD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions
ISP-1800-RG00 97

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FILE_EXECUTE

FILE_EXECUTE
FILE_EXECUTE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_EXISTS
FILE_EXISTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

FILE_INSTALLED
FILE_INSTALLED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerSearchAndUpdateFile

FILE_IS_LOCKED
FILE_IS_LOCKED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerUpdateFile VerSearchAndUpdateFile

FILE_LINE_LENGTH
FILE_LINE_LENGTH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
98

FileInsertLine
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FILE_LIST_DIRECTORY

FileGrep

FILE_LIST_DIRECTORY
FILE_LIST_DIRECTORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_LOCKED
FILE_LOCKED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

FILE_MD5_SIGNATURE
FILE_MD5_SIGNATURE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFileInfo

FILE_MODE_APPEND
FILE_MODE_APPEND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
OpenFileMode CreateFile

FILE_MODE_APPEND_UNICODE
FILE_MODE_APPEND_UNICODE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 99

Chapter 4: Predefined Constants FILE_MODE_BINARY

Used With
OpenFileMode

FILE_MODE_BINARY
FILE_MODE_BINARY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
WriteBytes OpenFileMode

FILE_MODE_BINARYREADONLY
FILE_MODE_BINARYREADONLY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
OpenFileMode

FILE_MODE_NORMAL
FILE_MODE_NORMAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
OpenFileMode

FILE_NOT_FOUND
FILE_NOT_FOUND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
100

VerGetFileVersion FileGrep FileInsertLine FileCompare

ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FILE_NO_VERSION

FileDeleteLine VerFindFileVersion

FILE_NO_VERSION
FILE_NO_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerGetFileVersion VerSearchAndUpdateFile VerFindFileVersion VerUpdateFile

FILE_RD_ONLY
FILE_RD_ONLY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerUpdateFile FileDeleteLine FileInsertLine VerSearchAndUpdateFile

FILE_READ_ATTRIBUTES
FILE_READ_ATTRIBUTES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_READ_DATA
FILE_READ_DATA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

101

Chapter 4: Predefined Constants FILE_READ_EA

Used With
SetObjectPermissions

FILE_READ_EA
FILE_LIST_DIRECTORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_SHARED_COUNT
Project: This information applies to InstallScript projects.

FILE_SHARED_COUNT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFileInfo

FILE_SIZE
FILE_SIZE (same as FILE_SIZE_LOW) is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFileInfo

FILE_SIZE_HIGH
FILE_SIZE_HIGH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFileInfo

102

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FILE_SIZE_LOW

FILE_SIZE_LOW
FILE_SIZE_LOW is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFileInfo

FILE_SRC_OLD
FILE_SRC_OLD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerSearchAndUpdateFile VerUpdateFile

FILE_TIME
FILE_TIME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFileInfo SetFileInfo

FILE_TRAVERSE
FILE_TRAVERSE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_WRITE_ATTRIBUTES
FILE_WRITE_ATTRIBUTES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

103

Chapter 4: Predefined Constants FILE_WRITE_DATA

Used With
SetObjectPermissions

FILE_WRITE_DATA
FILE_WRITE_DATA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_WRITE_EA
FILE_WRITE_EA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

FILE_WRITEABLE
Project: This information applies to the following project types:

Installscript InstallScript Object

FILE_WRITEABLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

FILENAME
FILENAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ParsePath

104

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants FILENAME_ONLY

FILENAME_ONLY
FILENAME_ONLY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ParsePath

FIXED_DRIVE
FIXED_DRIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetValidDrivesList

FONT_AVAILABLE
FONT_AVAILABLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

FULL
FULL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PathAdd PathFind PathMove PathDelete

FULLSCREEN
FULLSCREEN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

105

Chapter 4: Predefined Constants FULLSCREENSIZE

Used With
PlaceBitmap

FULLSCREENSIZE
FULLSCREENSIZE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceBitmap

FULLWINDOWMODE
FULLWINDOWMODE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Enable

FUNCTION_EXPORTED
Project: This information applies to InstallScript projects.

FUNCTION_EXPORTED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

GBYTES
GBYTES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ConvertSizeToUnits StrConvertSizeUnit

106

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants GENERIC_ALL

GENERIC_ALL
GENERIC_ALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

GENERIC_EXECUTE
GENERIC_EXECUTE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

GENERIC_READ
GENERIC_READ is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

GENERIC_WRITE
GENERIC_WRITE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

GREATER_THAN
GREATER_THAN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileCompare VerCompare
ISP-1800-RG00 107

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants GREEN

GREEN
GREEN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor SetTitle

GTFIS_OPTION_DELETE_TEMP_FILE
GTFIS_OPTION_DELETE_TEMP_FILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetTempFileNameIS

GTFIS_OPTION_DONT_CREATE_DIR
GTFIS_OPTION_DONT_CREATE_DIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetTempFileNameIS

GTFIS_OPTION_DONT_RESOLVE_TEXTSUBS
GTFIS_OPTION_DONT_RESOLVE_TEXTSUBS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetTempFileNameIS

GTFIS_OPTION_NONE
GTFIS_OPTION_NONE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

108

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants HELP

Used With
GetTempFileNameIS

HELP
Project: This information applies to the following project types:

InstallScript InstallScript MSI

HELP is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Do HandlerEx

HIDE_DISABLED_BTNS
HIDE_DISABLED_BTNS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant. The HIDE_DISABLED_BTNS constant indicates that the per-user and all-users options should be hidden instead of being disabled. The default value of this variable is TRUE. Note that when this variable is set to TRUE, both options are hidden if either option is determined to be disabled.

Used With
SdCustomerInformation SdCustomerInformationEx

HKEY_CLASSES_ROOT
HKEY_CLASSES_ROOT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBSetDefaultRoot RegDBSetKeyValueEx RegDBDeleteKey

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

109

Chapter 4: Predefined Constants HKEY_CURRENT_USER

RegDBDeleteValue RegDBGetKeyValueEx RegDBKeyExist RegDBCreateKeyEx

HKEY_CURRENT_USER
HKEY_CURRENT_USER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBSetDefaultRoot

HKEY_LOCAL_MACHINE
HKEY_LOCAL_MACHINE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Note: Windows NT 4.0 does not allow the creation of a key directly under HKEY_LOCAL_MACHINE.

Used With
RegDBConnectRegistry InstallationInfo RegDBSetDefaultRoot

HKEY_USERS
HKEY_USERS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Note: Windows NT 4.0 does not allow the creation of a key directly under HKEY_USERS.

Used With
RegDBSetDefaultRoot RegDBConnectRegistry

110

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants HKEY_USER_SELECTABLE

HKEY_USER_SELECTABLE
Project: This information applies to InstallScript projects.

HKEY_USER_SELECTABLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBSetDefaultRoot

HOURGLASS
HOURGLASS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Disable Enable

HWND_DESKTOP
HWND_DESKTOP is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetWindowHandle

HWND_INSTALL
HWND_INSTALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetWindowHandle

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

111

Chapter 4: Predefined Constants IDCANCEL

IDCANCEL
Project: This information applies to InstallScript projects.

IDCANCEL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDir SelectDirEx

IDOK
Project: This information applies to InstallScript projects.

IDOK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectDir SelectDirEx

IDS_IFX_ERROR_INVALID_MEDIA_PASSWORD
Project: This information applies to InstallScript projects.

IDS_IFX_ERROR_INVALID_MEDIA_PASSWORD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SdLoadString

112

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants IFX_ONNEXTDISK_PACKAGE_CAPTION

IFX_ONNEXTDISK_PACKAGE_CAPTION
Project: This information applies to InstallScript projects.

IFX_ONNEXTDISK_PACKAGE_CAPTION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SdLoadString

IFX_ONNEXTDISK_PACKAGE_MSG
Project: This information applies to InstallScript projects.

IFX_ONNEXTDISK_PACKAGE_MSG is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SdLoadString

INCLUDE_SUBDIR
INCLUDE_SUBDIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FindAllDirs XCopyFile

INDVFILESTATUS
INDVFILESTATUS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Disable

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

113

Chapter 4: Predefined Constants INFORMATION

SetStatusWindow Enable

INFORMATION
INFORMATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MessageBox SprintfBox

IS_PERMISSIONS_OPTION_ALLOW_ACCESS
IS_PERMISSIONS_OPTION_ALLOW_ACCESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

IS_PERMISSIONS_OPTION_DENY_ACCESS
IS_PERMISSIONS_OPTION_DENY_ACCESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

IS_PERMISSIONS_OPTION_NO_APPLYDOWN
IS_PERMISSIONS_OPTION_NO_APPLYDOWN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

114

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants IS_PERMISSIONS_TYPE_FILE

IS_PERMISSIONS_TYPE_FILE
IS_PERMISSIONS_TYPE_FILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

IS_PERMISSIONS_TYPE_FOLDER
IS_PERMISSIONS_TYPE_FOLDER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

IS_PERMISSIONS_TYPE_REGISTRY
IS_PERMISSIONS_TYPE_REGISTRY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

ISDIFX_OPTION_DONT_ASSOCIATE
ISDIFX_OPTION_DONT_ASSOCIATE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DIFxDriverPackageInstall DIFxDriverPackageUninstall

ISDIFX_OPTION_DONT_RESOLVE_TEXTSUBS
ISDIFX_OPTION_DONT_RESOVE_TEXTSUBS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 115

Chapter 4: Predefined Constants ISDIFX_OPTION_LOG_IN_DRIVER_PACKAGE_PATH

Used With
DIFxDriverPackageGetPath DIFxDriverPackageInstall DIFxDriverPackagePreinstall DIFxDriverPackageUninstall

ISDIFX_OPTION_LOG_IN_DRIVER_PACKAGE_PATH
ISDIFX_OPTION_LOG_IN_DRIVER_PACKAGE_PATH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DIFxDriverPackageInstall DIFxDriverPackagePreinstall

ISDIFX_OPTION_NO_REPAIR
ISDIFX_OPTION_NO_REPAIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DIFxDriverPackageInstall DIFxDriverPackagePreinstall

ISERR_GEN_FAILURE
Project: This information applies to InstallScript projects.

ISERR_GEN_FAILURE is a predefined constant that is used to represent the value that is returned by built-in functions when they fail and more specific information on the cause of the failure is not available. You cannot change the value of a predefined constant.

ISERR_SUCCESS
Project: This information applies to the following project types:
116 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_AFRIKAANS

InstallScript InstallScript MSI

ISERR_SUCCESS is a predefined constant that is used to represent the value that is returned by built-in functions when they are successful. You cannot change the value of a predefined constant.

ISLANG_AFRIKAANS
ISLANG_AFRIKAANS is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_AFRIKAANS_STANDARD
ISLANG_AFRIKAANS_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ALBANIAN
ISLANG_ALBANIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ALBANIAN_STANDARD
ISLANG_ALBANIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ALL
ISLANG_ALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterLanguage

ISLANG_ARABIC
ISLANG_ARABIC is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

117

Chapter 4: Predefined Constants ISLANG_ARABIC_ALGERIA

ISLANG_ARABIC_ALGERIA
ISLANG_ARABIC_ALGERIA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_BAHRAIN
ISLANG_ARABIC_BAHRAIN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_EGYPT
ISLANG_ARABIC_EGYPT is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_IRAQ
ISLANG_ARABIC_IRAQ is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_JORDAN
ISLANG_ARABIC_JORDAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_KUWAIT
ISLANG_ARABIC_KUWAIT is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_LEBANON
ISLANG_ARABIC_LEBANON is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_LIBYA
ISLANG_ARABIC_LIBYA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

118

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_ARABIC_MOROCCO

ISLANG_ARABIC_MOROCCO
ISLANG_ARABIC_MOROCCO is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_OMAN
ISLANG_ARABIC_OMAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_QATAR
ISLANG_ARABIC_QATAR is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_SAUDIARABIA
ISLANG_ARABIC_SAUDIARABIA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_SYRIA
ISLANG_ARABIC_SYRIA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_TUNISIA
ISLANG_ARABIC_TUNISIA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_UAE
ISLANG_ARABIC_UAE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ARABIC_YEMEN
ISLANG_ARABIC_YEMEN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

119

Chapter 4: Predefined Constants ISLANG_BASQUE

ISLANG_BASQUE
ISLANG_BASQUE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_BASQUE_STANDARD
ISLANG_BASQUE_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_BELARUSIAN
ISLANG_BELARUSIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_BELARUSIAN_STANDARD
ISLANG_BELARUSIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_BULGARIAN
ISLANG_BULGARIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_BULGARIAN_STANDARD
ISLANG_BULGARIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_CATALAN
ISLANG_CATALAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_CATALAN_STANDARD
ISLANG_CATALAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

120

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_CHINESE

ISLANG_CHINESE
ISLANG_CHINESE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_CHINESE_HONGKONG
ISLANG_CHINESE_HONGKONG is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_CHINESE_PRC
ISLANG_CHINESE_PRC is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_CHINESE_SINGAPORE
ISLANG_CHINESE_SINGAPORE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_CHINESE_TAIWAN
ISLANG_CHINESE_TAIWAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_CROATIAN
ISLANG_CROATIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_CROATIAN_STANDARD
ISLANG_CROATIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_CZECH
ISLANG_CZECH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

121

Chapter 4: Predefined Constants ISLANG_CZECH_STANDARD

ISLANG_CZECH_STANDARD
ISLANG_CZECH_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_DANISH
ISLANG_DANISH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_DANISH_STANDARD
ISLANG_DANISH_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_DUTCH
ISLANG_DUTCH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_DUTCH_BELGIAN
ISLANG_DUTCH_BELGIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_DUTCH_STANDARD
ISLANG_DUTCH_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH
ISLANG_ENGLISH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH_AUSTRALIAN
ISLANG_ENGLISH_AUSTRALIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

122

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_ENGLISH_BELIZE

ISLANG_ENGLISH_BELIZE
ISLANG_ENGLISH_BELIZE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH_CANADIAN
ISLANG_ENGLISH_CANADIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH_CARIBBEAN
ISLANG_ENGLISH_CARIBBEAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH_IRELAND
ISLANG_ENGLISH_IRELAND is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH_JAMAICA
ISLANG_ENGLISH_JAMAICA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH_NEWZEALAND
ISLANG_ENGLISH_NEWZEALAND is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH_SOUTHAFRICA
ISLANG_ENGLISH_SOUTHAFRICA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH_TRINIDAD
ISLANG_ENGLISH_TRINIDAD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

123

Chapter 4: Predefined Constants ISLANG_ENGLISH_UNITEDKINGDOM

ISLANG_ENGLISH_UNITEDKINGDOM
ISLANG_ENGLISH_UNITEDKINGDOM is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ENGLISH_UNITEDSTATES
ISLANG_ENGLISH_UNITEDSTATES is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ESTONIAN
ISLANG_ESTONIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ESTONIAN_STANDARD
ISLANG_ESTONIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FAEROESE
ISLANG_FAEROESE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FAEROESE_STANDARD
ISLANG_FAEROESE_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FARSI
ISLANG_FARSI is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FARSI_STANDARD
ISLANG_FARSI_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

124

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_FINNISH

ISLANG_FINNISH
ISLANG_FINNISH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FINNISH_STANDARD
ISLANG_FINNISH_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FRENCH
ISLANG_FRENCH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FRENCH_BELGIAN
ISLANG_FRENCH_BELGIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FRENCH_CANADIAN
ISLANG_FRENCH_CANADIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FRENCH_LUXEMBOURG
ISLANG_FRENCH_LUXEMBOURG is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FRENCH_STANDARD
ISLANG_FRENCH_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_FRENCH_SWISS
ISLANG_FRENCH_SWISS is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

125

Chapter 4: Predefined Constants ISLANG_GERMAN

ISLANG_GERMAN
ISLANG_GERMAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_GERMAN_AUSTRIAN
ISLANG_GERMAN_AUSTRIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_GERMAN_LIECHTENSTEIN
ISLANG_GERMAN_LIECHTENSTEIN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_GERMAN_LUXEMBOURG
ISLANG_GERMAN_LUXEMBOURG is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_GERMAN_STANDARD
ISLANG_GERMAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_GERMAN_SWISS
ISLANG_GERMAN_SWISS is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_GREEK
ISLANG_GREEK is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_GREEK_STANDARD
ISLANG_GREEK_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

126

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_HEBREW

ISLANG_HEBREW
ISLANG_HEBREW is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_HEBREW_STANDARD
ISLANG_HEBREW_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_HUNGARIAN
ISLANG_HUNGARIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_HUNGARIAN_STANDARD
ISLANG_HUNGARIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ICELANDIC
ISLANG_ICELANDIC is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ICELANDIC_STANDARD
ISLANG_ICELANDIC_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_INDONESIAN
ISLANG_INDONESIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_INDONESIAN_STANDARD
ISLANG_INDONESIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

127

Chapter 4: Predefined Constants ISLANG_ITALIAN

ISLANG_ITALIAN
ISLANG_ITALIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ITALIAN_STANDARD
ISLANG_ITALIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ITALIAN_SWISS
ISLANG_ITALIAN_SWISS is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_JAPANESE
ISLANG_JAPANESE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_JAPANESE_STANDARD
ISLANG_JAPANESE_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_KOREAN
ISLANG_KOREAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_KOREAN_JOHAB
ISLANG_KOREAN_JOHAB is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_KOREAN_STANDARD
ISLANG_KOREAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

128

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_LATVIAN

ISLANG_LATVIAN
ISLANG_LATVIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_LATVIAN_STANDARD
ISLANG_LATVIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_LITHUANIAN
ISLANG_LITHUANIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_LITHUANIAN_STANDARD
ISLANG_LITHUANIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_NORWEGIAN
ISLANG_NORWEGIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_NORWEGIAN_BOKMAL
ISLANG_NORWEGIAN_BOKMAL is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_NORWEGIAN_NYNORSK
ISLANG_NORWEGIAN_NYNORSK is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_POLISH
ISLANG_POLISH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

129

Chapter 4: Predefined Constants ISLANG_POLISH_STANDARD

ISLANG_POLISH_STANDARD
ISLANG_POLISH_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_PORTUGUESE
ISLANG_PORTUGUESE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_PORTUGUESE_BRAZILIAN
ISLANG_PORTUGUESE_BRAZILIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_PORTUGUESE_STANDARD
ISLANG_PORTUGUESE_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ROMANIAN
ISLANG_ROMANIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_ROMANIAN_STANDARD
ISLANG_ROMANIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_RUSSIAN
ISLANG_RUSSIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_RUSSIAN_STANDARD
ISLANG_RUSSIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

130

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_SERBIAN_CYRILLIC

ISLANG_SERBIAN_CYRILLIC
ISLANG_SERBIAN_CYRILLIC is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SERBIAN_LATIN
ISLANG_SERBIAN_LATIN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SLOVAK
ISLANG_SLOVAK is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SLOVAK_STANDARD
ISLANG_SLOVAK_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SLOVENIAN
ISLANG_SLOVENIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SLOVENIAN_STANDARD
ISLANG_SLOVENIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH
ISLANG_SPANISH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_ARGENTINA
ISLANG_SPANISH_ARGENTINA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

131

Chapter 4: Predefined Constants ISLANG_SPANISH_BOLIVIA

ISLANG_SPANISH_BOLIVIA
ISLANG_SPANISH_BOLIVIA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_CHILE
ISLANG_SPANISH_CHILE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_COLOMBIA
ISLANG_SPANISH_COLOMBIA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_COSTARICA
ISLANG_SPANISH_COSTARICA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_DOMINICANREPUBLIC
ISLANG_SPANISH_DOMINICANREPUBLIC is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_ECUADOR
ISLANG_SPANISH_ECUADOR is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_ELSALVADOR
ISLANG_SPANISH_ELSALVADOR is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_GUATEMALA
ISLANG_SPANISH_GUATEMALA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

132

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_SPANISH_HONDURAS

ISLANG_SPANISH_HONDURAS
ISLANG_SPANISH_HONDURAS is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_MEXICAN
ISLANG_SPANISH_MEXICAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_MODERNSORT
ISLANG_SPANISH_MODERNSORT is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_NICARAGUA
ISLANG_SPANISH_NICARAGUA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_PANAMA
ISLANG_SPANISH_PANAMA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_PARAGUAY
ISLANG_SPANISH_PARAGUAY is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_PERU
ISLANG_SPANISH_PERU is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_PUERTORICO
ISLANG_SPANISH_PUERTORICO is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

133

Chapter 4: Predefined Constants ISLANG_SPANISH_TRADITIONALSORT

ISLANG_SPANISH_TRADITIONALSORT
ISLANG_SPANISH_TRADITIONALSORT is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_URUGUAY
ISLANG_SPANISH_URUGUAY is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SPANISH_VENEZUELA
ISLANG_SPANISH_VENEZUELA is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SWEDISH
ISLANG_SWEDISH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SWEDISH_FINLAND
ISLANG_SWEDISH_FINLAND is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_SWEDISH_STANDARD
ISLANG_SWEDISH_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_THAI
ISLANG_THAI is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_THAI_STANDARD
ISLANG_THAI_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

134

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISLANG_TURKISH

ISLANG_TURKISH
ISLANG_TURKISH is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_TURKISH_STANDARD
ISLANG_TURKISH_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_UKRAINIAN
ISLANG_UKRAINIAN is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_UKRAINIAN_STANDARD
ISLANG_UKRAINIAN_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_VIETNAMESE
ISLANG_VIETNAMESE is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISLANG_VIETNAMESE_STANDARD
ISLANG_VIETNAMESE_STANDARD is a predefined constant that corresponds to a Windows language ID. For more information about how to use this constant, see Language IDs.

ISOSL_ALL
ISOSL_ALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

135

Chapter 4: Predefined Constants ISOSL_SUPPORTED

ISOSL_SUPPORTED
ISOSL_SUPPORTED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOSL_WIN2000
ISOSL_WIN2000 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOSL_WIN7_SERVER2008R2
ISOSL_WIN7_SERVER2008R2 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOSL_WINSERVER2003
ISOSL_WINSERVER2003 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOSL_WINVISTA
Note: ISOSL_WINVISTA_SERVER2008 supersedes ISOSL_WINVISTA.

ISOSL_WINVISTA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

136

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISOSL_WINVISTA_SERVER2008

Used With
FeatureFilterOS

ISOSL_WINVISTA_SERVER2008
ISOSL_WINVISTA_SERVER2008 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOSL_WINXP
ISOSL_WINXP is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_ALL
Project: This information applies to InstallScript projects.

ISOS_ST_ALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_BACKOFFICE
Project: This information applies to InstallScript projects.

ISOS_ST_BACKOFFICE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

137

Chapter 4: Predefined Constants ISOS_ST_DATACENTER

Used With
FeatureFilterOS

ISOS_ST_DATACENTER
Project: This information applies to InstallScript projects.

ISOS_ST_DATACENTER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_ENTERPRISE
Project: This information applies to InstallScript projects.

ISOS_ST_ENTERPRISE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_PROC_ARCH_32
Project: This information applies to InstallScript projects.

ISOS_ST_PROC_ARCH_32 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

138

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISOS_ST_PROC_ARCH_AMD64

ISOS_ST_PROC_ARCH_AMD64
Project: This information applies to InstallScript projects.

ISOS_ST_PROC_ARCH_AMD64 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_PROC_ARCH_IA64
Project: This information applies to InstallScript projects.

ISOS_ST_PROC_ARCH_IA64 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_SERVER
Project: This information applies to InstallScript projects.

ISOS_ST_SERVER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_SERVER2003_R2
Project: This information applies to InstallScript projects.

ISOS_ST_SERVER2003_R2 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

139

Chapter 4: Predefined Constants ISOS_ST_SMALLBUSINESS

Used With
FeatureFilterOS

ISOS_ST_SMALLBUSINESS
Project: This information applies to InstallScript projects.

ISOS_ST_SMALLBUSINESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_SMALLBUSINESS_RESTRICTED
Project: This information applies to InstallScript projects.

ISOS_ST_SMALLBUSINESS_RESTRICTED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_TERMINAL
Project: This information applies to InstallScript projects.

ISOS_ST_TERMINAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

140

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISOS_ST_WORKSTATION

ISOS_ST_WORKSTATION
Project: This information applies to InstallScript projects.

ISOS_ST_WORKSTATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_XP_HOME
Project: This information applies to InstallScript projects.

ISOS_ST_XP_HOME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISOS_ST_XP_PRO
Project: This information applies to InstallScript projects.

ISOS_ST_XP_PRO is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFilterOS

ISUS_AGENT_FEATURE
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

141

Chapter 4: Predefined Constants ISUS_MAIN_FEATURE

ISUS_MAIN_FEATURE
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

ISUS_TEXTSUB_HOST
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

ISUS_TEXTSUB_INTERVAL
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

ISUS_TEXTSUB_LANGUAGE
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

ISUS_TEXTSUB_LOGO
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

142

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ISUS_TEXTSUB_MANAGER

ISUS_TEXTSUB_MANAGER
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

ISUS_TEXTSUB_VERSION
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

ISUS_UPDATEMANAGER_FEATURE
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

IS_386
IS_386 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_486
IS_486 is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

143

Chapter 4: Predefined Constants IS_ALPHA

IS_ALPHA
IS_ALPHA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_CDROM
IS_CDROM is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_EGA
IS_EGA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_FIXED
IS_FIXED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_FOLDER
IS_FOLDER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
144

QueryProgItem ReplaceFolderIcon
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants IS_ITEM

IS_ITEM
IS_ITEM is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
QueryProgItem ReplaceFolderIcon

IS_PENTIUM
IS_PENTIUM is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_REMOTE
IS_REMOTE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_REMOVABLE
IS_REMOVABLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_SVGA
IS_SVGA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo
ISP-1800-RG00 145

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants IS_UNKNOWN

IS_UNKNOWN
IS_UNKNOWN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_UVGA
IS_UVGA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_VGA
IS_VGA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_WINDOWS
IS_WINDOWS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_WINDOWS9X
IS_WINDOWS9X is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

146

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants IS_WINDOWSNT

IS_WINDOWSNT
IS_WINDOWSNT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

IS_XVGA
IS_XVGA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

KBYTES
KBYTES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ConvertSizeToUnits StrConvertSizeUnit

KEY_CREATE_LINK
KEY_CREATE_LINK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

KEY_CREATE_SUB_KEY
KEY_CREATE_SUB_KEY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions
ISP-1800-RG00 147

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants KEY_ENUMERATE_SUB_KEYS

KEY_ENUMERATE_SUB_KEYS
KEY_ENUMERATE_SUB_KEYS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

KEY_NOTIFY
GENERIC_WRITE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

KEY_QUERY_VALUE
KEY_QUERY_VALUE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

KEY_SET_VALUE
KEY_SET_VALUE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

LAAW_OPTION_CHANGEDIRECTORY
Project: This information applies to InstallScript projects.

LAAW_OPTION_CHANGEDIRECTORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

148

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants LAAW_OPTION_FIXUP_PROGRAM

Used With
LaunchApplication

LAAW_OPTION_FIXUP_PROGRAM
Project: This information applies to InstallScript projects.

LAAW_OPTION_CHANGEDIRECTORY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
LaunchApplication

LAAW_0PTION_HIDDEN
Project: This information applies to InstallScript projects.

LAAW_OPTION_HIDDEN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall LaunchAppAndWait LaunchApplication WaitForApplication

LAAW_OPTION_MAXIMIZED
Project: This information applies to InstallScript projects.

LAAW_OPTION_MAXIMIZED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

149

Chapter 4: Predefined Constants LAAW_OPTION_MINIMIZED

LaunchAppAndWait LaunchApplication WaitForApplication

LAAW_OPTION_MINIMIZED
Project: This information applies to InstallScript projects.

LAAW_OPTION_MINIMIZED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall LaunchAppAndWait LaunchApplication WaitForApplication

LAAW_OPTION_NO_CHANGEDIRECTORY
Project: This information applies to InstallScript projects.

LAAW_OPTION_NO_CHANGEDIRECTORY is an obsolete predefined constant.

LAAW_OPTION_NOWAIT
Project: This information applies to InstallScript projects.

LAAW_OPTION_NOWAIT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
150

DoInstall LaunchAppAndWait LaunchApplication WaitForApplication

ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants LAAW_OPTION_SET_BATCH_INSTALL

LAAW_OPTION_SET_BATCH_INSTALL
Project: This information applies to InstallScript projects.

LAAW_OPTION_SET_BATCH_INSTALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall LaunchAppAndWait LaunchApplication WaitForApplication

LAAW_OPTION_SHOW_HOURGLASS
Project: This information applies to InstallScript projects.

LAAW_OPTION_SHOW_HOURGLASS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall LaunchAppAndWait

LAAW_OPTION_USE_CALLBACK
LAAW_OPTION_USE_CALLBACK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall LaunchAppAndWait LaunchApplication WaitForApplication

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

151

Chapter 4: Predefined Constants LAAW_OPTION_USE_SHELLEXECUTE

LAAW_OPTION_USE_SHELLEXECUTE
LAAW_OPTION_USE_SHELLEXECUTE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
LaunchApplication

LAAW_OPTION_WAIT
Project: This information applies to InstallScript projects.

LAAW_OPTION_WAIT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall LaunchAppAndWait LaunchApplication WaitForApplication

LAAW_OPTION_WAIT_INCL_CHILD
Project: This information applies to InstallScript projects.

LAAW_OPTION_WAIT_INCL_CHILD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DoInstall LaunchAppAndWait LaunchApplication WaitForApplication

152

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants LANGUAGE_SUPPORTED

LANGUAGE_SUPPORTED
LANGUAGE_SUPPORTED is a predefined constant that is used to specify the language that an installation supports. The language is a four-digit hexadecimal language code, including the 0x prefix. For example, for English, the value should be 0x0409. To build a string with STANDARD_SELECTED_LANGUAGE in this format, use a statement such as:
Sprintf (szLang, "0x%.04lx", STANDARD_SELECTED_LANGUAGE);

You cannot change the value of a predefined constant.

Used With
Is

LANGUAGE
LANGUAGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

LESS_THAN
LESS_THAN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileCompare VerCompare

LINE_NUMBER
LINE_NUMBER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileDeleteLine FileInsertLine

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

153

Chapter 4: Predefined Constants LISTBOX_ENTER

LISTBOX_ENTER
LISTBOX_ENTER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CtrlGetSubCommand

LISTBOX_SELECT
LISTBOX_SELECT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
CtrlGetSubCommand

LISTFIRST
LISTFIRST is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ListSetIndex

LISTLAST
LISTLAST is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ListSetIndex

LISTNEXT
LISTNEXT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ListSetIndex

154

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants LISTPREV

LISTPREV
LISTPREV is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ListSetIndex

LIST_NULL
LIST_NULL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ListCreate

LOCKEDFILE
LOCKEDFILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
XCopyFile InstallationInfo VerUpdateFile DeinstallStart

LOGGING
LOGGING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DeinstallStart Disable Enable InstallationInfo

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

155

Chapter 4: Predefined Constants LOWER_LEFT

LOWER_LEFT
LOWER_LEFT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceBitmap PlaceWindow

LOWER_RIGHT
LOWER_RIGHT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceBitmap PlaceWindow

LWTF_OPTION_APPEND_TO_FILE
LWTF_OPTION_APPEND_TO_FILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ListWriteToFileEx

LWTF_OPTION_WRITE_AS_ANSI
LWTF_OPTION_WRITE_AS_ANSI is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Note: In earlier versions of InstallShield, this constant was called LWFT_OPTION_WRITE_AS_ANSI (where LWFT was used instead of LWTF). To maintain backwards compatibility, both constants are now available, and they are defined the same way.

Used With
ListWriteToFileEx

156

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants LWTF_OPTION_WRITE_AS_UNICODE

LWTF_OPTION_WRITE_AS_UNICODE
LWTF_OPTION_WRITE_AS_UNICODE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Note: In earlier versions of InstallShield, this constant was called LWFT_OPTION_WRITE_AS_UNICODE (where LWFT was used instead of LWTF). To maintain backwards compatibility, both constants are now available, and they are defined the same way.

Used With
ListWriteToFileEx

MAGENTA
MAGENTA is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor SetTitle

MATH_COPROCESSOR
MATH_COPROCESSOR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

MBYTES
MBYTES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ConvertSizeToUnits StrConvertSizeUnit

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

157

Chapter 4: Predefined Constants MEDIA_FIELD_ADDREMOVE_NOMODIFY

MEDIA_FIELD_ADDREMOVE_NOMODIFY
Project: This information applies to InstallScript projects.

MEDIA_FIELD_ADDREMOVE_NOMODIFY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_ADDREMOVE_NOREMOVE
Project: This information applies to InstallScript projects.

MEDIA_FIELD_ADDREMOVE_NOREMOVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_COMPANY_NAME
Project: This information applies to InstallScript projects.

MEDIA_FIELD_COMPANY_NAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData

158

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants MEDIA_FIELD_MEDIA_FLAGS

MEDIA_FIELD_MEDIA_FLAGS
Project: This information applies to InstallScript projects.

MEDIA_FIELD_MEDIA_FLAGS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData

MEDIA_FIELD_PREVIOUS_VERSIONS
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PREVIOUS_VERSIONS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData

MEDIA_FIELD_PRODUCT_COMMENTS
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_COMMENTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_PRODUCT_EXE
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

159

Chapter 4: Predefined Constants MEDIA_FIELD_PRODUCT_ICON

MEDIA_FIELD_PRODUCT_EXE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData

MEDIA_FIELD_PRODUCT_ICON
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_ICON is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_PRODUCT_NAME
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_NAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData

MEDIA_FIELD_PRODUCT_README
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_README is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

160

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants MEDIA_FIELD_PRODUCT_SUPPORT_CONTACT

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_PRODUCT_SUPPORT_CONTACT
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_SUPPORT_CONTACT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_PRODUCT_SUPPORT_PHONE
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_SUPPORT_PHONE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_PRODUCT_SUPPORT_URL
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_SUPPORT_URL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

161

Chapter 4: Predefined Constants MEDIA_FIELD_PRODUCT_UPDATE_URL

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_PRODUCT_UPDATE_URL
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_UPDATE_URL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_PRODUCT_URL
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_URL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData MediaGetDataEx

MEDIA_FIELD_PRODUCT_VERSION
Project: This information applies to InstallScript projects.

MEDIA_FIELD_PRODUCT_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

162

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants MEDIA_FIELD_TARGETDIR

Used With
MediaGetData

MEDIA_FIELD_TARGETDIR
Project: This information applies to InstallScript projects.

MEDIA_FIELD_TARGETDIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData

MEDIA_FLAG_FORMAT_DIFFERENTIAL
Project: This information applies to InstallScript projects.

MEDIA_FLAG_FORMAT_DIFFERENTIAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData

MEDIA_FLAG_FORMAT_PATCH
Project: This information applies to InstallScript projects.

MEDIA_FLAG_FORMAT_PATCH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MediaGetData

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

163

Chapter 4: Predefined Constants MEDIA_FLAG_UPDATEMODE_SUPPORTED

MEDIA_FLAG_UPDATEMODE_SUPPORTED
Project: This information applies to InstallScript projects.

MEDIA_FLAG_UPDATEMODE_SUPPORTED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant. The MEDIA_FLAG_UPDATEMODE_SUPPORTED flag is always set.

Used With
MediaGetData MediaGetDataEx

MEDIA_PASSWORD_KEY
Project: This information applies to InstallScript projects.

MEDIA_PASSWORD_KEY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
LogReadCustomString LogWriteCustomString

METAFILE
METAFILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SizeWindow

MMEDIA_AVI
MMEDIA_AVI is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

164

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants MMEDIA_MIDI

Used With
PlayMMedia PlaceWindow SizeWindow

MMEDIA_MIDI
MMEDIA_MIDI is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlayMMedia

MMEDIA_PLAYASYNCH
MMEDIA_PLAYASYNCH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlayMMedia

MMEDIA_PLAYCONTINUOUS
MMEDIA_PLAYCONTINUOUS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlayMMedia

MMEDIA_PLAYSYNCH
MMEDIA_PLAYSYNCH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlayMMedia

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

165

Chapter 4: Predefined Constants MMEDIA_STOP

MMEDIA_STOP
MMEDIA_STOP is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlayMMedia

MMEDIA_SWF
MMEDIA_SWF is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlayMMedia PlaceWindow SizeWindow

MMEDIA_WAVE
MMEDIA_WAVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlayMMedia

MODIFY
Project: This information applies to InstallScript projects.

MODIFY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SdWelcomeMaint

166

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants NEXT

NEXT
NEXT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
AskDestPath AskOptions AskPath AskText FeatureDialog SdAskDestPath SdAskOptions SdAskOptionsList SdBitmap SdDisplayTopics SdFeatureDialog SdFeatureDialog2 SdFeatureDialogAdv SdFeatureMult SdLicense SdOptionsButtons SdRegisterUser SdRegisterUserEx SdSelectFolder SdShowAnyDialog SdShowDlgEdit1 SdShowDlgEdit2 SdShowDlgEdit3 SdShowFileMods SdShowInfoList SdStartCopy SdWelcome
ISP-1800-RG00 167

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants NEXTBUTTON

SelectFolder Welcome

NEXTBUTTON
NEXTBUTTON is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Disable Enable Is

NO
NO is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SdConfirmNewDir SdConfirmRegistration AskYesNo

NONEXCLUSIVE
NONEXCLUSIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SdAskOptionsList AskOptions SdAskOptions

NORMALMODE
NORMALMODE is a predefined constant that can be used to test whether or not a setup is running in silent mode. For more information, refer to the InstallShield system variable MODE.

168

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants NORMAL_PRIORITY_CLASS

NORMAL_PRIORITY_CLASS
Project: This information applies to InstallScript projects.

NORMAL_PRIORITY_CLASS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

NOSET
NOSET is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
EzBatchAddString

NOTEXISTS
NOTEXISTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ExistsDir ExistsDisk

NO_SUBDIR
Project: This information applies to InstallScript projects.

NO_SUBDIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureFileEnum

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

169

Chapter 4: Predefined Constants NULL

NULL
NULL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ReplaceFolderIcon QueryProgItem AddFolderIcon FindWindow

NUMBERLIST
NUMBERLIST is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ListCreate

OFF
OFF is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
StatusUpdate

OK
OK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
EnterDisk

ON
ON is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

170

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants ONLYDIR

Used With
StatusUpdate

ONLYDIR
ONLYDIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DeleteDir

OTHER_FAILURE
OTHER_FAILURE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileDeleteLine VerUpdateFile FileCompare FileGrep FileInsertLine

OUT_OF_DISK_SPACE
OUT_OF_DISK_SPACE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerUpdateFile FileInsertLine FileDeleteLine VerSearchAndUpdateFile

PARALLEL
PARALLEL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 171

Chapter 4: Predefined Constants PARTIAL

Used With
GetSystemInfo

PARTIAL
PARTIAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PathAdd PathFind PathMove PathDelete

PATH
PATH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ParsePath

PATH_EXISTS
InstallScript Language Reference PATH_EXISTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

PCRESTORE
Project: This information applies to InstallScript projects.

PCRESTORE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

172

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants PERSONAL

Used With
Disable Enable

PERSONAL
PERSONAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ProgDefGroupType

READ_CONTROL
READ_CONTROL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS SetObjectPermissions

REBOOTED
REBOOTED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

RECORDMODE
RECORDMODE is a predefined constant that can be used to test whether or not a setup is automatically generating a silent setup file (.iss file), which is a record of the setup input, in the Windows folder. For more information, refer to the InstallScript system variable MODE.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

173

Chapter 4: Predefined Constants RED

RED
RED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor SetTitle

REGDBREMOTEREGCONNECTED
REGDBREMOTEREGCONNECTED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

REGDB_APPPATH
REGDB_APPPATH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_APPPATH_DEFAULT
REGDB_APPPATH_DEFAULT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

174

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_BINARY

REGDB_BINARY
REGDB_BINARY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBSetAppInfo RegDBGetKeyValueEx RegDBSetKeyValueEx RegDBGetAppInfo RegDBSetKeyValueEx

REGDB_ERR_CONNECTIONEXISTS
REGDB_ERR_CONNECTIONEXISTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBConnectRegistry

REGDB_ERR_CORRUPTEDREGISTRY
REGDB_ERR_CORRUPTEDREGISTRY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBConnectRegistry

REGDB_ERR_INITIALIZATION
REGDB_ERR_INITIALIZATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBConnectRegistry

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

175

Chapter 4: Predefined Constants REGDB_ERR_INVALIDHANDLE

REGDB_ERR_INVALIDHANDLE
REGDB_ERR_INVALIDHANDLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBConnectRegistry

REGDB_ERR_INVALIDNAME
REGDB_ERR_INVALIDNAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBConnectRegistry

REGDB_KEYPATH_APPPATHS
REGDB_KEYPATH_APPPATHS is a predefined constant whose value is the registry location (not including the root key) of the general application paths key, that is, Software\Microsoft\Windows\CurrentVersion\App Paths\. You can use this constant to specify a key when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_KEYPATH_DOTNET_10
REGDB_KEYPATH_DOTNET_10 is a predefined constant whose value is the registry location (not including the root key) of the registry key for version 1.0 of the .NET Framework. It is defined as follows:
Software\Microsoft\NET Framework Setup\Full\v1.0.3705\1033\Microsoft .NET Framework Full v1.0.3705 (1033)\

You cannot change the value of a predefined constant. You can use this constant to specify a key when calling a general registry-related function. This predefined constant is also supported when using the Is function.

Used With
Is

REGDB_KEYPATH_DOTNET_11
REGDB_KEYPATH_DOTNET_11 is a predefined constant whose value is the registry location (not including the root key) of the registry key for version 1.1 of the .NET Framework. It is defined as follows:

176

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_KEYPATH_DOTNET_20

Software\Microsoft\NET Framework Setup\NDP\v1.1.4322\

You cannot change the value of a predefined constant. You can use this constant to specify a key when calling a general registry-related function. This predefined constant is also supported when using the Is function.

Used With
Is

REGDB_KEYPATH_DOTNET_20
REGDB_KEYPATH_DOTNET_20 is a predefined constant whose value is the registry location (not including the root key) of the registry key for version 2.0 of the .NET Framework. It is defined as follows:
Software\Microsoft\NET Framework Setup\NDP\v2.0.50215\

You cannot change the value of a predefined constant. You can use this constant to specify a key when calling a general registry-related function. This predefined constant is also supported when using the Is function.

Used With
Is

REGDB_KEYPATH_DOTNET_30
REGDB_KEYPATH_DOTNET_30 is a predefined constant whose value is the registry location (not including the root key) of the registry key for the RTM version of the .NET Framework 3.0. It is defined as follows:
Software\Microsoft\NET Framework Setup\NDP\v3.0\Setup\

Tip: You can use the REGDB_KEYPATH_DOTNET_30 variable to detect whether the RTM version of the .NET Framework 3.0 is installed. To detect whether SP1or a later service packof the .NET Framework 3.0 is installed, use REGDB_KEYPATH_DOTNET_30_SP.

You cannot change the value of a predefined constant. You can use this constant to specify a key when calling a general registry-related function. This predefined constant is also supported when using the Is function.

Used With
Is

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

177

Chapter 4: Predefined Constants REGDB_KEYPATH_DOTNET_30_SP

REGDB_KEYPATH_DOTNET_30_SP
REGDB_KEYPATH_DOTNET_30_SP is a predefined constant whose value is the registry location (not including the root key) of the registry key for SP1or a later service packof the .NET Framework 3.0. It is defined as follows:
Software\Microsoft\NET Framework Setup\NDP\v3.0\

Tip: You can use the REGDB_KEYPATH_DOTNET_30_SP variable when querying whether SP1or a later service pack of the .NET Framework 3.0 is installed. To detect whether the RTM version of the .NET Framework 3.0 is installed, use REGDB_KEYPATH_DOTNET_30.

You cannot change the value of a predefined constant. You can use this constant to specify a key when calling a general registry-related function. This predefined constant is also supported when using the Is function.

Used With
Is

REGDB_KEYPATH_DOTNET_35
REGDB_KEYPATH_DOTNET_35 is a predefined constant whose value is the registry location (not including the root key) of the registry key for version 3.5 of the .NET Framework. It is defined as follows:
Software\Microsoft\NET Framework Setup\NDP\v3.5\

You cannot change the value of a predefined constant. You can use this constant to specify a key when calling a general registry-related function. This predefined constant is also supported when using the Is function.

Used With
Is

REGDB_KEYPATH_DOTNET_40_CLIENT
REGDB_KEYPATH_DOTNET_40_CLIENT is a predefined constant whose value is the registry location (not including the root key) of the registry key for version 4.0 of the .NET Framework Client Profile. It is defined as follows:
Software\Microsoft\NET Framework Setup\NDP\v4\Client

You cannot change the value of a predefined constant. You can use this constant to specify a key when calling a general registry-related function. This predefined constant is also supported when using the Is function.

Used With
178

Is
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_KEYPATH_DOTNET_40_FULL

REGDB_KEYPATH_DOTNET_40_FULL
REGDB_KEYPATH_DOTNET_40_FULL is a predefined constant whose value is the registry location (not including the root key) of the registry key for version 4.0 of the .NET Framework. It is defined as follows:
Software\Microsoft\NET Framework Setup\NDP\v4\Full

You cannot change the value of a predefined constant. You can use this constant to specify a key when calling a general registry-related function. This predefined constant is also supported when using the Is function.

Used With
Is

REGDB_KEYPATH_ISUNINSTINFO
ISUNINSTINFO is a predefined constant whose value is the registry location (not including the root key) of the InstallShield Uninstall Information key. It is defined as follows:
Software\Microsoft\Windows\CurrentVersion\Uninstall\InstallShield Uninstall Information

You cannot change the value of a predefined constant. You can use this constant to specify a key when calling a general registry-related function. This predefined constant is also supported when using the Is function.

Used With
Is

REGDB_KEYPATH_RUN
REGDB_KEYPATH_RUN is a predefined constant whose value is the registry location (not including the root key) of the general application paths key, that is, Software\Microsoft\Windows\CurrentVersion\Run\. You can use this constant to specify a key when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_KEYPATH_RUNONCE
REGDB_KEYPATH_RUNONCE is a predefined constant whose value is the registry location (not including the root key) of the general application paths key, that is, Software\Microsoft\Windows\CurrentVersion\RunOnce\. You can use this constant to specify a key when calling a general registry-related function. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

179

Chapter 4: Predefined Constants REGDB_KEYPATH_RUNONCEEX

REGDB_KEYPATH_RUNONCEEX
REGDB_KEYPATH_RUNONCEEX is a predefined constant whose value is the registry location (not including the root key) of the general application paths key, that is, Software\Microsoft\Windows\CurrentVersion\RunOnceEx\. You can use this constant to specify a key when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_KEYPATH_SHAREDDLLS
REGDB_KEYPATH_SHAREDDLLS is a predefined constant whose value is the registry location (not including the root key) of the general application paths key, that is, Software\Microsoft\Windows\CurrentVersion\SharedDLLs\. You can use this constant to specify a key when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_KEYPATH_UNINSTALL
REGDB_KEYPATH_UNINSTALL is a predefined constant whose value is the registry location (not including the root key) of the general uninstallation key for applications, that is, Software\Microsoft\Windows\CurrentVersion\Uninstall\. You can use this constant to specify a key when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_KEYPATH_WINCURRVER
REGDB_KEYPATH_WINCURRVER is a predefined constant whose value is the registry location (not including the root key) of the Windows current version key, that is, Software\Microsoft\Windows\CurrentVersion\. You can use this constant to specify a key when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_KEYPATH_WINCURRVER_AUTO
The value of this system variable is REGDB_KEYPATH_WINCURRVER on Windows 95, Windows 95, and Windows Me, and REGDB_KEYPATH_WINNTCURRVER on Windows NT, Windows 2000, and Windows XP and later.

REGDB_KEYPATH_WINNTCURRVER
REGDB_KEYPATH_WINNTCURRVER is a predefined constant whose value is the registry location (not including the root key) of the Windows NT current version key, that is, Software\Microsoft\Windows NT\CurrentVersion\. You can use this constant to specify a key when calling a general registry-related function. You cannot change the value of a predefined constant.

180

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_KEYS

REGDB_KEYS
REGDB_KEYS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBQueryKey

REGDB_NAMES
REGDB_NAMES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBQueryKey

REGDB_NUMBER
REGDB_NUMBER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBGetAppInfo RegDBGetKeyValueEx RegDBSetKeyValueEx RegDBSetAppInfo

REGDB_STRING
REGDB_STRING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBGetAppInfo RegDBGetKeyValueEx RegDBSetKeyValueEx RegDBSetAppInfo

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

181

Chapter 4: Predefined Constants REGDB_STRING_EXPAND

REGDB_STRING_EXPAND
REGDB_STRING_EXPAND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBSetAppInfo RegDBGetKeyValueEx RegDBSetKeyValueEx RegDBGetAppInfo

REGDB_STRING_MULTI
REGDB_STRING_MULTI is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBGetAppInfo RegDBGetKeyValueEx RegDBSetKeyValueEx RegDBSetAppInfo

REGDB_UNINSTALL_COMMENTS
REGDB_UNINSTALL_COMMENTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_CONTACT
REGDB_UNINSTALL_CONTACT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

182

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_UNINSTALL_DISPLAYICON

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_DISPLAYICON
REGDB_UNINSTALL_DISPLAYICON is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_DISPLAY_VERSION
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_DISPLAY_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_HELPLINK
REGDB_UNINSTALL_HELPLINK is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

183

Chapter 4: Predefined Constants REGDB_UNINSTALL_HELPTELEPHONE

RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_HELPTELEPHONE
REGDB_UNINSTALL_HELPTELEPHONE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_INSTALLDATE
REGDB_UNINSTALL_INSTALLDATE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_INSTALLLOC
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_INSTALLLOC is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

184

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_UNINSTALL_INSTALLSOURCE

REGDB_UNINSTALL_INSTALLSOURCE
REGDB_UNINSTALL_INSTALLSOURCE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_LANGUAGE
REGDB_UNINSTALL_LANGUAGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_LOGFILE
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_LOGFILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

185

Chapter 4: Predefined Constants REGDB_UNINSTALL_MAINT_OPTION

REGDB_UNINSTALL_MAINT_OPTION
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_MAINT_OPTION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_MAJOR_VERSION
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_MAJOR_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_MAJOR_VERSION_OLD
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_MAJOR_VERSION_OLD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
186

RegDBDeleteItem RegDBGetItem
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_UNINSTALL_MINOR_VERSION

RegDBSetItem

REGDB_UNINSTALL_MINOR_VERSION
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_MINOR_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_MINOR_VERSION_OLD
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_MINOR_VERSION_OLD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_MODIFYPATH
REGDB_UNINSTALL_MODIFYPATH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

187

Chapter 4: Predefined Constants REGDB_UNINSTALL_NAME

RegDBSetItem

REGDB_UNINSTALL_NAME
REGDB_UNINSTALL_NAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_NOMODIFY
REGDB_UNINSTALL_NOMODIFY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_NOREMOVE
REGDB_UNINSTALL_NOREMOVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_NOREPAIR
REGDB_UNINSTALL_NOREPAIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
188 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_UNINSTALL_PRODUCTGUID

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_PRODUCTGUID
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_PRODUCTGUID is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_PRODUCTID
REGDB_UNINSTALL_PRODUCTID is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_PUBLISHER
REGDB_UNINSTALL_PUBLISHER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

189

Chapter 4: Predefined Constants REGDB_UNINSTALL_README

RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_README
REGDB_UNINSTALL_README is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_REGCOMPANY
REGDB_UNINSTALL_REGCOMPANY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_REGOWNER
REGDB_UNINSTALL_REGOWNER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

190

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_UNINSTALL_STRING

REGDB_UNINSTALL_STRING
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_STRING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_SYSTEMCOMPONENT
REGDB_UNINSTALL_SYSTEMCOMPONENT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_URLINFOABOUT
REGDB_UNINSTALL_URLINFOABOUT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

191

Chapter 4: Predefined Constants REGDB_UNINSTALL_URLUPDATEINFO

REGDB_UNINSTALL_URLUPDATEINFO
REGDB_UNINSTALL_URLUPDATEINFO is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_UNINSTALL_VERSION
Project: This information applies to InstallScript projects.

REGDB_UNINSTALL_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBDeleteItem RegDBGetItem RegDBSetItem

REGDB_VALUENAME_APPPATH
REGDB_VALUENAME_APPPATH is a predefined constant whose value is the path value name under the application path key, that is, Path. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_APPPATHDEFAULT
REGDB_VALUENAME_APPPATHDEFAULT is a predefined constant whose value is the default value name under the application path key, that is, a null string (""). You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

192

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_VALUENAME_INSTALL

REGDB_VALUENAME_INSTALL
REGDB_VALUENAME_INSTALL is a predefined constant whose value is Install. You can use this constant to specify a value when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_INSTALLSUCCESS
REGDB_VALUENAME_INSTALLSUCCESS is a predefined constant whose value is InstallSuccess. You can use this constant to specify a value when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_SP
REGDB_VALUENAME_INSTALL is a predefined constant whose value is SP. You can use this constant to specify a value when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_COMMENTS
REGDB_VALUENAME_UNINSTALL_COMMENTS is a predefined constant whose value is the comments value name under the application uninstallation keythat is, Comments. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_CONTACT
REGDB_VALUENAME_UNINSTALL_CONTACT is a predefined constant whose value is the contact value name under the application uninstallation keythat is, Contact. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_DISPLAYICON
REGDB_VALUENAME_UNINSTALL_DISPLAYICON is a predefined constant whose value is the display icon value name under the application uninstallation keythat is, DisplayIcon. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

193

Chapter 4: Predefined Constants REGDB_VALUENAME_UNINSTALL_DISPLAYNAME

REGDB_VALUENAME_UNINSTALL_DISPLAYNAME
REGDB_VALUENAME_UNINSTALL_DISPLAYNAME is a predefined constant whose value is the display name value name under the application uninstallation keythat is, DisplayName. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_DISPLAYVERSI ON
REGDB_VALUENAME_UNINSTALL_DISPLAYVERSION is a predefined constant whose value is the display version value name under the application uninstallation keythat is, DisplayVersion. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_HELPLINK
REGDB_VALUENAME_UNINSTALL_HELPLINK is a predefined constant whose value is the help link value name under the application uninstallation keythat is, HelpLink. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_HELPTELEPHO NE
REGDB_VALUENAME_UNINSTALL_HELPTELEPHONE is a predefined constant whose value is the help telephone value name under the application uninstallation keythat is, HelpTelephone. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_INSTALLDATE
REGDB_VALUENAME_UNINSTALL_INSTALLDATE is a predefined constant whose value is the installation date value name under the application uninstallation keythat is, InstallDate. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

194

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_VALUENAME_UNINSTALL_INSTALLLOCATION

REGDB_VALUENAME_UNINSTALL_INSTALLLOCATI ON
REGDB_VALUENAME_UNINSTALL_INSTALLLOCATION is a predefined constant whose value is the installation location value name under the application uninstallation keythat is, InstallLocation. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_INSTALLSOURC E
REGDB_VALUENAME_UNINSTALL_INSTALLSOURCE is a predefined constant whose value is the installation source value name under the application uninstallation keythat is, InstallSource. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_LANGUAGE
REGDB_VALUENAME_UNINSTALL_LANGUAGE is a predefined constant whose value is the language value name under the application uninstallation keythat is, Language. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_LOGFILE
REGDB_VALUENAME_UNINSTALL_LOGFILE is a predefined constant whose value is the log file value name under the application uninstallation keythat is, LogFile. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_LOGMODE
REGDB_VALUENAME_UNINSTALL_LOGMODE is a predefined constant whose value is the log mode value name under the application uninstallation keythat is, LogMode. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

195

Chapter 4: Predefined Constants REGDB_VALUENAME_UNINSTALL_MAJORVERSION

REGDB_VALUENAME_UNINSTALL_MAJORVERSIO N
REGDB_VALUENAME_UNINSTALL_MAJORVERSION is a predefined constant whose value is the major version value name under the application uninstallation keythat is, VersionMajor. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_MAJORVERSIO N_OLD
REGDB_VALUENAME_UNINSTALL_MAJORVERSION_OLD is a predefined constant whose value is the major version value name under the application uninstallation keythat is, MajorVersion. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_MINORVERSIO N
REGDB_VALUENAME_UNINSTALL_MINORVERSION is a predefined constant whose value is the minor version value name under the application uninstallation keythat is, VersionMinor. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_MINORVERSIO N_OLD
REGDB_VALUENAME_UNINSTALL_MINORVERSION_OLD is a predefined constant whose value is the minor version value name under the application uninstallation keythat is, MinorVersion. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_MODIFYPATH
REGDB_VALUENAME_UNINSTALL_MODIFYPATH is a predefined constant whose value is the modify path value name under the application uninstallation keythat is, ModifyPath. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

196

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_VALUENAME_UNINSTALL_NOMODIFY

REGDB_VALUENAME_UNINSTALL_NOMODIFY
REGDB_VALUENAME_UNINSTALL_NOMODIFY is a predefined constant whose value is the no modify value name under the application uninstallation keythat is, NoModify. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_NOREMOVE
REGDB_VALUENAME_UNINSTALL_NOREMOVE is a predefined constant whose value is the no remove value name under the application uninstallation keythat is, NoRemove. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_NOREPAIR
REGDB_VALUENAME_UNINSTALL_NOREPAIR is a predefined constant whose value is the no repair value name under the application uninstallation keythat is, NoRepair. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_PRODUCTGUID
REGDB_VALUENAME_UNINSTALL_PRODUCTGUID is a predefined constant whose value is the product GUID value name under the application uninstallation keythat is, ProductGuid. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_PRODUCTID
REGDB_VALUENAME_UNINSTALL_PRODUCTID is a predefined constant whose value is the product ID value name under the application uninstallation keythat is, ProductId. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_PUBLISHER
REGDB_VALUENAME_UNINSTALL_PUBLISHER is a predefined constant whose value is the publisher value name under the application uninstallation keythat is, Publisher. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

197

Chapter 4: Predefined Constants REGDB_VALUENAME_UNINSTALL_README

REGDB_VALUENAME_UNINSTALL_README
REGDB_VALUENAME_UNINSTALL_README is a predefined constant whose value is the readme value name under the application uninstallation keythat is, Readme. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_REGCOMPANY
REGDB_VALUENAME_UNINSTALL_REGCOMPANY is a predefined constant whose value is the reg company value name under the application uninstallation keythat is, RegCompany. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_REGOWNER
REGDB_VALUENAME_UNINSTALL_REGOWNER is a predefined constant whose value is the reg owner value name under the application uninstallation keythat is, RegOwner. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_SYSTEMCOMP ONENT
REGDB_VALUENAME_UNINSTALL_SYSTEMCOMPONENT is a predefined constant whose value is the system component value name under the application uninstallation keythat is, SystemComponent. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_UNINSTALLSTRI NG
REGDB_VALUENAME_UNINSTALL_UNINSTALLSTRING is a predefined constant whose value is the uninstallation string value name under the application uninstallation keythat is, UninstallString. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

198

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGDB_VALUENAME_UNINSTALL_URLINFOABOUT

REGDB_VALUENAME_UNINSTALL_URLINFOABOUT
REGDB_VALUENAME_UNINSTALL_URLINFOABOUT is a predefined constant whose value is the URL info about value name under the application uninstallation keythat is, URLInfoAbout. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_URLUPDATEINF O
REGDB_VALUENAME_UNINSTALL_URLUPDATEINFO is a predefined constant whose value is the URL date info value name under the application uninstallation keythat is, URLDateInfo. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALL_VERSION
REGDB_VALUENAME_UNINSTALL_VERSION is a predefined constant whose value is the application version value name under the application uninstallation keythat is, Version. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_UNINSTALLKEY
REGDB_VALUENAME_UNINSTALLKEY is a predefined constant whose value is defined as UninstallKey. You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

REGDB_VALUENAME_WINCURRVER_REGORGANIZ ATION
REGDB_VALUENAME_WINCURRVER_REGORGANIZATION is a predefined constant whose value is the registered organization value name under the Windows (on Windows 95, Windows 95, and Windows Me) or Windows NT (on Windows 95, Windows 95, and Windows Me) current version key, that is, "RegisteredOrganization". You can use this constant to specify a value name when calling a general registry-related function. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

199

Chapter 4: Predefined Constants REGDB_VALUENAME_WINCURRVER_REGOWNER

REGDB_VALUENAME_WINCURRVER_REGOWNER
REGDB_VALUENAME_WINCURRVER_REGOWNER is a predefined constant whose value is the registered owner value name under the Windows (on Windows 95, Windows 95, and Windows Me) or Windows NT (on Windows 95, Windows 95, and Windows Me) current version key, that is, "RegisteredOwner". You can use this constant to specify a value name when calling a general registryrelated function. You cannot change the value of a predefined constant.

REGDB_WINCURRVER_REGORGANIZATION
REGDB_WINCURRVER_REGORGANIZATION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBGetItem

REGDB_WINCURRVER_REGOWNER
REGDB_WINCURRVER_REGOWNER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegDBGetItem

REGFONT_OPTION_DEFAULT
REGFONT_OPTION_DEFAULT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegisterFontResource

REGFONT_OPTION_DONTBROADCASTFONTCHAN GEMSG
REGFONT_OPTION_DONTBROADCASTFONTCHANGEMSG is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

200

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants REGFONT_OPTION_DONTUPDATEREGISTRY

Used With
RegisterFontResource

REGFONT_OPTION_DONTUPDATEREGISTRY
REGFONT_OPTION_DONTUPDATEREGISTRY is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
RegisterFontResource

REGISTRYFUNCTIONS_USETEXTSUBS
REGISTRYFUNCTIONS_USETEXTSUBS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Disable Enable

REMOTE_DRIVE
REMOTE_DRIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetValidDrivesList

REMOVE
REMOVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceBitmap

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

201

Chapter 4: Predefined Constants REMOVEABLE_DRIVE

REMOVEABLE_DRIVE
REMOVEABLE_DRIVE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetValidDrivesList

REMOVEALL
Project: This information applies to InstallScript projects.

REMOVEALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SdWelcomeMaint

REPAIR
Project: This information applies to InstallScript projects.

REPAIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SdWelcomeMaint

REPLACE
REPLACE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
202

ConfigAdd AddFolderIcon FileInsertLine BatchAdd

ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants RESET

ReplaceFolderIcon

RESET
RESET is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FindFile

RESTART
RESTART is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FileGrep PathFind ConfigFind BatchFind

ROOT
ROOT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
DeleteDir

RUN_MAXIMIZED
RUN_MAXIMIZED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
AddFolderIcon ReplaceFolderIcon

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

203

Chapter 4: Predefined Constants RUN_MINIMIZED

RUN_MINIMIZED
RUN_MINIMIZED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
QueryProgItem AddFolderIcon ReplaceFolderIcon

SELECTFOLDER
SELECTFOLDER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SelectFolder

SELFREGISTER
SELFREGISTER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerUpdateFile XCopyFile

SELFREGISTERBATCH
SELFREGISTERBATCH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Enable Disable

204

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SELFREGISTRATIONPROCESS

SELFREGISTRATIONPROCESS
SELFREGISTRATIONPROCESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Do

SERIAL
SERIAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

SERVICE_ADAPTER
Project: This information applies to InstallScript projects.

SERVICE_ADAPTER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_ALL_ACCESS
Project: This information applies to InstallScript projects.

SERVICE_ALL_ACCESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

205

Chapter 4: Predefined Constants SERVICE_AUTO_START

SERVICE_AUTO_START
Project: This information applies to InstallScript projects.

SERVICE_AUTO_START is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_BOOT_START
Project: This information applies to InstallScript projects.

SERVICE_BOOT_START is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_CHANGE_CONFIG
Project: This information applies to InstallScript projects.

SERVICE_CHANGE_CONFIG is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_CONTINUE_PENDING
Project: This information applies to InstallScript projects.

206

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SERVICE_DEMAND_START

SERVICE_CONTINUE_PENDING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_STATUS

SERVICE_DEMAND_START
Project: This information applies to InstallScript projects.

SERVICE_DEMAND_START is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_DISABLED
Project: This information applies to InstallScript projects.

SERVICE_DISABLED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_ENUMERATE_DEPENDENTS
Project: This information applies to InstallScript projects.

SERVICE_ENUMERATE_DEPENDENTS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS
ISP-1800-RG00 207

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SERVICE_ERROR_CRITICAL

SERVICE_ERROR_CRITICAL
Project: This information applies to InstallScript projects.

SERVICE_ERROR_CRITICAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_ERROR_IGNORE
Project: This information applies to InstallScript projects.

SERVICE_ERROR_IGNORE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_ERROR_NORMAL
Project: This information applies to InstallScript projects.

SERVICE_ERROR_NORMAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_ERROR_SEVERE
Project: This information applies to InstallScript projects.

208

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SERVICE_FILE_SYSTEM_DRIVER

SERVICE_ERROR_SEVERE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_FILE_SYSTEM_DRIVER
Project: This information applies to InstallScript projects.

SERVICE_FILE_SYSTEM_DRIVER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_FLAG_DIFX_32
Project: This information applies to the following project types:

InstallScript InstallScript Object

SERVICE_FLAG_DIFX_32 is a predefined constant that is used to represent a value that can be set as a bit flag in the system variable ENABLED_ISERVICES. You cannot change the value of a predefined constant.

SERVICE_FLAG_DIFX_AMD64
Project: This information applies to the following project types:

InstallScript InstallScript Object

SERVICE_FLAG_DIFX_AMD64 is a predefined constant that is used to represent a value that can be set as a bit flag in the system variable ENABLED_ISERVICES. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

209

Chapter 4: Predefined Constants SERVICE_FLAG_DIFX_IA64

SERVICE_FLAG_DIFX_IA64
Project: This information applies to the following project types:

InstallScript InstallScript Object

SERVICE_FLAG_DIFX_IA64 is a predefined constant that is used to represent a value that can be set as a bit flag in the system variable ENABLED_ISERVICES. You cannot change the value of a predefined constant.

SERVICE_FLAG_ISFONTREG
Project: This information applies to the following project types:

InstallScript InstallScript Object

SERVICE_FLAG_ISFONTREG is a predefined constant that is used to represent a value that can be set as a bit flag in the system variable ENABLED_ISERVICES. If the expression ENABLED_ISERVICES & SERVICE_FLAG_ISFONTREG is equal to a non-zero value, global font registration is currently enabled. You cannot change the value of a predefined constant.

SERVICE_INTERACTIVE_PROCESS
Project: This information applies to InstallScript projects.

SERVICE_INTERACTIVE_PROCESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_INTERROGATE
Project: This information applies to InstallScript projects.

210

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SERVICE_ISFONTREG

SERVICE_INTERROGATE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_ISFONTREG
SERVICE_ISFONTREG is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Disable

SERVICE_ISUPDATE
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

SERVICE_KERNEL_DRIVER
Project: This information applies to InstallScript projects.

SERVICE_KERNEL_DRIVER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_PAUSED
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

211

Chapter 4: Predefined Constants SERVICE_PAUSE_CONTINUE

SERVICE_PAUSED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_STATUS

SERVICE_PAUSE_CONTINUE
Project: This information applies to InstallScript projects.

SERVICE_PAUSE_CONTINUE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_PAUSE_PENDING
Project: This information applies to InstallScript projects.

SERVICE_PAUSE_PENDING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_STATUS

SERVICE_QUERY_CONFIG
Project: This information applies to InstallScript projects.

SERVICE_QUERY_CONFIG is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
212

SERVICE_IS_PARAMS
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SERVICE_QUERY_STATUS

SERVICE_QUERY_STATUS
Project: This information applies to InstallScript projects.

SERVICE_QUERY_STATUS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_RECOGNIZER_DRIVER
Project: This information applies to InstallScript projects.

SERVICE_RECOGNIZER_DRIVER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_RUNNING
Project: This information applies to InstallScript projects.

SERVICE_RUNNING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_STATUS

SERVICE_START
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

213

Chapter 4: Predefined Constants SERVICE_START_PENDING

SERVICE_START is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_START_PENDING
Project: This information applies to InstallScript projects.

SERVICE_START_PENDING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_STATUS

SERVICE_STOP
Project: This information applies to InstallScript projects.

SERVICE_STOP is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_STOPPED
Project: This information applies to InstallScript projects.

SERVICE_STOPPED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
214

SERVICE_IS_STATUS
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SERVICE_STOP_PENDING

SERVICE_STOP_PENDING
Project: This information applies to InstallScript projects.

SERVICE_STOP_PENDING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_STATUS

SERVICE_SYSTEM_START
Project: This information applies to InstallScript projects.

SERVICE_SYSTEM_START is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_USER_DEFINED_CONTROL
Project: This information applies to InstallScript projects.

SERVICE_USER_DEFINED_CONTROL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_WIN32_OWN_PROCESS
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

215

Chapter 4: Predefined Constants SERVICE_WIN32_SHARE_PROCESS

SERVICE_WIN32_OWN_PROCESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SERVICE_WIN32_SHARE_PROCESS
Project: This information applies to InstallScript projects.

SERVICE_WIN32_SHARE_PROCESS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS

SETUPTYPE
SETUPTYPE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetupType

SETUPTYPE_INFO_DESCRIPTION
SETUPTYPE_INFO_DESCRIPTION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureSetupTypeGetData

SETUPTYPE_INFO_DISPLAYNAME
SETUPTYPE_INFO_DISPLAYNAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

216

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SETUPTYPE_STR_COMPACT

Used With
FeatureSetupTypeGetData

SETUPTYPE_STR_COMPACT
SETUPTYPE_STR_COMPACT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureStandardSetupTypeSet

SETUPTYPE_STR_COMPLETE
SETUPTYPE_STR_COMPLETE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureStandardSetupTypeSet

SETUPTYPE_STR_CUSTOM
SETUPTYPE_STR_CUSTOM is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureStandardSetupTypeSet

SETUPTYPE_STR_TYPICAL
SETUPTYPE_STR_TYPICAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
FeatureStandardSetupTypeSet

SETUP_PACKAGE
Project: This information applies to InstallScript projects.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 217

Chapter 4: Predefined Constants SEVERE

SETUP_PACKAGE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
Is

SEVERE
SEVERE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MessageBox SprintfBox

SHAREDFILE
SHAREDFILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
XCopyFile VerUpdateFile DeinstallStart InstallationInfo System

SILENTMODE
SILENTMODE is a predefined constant that can be used to test whether or not a setup is running in silent mode. For more information, refer to the InstallShield system variable MODE.

SKIN_LOADED
Project: This information applies to InstallScript projects.

218

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SQL_BATCH_INSTALL

SKIN_LOADED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

SQL_BATCH_INSTALL
SQL_BATCH_INSTALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetBatchList

SQL_BATCH_UNINSTALL
SQL_BATCH_UNINSTALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetBatchList

SQL_BROWSE_ALIAS
SQL_BROWSE_ALIAS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetBrowseOption SQLRTSetBrowseOption

SQL_BROWSE_ALL
SQL_BROWSE_ALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetBrowseOption SQLRTSetBrowseOption

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

219

Chapter 4: Predefined Constants SQL_BROWSE_LOCAL

SQL_BROWSE_LOCAL
SQL_BROWSE_LOCAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetBrowseOption SQLRTSetBrowseOption

SQL_BROWSE_REMOTE
SQL_BROWSE_REMOTE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetBrowseOption SQLRTSetBrowseOption

SQL_ERROR_GET_SCHEMA_VERSION
SQL_ERROR_GET_SCHEMA_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetComponentScriptError SQLRTGetComponentScriptError2

SQL_ERROR_SCRIPT_COMMAND_ERROR
SQL_ERROR_SCRIPT_COMMAND_ERROR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetComponentScriptError SQLRTGetComponentScriptError2

220

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SQL_ERROR_SCRIPT_CONNECTION_NOT_OPEN

SQL_ERROR_SCRIPT_CONNECTION_NOT_OPEN
SQL_ERROR_SCRIPT_CONNECTION_NOT_OPEN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetComponentScriptError SQLRTGetComponentScriptError2

SQL_ERROR_SCRIPT_UNABLE_OPEN_FILE
SQL_ERROR_SCRIPT_UNABLE_OPEN_FILE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetComponentScriptError SQLRTGetComponentScriptError2

SQL_ERROR_SET_SCHEMA_VERSION
SQL_ERROR_SET_SCHEMA_VERSION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SQLRTGetComponentScriptError SQLRTGetComponentScriptError2

SRCINSTALLDIR
Note: SRCTARGETDIR replaces SRCINSTALLDIR.

SRCINSTALLDIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VarRestore

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

221

Chapter 4: Predefined Constants SRCTARGETDIR

VarSave

SRCTARGETDIR
Note: SRCTARGETDIR replaces SRCINSTALLDIR.

SRCTARGETDIR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VarRestore VarSave

STANDARD_RIGHTS_ALL
STANDARD_RIGHTS_ALL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

STANDARD_RIGHTS_EXECUTE
STANDARD_RIGHTS_EXECUTE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

STANDARD_RIGHTS_READ
STANDARD_RIGHTS_READ is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

222

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants STANDARD_RIGHTS_REQUIRED

STANDARD_RIGHTS_REQUIRED
STANDARD_RIGHTS_REQUIRED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS SetObjectPermissions

STANDARD_RIGHTS_WRITE
STANDARD_RIGHTS_WRITE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SetObjectPermissions

STATUS
STATUS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceWindow Enable Disable

STATUSBAR
STATUSBAR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

223

Chapter 4: Predefined Constants STATUSBBRD

STATUSBBRD
STATUSBBRD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Enable Disable

STATUSDLG
STATUSDLG is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceWindow Enable Disable

STATUSEX
STATUSEX is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceWindow Enable Disable

STATUSOLD
STATUSOLD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
224

PlaceWindow Enable Disable

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants STRINGLIST

STRINGLIST
STRINGLIST is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ListCreate

STYLE_BOLD
STYLE_BOLD is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFont SetFont

STYLE_ITALIC
STYLE_ITALIC is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFont SetFont

STYLE_NORMAL
STYLE_NORMAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFont SetFont

STYLE_SHADOW
STYLE_SHADOW is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

225

Chapter 4: Predefined Constants STYLE_UNDERLINE

Used With
SetFont

STYLE_UNDERLINE
STYLE_UNDERLINE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetFont SetFont

SW_MAXIMIZE
SW_MAXIMIZE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ShowProgramFolder

SW_MINIMIZE
SW_MINIMIZE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ShowProgramFolder

SW_RESTORE
SW_RESTORE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ShowProgramFolder

226

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants SW_SHOW

SW_SHOW
SW_SHOW is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ShowProgramFolder

SYNCHRONIZE
SYNCHRONIZE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS SetObjectPermissions

SYS_BOOTMACHINE
SYS_BOOTMACHINE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
System RebootDialog SdFinishReboot

TBYTES
TBYTES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
ConvertSizeToUnits StrConvertSizeUnit

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

227

Chapter 4: Predefined Constants TILED

TILED
TILED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceBitmap

TIME
TIME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

TRUE
TRUE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
228

AskOptions CtrlSetMultCurSel DialogSetInfo FeatureAddItem FeatureGetData FeatureIsItemSelected FeatureSelectItem FeatureTotalSize LongPathToQuote SdDiskSpace2 SelectDir SdShowMsg SQLDatabaseBrowse SQLRTConnect

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants TTFONTFILEINFO_FONTTITLE

SQLRTConnect2 SQLRTConnectDB SQLRTGetDatabases SQLRTGetServers SQLRTGetServers2 SQLRTPutConnectionAuthentication SQLRTTestConnection SQLRTTestConnection2 SQLServerSelectLogin SQLServerSelectLogin2

TTFONTFILEINFO_FONTTITLE
TTFONTFILEINFO_FONTTITLE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetTrueTypeFontFileInfo

TYPICAL
TYPICAL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SdSetupType SetupType

UPDATE_SERVICE_INSTALL
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

229

Chapter 4: Predefined Constants UPDATESERVICECOMPONENT

UPDATESERVICECOMPONENT
Project: This information applies to InstallScript projects.

This constant is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

UPPER_LEFT
UPPER_LEFT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceBitmap PlaceWindow

UPPER_RIGHT
UPPER_RIGHT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
PlaceBitmap PlaceWindow

URL
Project: This information applies to InstallScript projects.

URL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

230

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants USER_ADMINISTRATOR

USER_ADMINISTRATOR
USER_ADMINISTRATOR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

USER_INADMINGROUP
USER_INADMINGROUP is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

USER_POWERUSER
Project: This information applies to InstallScript projects.

USER_POWERUSER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

USE_LOADED_SKIN
Project: This information applies to InstallScript projects.

USE_LOADED_SKIN is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Disable Enable

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

231

Chapter 4: Predefined Constants VALID_PATH

VALID_PATH
VALID_PATH is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

VERSION_COMPARE_RESULT_NEWER
Project: This information applies to InstallScript projects.

VERSION_COMPARE_RESULT_NEWER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerProductCompareVersions

VERSION_COMPARE_RESULT_NEWER_NOT_SUPP ORTED
Project: This information applies to InstallScript projects.

VERSION_COMPARE_RESULT_NEWER_NOT_SUPPORTED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerProductCompareVersions

VERSION_COMPARE_RESULT_NOT_INSTALLED
Project: This information applies to InstallScript projects.

VERSION_COMPARE_RESULT_NOT_INSTALLED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
232 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants VERSION_COMPARE_RESULT_OLDER

Used With
VerProductCompareVersions

VERSION_COMPARE_RESULT_OLDER
Project: This information applies to InstallScript projects.

VERSION_COMPARE_RESULT_OLDER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerProductCompareVersions

VERSION_COMPARE_RESULT_SAME
Project: This information applies to InstallScript projects.

VERSION_COMPARE_RESULT_SAME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerProductCompareVersions

VERSION_PREVIOUS_VERSION_DELIMITER
Project: This information applies to InstallScript projects.

VERSION_PREVIOUS_VERSION_DELIMITER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerProductCompareVersions

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

233

Chapter 4: Predefined Constants VER_DLL_NOT_FOUND

VER_DLL_NOT_FOUND
VER_DLL_NOT_FOUND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerSearchAndUpdateFile

VER_UPDATE_ALWAYS
VER_UPDATE_ALWAYS is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerUpdateFile VerSearchAndUpdateFile

VER_UPDATE_COND
VER_UPDATE_COND is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
VerSearchAndUpdateFile

VIDEO
VIDEO is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

VIRTUAL_MACHINE_TYPE
VIRTUAL_MACHINE_TYPE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
234

GetSystemInfo
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants VOLUMELABEL

VOLUMELABEL
VOLUMELABEL is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

WARNING
WARNING is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
MessageBox SprintfBox

WEB_BASED_SETUP
Project: This information applies to InstallScript projects.

WEB_BASED_SETUP is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

WELCOME
WELCOME is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Welcome

WHITE
WHITE is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 235

Chapter 4: Predefined Constants WILL_REBOOT

Used With
SetTitle

WILL_REBOOT
WILL_REBOOT is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or event handlers. You cannot change the value of a predefined constant.

Used With
RebootDialog SdFinishReboot

WINDOWS_SHARED
WINDOWS_SHARED is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Is

WINMAJOR
WINMAJOR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

WINMINOR
WINMINOR is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
GetSystemInfo

236

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants WOW64FSREDIRECTION

WOW64FSREDIRECTION
Project: This information applies to InstallScript projects.

WOW64FSREDIRECTION is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
Disable Enable

WRITE_DAC
WRITE_DAC is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS SetObjectPermissions

WRITE_OWNER
WRITE_OWNER is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions or assigned to one or more system variables. You cannot change the value of a predefined constant.

Used With
SERVICE_IS_PARAMS SetObjectPermissions

YELLOW
YELLOW is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
SetColor SetTitle
ISP-1800-RG00 237

InstallShield 2012 InstallScript Reference Guide

Chapter 4: Predefined Constants YES

YES
YES is a predefined constant that is used to represent a value that is passed to or returned by one or more built-in functions. You cannot change the value of a predefined constant.

Used With
AskYesNo SdLicense SdConfirmNewDir SdConfirmRegistration

_MAX_PATH
Project: This information applies to InstallScript projects.

MAX_PATH is a predefined constant that is used to represent the maximum length of a path variable that is passed to a Windows API function. The following sample code lines illustrate possible uses of _MAX_PATH:
string szPath[_MAX_PATH]; /* variable declaration */ ... Kernel32.GetTempPathA( _MAX_PATH, szPath ); /* Windows API function call */

238

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

5
Predefined Script Variables
This section includes a list of predefined script variables that are reserved during script compilation.

__FILE__
During script compilation this reserved identifier is replaced by a string that contains the fully qualified name of the source file in which __FILE__ resides. __FILE__ can be specified anywhere in a script where a string constant is allowed, but it is most useful when used with __LINE__ for simple debugging. For example, by constructing a statement like the one below and copying it to strategic locations in your source files during testing, you can easily associate specific parts of your setup with specific sections of your script as you observe your setup run.
SprintfBox (INFORMATION, "", "File: %s\nLine:%ld";, __FILE__, __LINE__);

Note that the path will be the location from which the file was compiled, not the location from which the setup is being run. If necessary, the ParsePath function can be called with __FILE__ in the second parameter to extract parts of the fully qualified file name. The code fragment below extracts the file name and displays it.
ParsePath (svReturnString, __FILE__, FILENAME); MessageBox (svReturnString, INFORMATION);

For more complete and powerful debugging, use the InstallScript Debugger by clicking Debug on the Build menu in InstallShield. For more information, see the InstallScript Debugger Help.

__LINE__
During setup compilation, this reserved identifier is replaced by the number of the source file line in which __LINE__ resides. Note that __LINE__ can be specified anywhere in a script where a number constant is allowed, but it is most useful when used with __FILE__ for simple debugging. For example, by constructing a statement like the one below and copying it to strategic locations in your source files during testing, you can easily associate specific parts of your setup with specific sections of your script as you observe your setup run.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 239

Chapter 5: Predefined Script Variables BASICMSI

SprintfBox (INFORMATION, "", "File: %s\nLine:%ld", __FILE__, __LINE__);

For more complete and powerful debugging, use the InstallScript Debugger by clicking Debug on the Build menu in InstallShield. For more information, see the InstallScript Debugger Help.

BASICMSI
The BASICMSI script variable is defined for Basic MSI projects, but it is undefined and evaluates as zero in InstallScript MSI projects and in InstallScript projects.

Note: BASICMSI is not a preprocessor switch; therefore, you can use this script variable to create script code that will work differently in different project types without being recompiled.

You can use BASICMSI to write a single script that produces different behavior in the different project types by including code such as the following in your script:
if( BasicMSI ) then //Code for Basic MSI projects else //Code for InstallScript MSI or InstallScript projects endif;

INSTALLSCRIPTMSI
INSTALLSCRIPTMSI is defined in InstallScript MSI and Basic MSI projects, but it is undefined and evaluates as zero in InstallScript projects (and in InstallShield Professional projects).

Note: INSTALLSCRIPTMSI is not a preprocessor switch; therefore, you can use this script variable to create script code that will work differently in the two project types without being recompiled.

You can use INSTALLSCRIPTMSI to write a single script that produces different behavior in the different project types by including code such as the following in your script:
if( INSTALLSCRIPTMSI ) then //Code for InstallScript MSI and Basic MSI projects... else //Code for InstallScript projects... endif;

INSTALLSCRIPTMSIEEUI
The INSTALLSCRIPTMSIEEUI variable is set to enable an installation to determine at run time whether the InstallScript engine is used as the embedded user interface (UI) handler for an InstallScript MSI installation. This implementation is also known as the new style of InstallScript UI. If the InstallScript engine is used as the embedded user interface handler for an InstallScript MSI installation, INSTALLSCRIPTMSIEEUI is set to TRUE. If it is not an embedded user interface handler, this variable is set to FALSE.
240 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 5: Predefined Script Variables ISUS_PRODUCT_CODE

Tip: For information on using the InstallScript engine as an embedded user interface handler for an InstallScript MSI installation, see Using the InstallScript Engine as an External vs. Embedded UI Handler for InstallScript MSI Installations.

You can use INSTALLSCRIPTMSIEEUI to write a single script that produces different behavior for the different user interface styles by including code such as the following in your script:
if( INSTALLSCRIPTMSIEEUI ) then //Code for new-style InstallScript MSI installations //(InstallScript engine as an embedded UI handler)... else //Code for traditional-style InstallScript MSI installations (InstallScript engine as an external UI handler)... endif;

ISUS_PRODUCT_CODE
This is a read-write script variable which is set to PRODUCT_GUID during initialization. Like PRODUCT_GUID, this variable is not linked to a text-sub. Therefore, if customized, this script variable must be customized each time the setup is run, even during maintenance mode.

SERVICE_IS_PARAMS
Project: This information applies to InstallScript projects.

This system variable is initialized automatically during installation initialization by a call to ServiceInitParams.

Note: Certain InstallScript service functions internally call the Windows API functions OpenSCManager, CreateService, or ChangeServiceConfig. The following members of the structured variable SERVICE_IS_PARAMS specify the corresponding arguments for these Windows API functions: SERVICE_IS_PARAMS.lpMachineName SERVICE_IS_PARAMS.lpDatabaseName SERVICE_IS_PARAMS.dwDesiredAccess SERVICE_IS_PARAMS.dwServiceType SERVICE_IS_PARAMS.dwStartType SERVICE_IS_PARAMS.dwErrorControl SERVICE_IS_PARAMS.lpLoadOrderGroup SERVICE_IS_PARAMS.lpdwTagId SERVICE_IS_PARAMS.lpDependencies SERVICE_IS_PARAMS.lpServiceStartName SERVICE_IS_PARAMS.lpPassword

The following members of SERVICE_IS_PARAMS control how the installation behaves when waiting for a service to reach a desired state. See the descriptions for each member for additional information.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

241

Chapter 5: Predefined Script Variables SERVICE_IS_PARAMS

SERVICE_IS_PARAMS.nWaitHintMin SERVICE_IS_PARAMS.nWaitHintMax SERVICE_IS_PARAMS.nStartServiceWaitCount SERVICE_IS_PARAMS.nStopServiceWaitCount

The SERVICE_IS_PARAMS script variable has the following members:

Table 5-1: SERVICE_IS_PARMS Parameters Member dwServiceType Description This member can be set to these predefined constants:

dwStartType

SERVICE_WIN32_OWN_PROCESS SERVICE_WIN32_SHARE_PROCESS SERVICE_KERNEL_DRIVER SERVICE_FILE_SYSTEM_DRIVER SERVICE_ADAPTER SERVICE_RECOGNIZER_DRIVER SERVICE_INTERACTIVE_PROCESS

This member can be set to these predefined constants:

dwErrorControl

SERVICE_BOOT_START SERVICE_SYSTEM_START SERVICE_AUTO_START SERVICE_DEMAND_START SERVICE_DISABLED

This member can be set to these predefined constants:

nWaitHintMin

SERVICE_ERROR_IGNORE SERVICE_ERROR_NORMAL SERVICE_ERROR_SEVERE SERVICE_ERROR_CRITICAL

Specifies the minimum dwWaitHint wait time (in milliseconds). If a service specifies a dwWaitHint smaller than nWaitHintMin, nWaitHintMin is used instead as the wait time. This applies to both starting and stopping services. The default value of this member variable is 1000 (1 second), and is set by calling ServiceInitParams. See the MDSN documentation for more information on how a service sets dwWaitHint.

nWaitHintMax

Specifies the maximum dwWaitHint wait time (in milliseconds). If a service specifies a dwWaitHint longer than nWaitHintMax, nWaitHintMax is used instead as the wait time. This applies to both starting and stopping services. The default value of this member variable is 10000 (10 seconds), and is set by calling ServiceInitParams. See the MDSN documentation for more information on how a service sets dwWaitHint.

242

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 5: Predefined Script Variables SERVICE_IS_STATUS

Table 5-1: SERVICE_IS_PARMS Parameters (cont.) Member nStartServiceWaitCount Description Specifies the service start timeout in seconds. This value can be set to a specific value to force the installation to stop waiting after the specified interval regardless of whether the service has reached the desired state.

Important: Unlike nWaitHintMax, if a service specifies a long dwWaitHint, the installation does not interrupt this wait regardless of the value of this parameter. Therefore, it is recommended that this value not be changed from the default value of INFINITE set by ServiceInitParams. Instead, update nWaitHintMax to prevent an undesired wait interval. nStopServiceWaitCount Specifies the service stop timeout in seconds. This value can be set to a specific value to force the setup to stop waiting after the specified interval regardless of whether the service has reached the desired state.

Important: Unlike nWaitHintMax, if a service specifies a long dwWaitHint, the installation does not interrupt this wait regardless of the value of this parameter. Therefore, it is recommended that this value not be changed from the default value of INFINITE set by ServiceInitParams. Instead, update nWaitHintMax to prevent an undesired wait interval.

Additional Information
For more information about the Windows API functions OpenSCManager, CreateService, or ChangeServiceConfig, consult the Windows API documentation.

SERVICE_IS_STATUS
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

243

Chapter 5: Predefined Script Variables SERVICE_IS_STATUS

When you call ServiceGetServiceState, this structured variable returns identification information about the service. This system variable is of type SERVICE_IS_STATUS; it has the following members:
Table 5-2: SERVICE_IS_STATUS Parameters Member dwServiceType Meaning The type of service. This member can be one of the following values.

SERVICE_FILE_SYSTEM_DRIVERThe service is a file system driver. SERVICE_KERNEL_DRIVERThe service is a device driver. SERVICE_WIN32_OWN_PROCESSThe service runs in its own process. SERVICE_WIN32_SHARE_PROCESSThe service shares a process with other services.

If the service type is either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, the following type may also be specified.

dwCurrentState

SERVICE_INTERACTIVE_PROCESSThe service can interact with the desktop.

The current state of the service. This member can be one of the following values.

dwWin32ExitCode

SERVICE_CONTINUE_PENDINGThe service continue is pending. SERVICE_PAUSE_PENDINGThe service pause is pending. SERVICE_PAUSEDThe service is paused. SERVICE_RUNNINGThe service is running. SERVICE_START_PENDINGThe service is starting. SERVICE_STOP_PENDINGThe service is stopping. SERVICE_STOPPEDThe service is not running.

A Win32 error code that the service uses to report an error that occurs when it is starting or stopping. To return an error code specific to the service, the service must set this value to ERROR_SERVICE_SPECIFIC_ERROR to indicate that the dwServiceSpecificExitCode member contains the error code. The service should set this value to NO_ERROR when it is running and on normal termination. A service-specific error code that the service returns when an error occurs while the service is starting or stopping. This value is ignored unless the dwWin32ExitCode member is set to ERROR_SERVICE_SPECIFIC_ERROR.

dwServiceSpecificExitCode

244

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 5: Predefined Script Variables SERVICE_IS_STATUS

Table 5-2: SERVICE_IS_STATUS Parameters (cont.) Member dwCheckPoint Meaning A value that the service increments periodically to report its progress during a lengthy start, stop, pause, or continue operation. For example, the service should increment this value as it completes each step of its initialization when it is starting up. The user interface program that invoked the operation on the service uses this value to track the progress of the service during a lengthy operation. This value is not valid and should be zero when the service does not have a start, stop, pause, or continue operation pending. An estimate of the amount of time, in milliseconds, that the service expects a pending start, stop, pause, or continue operation to take before the service makes its next call to the Windows API function SetServiceStatus with either an incremented dwCheckPoint value or a change in dwCurrentState. If the amount of time specified by dwWaitHint passes, and dwCheckPoint has not been incremented, or dwCurrentState has not changed, the service control manager or service control program can assume that an error has occurred. The control codes that the service will accept and process in its handler function. A user interface process can control a service by specifying a control command in the Windows API function ControlService. By default, all services accept the SERVICE_CONTROL_INTERROGATE value. Table 5-3 lists the possible control codes for this member.

dwWaitHint

dwControlsAccepted

dwControlAccepted Control Codes

This table lists the possible control codes for dwControlAccept script variable.
Table 5-3: dwControlsAccepted Control Codes Control Code SERVICE_ACCEPT_NETBINDCHANGE Description Windows 2000 and later: The service is a network component that can accept changes in its binding without being stopped and restarted. This control code allows the service to receive SERVICE_CONTROL_NETBINDADD, SERVICE_CONTROL_NETBINDREMOVE, SERVICE_CONTROL_NETBINDENABLE, and SERVICE_CONTROL_NETBINDDISABLE notifications. SERVICE_ACCEPT_PARAMCHANGE Windows 2000 and later: The service can reread its startup parameters without being stopped and restarted. This control code allows the service to receive SERVICE_CONTROL_PARAMCHANGE notifications. SERVICE_ACCEPT_PAUSE_CONTINUE The service can be paused and continued. This control code allows the service to receive SERVICE_CONTROL_PAUSE and SERVICE_CONTROL_CONTINUE notifications.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

245

Chapter 5: Predefined Script Variables SERVICE_IS_STATUS

Table 5-3: dwControlsAccepted Control Codes (cont.) Control Code SERVICE_ACCEPT_SHUTDOWN Description The service is notified when system shutdown occurs. This control code allows the service to receive SERVICE_CONTROL_SHUTDOWN notifications. Note that the Windows API function ControlService cannot send this notification; only the system can send it. SERVICE_ACCEPT_STOP The service can be stopped. This control code allows the service to receive SERVICE_CONTROL_STOP notifications.

The dwControlAccept value can also contain the following extended control codes, which are supported only by service handler functions that are used with the Windows API function RegisterServiceCtrlHandlerEx.
Table 5-4: Extended Control Codes for dwControlAccept Control Code Description

SERVICE_ACCEPT_HARDWAREPROFILECH Windows 2000 and later: The service is notified when the computer's ANGE hardware profile has changed. This enables the system to send SERVICE_CONTROL_HARDWAREPROFILECHANGE notifications to the service. SERVICE_ACCEPT_POWEREVENT Windows 2000 and later: The service is notified when the computer's power status has changed. This enables the system to send SERVICE_CONTROL_POWEREVENT notifications to the service. Whistler: The service is notified when the computer's session status has changed. This enables the system to send SERVICE_CONTROL_SESSIONCHANGE notifications to the service.

SERVICE_ACCEPT_SESSIONCHANGE

246

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

6
Data Types and Predefined Structures
Data Types
InstallScript supports the following data types. Note that some data types can be entered in either lowercase or uppercase letters:
Table 6-1: Data Types Data Type binary BINARY Description Indicates binary data (specified in a string variable) to be passed to or retrieved from an external DLL function. Unlike the STRING or WSTRING data types, when the BINARY data type is specified, the InstallScript engine does not attempt to interpret the data as a string or perform any type of data conversion or validation; thus, this data type is used when passing binary data that may or may not consist of valid string characters. Note that this data type can be used only in a prototype of an external DLL function. If this data type is used for a variable instance or as a parameter for a non-DLL InstallScript function, compile error C8116 error occurs. If a standard InstallScript string is passed through the BINARY data type, the characters in the string are passed as ASCII characters. Therefore, the binary type is similar to the STRING data type, not the WSTRING data type, for valid string characters. BOOL Boolean data: either TRUE (1) or FALSE (0). Variables of this type should not be used to store any other values. Like C++, InstallScript evaluates non-zero values as TRUE; only the value of zero is evaluated as FALSE. Normally, the value of one is used to indicate TRUE.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

247

Chapter 6: Data Types and Predefined Structures

Table 6-1: Data Types (cont.) Data Type char CHAR Description Character data: a single 8-bit signed character. When a literal character appears in a script, it must be enclosed within single or double quotation marks. Note that you can assign a numeric ASCII value to a character value. To display a char variable as a character, use the Format Specifiers %c with the function SprintfBox. To display the numeric value of a char variable use the specifier %d. InstallScript character variable types are signed; therefore extended ASCII characters will be interpreted as negative numbers when interpreted numerically. To avoid this problem, assign the value to a number variable; then AND (&) the number variable with the value 255 before interpreting the number. HWND Handle to a window. The HWND variable type also can be used to store any other type of handle valid in Windows. HWND variables are normally initialized using the CmdGetHwndDlg or GetWindowHandle functions. Internally, HWND variables are equivalent to the data type NUMBER. Equivalent to the number type; provided for convenience.

int INT LIST

Pointer to an InstallScript list. LIST variables are always initialized and uninitialized using the ListCreate and ListDestroy functions. Internally, LIST variables are equivalent to the data type NUMBER. Equivalent to the NUMBER type; provided for convenience.

long LONG LPSTR

Equivalent to the POINTER type; provided for convenience. For more information, see Pointers.

LPWSTR

Equivalent to the WPOINTER type; provided for convenience. For more information, see Pointers.

number NUMBER

Signed four-byte integer. Number is the recommended data type for storing numeric data. The data type is similar to the LONG variable type of other programming languages. It can hold any value between -2,147,483,648 and +2,147,483,647. Note that all numeric data types in InstallScript are equivalent to the NUMBER variable type. A reference to a COM object. The reference is returned by the CreateObject function and assigned to the object variable using the set keyword.

object OBJECT pointer POINTER

A pointer to data. In the case of a pointer to a string variable, the data pointed to is an ANSI string. Pointer variables are normally initialized by using the address-of (&) operator to assign the address of a variable to the pointer variable. For more information, see Pointers.

short SHORT
248

Equivalent to the NUMBER type; provided for convenience.

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 6: Data Types and Predefined Structures

Table 6-1: Data Types (cont.) Data Type string STRING Description An array of Unicode characters (two bytes per character). String variables, which are similar to arrays of characters in the C++ language, are NULL terminated. However, InstallShield does not support multiple NULL-terminated strings in the same string variable. String variables can be declared with an explicit size of up to 65,535 characters. Strings variables that are declared without an explicit size are automatically sized by InstallShield. Note that string concatenation in a setup script is performed by using the concatenation operator, which is a plus sign (+). Strings to be concatenated are positioned as operands on either side of the operator, as shown in the statement below, which appends the value of szLastName to the value of szFirstName and assigns the resulting string to szFullName:
szFullName = szFirstName + szLastName;

To display a string variable, use the SprintfBox function with the format specifier %s, or use the MessageBox function.

Note: You can declare string variables as STRING in InstallScript code; string variables that are declared this way in InstallScript code are stored as Unicode strings in string tables. However, if you want to store Unicode strings in structures that are passed outside of the InstallScript codefor example, to a DLL functionyou may need to use the WSTRING type when declaring the strings as structure members in your InstallScript code. For more information, see Data Structures. variant VARIANT Any kind of data: character, string, numeric, object reference, and so on. It is recommended that you use the other data types whenever possible; the VARIANT data type is necessary only when declaring a script-defined function that takes an array as an argument, for example:
prototype number AverageValue( variant ); function OnBegin( ) number nAverage , nArray(10); begin /* Assign values to array elements here. */ /* Pass the array to the function. */ nAverage = AverageValue( nArray ); end;

Note that the VARIANT data type cannot be defined within a data structure. void VOID Void is not a true data type, in the sense that a variable cannot be declared as type void. Void is only used in function prototypes to indicate that the function does not return a value, as in the following:
prototype void Subroutine(int); function void Subroutine(int); begin // perform operations, but // do not return a value end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

249

Chapter 6: Data Types and Predefined Structures

Table 6-1: Data Types (cont.) Data Type wpointer WPOINTER Description A pointer to string data. The POINTER type should be used in all cases except when a pointer to Unicode string data is needed. Pointer variables are normally initialized by using the address-of (&) operator to assign the address of a variable to the pointer variable. For more information, see Pointers. wstring WSTRING Same as STRING except that, unlike STRING, it can be used when declaring DLL function calls in which a wide-character string argument or Unicode string argument is expected. For example:
prototype long Kernel32.GetWindowsDirectoryW(BYREF wstring, int);

You can pass a string variable in a WSTRING argument; for example:

wstring svWinDir; ... GetWindowsDirectoryW(svWinDir, 1024);

Note: You can declare string variables as STRING in InstallScript code; string variables that are declared this way in InstallScript code are stored as Unicode strings in string tables. However, if you want to store Unicode strings in structures that are passed outside of the InstallScript codefor example, to a DLL functionyou may need to use the WSTRING type when declaring the strings as structure members in your InstallScript code. For more information, see Data Structures.

Note: InstallScript does not provide unsigned or floating-point data types.

Predefined Structures
InstallScript supports the following predefined structures:
Table 6-2: Predefined Structures Predefined Structure _FONTFILEINFO Description This is a data structure that is passed to the OnInstalledFontFile and OnUninstallingFontFile event handlers. It has the following members:

string szFileName[_MAX_PATH]The complete path to the font file being installed on the system string szFaceName[_MAX_PATH]The face name of the font being installed (if you specify the name for the font file in InstallShield)

Note that the information in the structure is passed to the event handler so that the event handler can use the information. Thereafter, the values of the structure are used by the installation. Therefore, changing the structure members does not have any effect on the installation.

250

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 6: Data Types and Predefined Structures Arrays

Table 6-2: Predefined Structures (cont.) Predefined Structure _LAAW_PARAMETERS Description For a list of this data structure's members and their purposes and permitted values, see LAAW_PARAMETERS. For a list of this data structure's members and their purposes and permitted values, see SERVICE_IS_PARAMS. For a list of this data structure's members and their purposes and permitted values, see SERVICE_IS_STATUS. This is a data structure that contains the constituent parts of a URL. This structure is similar to the Windows API structure URL_COMPONENTS. For an example of the use of this structure, see ParseUrl. This structure has the following members:

_SERVICE_IS_PARAMS

_SERVICE_IS_STATUS

ISURL_COMPONENTS

PROCESS_INFORMATION

szSchemeString value that contains the scheme name. nInternetSchemeNumeric value that indicates the Internet protocol scheme; equals 3 for HTTP and 4 for HTTPS. szUserNameString value that contains the user name. szPasswordString value that contains the password. szHostNameString value that contains the host name. nInternetPortPort number. szUrlPathString value that contains the URL path. szExtraInfoString value that contains the extra information (for example, ?something or #something).

For a list of this data structure's members and their purposes and permitted values, see LAAW_PROCESS_INFORMATION. For a list of this data structure's members and their purposes and permitted values, see LAAW_STARTUPINFO.

STARTUPINFO

Arrays
You can declare and use any InstallScript data type as an array. To declare a variable as an array, append an open parenthesis and a close parenthesis, with an array size optionally between the parentheses, to the variable name in the declaration. For example, the following declares a variable called nArray to be an array containing 10 NUMBER elements:
NUMBER nArray(10);

If you do not declare an array size, for example,

NUMBER nArray( );

the array size defaults to zero. You can resize arrays in the script by using the Resize operator. You can get the size of an array by using the SizeOf operator. Use the following syntax to assign values to array elements:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

251

Chapter 6: Data Types and Predefined Structures Constant Data

Syntax
<array variable name>(<array index>) = <value>;

For example:
nArray(0) = 1; /* Array indexing begins with zero. */ nArray(5) = 17;

When declaring a script-defined function that takes an array as an argument, do not use an array as the parameter data type; for example:
prototype NUMBER AverageValue( NUMBER( ) ); /* This will not compile. */

Instead, use the VARIANT data type; for example:

prototype NUMBER AverageValue( VARIANT ); function OnBegin( ) NUMBER nAverage, nArray(10); begin /* Assign values to array elements here. */ /* Pass the array to the function. */ nAverage = AverageValue( nArray ); end;

Constant Data
A constant is a named data item with a defined value. InstallShield supports two types of constants:

Predefined constants, such as TRUE and RESET, are part of InstallScript. These constants, which are used as function parameters and return values for built-in functions, cannot be redefined in the script. Attempting to redefine a predefined constant results in a compiler error. User-defined constants are declared by the programmer as needed for individual scripts. Although a user-defined constant can be redefined after the initial declaration, it is generally not considered good programming practice to do so.

User-defined constants are declared with a #define preprocessor statement. (InstallScript does not support the const keyword for declaring variable constants as the C++ language does.) String constants must be enclosed within quotation marks; numeric constants are defined without quotation marks and contain only numeric characters. Once declared, a string constant can be used anywhere that a string literal can be used. Likewise, number constants can be used anywhere that a numeric literal can be used. In the following example, a string constant and a numeric constant are declared:
#define COMPANY_NAME "Example_Company" #define MAXCOUNT 1000

A constant name must follow the rules for InstallScript identifiers. By convention, constant identifiers are created with all uppercase characters. InstallScripts predefined constants follow that convention.

252

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 6: Data Types and Predefined Structures Data Structures

Data Structures
A data structure is a named data item that consists of logically related variables, called members. In many programming languages, data structures are called records, and the variables within records are called fields. In InstallScript, data structures are similar in form and function to structures in C. They can include members of different data types, and those members within the data structure can be referenced directly by using the member operator (.).

Defining a Data Structure

To define a data structure, use the keyword typedef and follow it with the name of the data structure. Fields in the structure must be defined within a begin...end block, as shown in the example below, which defines a structure called EMPLOYEE. The data structure EMPLOYEE includes three variables: a string variable for an employees name, a string variable for an employees department, and a number variable for an employees phone extension.
typedef EMPLOYEE begin STRING szName[50]; STRING szDepartment[50]; NUMBER nExtension; end;

When you define a data structure, you are actually defining a new data type. To use a data structure within a program, you must first declare a variable of that type. To do that, use the name of the defined data structure as the data type and follow it with an identifier, as shown in the example below, which creates a variable of type EMPLOYEE.
EMPLOYEE structEmployee;

To reference members of the structure variable, use the member operator ( . ). In the example below, literal values are assigned to each member of structEmployee.
structEmployee.szName = "I. S. Coder"; structEmployee.szDepartment = "Development"; structEmployee.nExtension = 555;

Restrictions
The following restrictions apply to structures:

You cannot assign the contents of one structure to another structure with the assignment operator, as in newstruct = struct1. Instead, you must copy the structure one element at a time. You must specify the size of all STRING declarations in a structurethe autosizing functionality in InstallScript does not work in typedef statements. You cannot declare a structure within a function. You cannot use the BYREF operator with a structure, nor can you pass a structure member in a parameter that was declared with the BYREF operator. To modify a member of a user-defined structure in a user-defined function, pass a pointer to the structure and then use the Structure Pointer Operator (->) to access the data within the function. Referencing a pointer before the address of a data structure has been assigned to the pointer results in a run-time error.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

253

Chapter 6: Data Types and Predefined Structures Data Structures

Unicode Support for Structures

Structures in InstallScript can contain any basic data type, including strings and pointers, or other structures. If a structure needs to contain a Unicode string and the structure is passed to an external DLL, the InstallScript engine can distinguish between string member types in a structure, and then size the structure and calculate member offsets correctly. String members that need to be stored and passed as Unicode can be declared with the WSTRING type. Note that if a Unicode string is declared with the STRING type and the string is used in a structure, the InstallScript engine treats the string as ANSI when passing it to an external DLL. As a result, the size of the structure and member offsets in the structure could be wrong, causing the DLL to incorrectly read or write data related to the structure. Pointer members in structures can be declared as WPOINTER. This enables you to store pointers to Unicode strings in a structure.

Examples
Like C, InstallScript allows you to nest or embed data structures. For example, suppose you wanted to create a structure that could be used to define the upper-left and lower-right coordinates of a rectangle. Each coordinate consists of two values: an x value and a y value. You could define a structure that consists of four members: the x and y positions of the upper-left corner and the x and y positions of the lower-right corner. However, since each x and y pair is a logical unit, you might first define a structure called POINT that has two members defining a vertical and horizontal position. Then you could define a structure called RECT that includes two members of type POINT, one to define the upper left coordinate, another to define the lower right coordinate. These two structures are shown below:
// Define a point structure. typedef POINT begin SHORT nX; SHORT nY; end; // Use nested point structures to define a rectangle structure. typedef RECT begin POINT UpperLeft; POINT LowerRight; end;

When a structure is to be referenced by a pointer to that structure, you must use the structure pointer operator ( -> ) to address members of the structure. In the example below, a variable of type RECT is declared, a pointer to the structure is declared, and then the address of the RECT variable is assigned to the pointer. Finally, the structure pointer operator is used to initialize each member to 0.
RECT Rectangle; RECT POINTER pRect; pRect = &Rectangle; pRect->UpperLeft.nX pRect->UpperLeft.nY pRect->LowerRight.nX pRect->LowerRight.nY

= = = =

0; 0; 0; 0;

The following script presents a more complete demonstration of structure pointers, nested structures, and structure pointer dereferencing with the structure pointer operator.
254 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 6: Data Types and Predefined Structures Data Structures

// Use a structure to define a point. typedef POINT begin SHORT nX; SHORT nY; end; // Use nested structures to define a rectangle. typedef RECT begin POINT UpperLeft; POINT LowerRight; end; // Declare a rectangle structure variable. RECT Rectangle; // Define a pointer to a RECT structure. RECT POINTER pRect; // Declare a function to display structure contents. prototype ShiftRectBy2(RECT POINTER); . . . // Get a pointer to the Rectangle structure. pRect = &Rectangle; // Define the points that define the rectangle. pRect->UpperLeft.nX = 100; pRect->UpperLeft.nY = 400; pRect->LowerRight.nX = 200; pRect->LowerRight.nY = 100; // Display point x and y values before calling ShiftRectBy2. SprintfBox (INFORMATION, "BEFORE calling ShiftRectBy2", "pRect->UpperLeft.nX = %d\n" + "pRect->UpperLeft.nY = %d\n" + "pRect->LowerRight.nX = %d\n" + "pRect->LowerRight.nY = %d\n", pRect->UpperLeft.nX, pRect->UpperLeft.nY, pRect->LowerRight.nX, pRect->LowerRight.nY ); // Shift the rectangle 2 up and 2 to the right. ShiftRectBy2(pRect); // Display point x and y values after calling ShiftRectBy2. SprintfBox (INFORMATION, "AFTER calling ShiftRectBy2", "pRect->UpperLeft.nX = %d\n" + "pRect->UpperLeft.nY = %d\n" + "pRect->LowerRight.nX = %d\n" + "pRect->LowerRight.nY = %d\n", pRect->UpperLeft.nX, pRect->UpperLeft.nY, pRect->LowerRight.nX, pRect->LowerRight.nY );
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 255

Chapter 6: Data Types and Predefined Structures Language IDs

// Define the rectangle shifting function. function ShiftRectBy2(pR) begin pR->UpperLeft.nX = pR->UpperLeft.nX + 2; pR->UpperLeft.nY = pR->UpperLeft.nY + 2; pR->LowerRight.nX = pR->LowerRight.nX + 2; pR->LowerRight.nY = pR->LowerRight.nY + 2; end;

Language IDs
InstallShield provides language constants for all languages supported by Windows. However, most of these constants are not supported for the designation of language-specific components and language filtering. InstallScript constants can be used in the following contexts.

Parameter for FeatureFilterLanguage

InstallScript language constants are used as the second parameter to the function FeatureFilterLanguage. In this context, the language constant specifies which files to filter or unfilter. Only supported language constants, which are listed in the supported language table should be used for this purpose. Using an unsupported language constant for component filtering has no effect since components designated for an unsupported language are filtered (not included) during the media build and so cannot be installed.

Return Value for GetSystemInfo

A language constant serves as the value returned in nvResult by function GetSystemInfo when it is called with the constant LANGUAGE in the nItem parameter. In this context, any of the language constants that are listed in ISRTDefs.h can be returned because Windows supports all the language constants.

Note: If your installation includes language filtering based on these return values, you must use a switch statement to convert constants returned by this function into one of the constants supported for language filtering.

Language Constant Reference

For a complete list of language constants that are supported by InstallShield, as well as their numeric equivalents, refer to the file ISRTDefs.h, which is located in the Script\Include folder within the InstallShield Program Files folder. For a list of supported languages and the appropriate InstallScript constants, see Language Support for InstallScript.

Note: The language that the setup is using to display prompts and messages is stored in the system variable SELECTED_LANGUAGE.

256

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 6: Data Types and Predefined Structures Pointers

When the language selection dialog is used by a multilanguage installation to allow the end user to select the installation language during setup initialization, the language dialog will display the Windows equivalent names. Because these names are generated by Windows, they will be localized to the version of Windows under which the installation is being run.

Pointers
A pointer is a variable that contains the address of another variable. To declare a pointer, use the keyword POINTER or WPOINTER followed by a variable name, as shown in the following two sample lines of code:
POINTER pPointerName; WPOINTER pWPointerName;

To declare a pointer that will be used to access the members of a data structure, precede the keyword POINTER or WPOINTER with the structure type:
typedef RECT begin SHORT sX; SHORT sY; end; RECT Rectangle; RECT POINTER pRect;

Use the address operator (&) to assign the address of a variable to a pointer variable:
pPointerName = &MyStructure; pNum = &nvNumber; pString = &svString;

When you are defining a function that takes a pointer to a structure as a parameter, use the structure name with POINTER or WPOINTER in the function prototype, as shown below. Note that any function prototype that specifies a pointer to a structure as one of its parameters must be declared after the structure declaration.
typedef RECT begin SHORT sX; SHORT sY; end; RECT Rectangle; RECT POINTER pRect; prototype SizeRectangle(RECT POINTER); . . . pRect = &Rectangle; SizeRectangle(pRect); . . . function SizeRectangle(pRectangle) begin pRectangle->sX = 10;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

257

Chapter 6: Data Types and Predefined Structures Pointers

pRectangle->sY = 5; end;

Passing Pointers to Strings to Functions that Are Implemented Outside InstallScript Code
The InstallScript compiler lets you pass pointers to Unicode or ANSI strings to functions that are implemented outside script. For example, if you want to call a DLL function that accepts pointers to strings in its parameters, the DLL function prototype would look something like the following in C or C++:
void __stdcall MyDllFunction(LPCSTR pszString);

In InstallScript, the function could be prototyped as follows:

prototype DLL.MyDllFunction(POINTER);

You can use the address-of operator (&) to call the function and pass a pointer to a string:
DLL.MyDllFunction(&myString);

When the script engine makes this function call, the data in string myString is passed through a pointer value to MyDllFunction. MyDllFunction receives a pointer to an ANSI representation of the string that is contained in myString. The pointer type WPOINTER (or optionally wpointer or LPWSTR) lets you pass pointers to Unicode strings to functions outside of script. For example, if the DLL uses Unicode strings, you could change its prototype in C or C++ to the following:
void __stdcall MyDllFunction(LPCWSTR pszString);

In InstallScript, the only change that is required to pass a Unicode string pointer to a DLL that uses Unicode strings is the prototype, which would contain the WPOINTER type, as follows:
prototype DLL.MyDllFunction(WPOINTER);

When the DLL function is called in the running script, the engine passes a pointer to a Unicode copy of the string that is stored in myString instead of an ANSI version.

Using STRING and WSTRING Instead of Pointers

In most cases, you do not need to use pointers to pass strings to external DLL functions. The STRING and WSTRING types may be used in place of POINTER or WPOINTER. If a DLL function expects an ANSI string, you can use the STRING type; if a DLL function expects a Unicode string, you can use the WSTRING type. Using BYREF and BYVAL will allow for passing a string that either can be modified by the external DLL function or not. Thus, if you use the following prototype for the function, an ANSI string could be passed by value or by references (modifying the prototype to BYREF as needed):
prototype DLL.MyDllFunction(byval string);

Changing the parameter type to BYVAL WSTRING allows a Unicode version of the string to be passed instead of the ANSI version.

258

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

7
Variable Data
A variable is a named data item whose value can change during program execution.

Variable Declaration
Format A variable must be declared in the following format:
data_type VariableName1[, VariableName2 [,...]];

Rules Variable declaration must follow these rules:

A variable name can have a maximum of 32 characters. When more than one variable name is specified in a single declaration, the names must be separated by commas. Each variable declaration must be terminated with a semicolon.

Caution: The names of InstallScript variables and functions are case sensitive. For example, svItemCounter is not equivalent to svITEMCOUNTER.

Variable Declaration Example

In the following example, seven variables are declared. Note that the last declaration creates three numeric variables.
BOOL bValidEntry; LONG lPopulation; //String explicitly sized STRING szUserName[128]; //String autosized

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

259

Chapter 7: Variable Data Global vs. Local Variables

STRING szMessage; NUMBER nFileSize, nDirSize, nDiskSpace;

Declaring String Variables

You can declare a string variable with or without an explicit size. String variables that are not declared with an explicit size are then sized automatically during a setup to accommodate the values assigned to them. Autosizing is recommended for all string variables except those that will be passed to an external (DLL or Windows API) functionin these cases, the string's size must be declared explicitly. The maximum size of a string is 65534 characters.

Global vs. Local Variables

Variables may be either global or local:

A variable is global if it is declared outside of the main program block and not within a function. Global variables are visible and available to all statements in a setup script that follow its declaration. A variable is local if it is declared between the function declaration and the keyword begin within that function. Local variables are visible and available only within the function where they are declared.

Project: InstallScript events are not used in Basic MSI and merge module projects; therefore, all InstallScript code for these project types must be written in InstallScript custom actions. Global variables do not share state between these custom action invocations.

Note: InstallScript system variables are global and therefore are visible to the main program and to all functions in a script.

In the following example, the variable nVisibleEverywhere can be referenced by any statement in the script. The variable nVisibleOnlyToFunctions may be referenced only by the functions. The variable nVisibleOnlyToSecondFunction cannot be referenced by the main program or by FirstFunction. The variable szString is local to FirstFunction.
prototype FirstFunction(); prototype SecondFunction(); NUMBER nVisibleEverywhere; . . . nVisibleEverywhere = 10; FirstFunction(); SecondFunction(); . . . NUMBER nVisibleOnlyToFunctions; function FirstFunction()

260

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data Global vs. Local Variables

STRING szString; begin szString = "Local to FirstFunction"; nVisibleOnlyToFunctions = 20; end; NUMBER nVisibleOnlyToSecondFunction; function SecondFunction() begin nVisibleOnlyToSecondFunction = 30; end;

Although identifiers in a script must be unique, it is valid for a local variable to have a name identical to that of a global variable, or for one function to declare a local variable that has the same name as a local variable declared in another function. These exceptions are allowed because InstallShield qualifies local variable names based on the function with which they are associated. In the example below, the global variable szVal is not affected by the action of AFunction, which has a local variable of the same name; the function MessageBox displays the string YES, which was the value assigned to the global variable szVal.
STRING szVal; prototype AFunction(); . . . szVal = "YES"; AFunction(); MessageBox(szVal, INFORMATION); . . . function AFunction() STRING szVal; begin szVal = "NO"; end;

Parameter names in function definitions are considered to be local variables. If a global variable is passed to a function whose parameter has the same name as the global variable, the value of that global variable will not be changed (unless the parameter was specified with the BYREF operator in the function prototype). In the following example, AFunction has no effect on the global variable szVal; the script displays the string YES.
STRING szVal; prototype AFunction(STRING); . . . szVal = "YES"; AFunction(szVal); MessageBox(szVal, INFORMATION);

. . . function AFunction(szVal) begin szVal = "NO"; end;

InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 261

Chapter 7: Variable Data String Variables

String Variables
For information about string variables, refer to the following topics:

String Indexing String Size and Autosize

String Indexing
A string variable is an array of Unicode characters with a null terminator. You can reference individual characters within a string by specifying the string name followed by an index value within square brackets. Note that the first character in a string is in position 0. In the example below, the function BlankLeadingZeros uses the string indexing technique to replace leading zeros in the string representation of a number with blank characters.
prototype BlankLeadingZeros(BYREF STRING); function BlankLeadingZeros(szString) INT iVal, iLength; begin iVal = 0; iLength = StrLength (szString); while (szString[iVal] = "0") && (iVal <= iLength) szString[iVal] = " "; iVal++; endwhile; end;

String Size and Autosize

InstallShield Autosizing
When you declare a string variable without a size specification, InstallShield automatically sizes a string buffer for that variable. The allocation for the buffer occurs when you first assign a string to the variable. If later, you assign a longer string to that variable, InstallShield increases the memory allocation to accommodate the longer stringup to the amount of available memory. However, if you later assign a shorter string to an autosized variable, InstallShield does not decrease the memory allocation.

Caution: InstallShield's autosizing feature does not work in typedef statements; you must specify the size of all STRING declarations in a structure.

Specifying a String Size

When specifying a string size, you must declare one character position for the null terminator. For example, if you want your string to hold up to 128 characters, you must declare it with a length of 129 to allow room for the null terminator. For this reason, the minimum size of a string is 2. When you are using a string that you have declared with a size, you must be aware of how that string might be used with other strings. For example, consider the following function call:
262 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

STRING szQuestion[20], szDefault[20], svResult[50]; begin szQuestion = "Enter company name"; szDefault = "My Software Company"; AskText (szQuestion, szDefault, svResult);

The size of the string svResult should be greater than or equal to the size of the string szDefault. If not, then szDefault, if accepted, will not fit into the svResult variable returned by the function. The easiest way to avoid conflicts is to let InstallShield autosize all strings (except those in a typedef statement).

Caution: An autosized string variable that is passed by reference to a function is not autosized within the called function. If the function attempts to assign a value whose length is greater than the current size of that parameter, run-time error 401 occurs. To avoid this error, declare strings with a specific size when they are to be passed by reference to a function.

System Variables
System variables are predefined script variables that contain information such as the source path, the target path, the Windows folder, and the Windows system folder. InstallShield automatically initializes these system variables when the installation process begins, and it is not necessary to declare these variables in your script.

Project: Many Windows Installer directory propertiessuch as INSTALLDIR, AppDataFolder, and TempFolderare available directly as variables in your InstallScript code for Basic MSI and InstallScript MSI projects.

System Variables and Text Substitutions

Some of the system variables have corresponding text substitutions. The installation internally uses text substitution to set the values of certain system variables as shown in the following tables. You can use these text substitutions in your script in the same way that you use text substitutions that you have defined.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

263

Chapter 7: Variable Data System Variables

Writable System Variables and Text Substitutions

Table 7-1: Writable System Variables and Text Substitutions Script Variable ALLUSERS DISK1TARGET IFX_COMPANY_NAME Corresponding Text Substitution <PERUSER_INSTALL> <DISK1TARGET> <IFX_COMPANY_NAME> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. IFX_INSTALLED_DISPLAY_VERSIO <IFX_INSTALLED_DISPLAY_VERSION> N If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. IFX_INSTALLED_VERSION <IFX_INSTALLED_VERSION> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. IFX_MULTI_INSTANCE_SUFFIX IFX_PRODUCT_DISPLAY_NAME <IFX_MULTI_INSTANCE_SUFFIX> <IFX_PRODUCT_DISPLAY_NAME> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. IFX_PRODUCT_DISPLAY_VERSIO N <IFX_PRODUCT_DISPLAY_VERSION> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. IFX_PRODUCT_KEY <IFX_PRODUCT_KEY> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. Comments

264

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

Table 7-1: Writable System Variables and Text Substitutions (cont.) Script Variable IFX_PRODUCT_NAME Corresponding Text Substitution <IFX_PRODUCT_NAME> Comments If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. IFX_PRODUCT_VERSION <IFX_PRODUCT_VERSION> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. IFX_SETUP_TITLE <IFX_SETUP_TITLE> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. IFX_SUPPORTED_VERSIONS <IFX_SUPPORTED_VERSIONS> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. SHELL_OBJECT_FOLDER SRCDIR (Read from local) SRCDISK (Read from local) TARGETDIR TARGETDISK UNINST UNINSTALL_STRING <SHELL_OBJECT_FOLDER> <SRCDIR> <SRCDISK> <TARGETDIR> <TARGETDISK> <UNINST> <UNINSTALL_STRING>

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

265

Chapter 7: Variable Data System Variables

Read-Only System Variables and Text Substitutions

Table 7-2: Read-Only System Variables and Text Substitutions Script Variable COMMONFILES DISK1SETUPEXENAME ENGINECOMMONDIR ENGINEDIR FOLDER_APPDATA FOLDER_DOTNET_10 FOLDER_DOTNET_11 FOLDER_DOTNET_20 FOLDER_DOTNET_30 FOLDER_DOTNET_35 FOLDER_DOTNET_40 FOLDER_PERSONAL FOLDER_TEMP ISRES Corresponding Text Substitution <COMMONFILES> <DISK1SETUPEXENAME> <ENGINECOMMONDIR> <ENGINEDIR> <FOLDER_APPDATA> <FOLDER_DOTNET_10> <FOLDER_DOTNET_11> <FOLDER_DOTNET_20> <FOLDER_DOTNET_30> <FOLDER_DOTNET_35> <FOLDER_DOTNET_40> <PERSONALDIR> <FOLDER_TEMP> <ISRES> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. ISUSER <ISUSER> If this text substitution is defined in an object script, it applies to only that object, not to the main installation or any other objects in the installation. If it is defined in the main installation, it does not apply to any objects. MULTI_INSTANCE_COUNT PACKAGE_LOCATION PROGRAMFILES SELECTED_LANGUAGE SHAREDSUPPORTDIR <MULTI_INSTANCE_COUNT> <PACKAGE_LOCATION> <PROGRAMFILES> <SELECTED_LANGUAGE> <SHOW_PASSWORD_DIALOG> Comments

266

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

Table 7-2: Read-Only System Variables and Text Substitutions (cont.) Script Variable SHOW_PASSWORD_DIALOG SUPPORTDIR WINDIR WINDISK WINSYSDIR WINSYSDISK Corresponding Text Substitution <SHOW_PASSWORD_DIALOG> <SUPPORTDIR> <WINDIR> <WINDISK> <WINSYSDIR> <WINSYSDISK> Comments

ADDREMOVE
Project: This information applies to InstallScript projects.

The ADDREMOVE system variable is set equal to a non-zero value if the setup is run from Add or Remove Programs in the Control Panel and is set equal to FALSE otherwise. This system variable is read-only; if you attempt to assign a value to it, a compiler error results.

ADDREMOVE_COMBINEDBUTTON
Project: This information applies to InstallScript projects.

This system variable's value is used by the MaintenanceStart function to specify the existence of and data in the application uninstallation registry keys ModifyPath and UninstallString values, so as to specify whether the applications Add or Remove Programs entry displays separate Change and Remove buttons or a combined Change/Remove button. For more information on this variable, see MaintenanceStart. This system variable is initialized to FALSE.

ADDREMOVE_HIDECHANGEOPTION
Project: This information applies to InstallScript projects.

This system variables value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's ModifyPath, NoModify, and UninstallString values. The NoModify registry value specifies whether a Change button is displayed for the application in Add or Remove Programs in the Control Panel. The ModifyPath and UninstallString registry values specify the behaviors of the Change and Remove buttons.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

267

Chapter 7: Variable Data System Variables

This system variable is initialized based on the value that you specify in the Disable Change Button setting in the General Information view.

ADDREMOVE_HIDEREMOVEOPTION
Project: This information applies to InstallScript projects.

This system variable's value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's ModifyPath, NoRemove, and UninstallString values. The NoRemove registry value specifies whether a Remove button is displayed for the application in Add or Remove Programs in the Control Panel. The ModifyPath and UninstallString registry values specify the behaviors of the Change and Remove buttons. This system variable is initialized based on the value that you specify in the Disable Remove Button setting in the General Information view.

ADDREMOVE_STRING_REMOVEONLY
Project: This information applies to InstallScript projects.

This system variable's value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's UninstallString value, which specifies the behavior of the Remove button (if any) in the applications Add or Remove Programs entry. For more information on this variable, see MaintenanceStart. This system variable is initialized to the string value " -removeonly".

ADDREMOVE_SYSTEMCOMPONENT
Project: This information applies to InstallScript projects.

This system variable's value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's SystemComponent value, which specifies whether an entry is displayed for the application in Add or Remove Programs in the Control Panel. This system variable is initialized to FALSE, meaning that an entry is displayed.

ALLUSERS
The ALLUSERS system variable is the key to installations that allow installing the application to the current user or all users on the target system. The value of ALLUSERS determines the following:

The root key that is used by registry functions that are called after RegDBSetDefaultRoot(HKEY_USER_SELECTABLE) is called

268

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

The root key under which the application uninstallation key is created The location of registry entries that are specified in a registry sets HKEY_USER_SELECTABLE root key The value of the DISK1TARGET system variable (which specifies the path to the folder in which copies of certain installation files are placed to enable maintenance installations and uninstallation) The default value of the TARGETDIR system variable that is set by the default OnFirstUIBefore code Whether a shortcut that is defined in InstallShield with its Type property set to Automatic appears in the list of personal shortcuts or common shortcuts when the shortcut is created The default option selection in the SdCustomerInformation and SdCustomerInformationEx dialogs

ALLUSERS has no effect on the registration of COM DLL files. The following sections explain how the value of ALLUSERS is determined and set in different project types.

InstallScript Installations
If an installation is running as a first-time installation, the InstallScript engine determines during initialization the most appropriate value for the ALLUSERS variable and initializes it to that value:

If the user does not have administrator privileges, ALLUSERS is set to 0. This results in a per-user installation. Otherwise, ALLUSERS is set to 1. This results in a per-machine installation by default.

If an installation is running in maintenance mode, the InstallScript engine determines the value of the ALLUSERS variable based on whether the initial installation was installed as per-user or per-machine (based on the location of where the uninstallation information was installed). For an example of an InstallScript installation that allows installing the application to the current user or all users on the target system, see the sample project in the ALLUSERS Sample Project folder. This folder is a subfolder in the Samples folder of your InstallShield Program Files folder. The default location is:
C:\Program Files\InstallShield\2012\Samples\InstallScript\ALLUSERS Sample Project

InstallScript Custom Actions in Basic MSI and InstallScript MSI Installations

Getting the Value of the ALLUSERS Variable The ALLUSERS InstallScript variable is determined by querying the Windows Installer property ALLUSERS:
Table 7-3: Getting the Value of the ALLUSERS InstallScript Variable Windows Installer Property "" InstallScript Variable 0 Notes Any per-user or per-machine dependent script code in the custom action results in per-user behavior.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

269

Chapter 7: Variable Data System Variables

Table 7-3: Getting the Value of the ALLUSERS InstallScript Variable (cont.) Windows Installer Property 1 InstallScript Variable 1 Notes Any per-user or per-machine dependent script code in the custom action results in per-machine behavior.

Any other value

The InstallScript engine attempts to determine the appropriate value.

If the Windows Installer property ALLUSERS cannot be determined because the InstallScript engine determines that a deferred custom action is running, an unexpected property value is returned, or MSIGetProperty returns an error value. Therefore, the InstallScript engine attempts to determine the best value for the variable. Note that the InstallScript engine uses MsiGetMode with the MSIRUNMODE_SCHEDULED, MSIRUNMODE_ROLLBACK, and MSIRUNMODE_COMMIT flags to determine if a deferred custom action is running. If MsiGetMode returns true for any of the above values, the custom action is assumed to be deferred and the InstallScript mechanism is used. Note that if a Basic MSI installation does not have a value for ALLUSERS in the Property table, any InstallScript custom action that runs before the installation displays an ALLUSERS dialog (such as the CustomerInformation dialog, which sets the ALLUSERS Windows Installer property) has the ALLUSERS InstallScript variable set to 0. Therefore, the InstallScript custom action exhibits per-user behavior. Thus, it is recommended that all Basic MSI installations have a default value for ALLUSERS in the Property table. Setting the Value of the ALLUSERS Variable When the ALLUSERS InstallScript variable is set in script, the InstallScript engine first determines whether the platform and privilege level allow the ALLUSERS InstallScript variable to be changed. (In scenarios where the end user is not an administrator or power user, ALLUSERS cannot be changed.) If the ALLUSERS InstallScript variable can be changed, the InstallScript engine attempts to update the ALLUSERS Windows Installer property appropriately as follows:
Table 7-4: Setting the Value of the ALLUSERS InstallScript Variable InstallScript Variable 1 0 Windows Installer Property 1 ""

Note that the InstallScript engine sets the ALLUSERS InstallScript variable even if the Windows Installer property cannot be set. This could result in synchronization problems between the Windows Installer property and the InstallScript variable. Therefore, if you change the ALLUSERS InstallScript variable in a custom action, it is recommended that you set the Windows Installer property manually as well to ensure that the property can be changed successfully.

270

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

The following table shows the behavior for various scenarios on Windows Vista with User Account Control (UAC) enabled.
Table 7-5: ALLUSERS Value on Windows Vista with UAC Enabled Resulting InstallScript Variable 1 0 The InstallScript variable cannot be changed. Permachine InstallScript actions are not possible.

Type of Custom Action Immediate Immediate

Manifest Highest available Invoker

ALLUSERS Value in Property Table 2 2

Windows Installer Property 1 ""

Notes

Immediate Immediate

Highest available Invoker

1 1

1 1

1 1 The InstallScript variable cannot be changed. Permachine InstallScript actions fail. The InstallScript variable cannot be changed. Permachine InstallScript actions are not possible.

Immediate, before CustomerInformat ion dialog (or end user selects to install per user)

Invoker

""

""

Immediate, after CustomerInformat ion dialog Deferred

Highest available

""

Invoker

Any

Cannot be determined

The InstallScript variable cannot be changed. InstallScript method for determining ALLUSERS is used. InstallScript method for determining ALLUSERS is used.

Deferred

Highest available

Any

Cannot be determined

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

271

Chapter 7: Variable Data System Variables

The following table shows the behavior for various scenarios on pre-Windows Vista systems and on Windows Vista systems with User Account Control (UAC) disabled.
Table 7-6: ALLUSERS Value on Systems Earlier than Windows Vista and on Windows Vista with UAC Disabled Resulting InstallScript Variable 1 0 The InstallScript variable cannot be changed.

Type of Custom Action Immediate Immediate

User Privileges Administrator Limited

ALLUSERS Value in Property Table 2 2

Windows Installer Property 1 ""

Notes

Immediate Immediate

Administrator Limited

1 1

1 1

1 1 The InstallScript variable cannot be changed. The installation fails during UI sequence, and per-machine InstallScript custom actions fail. The InstallScript variable cannot be changed. Permachine InstallScript actions are not possible.

Immediate, before CustomerInformat ion dialog (or end user selects to install per user)

Administrator

""

""

Immediate, after CustomerInformat ion dialog Deferred

Administrator

""

Administrator

Any

Cannot be determined

InstallScript method for determining ALLUSERS is used. The InstallScript variable cannot be changed. InstallScript method for determining ALLUSERS is used. The InstallScript variable cannot be changed. InstallScript method for determining ALLUSERS is used.

Deferred

Limited

Any

Cannot be determined

Any on Windows 9x

Not applicable

Any

Any

272

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

If the resulting InstallScript variable is 0, InstallScript custom actions are used in a per-user context. If the resulting InstallScript variable is 1, InstallScript custom actions are used in a per-machine context.

Event-Driven InstallScript Code in InstallScript MSI Installations

InstallScript MSI installations work similarly to InstallScript installations except that when the ALLUSERS InstallScript variable is changed, the installation attempts to update the Windows Installer property ALLUSERS as described for InstallScript custom actions. During InstallScript MSI installations, the Windows Installer property ALLUSERS is not queried to determine the appropriate value of the ALLUSERS InstallScript variable; the InstallScript engine always attempts to determine the value, as described for InstallScript installations.

How an InstallScript Installation Works by Default Depending on ALLUSERS

Project: This information applies to InstallScript projects.

The following table provides information on how an installation is installed based on the ALLUSERS system variable.
Table 7-7: ALLUSERS Admin & Power User Default setting of ALLUSERS Automatic setting will check ALLUSERS property HKEY_USER_SELECTABLE_AUTO Registry Set Data DISK1TARGET True Per machine User and Guest False Per user

HKEY_LOCAL_MACHINE HKEY_LOCAL_MACHINE Program Files\InstallShield Installation Information\GUID HKEY_LOCAL_MACHINE\...\Uninstall\G UID Program Files\Company Name\Product Name Program Files\Common Files Supported

HKEY_CURRENT_USER HKEY_CURRENT_USER My Docs\InstallShield Installation Information\GUID HKEY_CURRENT_USER\...\Uninstall\G UID My Docs\Company Name\Product Name My Docs\... Not supported

Uninstall Registry Key

TARGETDIR

Engine Installation Register COM Information (.dll, .ocx, .exe)

Note: My Docs refers to a destination location to which the user has rights. This value depends on the operating system.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

273

Chapter 7: Variable Data System Variables

BATCH_INSTALL
Project: This information applies to the following project types:

InstallScript InstallScript MSIif the InstallScript user interface (UI) style is the traditional style (which uses the InstallScript engine as an external UI handler)

This information does not apply to InstallScript MSI projects in which the InstallScript UI style is the new style (which uses the InstallScript engine as an embedded UI handler). To learn more, see Using the InstallScript Engine as an External vs. Embedded UI Handler for InstallScript MSI Installations.

The BATCH_INSTALL system variable is set to a non-zero value to indicate that one or more operations need to be performed after the target system restarts. BATCH_INSTALL can be set to a non-zero value for any of the following reasons:

The installation determines that a file cannot be installed because the file already exists on the target system and it is locked. BATCH_INSTALL is set to non-zero manually through script. Note that this can occur in some objects if the object determines that an embedded installation needs a reboot to complete. LAAW_OPTION_SET_BATCH_INSTALL is used when calling LaunchApplication, and the function determines that the launched installation needs a reboot to complete. The installation attempted to update a Windows service (through ServiceAddService and the related functions), but it could not stop the existing service. The DIFx integration indicated that a reboot is needed, due to the installation of a DIFx driver.

If BATCH_INSTALL is set to FALSE, no locked files were found and the installation process can end normally. For more information, see Understanding When an Installation or Uninstallation Restarts the Target System.

CMDLINE
In InstallScript projects, Setup.exe accepts all user-defined command-line arguments and assigns them to the system string variable CMDLINE at run time.

Note: Note the following about CMDLINE in InstallScript projects:

CMDLINE stores only user-defined command-line arguments. InstallShield command-line arguments (predefined arguments) are not copied to CMDLINE. The installation converts all characters in user-defined command-line arguments to lowercase when copying them to CMDLINE. Use case insensitive logic when processing CMDLINE.

In InstallScript MSI projects, any command-line data that are passed to Setup.exe with the /z switch are stored in the system string variable CMDLINE. For example, if the user runs the following command line, CMDLINE is set to the string My custom data.
274 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

Setup.exe /z"My custom data"

In Basic MSI projects, you can pass public properties through Setup.exe to Msiexec.exe using the /v command-line argument.

COMMONFILES
The COMMONFILES system variable contains the fully qualified name of the folder that is defined by Windows and that stores files shared by applications that are installed on the system. In English Windows, that folder is named Common Files, and it is located in the Program Files folder. (In other language versions of Windows, the common files folder name is localized appropriately by default.) The common files folder is the recommended default location for files and folders that are shared by applications. On 64-bit Windows systems, this folder stores common files for 32-bit applications; common files for 64-bit applications should be installed to the COMMONFILES64 folder.

Project: During setup initialization in InstallScript installations, the value of the COMMONFILES variable is obtained by calling the Windows API function SHGetSpecialFolderPath with the CSIDL_COMMON_FILES parameter. In Basic MSI and InstallScript MSI installations, the value of the COMMONFILES variable is initialized based on the Windows Installer property CommonFilesFolder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding COMMONFILES variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

COMMONFILES64
The COMMONFILES64 system variable contains the fully qualified name of the folder that is defined by Windows and that stores files shared by 64-bit applications. In English Windows, that folder is named Common Files, and it is located in the PROGRAMFILES64 folder. (In other language versions of Windows, the common files folder name is localized appropriately by default.) The common files folder is the recommended default location for files and folders that are shared by applications.

Project: During setup initialization in InstallScript installations, the value of the COMMONFILES64 variable is obtained by calling the Windows API function SHGetSpecialFolderPath with the CSIDL_COMMON_FILES parameter from a 64-bit executable file. In Basic MSI and InstallScript MSI installations, the value of the COMMONFILES64 variable is initialized based on the Windows Installer property CommonFiles64Folder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding COMMONFILES64 variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

275

Chapter 7: Variable Data System Variables

DISK1SETUPEXENAME
DISK1SETUPEXENAME is a read-only system variable that contains the file name and file name extensionbut not the pathof the setup launcher, the installations executable file. The default value is Setup.exe.

Project: DISK1SETUPEXENAME can be used in Basic MSI projects that have custom actions if the installation is initialized using Setup.exe. If the installation is not initialized using Setup.exe, DISK1SETUPEXENAME is blank.

DISK1TARGET
This system variable contains the path to the folder in which copies of certain of the installation's files (such as the compiled script file) are placed to enable maintenance installations and uninstallation.

ENABLED_ISERVICES
Project: This information applies to InstallScript projects.

This system variable contains a set of bit flags indicating which InstallShield services are currently enabled. For example, if the expression ENABLED_ISERVICES & SERVICE_FLAG_ISFONTREG is equal to a non-zero value, global font registration is currently enabled.

ENGINECOMMONDIR
Project: This information applies to InstallScript projects.

The ENGINECOMMONDIR system variable stores the fully qualified path to the folder that contains the run-time files that are used by all 6.x, 7.x, and 9.x InstallScript (not InstallScript MSI) setups running on the system. The value of this system variable is shared among object scripts and between object scripts and the main setup script. This system variable is read-only; if you attempt to assign a value to it, a compiler error results.

ENGINEDIR
Project: This information applies to InstallScript projects.

276

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

The ENGINEDIR system variable stores the fully qualified path to the folder that contains the run-time files specific to the version of the engine being used by the setup, i.e., 7.00, 7.01, or 9.00, but not by InstallShield Professional 6.x setups. The value of this system variable is shared among object scripts and between object scripts and the main setup script. This system variable is read-only; if you attempt to assign a value to it, a compiler error results.

ERRORFILENAME
This system variable stores the name of the file that was involved in an error. For example, if an error occurs while copying a specific file with a built-in function, InstallShield sets ERRORFILENAME to the name of the file that caused the error. Not all file-operation functions use ERRORFILENAME.

FOLDER_APPDATA
The FOLDER_APPDATA system variable stores the fully qualified path to the folder that is defined by the operating system and that serves as a common repository for application-specific data. This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

Project: During setup initialization in InstallScript installations, the value of the FOLDER_APPDATA variable is obtained by calling the Windows API function SHGetSpecialFolderPath with the CSIDL_APPDATA value for LPITEMIDLIST. In Basic MSI and InstallScript MSI installations, the value of the FOLDER_APPDATA variable is initialized based on the Windows Installer property AppDataFolder or LocalAppDataFolder. Note that deferred, commit, and rollback custom actions do not have access to these properties. Therefore, the corresponding FOLDER_APPDATA variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

FOLDER_APPLICATIONS
The FOLDER_APPLICATIONS system variable stores the fully qualified path to the root folder for application folders. The value of this system variable is equal to the value of the system variable PROGRAMFILES when the value of the system variable ALLUSERS is non-zero; when ALLUSERS is FALSE, the value of this system variable is equal to the value of the system variable FOLDER_APPDATA. This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

277

Chapter 7: Variable Data System Variables

FOLDER_APPLICATIONS64
The FOLDER_APPLICATIONS64 system variable stores the fully qualified path to the root folder for application folders on a 64-bit system. The value of this system variable is equal to the value of the system variable PROGRAMFILES64 when the value of the system variable ALLUSERS is non-zero; when ALLUSERS is FALSE, the value of this system variable is equal to the value of the system variable FOLDER_APPDATA. This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

FOLDER_COMMON_APPDATA
The FOLDER_COMMON_APPDATA system variable stores the fully qualified path to the folder that is defined by the operating system and that serves as a common repository for application-specific data. This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

Project: During setup initialization in InstallScript installations, the value of the FOLDER_COMMON_APPDATA variable is obtained by calling the Windows API function SHGetSpecialFolderPath with the CSIDL_COMMON_APPDATA value for LPITEMIDLIST. In Basic MSI and InstallScript MSI installations, the value of the FOLDER_COMMON_APPDATA variable is initialized based on the Windows Installer property CommonAppDataFolder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding FOLDER_COMMON_APPDATA variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

FOLDER_DESKTOP
The FOLDER_DESKTOP system variable stores the fully qualified path to the Desktop folder, which holds the program folders and items that are displayed on the end users desktop. To ensure that groups and folders are created at the proper location, the location to which FOLDER_DESKTOP points changes when the default group or folder type is changed from Common to Personal or from Personal to Common when the system variable ALLUSERS is changed.

FOLDER_DOTNET_10
The FOLDER_DOTNET_10 system variable stores the fully qualified path of the folder where the Microsoft .NET Framework 1.0 redistributable files are located:
<WINDIR>\Microsoft.NET\Framework\v1.0.3705\

This system variable is read-only. If you attempt to assign a value to it, a compiler error results.

278

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

FOLDER_DOTNET_11
The FOLDER_DOTNET_11 system variable stores the fully qualified path of the folder where the Microsoft .NET Framework 1.1 redistributable files are located:
<WINDIR>\Microsoft.NET\Framework\v1.1.4322\

This system variable is read-only. If you attempt to assign a value to it, a compiler error results.

FOLDER_DOTNET_20
The FOLDER_DOTNET_20 system variable stores the fully qualified path of the folder where the Microsoft .NET Framework 2.0 redistributable files are located:
<WINDIR>\Microsoft.NET\Framework\v2.0.50727\

This system variable is read-only. If you attempt to assign a value to it, a compiler error results.

FOLDER_DOTNET_30
The FOLDER_DOTNET_30 system variable stores the fully qualified path of the folder where the Microsoft .NET Framework 3.0 redistributable files are located:
<WINDIR>\Microsoft.NET\Framework\v3.0

This system variable is read-only. If you attempt to assign a value to it, a compiler error results.

FOLDER_DOTNET_35
The FOLDER_DOTNET_35 system variable stores the fully qualified path of the folder where the Microsoft .NET Framework 3.5 redistributable files are located:
<WINDIR>\Microsoft.NET\Framework\v3.5

This system variable is read-only. If you attempt to assign a value to it, a compiler error results.

FOLDER_DOTNET_40
The FOLDER_DOTNET_40 system variable stores the fully qualified path of the folder where the Microsoft .NET Framework 4.0 redistributable files are located:
<WINDIR>\Microsoft.NET\Framework\v4.0.30319

This system variable is read-only. If you attempt to assign a value to it, a compiler error results.

FOLDER_FONTS
Project: This information applies to the following project types:

InstallScript

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

279

Chapter 7: Variable Data System Variables

InstallScript Object

The FOLDER_FONTS system variable stores the fully qualified path of the Windows font folder. This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

FOLDER_LOCAL_APPDATA
The FOLDER_LOCAL_APPDATA system variable stores the fully qualified path to the folder that is defined by the operating system and that serves as a common repository for application-specific data. Common values are C:\Users\<User>\Application Data on Windows Vista and later and C:\Documents and Settings\<User>\Application Data on Windows 2000 and later. This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

Project: During setup initialization in InstallScript installations, the value of the FOLDER_LOCAL_APPDATA variable is obtained by calling the Windows API function SHGetSpecialFolderPath with the CSIDL_LOCAL_APPDATA value for LPITEMIDLIST. In Basic MSI and InstallScript MSI installations, the value of the FOLDER_LOCAL_APPDATA variable is initialized based on the Windows Installer property LocalAppDataFolder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding FOLDER_LOCAL_APPDATA variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

FOLDER_PERSONAL
Project: This information applies to InstallScript projects.

The FOLDER_PERSONAL system variable stores the fully qualified path to the folder that is defined by the operating system and that serves as a common repository for application-specific data. Common values are C:\Users\<User>\Application Data on Windows Vista and later and C:\Documents and Settings\<User>\Application Data on Windows 2000 and later. This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

Project: During setup initialization in InstallScript installations, the value of the FOLDER_PERSONAL variable is obtained by calling the Windows API function SHGetSpecialFolderPath with the CSIDL_PERSONAL value for LPITEMIDLIST. In Basic MSI and InstallScript MSI installations, the value of the FOLDER_PERSONAL variable is initialized based on the Windows Installer property PersonalFolder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding FOLDER_PERSONAL variable is empty in deferred, commit, and rollback

280

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

FOLDER_PROGRAMS
The FOLDER_PROGRAMS system variable stores the fully qualified path to the Start Menu\Programs folder, which is displayed when you select Programs from the Start Menu. To ensure that groups and folders are created at the proper location, the location to which FOLDER_PROGRAMS points changes when the default group or folder type is changed from Common to Personal or from Personal to Common when the system variable ALLUSERS is changed.

FOLDER_STARTMENU
The FOLDER_STARTMENU system variable stores the fully qualified path to the Start Menu folder, which is displayed when you click the Windows Start button. To ensure that groups and folders are created at the proper location, the location to which FOLDER_STARTMENU points changes when the default group or folder type is changed from Common to Personal or from Personal to Common when the system variable ALLUSERS is changed.

FOLDER_STARTUP
The FOLDER_STARTUP system variable stores the fully qualified path to the Startup folder, which contains the program folders and items that are launched when Windows starts. To ensure that groups and folders are created at the proper location, the location to which FOLDER_STARTUP points changes when the default group or folder type is changed from Common to Personal or from Personal to Common when the system variable ALLUSERS is changed.

FOLDER_TEMP
Project: This information applies to InstallScript projects.

The FOLDER_TEMP system variable stores the fully qualified path of the folder designated for temporary files. This folder is used by Windows and most applications on the system and is not created or deleted by the installation. (The folder whose path is stored in the system variable SUPPORTDIR is created by the installation to store installation-specific files and is deleted after the installation completes.) This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

Project: During setup initialization in InstallScript installations, the value of the FOLDER_TEMP variable is obtained by calling the Windows API function GetTempPath.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

281

Chapter 7: Variable Data System Variables

In Basic MSI and InstallScript MSI installations, the value of the FOLDER_TEMP variable is initialized based on the Windows Installer property TempFolder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding FOLDER_TEMP variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

HKEYCURRENTROOTKEY
The value of this system variable is the root key that is used by the general registry-related functions. The system variable's possible values are the following:

HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG HKEY_DYN_DATA

You can set the default root key by setting HKEYCURRENTROOTKEY equal to one of the preceding predefined constants, the predefined constant HKEY_USER_SELECTABLE, or the system variable HKEY_USER_SELECTABLE_AUTO. Unlike RegDBGetDefaultRoot, the value of HKEYCURRENTROOTKEY is never HKEY_USER_SELECTABLE. If you most recently set the default root key by using HKEY_USER_SELECTABLE, the value of HKEYCURRENTROOTKEY is HKEY_LOCAL_MACHINE if the ALLUSERS system variable is non-zero or HKEY_CURRENT_USER if ALLUSERS is FALSE.

HKEY_USER_SELECTABLE_AUTO
The value of this system variable is HKEY_LOCAL_MACHINE if the ALLUSERS system variable is nonzero or HKEY_CURRENT_USER if ALLUSERS is FALSE.

IFX_COMPANY_NAME
Project: This information applies to InstallScript projects.

This system variable is automatically initialized to the value of the string entry COMPANY_NAME, if that entry exists; if that entry does not exist, IFX_COMPANY_NAME is initialized to the company name that you specified in the Project Settings property sheet's Application page.

IFX_DISK1INSTALLED
Project: This information applies to InstallScript projects.
282 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

This system variable is set equal to zero at the beginning of a setup and is reset to a non-zero value if the setup installs or reinstalls the feature with the files needed for maintenance setups and uninstallation. (Note that this feature is automatically placed in your .cab files by the media builder and is not displayed in the IDE.)

IFX_INITIALIZED
Project: This information applies to InstallScript projects.

This system variable is set equal to a non-zero value if the setup is event based and is set equal to FALSE if the setup is procedural (that is, has a program...endprogram block).

IFX_INSTALLED_DISPLAY_VERSION
Project: This information applies to InstallScript projects.

The IFX_INSTALLED_DISPLAY_VERSION system variable replaces the placeholder %VI in Sd dialog static text fields and string passed to the SdSubstituteProductInfo function. This system variable is automatically initialized to the value of the system variable IFX_INSTALLED_VERSION; if you assign a new value to IFX_INSTALLED_VERSION the value of IFX_INSTALLED_DISPLAY_VERSION does not automatically change.

IFX_INSTALLED_VERSION
Project: This information applies to InstallScript projects.

This system variable is automatically initialized to the string equivalent of the data in the Version value of the application uninstallation registry key if that data is a packed DWORD; if the key or value does not exist or the data is not a packed DWORD, IFX_INSTALLED_VERSION is initialized to a null string ("").

IFX_KEYPATH_PRODUCT_INFO
This system variable specifies the registry location of the application information key that is created by CreateInstallationInfo and whose values are read by RegDBGetAppInfo and modified by RegDBSetAppInfo. This system variable is initialized to a value of:
Software\<IFX_COMPANY_NAME>\<IFX_PRODUCT_NAME>\<IFX_PRODUCT_VERSION>\.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

283

Chapter 7: Variable Data System Variables

IFX_MULTI_INSTANCE_SUFFIX
Project: This information applies to InstallScript projects.

The IFX_MULTI_INSTANCE_SUFFIX system variable is set in the default code for the OnFirstUIBefore event handler function. IFX_MULTI_INSTANCE_SUFFIX is used in that handler function to construct a unique target folder name for a multi-instance installation. It is also used in the OnCustomizeUninstInfo handler function to construct a unique uninstallation display name for a multiinstance installation.

IFX_PRODUCT_COMMENTS
Project: This information applies to InstallScript projects.

If this system variables value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry keys Comments value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variable is initialized to the value that you specify in ARP Comments setting in the General Information view.

IFX_PRODUCT_DISPLAY_NAME
This system variable replaces the placeholder %P in Sd dialog static text fields and string passed to the SdSubstituteProductInfo function. This system variable is automatically initialized to the value of the system variable IFX_PRODUCT_NAME; if you assign a new value to IFX_PRODUCT_NAME the value of IFX_PRODUCT_DISPLAY_NAME does not automatically change.

Note: The system variable IFX_SETUP_TITLE specifies the text in the title bar of all built-in dialogs.

IFX_PRODUCT_DISPLAY_VERSION
Project: This information applies to InstallScript projects.

This system variable replaces the placeholder %VS in Sd dialog static text fields and string passed to the SdSubstituteProductInfo function. This system variable is automatically initialized to the value of the system variable IFX_PRODUCT_VERSION; if you assign a new value to IFX_PRODUCT_VERSION the value of IFX_PRODUCT_DISPLAY_VERSION does not automatically change.

284

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

IFX_PRODUCT_ICON
Project: This information applies to InstallScript projects.

If this system variables value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry keys DisplayIcon value. This registry value specifies the icon that is displayed for the application in Add or Remove Programs in the Control Panel. This system variable is initialized to the value that you specify for the Display Icon setting in the Add or Remove Programs area of the General Information view.

IFX_PRODUCT_KEY
Project: This information applies to InstallScript projects.

This system variable is automatically initialized to the value of the string entry PRODUCT_KEY, if that entry exists; if that entry does not exist, IFX_PRODUCT_KEY is initialized to the executable file name that you specified in the Project Settings property sheet's Application page.

IFX_PRODUCT_NAME
Project: This information applies to InstallScript projects.

This system variable is automatically initialized to the value of the string entry PRODUCT_NAME, if that entry exists; if that entry does not exist, IFX_PRODUCT_NAME is initialized to the product name that you specified in the Project Settings property sheet's Application page.

IFX_PRODUCT_README
Project: This information applies to InstallScript projects.

If this system variable's value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's Readme value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variable is initialized to the value that you specify in the Read Me setting in the General Information view.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

285

Chapter 7: Variable Data System Variables

IFX_PRODUCT_REGISTEREDCOMPANY
If the IFX_PRODUCT_REGISTEREDCOMPANY system variables value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry keys RegCompany value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variable is initialized to the data in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Windows key\CurrentVersion\RegisteredOrganizatio n, where Windows key is Windows NT if the target operating system is Windows NT, Windows 2000, Windows XP, or later, or is Windows for other Windows operating systems. This system variables value is modified by end-user input in the Company Name edit box of the SdRegisterUser, SdRegisterUserEx, SdCustomerInformation, and SdCustomerInformationEx dialogs.

Project: In an InstallScript MSI installation, if the value of IFX_PRODUCT_REGISTEREDCOMPANY is set, the Windows Installer property COMPANYNAME is automatically updated.

IFX_PRODUCT_REGISTEREDOWNER
If the IFX_PRODUCT_REGISTEREDOWNER system variables value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry keys RegOwner value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variable is initialized to the data in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Windows key\CurrentVersion\RegisteredOwner, where Windows key is Windows NT if the target operating system is Windows NT, Windows 2000, Windows XP, or later, or is Windows for other Windows operating systems. This system variables value is modified by end-user input in the User Name edit box of the SdRegisterUser, SdRegisterUserEx, SdCustomerInformation, and SdCustomerInformationEx dialogs.

Project: In an InstallScript MSI installation, if the value of IFX_PRODUCT_REGISTEREDOWNER is set, the Windows Installer property USERNAME is automatically updated.

IFX_PRODUCT_REGISTEREDSERIALNUM
If the IFX_PRODUCT_REGISTEREDSERIALNUM system variables value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry keys ProductId value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variables value is modified by end-user input in the Serial Number edit box of the SdCustomerInformation, and SdCustomerInformationEx dialogs.

286

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

IFX_PRODUCT_SUPPORT_CONTACT
Project: This information applies to InstallScript projects.

If this system variable's value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's Contact value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variable is initialized to the value that you specify in the Support Contact setting in the General Information view.

IFX_PRODUCT_SUPPORT_PHONE
Project: This information applies to InstallScript projects.

If this system variable's value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's HelpTelephone value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variable is initialized to the value that you specify in the Support Phone Number setting in the General Information view.

IFX_PRODUCT_SUPPORT_URL
Project: This information applies to InstallScript projects.

If this system variable's value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's HelpLink value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variable is initialized to the value that you specify in the Support URL setting in the General Information view.

IFX_PRODUCT_UPDATE_URL
Project: This information applies to InstallScript projects.

If this system variable's value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's URLUpdateInfo value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variable is initialized to the value that you specify in the Product Update URL setting in the General information view.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

287

Chapter 7: Variable Data System Variables

IFX_PRODUCT_URL
Project: This information applies to InstallScript projects.

If this system variable's value is not a null string (""), its value is used by the MaintenanceStart function to specify the data in the application uninstallation registry key's URLInfoAbout value. This registry value provides information about the application to Add or Remove Programs in the Control Panel. This system variable is initialized to the value that you specify in the Publisher/Product URL setting in the General Information view.

IFX_PRODUCT_VERSION
Project: This information applies to InstallScript projects.

This system variable is automatically initialized to the value of the string entry PRODUCT_VERSION, if that entry exists; if that entry does not exist, IFX_PRODUCT_VERSION is initialized to the product version that you specified in the Project Settings property sheet's Application page.

IFX_SETUP_TITLE
This system variable specifies the text in the title bar of all built-in dialogs (except dialogs generated directly by Windows API function calls) and all message boxes generated by the MessageBox function. This system variable is automatically initialized to the value of the string entry TITLE_CAPTIONBAR, if that entry exists; if that entry does not exist, IFX_SETUP_TITLE is initialized with the following internal code:
Sprintf( IFX_SETUP_TITLE, SdLoadString( IDS_IFX_FORMAT_SETUP_TITLE ), IFX_PRODUCT_DISPLAY_NAME );

Changing the value of IFX_SETUP_TITLE automatically resets the title of all dialogs displayed by the setup.

IFX_SUPPORTED_VERSIONS
Project: This information applies to InstallScript projects.

This system variable is automatically initialized to a pipe(|)-delimited list of the versions of your product to which the update can be applied, which you specified in the media property sheet's Update page or the Media Wizard's Update panel.

288

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

INFOFILENAME
When you use BatchFileSave to save a batch file or ConfigFileSave to save a Config.sys file, you can specify that InstallShield create a backup of the file as it existed before you updated it. InstallShield assigns the name of that backup file to the system variable INFOFILENAME. If you want to alert the user to the existence of the backup file, use the function MessageBox to display the value of INFOFILENAME.

INSTALLDIR
Project: This information applies to the following project types:

Basic MSI InstallScript MSI

In an InstallScript project, use TARGETDIR.

During setup initialization, the installation assigns to the system variable INSTALLDIR the fully qualified path to a target folder on the hard drive. The INSTALLDIR path is resolved based on the destination that is specified in the INSTALLDIR setting in the General Information view. By default, the INSTALLDIR path is resolved based on the [ProgramFilesFolder]ISYourCompanyDir\ISYourProductDir entries in the Directory table of your .msi package.

INSTANCE_GUID
Project: This information applies to InstallScript projects.

This system variable contains a globally unique identifier (GUID) for the installation, which is used as the name of the application uninstallation registry key. This variable's value is set at run time to equal PRODUCT_GUID except in a multi-instance installation. The value of this system variable is shared among object scripts and between object scripts and the main installation script. You cannot assign a new value to this system variable.

ISDIFXAPPID
This predefined global system variable determines the application to associate when installing or uninstalling device drivers. ISDIFXAPPID is set to PRODUCT_GUID by default during initialization and can be changed as desired to specify an alternate application ID.

Note: See the DIFxAPI documentation for the INSTALLERINFO structure for more information regarding specifying application association.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

289

Chapter 7: Variable Data System Variables

ISMSI_HANDLE
This system variable is set to the handle of the currently running .msi database, and can be used in event-handler functions as an argument to Windows Installer API functions that require a handle to the currently running database. For example, to retrieve the value of the USERNAME property in the OnBegin event handler, you can use code similar to the following:
function OnBegin( ) STRING svUsername[256]; NUMBER nBuffer; begin nBuffer = 256; MsiGetProperty(ISMSI_HANDLE, "USERNAME", svUsername, nBuffer); MessageBox("USERNAME = " + svUsername, INFORMATION); end;

Project: ISMSI_HANDLE is not supported in Basic MSI projects, and is not supported in InstallScript custom actions.

IS_NULLSTR_PTR
You can use the IS_NULLSTR_PTR variable to pass a null pointer to an external DLL function or Windows API through a parameter that has been prototyped as an InstallScript string. This functionality works for byval string, byref string, wstring, and binary data types. This functionality does not apply to byref number parameters. If you want to specify a NULL pointer for byref number parameters, you must prototype the parameter as a pointer data type and pass the address of the number variable or NULL, as needed. IS_NULLSTR_PTR is a global string variable instance with the value of <IS_NULLSTR_PTR>. A statement that assigns a new value to this variable compiles; however, the assignment does not have any effect. The variables value remains <IS_NULLSTR_PTR>. If you pass this variable to a non-DLL function, the function receives the string <IS_NULLSTR_PTR>. If you pass a string that has the value <IS_NULLSTR_PTR> to an external DLL function, the result is the same as if you used IS_NULLSTR_PTR.

Using the IS_NULLSTR_PTR Variable to Pass a Null Pointer to a Windows API

The Windows function WritePrivateProfileString lets you flush the INI file buffer on Windows 9x by specifying NULL for the first three parameters. However, since this function is prototyped as follows, there does not appear to be any way to accomplish this:
prototype number KERNEL32.WritePrivateProfileString (byval string, byval string, byval string, byval string);

Using the pointer data type allows NULL to be specified, but it causes problems when trying to specify a valid string. If you want the InstallScript engine to pass a null pointer to the function, you can use the following code:

290

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

KERNEL32.WritePrivateProfileString (IS_NULLSTR_PTR, IS_NULLSTR_PTR, IS_NULLSTR_PTR, szFile);

Using the IS_NULLSTR_PTR Variable to Pass a Null Pointer to an External DLL Function
You can use IS_NULLSTR_PTR with any external DLL function that expects a string. In this case, the DLL function receives a NULL pointer.

ISRES
During setup initialization, the installation decompresses _isres.dll from your setup and copies it to a temporary folder on the target system, giving it a unique name so that it does not interfere with other InstallShield installations. The fully qualified name of this file, which contains setup resources, is assigned to the system variable ISRES.

ISUSER
During setup initialization, the installation decompresses _isuser.dll, if present, from your setup and copies it to the temporary folder SUPPORTDIR on the target system, giving the file a unique name so that it does not interfere with other InstallShield installations. The fully qualified name of this file, which contains user-defined setup resources, is assigned to the system variable ISUSER.

ISVERSION
When the setup script starts running, the installation gets the version of Setup.exe that is running and assigns it to the system variable ISVERSION. The version number also appears in the Setup program's About box.

LAAW_PARAMETERS
Project: This information applies to InstallScript projects.

If you call LaunchApplication without LAAW_OPTION_USE_SHELLEXECUTE or you call LaunchAppAndWait or LaunchApp, these functions internally call the Windows API function CreateProcess. The LAAW_PARAMETERS structured variable specifies certain arguments for CreateProcess, and whether to display a text window while the launched application is running. For information on CreateProcess, consult the Windows API documentation. The LAAW_PARAMETERS system variable is initialized automatically during setup initialization by a call to LaunchAppAndWaitInitStartupInfo.
Table 7-8: LAAW_PARAMETERS Member bCallbackEndedWait Description Indicates that WaitForApplication ended the wait because the callback function returned LAAW_CALLBACK_RETURN_END_WAIT.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

291

Chapter 7: Variable Data System Variables

Table 7-8: LAAW_PARAMETERS (cont.) Member bInheritHandles dwCreationFlags lpCurrentDirectory Description Sets the corresponding argument to CreateProcess. Sets the corresponding argument to CreateProcess. Sets the corresponding argument to CreateProcess. This member is set to the szDirectory parameter of LaunchApplication or LaunchAndAppAndWait. Note that setting the value of lpCurrentDirectory manually has no effect on LaunchApplication or LaunchAndAppAndWait. lpEnvironment lpProcessAttributes lpThreadAttributes nCallbackInterval Sets the corresponding argument to CreateProcess. Sets the corresponding argument to CreateProcess. Sets the corresponding argument to CreateProcess. This member defines the callback interval in milliseconds. It is set to 1000 (1 second) by default when you call the LaunchApplicationInit or LaunchAppAndWaitInitStartupInfo functions. If the application cannot be launched, the nLaunchResult member contains the result of calling GetLastError after the CreateProcess call. If LaunchApp, LaunchAppAndWait, or LaunchApplication is successful and the LAAW_OPTION_WAIT option was specified, the nLaunchResult member contains the return code of the launched application. Indicates the timeout value used internally by LaunchApplication or LaunchAndAppAndWait when WaitForApplication is called. The default value is INFINITE. You can customize this value to set a wait timeout for LaunchApplication or LaunchAndAppAndWait. Indicates the interval for how often the installation checks whether the timeout interval has elapsed while waiting for an application through WaitForApplication (or through LaunchApplication or LaunchAndAppAndWait, which may call WaitForApplication internally). This value is not used if nTimeOut is set to INFINITE and LAAW_USE_CALLBACK is not specified. If LAAW_USE_CALLBACK is specified, the timeout/callback check interval is the lower of the two values for LAAW_PARAMETERS.nTimeOutCheckInterval and LAAW_PARAMETERS.nCallbackInterval. The default value is 1000. Indicates the maximum amount of time (in milliseconds) to wait for the application to complete its initialization through the Windows API WaitForInputIdle. The default value for this structure member is 2000. You can set it to 0 to indicate that the installation should not wait for the application to initialize before beginning the wait for the application to complete. Since LaunchApplication and LaunchAndAppAndWait wait for the application to initialize only if LAAW_OPTION_WAIT is specified, this value is only used if LAAW_OPTION_WAIT is specified.

nLaunchResult

nTimeOut

nTimeOutCheckInterval

nWaitForInputIdleMax

292

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

Table 7-8: LAAW_PARAMETERS (cont.) Member nWaitResult Description Indicates additional information about the last wait that occurred as a result of calling WaitForApplication. For more information, see WaitForApplication. Contains the resulting command line used as the lpCommandLine parameter in the internal call to CreateProcess. This member is populated when LaunchApplication or LaunchAndAppAndWait is called, so setting its value directly before or after this function is called has no effect. Also, this member is set to null ("") when you call the LaunchApplicationInit or LaunchAppAndWaitInitStartupInfo functions. If this member is set to anything other than a null string ("") ,the installation displays its contents in a text window (by calling SdShowMsg) while the launched application is running. Note that szStatusText cannot contain more than 4 kilobytes of data.

szCommandLineResult

szStatusText

LAAW_PROCESS_INFORMATION
Project: This information applies to InstallScript projects.

When you call LaunchApplication, LaunchAndAppAndWait, or LaunchApp, this structured variable returns identification information about the launched process. The PROCESS_INFORMATION system variable has the following members:
Table 7-9: LAAW_PROCESS_INFORMATION Member hProcess Description A handle to the newly created process. The handle is used to specify the process in all functions that perform operations on the process object. A handle to the primary thread of the newly created process. The handle is used to specify the thread in all functions that perform operations on the thread object. A global process identifier that can be used to identify a process. The value is valid from the time the process is created until the time the process is terminated. A global thread identifiers that can be used to identify a thread. The value is valid from the time the thread is created until the time the thread is terminated.

hThread

dwProcessId

dwThreadId

LAAW_SHELLEXECUTEINFO
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

293

Chapter 7: Variable Data System Variables

The LAAW_SHELLEXECUTEINFO script variable is an instance of a SHELLEXECUTEINFO structure used by the LaunchApplication function when the ShellExecuteEx function is called. You can customize the members of this structure to affect how using LaunchApplication with the LAAW_OPTION_USE_SHELLEXECUTE parameter works.

SHELLEXECUTEINFO Structure
typedef SHELLEXECUTEINFO begin int int HWND cbSize; fMask; hwnd;

pointer lpVerb; pointer lpFile; pointer lpParameters; pointer lpDirectory; int HWND nShow; hInstApp;

pointer lpIDList; pointer lpClass; HWND int HWND HWND end; hkeyClass; dwHotKey; hIconMonitor; hProcess;

LAAW_SHELLEXECUTEVERB
Project: This information applies to InstallScript projects.

The LAAW_SHELLEXECUTEVERB script variable is a string that indicates the verb used by LaunchApplication when calling ShellExecuteEx. The default value is open. The lpVerb member of LAAW_SHELLEXECUTEINFO points to this string by default.

Tip: If you are using LAAW_OPTION_USE_SHELLEXECUTE on systems running Windows Vista or later and you want to launch the application using the full administrator account (similar to right-clicking the executable file to be run and clicking Run as Administrator), set LAAW_SHELLEXECUTEVERB to runas before using LaunchApplication in your script:
LAAW_SHELLEXECUTEVERB = "runas";

This ensures that the application is always run with full administrator privileges regardless of whether the application to be launched has an application manifest with relevant settings. Note that this may trigger a User Account Control (UAC) prompt for consent or credentials.

294

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

On systems running operating systems earlier than Windows Vista, if runas is used, a Run As dialog box is displayed. The behavior is similar to right-clicking the executable file to be run and clicking Run As. This dialog box enables the end user to select the user account that should be used to run the application.

LAAW_STARTUPINFO
When you call LaunchApplication, LaunchAndAppAndWait, or LaunchApp, the LAAW_STARTUPINFO structured variable specifies main window properties if a new window is created for the launched process. This system variable is initialized automatically during installation initialization by a call to LaunchAppAndWaitInitStartupInfo. The STARTUPINFO system variable has the following members:
Table 7-10: LAAW_STARTUPINFO Member cb lpReserved lpDesktop Description Specifies the size, in bytes, of the structure. Reserved. Set this member to NULL. Pointer to a null-terminated string that specifies either the name of the desktop only or the name of both the desktop and window station for this process. A backslash in the string pointed to by lpDesktop indicates that the string includes both desktop and window station names. If lpDesktop is NULL, the new process inherits the desktop and window station of its parent process. If lpDesktop is an empty string, the process does not inherit the desktop and window station of its parent process; instead, the system determines if a new desktop and window station need to be created. If the impersonated user already has a desktop, the system will use the existing desktop. For console processes, this is the title displayed in the title bar if a new console window is created. If NULL, the name of the executable file is used as the window title instead. This parameter must be NULL for GUI or console processes that do not create a new console window. Ignored unless dwFlags specifies STARTF_USEPOSITION. Specifies the x offset, in pixels, of the upper left corner of a window if a new window is created. The offset is from the upper left corner of the screen. For GUI processes, the specified position is used the first time the new process calls the Windows API function CreateWindow to create an overlapped window if the x parameter of CreateWindow is CW_USEDEFAULT. Ignored unless dwFlags specifies STARTF_USEPOSITION. Specifies the y offset, in pixels, of the upper left corner of a window if a new window is created. The offset is from the upper left corner of the screen. For GUI processes, the specified position is used the first time the new process calls the Windows API function CreateWindow to create an overlapped window if the y parameter of CreateWindow is CW_USEDEFAULT. Ignored unless dwFlags specifies STARTF_USESIZE. Specifies the width, in pixels, of the window if a new window is created. For GUI processes, this is used only the first time the new process calls the Windows API function CreateWindow to create an overlapped window if the nWidth parameter of CreateWindow is CW_USEDEFAULT.

lpTitle

dwX

dwY

dwXSize

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

295

Chapter 7: Variable Data System Variables

Table 7-10: LAAW_STARTUPINFO (cont.) Member dwYSize Description Ignored unless dwFlags specifies STARTF_USESIZE. Specifies the height, in pixels, of the window if a new window is created. For GUI processes, this is used only the first time the new process calls CreateWindow to create an overlapped window if the nHeight parameter of CreateWindow is CW_USEDEFAULT. Ignored unless dwFlags specifies STARTF_USECOUNTCHARS. For console processes, if a new console window is created, dwXCountChars specifies the screen buffer width in character columns. This value is ignored in a GUI process. Windows NT/2000 or later: Ignored unless dwFlags specifies STARTF_USECOUNTCHARS. For console processes, if a new console window is created, dwYCountChars specifies the screen buffer height in character rows. This value is ignored in a GUI process. Ignored unless dwFlags specifies STARTF_USEFILLATTRIBUTE. Specifies the initial text and background colors if a new console window is created in a console application. These values are ignored in GUI applications. This value can be any combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For information on using these Windows constants, which are not defined in ISRTWindows.h, see Using Windows Constants in a Script. For example, the following combination of values produces red text on a white background:
FOREGROUND_RED| BACKGROUND_RED| BACKGROUND_GREEN| BACKGROUND_BLUE

dwXCountChars

dwYCountChars

dwFillAttribute

296

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

Table 7-10: LAAW_STARTUPINFO (cont.) Member dwFlags Description This is a bit field that determines whether certain STARTUPINFO members are used when the process creates a window. Any combination of the following values can be specified:

STARTF_FORCEONFEEDBACKIndicates that the cursor is in feedback mode for two seconds after LaunchApplication or LaunchAndAppAndWait is called. If during those two seconds the process makes the first GUI call, the system gives five more seconds to the process. If during those five seconds the process shows a window, the system gives five more seconds to the process to finish drawing the window. The system turns the feedback cursor off after the first call to the Windows API function GetMessage, regardless of whether the process is drawing.

STARTF_FORCEOFFFEEDBACKIndicates that the feedback cursor is forced off while the process is starting. The normal cursor is displayed. STARTF_RUNFULLSCREENIndicates that the process should be run in full-screen mode, rather than in windowed mode. This flag is only valid for console applications running on an x86 computer. STARTF_USECOUNTCHARSIf this value is not specified, the dwXCountChars and dwYCountChars members are ignored. STARTF_USEFILLATTRIBUTEIf this value is not specified, the dwFillAttribute member is ignored. STARTF_USEPOSITIONIf this value is not specified, the dwX and dwY members are ignored. STARTF_USESHOWWINDOWIf this value is not specified, the wShowWindow member is ignored. STARTF_USESIZEIf this value is not specified, the dwXSize and dwYSize members are ignored. STARTF_USESTDHANDLESSets the standard input, standard output, and standard error handles for the process to the handles specified in the hStdInput, hStdOutput, and hStdError members of the STARTUPINFO structure. LAAW_PARAMETERS.bInheritHandles must be set to TRUE for this to work properly. If this value is not specified, the hStdInput, hStdOutput, and hStdError members of the STARTUPINFO structure are ignored.

wShowWindow

Ignored unless dwFlags specifies STARTF_USESHOWWINDOW. The wShowWindow member can be any of the SW_ constants defined in Winuser.h. For GUI processes, wShowWindow specifies the default value the first time the Windows API function ShowWindow is called. The nCmdShow parameter of ShowWindow is ignored. In subsequent calls to ShowWindow, the wShowWindow member is used if the nCmdShow parameter of ShowWindow is set to SW_SHOWDEFAULT. Reserved; must be zero. Reserved; must be NULL. Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the standard input handle to the process if STARTF_USESTDHANDLES is specified. Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the standard output handle to the process if STARTF_USESTDHANDLES is specified.

cbReserved2 lpReserved2 hStdInput

hStdOutput

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

297

Chapter 7: Variable Data System Variables

Table 7-10: LAAW_STARTUPINFO (cont.) Member hStdError Description Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the standard error handle to the process if STARTF_USESTDHANDLES is specified.

Example
To specify that the launched application should be displayed at coordinates (0,0), before calling LaunchAppAndWait, you would customize the structure as follows:
LAAW_STARTUPINFO.dwFlags = LAAW_STARTUPINFO.dwFlags | STARTF_USEPOSITION; LAAW_STARTUPINFO.dwX = 0; LAAW_STARTUPINFO.dwY = 0;

MAINTENANCE
This system variable is set to TRUE if your installation program is running in maintenance mode, or set to FALSE for a first-time installation.

MAINT_OPTION
Project: This information applies to InstallScript projects.

The MAINT_OPTION system variable is set to one of the following values, corresponding to the maintenance option that you set for the Maintenance Experience setting in the General Information view:

MAINT_OPTION_STANDARD MAINT_OPTION_MULTI_INSTANCE MAINT_OPTION_NONE

MEDIA
This system variable stores the name of the current file media library or script-created feature set. During setup initialization, MEDIA is assigned the value of 'DATA', which corresponds to the DATAx.cab file that was created by the media build. If you change the value of this system variable to refer to a script-created component set, you must change the value back to 'DATA' before calling FeatureMoveData.

298

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

MODE
The system variable MODE holds one of the following constant values (note that the value cannot be changed at run time):
Table 7-11: MODE Constant SILENTMODE Meaning Indicates that Setup.exe is running in silent mode. (That is, the user ran Setup.exe with the /s argument.) Indicates Setup.exe is running in normal mode. Indicates Setup.exe is automatically generating a silent setup file (.iss file), which is a record of the setup input, by default in the Windows folder. (That is, when you run Setup.exe with the /r argument.)

NORMALMODE RECORDMODE

You can use the system variable MODE in if statements to control the flow of your script based on mode, as shown below:
if (MODE = SILENTMODE) then // Perform silent setup actions and events. else // Perform normal setup actions and events. endif;

Note: For a Basic MSI project, you can find if the user is running the installation in silent mode with the Windows Installer condition UILevel=2.

MSI_TARGETDIR
MSI_TARGETDIR represents the destination of an administrative installation (when a user runs Setup.exe with the /a argument) for an InstallScript MSI project. For a Basic MSI project, the TARGETDIR property (not the InstallScript variable) contains the destination of an administrative installation.

MULTI_INSTANCE_COUNT
Project: This information applies to InstallScript projects.

This system variable is set equal to the number of instances of the currently running multi-instance setup that are already installed on the target system. You cannot assign a new value to this system variable.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

299

Chapter 7: Variable Data System Variables

PACKAGE_LOCATION
Project: The PACKAGE_LOCATION system variable applies to InstallScript projects only.

This system variable contains the fully qualified file name of the installations self-extracting executable file if the installation is running from a self-extracting executable file that was created from within InstallShield, or a null string ("") value otherwise.

PRODUCT_GUID
This read-only system variable contains the GUID for the setup, which is initialized to the value of the projects ProductCode property. By default, PRODUCT_GUID is used as part of the UNINSTALLKEY variable and also as part of the DISK1TARGET and SUPPORTDIR directories.

PRODUCT_INSTALLED
Project: This information applies to InstallScript projects.

This system variable is set to a non-zero value if a valid log file exists for the installation. If the installation is running with the standard maintenance option, this variable is equal to the MAINTENANCE system variable.

PROGRAMFILES
The PROGRAMFILES system variable contains the fully qualified name of the folder defined by Windows to store applications. In English Windows, that folder is named Program Files, and it is located off the root of the drive on which Windows is installed. (In other language versions of Windows, the folder name is localized appropriately by default.) The program files folders is the recommended default location for application folders. On 64-bit Windows systems, this folder is for 32-bit applications only and has the name Program Files (x86) by default; 64-bit applications should be installed to the PROGRAMFILES64 folder.

Tip: If your company distributes more than one application, you may prefer to create a company folder inside the program files folder and then create application folders within the company folder.

This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

Project: During setup initialization in InstallScript installations, the value of the PROGRAMFILES variable is obtained by calling the Windows API function SHGetSpecialFolderPath with the CSIDL_PROGRAM_FILES parameter.

300

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

In Basic MSI and InstallScript MSI installations, the value of the PROGRAMFILES variable is initialized based on the Windows Installer property ProgramFilesFolder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding PROGRAMFILES variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

PROGRAMFILES64
The PROGRAMFILES64 system variable contains the fully qualified name of the folder defined by Windows to store 64-bit applications on a 64-bit system. (Note that 32-bit applications are stored under the PROGRAMFILES folder.) In English Windows, that folder is named Program Files, and it is located off the root of the drive on which Windows is installed. (In other language versions of Windows, the folder name is localized appropriately by default.) The program files folders are the recommended default locations for application folders.

Tip: If your company distributes more than one application, you may prefer to create a company folder inside the program files folder and then create application folders within the company folder.

This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

Project: During setup initialization in InstallScript installations, the value of the PROGRAMFILES64 variable is obtained by calling the Windows API function SHGetSpecialFolderPath with the CSIDL_PROGRAM_FILES parameter from a 64-bit executable file. In Basic MSI and InstallScript MSI installations, the value of the PROGRAMFILES64 variable is initialized based on the Windows Installer property ProgramFiles64Folder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding PROGRAMFILES64 variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

REGDB_OPTIONS
The REGDB_OPTIONS system variable enables you to set various options for the general registry functions. The following table describes the options that you can specify:
Table 7-12: REGDB_OPTIONS Option REGDB_OPTION_DISABLETEXTSUBS Meaning Disables text substitutions in strings that are passed to registry functions. Use this option when working with registry function strings that contain opening angle brackets (<) and closing angle brackets (>) but that should not be interpreted as text substitutions.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

301

Chapter 7: Variable Data System Variables

Table 7-12: REGDB_OPTIONS (cont.) Option REGDB_OPTION_NO_DELETE_OLD_MAJMIN_VERSIO N Meaning Prevents the MaintenanceStart function from deleting the legacy values of the following constants:

REGDB_VALUENAME_UNINSTALL_MAJORVERSION (the major version value name under the application uninstallation key), whose value was MajorVersion for installations that were created with InstallShield 2009 and earlier REGDB_VALUENAME_UNINSTALL_MINORVERSION (the minor version value name under the application uninstallation key), whose value was MinorVersion for installations that were created with InstallShield 2009 and earlier

For more information, see the Changes to the Major and Minor Version Registry Entries for the Uninstall Key of InstallScript Installations section in Upgrading Projects from InstallShield 2009 or Earlier. REGDB_OPTION_WOW64_64KEY Specifies that all future general registry operations affect the 64-bit parts of the registry instead of the 32-bit parts of the registry (on a 64-bit system). Setting this option on a 32-bit system has no effect. Resets (clears) all previously set options.

REGDB_OPTION_USE_DEFAULT_OPTIONS

To add options, combine one or more options using bitwise OR (|) operator as shown:
REGDB_OPTIONS = REGDB_OPTIONS | REGDB_OPTION_WOW64_64KEY

To remove options, specify the option to remove using the bitwise AND (&) operator and the bitwise NOT (~) operator as shown:
REGDB_OPTIONS = REGDB_OPTIONS & ~REGDB_OPTION_WOW64_64KEY

Note: When you enable the REGDB_OPTION_WOW64_64KEY option, this affects where registry entries from registry sets are created. For example, if this option is enabled when you call the CreateRegistrySet function, the registry set is created in the 64-bit part of the registry. It is recommended that you enable this option for the specific 64-bit registry sets you want to install, then disable the option so other registry entries or sets are not incorrectly created in the 64-bit part of the registry. The InstallScript engine currently does not support installing Add or Remove Programs information for a product in the 64bit part of the registry; therefore, the REGDB_OPTION_WOW64_64KEY option is not supported for the specific registry functions such as CreateInstallationInfo, MaintenanceStart, RegDBGetItem, RegDBSetItem, RegDBGetAppInfo, RegDBSetAppInfo, and RegGetUninstCmdLine.

302

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

REINSTALLMODE
This system variable is non-zero if one of the reinstall functions has been called in an InstallScript installationthat is, if FeatureReinstall, FeatureUpdate, or FeaturePatch have been called in the current instance of the installation.

Project: In an InstallScript MSI installation, this system variable is non-zero if the FeatureReinstall function is called. FeatureUpdate and FeaturePatch are not defined in an InstallScript MSI installation and should not be called.

REMOVEALLMODE
Project: This information applies to InstallScript projects.

This system variable is non-zero if the application is being completely uninstalledthat is, if FeatureRemoveAll, FeatureRemoveAllInMedia, or FeatureRemoveAllInMediaAndLog have been called in the current instance of the setupand FALSE otherwise. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

Note: To execute script code only when the application is being completely uninstalled, enclose the code in the following ifthen statement:
if REMOVEALLMODE!=0 then /* this code is executed only during uninstallation */ endif;

To perform specific uninstallation actions when a particular component is uninstalled, override the component's <ComponentName>_Uninstalling event and perform the actions in this event.

REMOVEONLY
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The REMOVEONLY system variable is set equal to a non-zero value if Setup.exe is run with the removeonly option, and is set equal to FALSE otherwise. The default code for the OnMaintUIBefore event handler function conditionally displays the SdWelcomeMaint dialog, depending on the value of REMOVEONLY. This system variable is read-only; if you attempt to assign a value to it, a compiler error results.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

303

Chapter 7: Variable Data System Variables

SELECTED_LANGUAGE
Project: The following project types support SELECTED_LANGUAGE:

InstallScript InstallScript MSI

The numeric system variable SELECTED_LANGUAGE contains the ID of the language that the installation is using to display prompts and messages. This system variable has a corresponding <SELECTED_LANGUAGE> text substitution, which contains the value of SELECTED_LANGUAGE formatted as a four-digit hexadecimal value (including the 0x prefix). For example, if SELECTED_LANGUAGE is ISLANG_ENGLISH, the value of the text substitution is 0x0409.

SHAREDSUPPORTDIR
Project: InstallScript projects support SHAREDSUPPORTDIR.

The read-only variable SHAREDSUPPORTDIR identifies the directory that contains all of the support files that are shared among an InstallScript installation and all of the InstallScript objects in that installation. This system variable has a corresponding <SHAREDSUPPORTDIR> text substitution.

SHELL_OBJECT_FOLDER
Project: The following project types support SHELL_OBJECT_FOLDER:

InstallScript InstallScript MSI

The SHELL_OBJECT_FOLDER system variable is used to specify the name of a shell object folder typically a Start Menu folderat run time through script. You can specify SHELL_OBJECT_FOLDER (for InstallScript or InstallScript MSI projects) or <SHELL_OBJECT_FOLDER> (for InstallScript projects) in the Display Name setting for a folder in the Shortcuts view. Then you can define the display name for the folder at run time by setting the SHELL_OBJECT_FOLDER variable in your script before the shortcut is created. The shortcut is typically created during file transfer.

Project: For InstallScript projects, you can specify either <SHELL_OBJECT_FOLDER> or SHELL_OBJECT_FOLDER in the Display Name setting. In both cases, text substitution is used. However, including the angle brackets <SHELL_OBJECT_FOLDER>is recommended. For InstallScript MSI projects, you must specify SHELL_OBJECT_FOLDER (without the angle brackets).
304 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

To use this functionality in an InstallScript MSI installation, any letters that are specified for the Key Name setting of the folder in the Shortcuts view must be all uppercase (for example, NEWFOLDER1).

If the installation is not in maintenance mode, SHELL_OBJECT_FOLDER is initialized to the same value as IFX_PRODUCT_NAME during initialization of the InstallScript engine. Note that these variables are not synchronized once initialized; therefore, if you change one and want the other to change, you must change both manually. These types of manual changes are logged, and the changes are read from the log on subsequent maintenance operations. Therefore, a shortcut that uses the SHELL_OBJECT_FOLDER variable for its display name can be removed during uninstallation.

SHOW_PASSWORD_DIALOG
Project: This information applies to InstallScript projects.

The SHOW_PASSWORD_DIALOG system variable is TRUE if the "Show Password dialog box during setup initialization" check box was checked in the Media Wizard's General Options panel or the media property sheet's General page, or FALSE otherwise.

SRCDIR
This system variable contains the fully qualified path to the source folder that contains the Windows Installer package. SRCDIR is initialized to the value of the Windows Installer property SourceDir when the sequence begins, and it cannot be assigned a new value in an InstallScript custom action.

SRCDISK
This system variable contains the name of the drive with the source disk. During setup initialization, InstallShield assigns to SRCDISK the name of the drive that holds the disk containing the setup script file, Setup.inx. For example, if you start Setup.exe from a floppy disk in the A drive, then if that disk contains the file Setup.inx, InstallShield assigns the value A: to SRCDISK. Note that InstallShield includes the colon (:) with the drive letter.

Note: If you intend to reference the root folder of the drive specified by this variable, you must append a backslash to it (specified as two backslashes). For example, if the value of SRCDISK is A:, the following statement refers to the root folder of that drive: SRCDISK + "\\".

SUPPORTDIR
During setup initialization, the installation locates a folder on the target system into which it can copy temporary files and files that were compressed into your installation. The installation sets the value of SUPPORTDIR to the fully qualified path for that folder.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

305

Chapter 7: Variable Data System Variables

In addition, files that you add to the Language Independent (or language-specific) file list in the Support Files/Billboards view of InstallShield are decompressed into SUPPORTDIR when the installation initializes, and they are deleted when the installation is complete. To access a particular support file in an InstallScript project, use the SUPPORTDIR variable directly and then append the file name to the SUPPORTDIR value to obtain the complete path of the file. Following is an example of InstallScript event code:
prototype STRING GetSupportFilePathIS(STRING); function STRING GetSupportFilePathIS(szSupportFile) begin return SUPPORTDIR ^ szSupportFile; end;

Note: The value of the InstallScript variable SUPPORTDIR is not shared among InstallScript Object scripts or between InstallScript Object scripts and the main installation script.

Project: Note that the value of the InstallScript system variable SUPPORTDIR is not the same as the value of the Windows Installer property SUPPORTDIR. In event-driven InstallScript, the SUPPORTDIR system variable points to the folder that contains support files. In Basic MSI or InstallScript MSI projects, each InstallScript custom action initializes its own engine. Each engine does not know where the primary SUPPORTDIR is, and each engine does not extract its own private copy of the support files. For instructions on locating the extracted support files from a custom action, see Placing Files in the .msi Database and Extracting Them During Run Time.

SYSINFO
During setup initialization, the installation sets the members of the SYSINFO structure variable to identify the operating platform of the target computer. By inspecting the values assigned to members of this variable, your script can determine information such as the following:

The operating system The major and minor version number of the operating system The subversion of the operating system The version of Internet Explorer The latest service pack that is installed If the end user has administrator rights under Windows NT If the end user is a power user If the system is 64-bit If the system is a virtual machine The language IDs of the system language, user language, and operating system language

306

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

The following table shows the meaning of each SYSINFO member:

Table 7-13: SYSINFO Members Member SYSINFO.bIntel SYSINFO.bIsVirtualMachine Meaning If TRUE, the processor is Intel. If TRUE, a virtual machine is detected. For more information, see Detecting Whether the Installation Is Being Run on a Virtual Machine. SYSINFO.bIsWow64 SYSINFO.bShellExplorer SYSINFO.bWinServer2003R2 SYSINFO.nISOSL If the installation is running on a 64-bit platform, this value is non-zero. If TRUE, the shell is Explorer. If this member is TRUE, the operating system is Windows Server 2003 R2. Value indicates the operating system of the target machine. Possible values are the following:

ISOSL_WIN2000Windows 2000 ISOSL_WINXPWindows XP Edition ISOSL_WINSERVER2003Windows Server 2003 ISOSL_WINVISTA_SERVER2008 (or ISOSL_WINVISTA)Note that Windows Vista and Windows Server 2008 use the same major and minor version numbers. Therefore, if you want to use InstallScript to distinguish between Windows Server 2008 and Windows Vista, check whether SYSINFO.nOSProductType = VER_NT_WORKSTATION; for Windows Vista, this is TRUE; for Windows Server 2008, it is FALSE. ISOSL_WIN7_SERVER2008R2Windows 7 or Windows Server 2008 R2

SYSINFO.nOSMajor SYSINFO.nOSMinor SYSINFO.nOSProductType

Value indicates operating system's major version number. Value indicates operating system's major version number. Value indicates the wProductType of the Windows OSVERSIONINFOEX structure as defined for the current platform. Possible values are the following:

VER_NT_WORKSTATION VER_NT_DOMAIN_CONTROLLER VER_NT_SERVER

You can also #define and test for any other constant supported by wProduct Type. The OSVERSIONINFOEX structure is documented at http:// msdn.microsoft.com/library/en-us/sysinfo/base/osversioninfoex_str.asp.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

307

Chapter 7: Variable Data System Variables

Table 7-13: SYSINFO Members (cont.) Member SYSINFO.nOSSuiteMask Meaning Value indicates the wSuitesMask of the Windows OSVERSIONINFOEX structure as defined for the current platform. Possible values are the following:

VER_SUITE_BACKOFFICE VER_SUITE_DATACENTER VER_SUITE_ENTERPRISE VER_SUITE_PERSONAL VER_SUITE_SMALLBUSINESS VER_SUITE_SMALLBUSINESS_RESTRICTED VER_SUITE_TERMINAL

You can also #define and test for any other constant supported by wSuiteMask. The OSVERSIONINFOEX structure is documented at http:// msdn.microsoft.com/library/en-us/sysinfo/base/osversioninfoex_str.asp. SYSINFO.nSuites A combination of one or more bit flags that indicate the suite or suites on the target machine. Possible bit flags are the following:

ISOS_ST_ALL ISOS_ST_XP_PRO ISOS_ST_XP_HOME ISOS_ST_SERVER ISOS_ST_SERVER2003_R2 ISOS_ST_WORKSTATION ISOS_ST_BACKOFFICE ISOS_ST_DATACENTER ISOS_ST_ENTERPRISE ISOS_ST_SERVER2003_R2 ISOS_ST_SMALLBUSINESS ISOS_ST_SMALLBUSINESS_RESTRICTED ISOS_ST_TERMINAL 0 (zero)indicates that no suite is detected on the target machine

To check whether a bit flag is set, use the bitwise AND (&) operator as in the following example:
if (SYSINFO.nSuites & ISOS_ST_XP_HOME) then /* Perform operations that are specific to Windows XP Home Edition. */ endif;

Note: The suites listed here are those that can be specified in the Windows API's OSVERSIONINFOEX data structure (as documented at http:// msdn.microsoft.com/library/en-us/sysinfo/base/osversioninfoex_str.asp).

308

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

Table 7-13: SYSINFO Members (cont.) Member SYSINFO.nSystemDefaultUILangI D SYSINFO.nSystemLangID SYSINFO.nUserLangID SYSINFO.nWinMajor SYSINFO.nWinMinor SYSINFO.szInstalledIEVersion Meaning Value indicates the installed operating system language's ID.

Value indicates the system language's ID. Value indicates the user language's ID. Value indicates Windows major version number. Value indicates Windows minor version number. Value indicates the Internet Explorer version on the system. This member is supported for versions 4 and later. If the version installed is earlier than 4, the value is null ("").

Note: Do not rely on the fact that this value is null for versions earlier than 4. Instead, test specifically for 4 or later, since in the future, this member variable could support detecting Internet Explorer versions earlier than 4. SYSINFO.WINNT.bAdmin_Logged _On SYSINFO.WINNT.bPowerUser_Log ged_On SYSINFO.WINNT.bWin7_Server20 08R2 SYSINFO.WINNT.bWinNT If this member is TRUE, the end user is logged on under NT with administrator rights. If this member is TRUE, the current user belongs to the power user group.

If this member is TRUE, the operating system is Windows 7 or Windows Server 2008 R2. If this member is TRUE, the operating system is Windows NT (includes Windows 2000 and Windows XP). If either SYSINFO.WINNT.bWinVista_Server2008 or SYSINFO.WINNT.bWinVista is TRUE, the operating system is Windows Vista or Windows Server 2008. To distinguish between Windows Server 2008 and Windows Vista, check whether SYSINFO.nOSProductType is equal to VER_NT_WORKSTATION; for Windows Vista, this is TRUE; for Windows Server 2008, it is FALSE. If this member is TRUE, the operating system is Windows XP. If this member is TRUE, the operating system is Windows 2000.

SYSINFO.WINNT.bWinVista_Serve r2008 (SYSINFO.WINNT.bWinVista)

SYSINFO.WINNT.bWinXP SYSINFO.WINNT.bWin2000

SYSINFO.WINNT.bWinServer2003 If this member is TRUE, the operating system is Windows Server 2003 or Windows Server 2003 R2. SYSINFO.WINNT.nServicePack The number of the installed service pack. The installation obtains this information by calling the Windows API GetVersionEx and reading the nServicePackMajor value.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

309

Chapter 7: Variable Data System Variables

Example
The following code fragment displays a message box if the operating system on the target system is Windows XP.
if (SYSINFO.WINNT.bWinXP) then MessageBox("Installing on Windows XP",INFORMATION); endif;

SYSPROCESSORINFO
During setup initialization, the installation sets the members of this structure variable to identify information about the processor of the target computer. By inspecting the values assigned to members of this variable, your script can determine information such as the number of processors on the system and the type of processor. The following table shows the meaning of each SYSPROCESSORINFO member:

Note: Each of these members corresponds to a member in the Windows SYSINFO structure. These are populated during initialization by calling the Windows API GetSystemInfo or GetNativeSystemInfo functions on 64-bit Windows systems. Consult the documentation on this structure in the MSDN Library. Also, as documented by Microsoft, using nProcessorType is not recommended. Use nProcessorLevel and nProcessorArchitecture instead. Table 7-14: SYSPROCESSORINFO Member Meaning

SYSPROCESSORINFO.nProcessorA Indicates the processor architecture. Possible values are the following: rchitecture PROCESSOR_ARCHITECTURE_INTEL PROCESSOR_ARCHITECTURE_IA64 PROCESSOR_ARCHITECTURE_AMD64 PROCESSOR_ARCHITECTURE_UNKNOWN

Note: InstallScript includes constants for the most common values for this structure member. However, in unusual cases, this structure member could contain other values defined by Windows. Consult the Windows documentation on the corresponding SYSINFO member for more information on possible additional values. SYSPROCESSORINFO.nNumberOf Processors Indicates the number of processors on the system.

310

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

Table 7-14: SYSPROCESSORINFO (cont.) Member Meaning

SYSPROCESSORINFO.nProcessorT Indicates the processor type. Possible values are the following: ype PROCESSOR_INTEL_386 PROCESSOR_INTEL_486 PROCESSOR_INTEL_PENTIUM PROCESSOR_INTEL_IA64 PROCESSOR_AMD_X8664

Note: InstallScript includes constants for the most common values for this structure member. However, in unusual cases, this structure member could contain other values defined by Windows. Consult the Windows documentation on the corresponding SYSINFO member for more information on possible additional values. SYSPROCESSORINFO.nProcessorL evel Indicates the system's architecture-dependent processor level. This is often defined by the vendor and should be used for display purposes. See the Windows documentation on the SYSINFO structure for further information on the meaning of these members.

SYSPROCESSORINFO.nProcessorR Indicates the system's architecture-dependent processor revision. See the evision Windows documentation on the SYSINFO structure for further information on the meaning of these members.

TARGETDIR
During setup initialization, the installation assigns to the system variable TARGETDIR the fully qualified path to a target folder on the hard disk. This folder will be the one containing the file Win.ini, usually the Windows folder. Some InstallScript functions use this variable when performing file operations. You must set this variable to the folder you want to target before calling these functions. The default code for the OnFirstUIBefore event handler function assigns a value to TARGETDIR. The value of this system variable is shared among object scripts and between object scripts and the main setup script. The value you assign to this system variable in any script is the value it has in the subsequently executed code in any script (until its value is explicitly reset).

TARGETDISK
During setup initialization, the installation assigns the name of the target disk drive to the system variable TARGETDISK. This drive will be the one containing the file Win.ini, usually the C: drive. Note that InstallShield includes the colon (:) with the drive letter.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

311

Chapter 7: Variable Data System Variables

Note: If you intend to reference the root folder of the drive specified by this variable, you must append a backslash to it (specified as two backslashes). For example, if the value of TARGETDISK is C:, the following statement refers to the root folder of that drive: TARGETDISK + "\\".

UNINST
Project: The following project types support UNINST:

InstallScript InstallScript MSI

The UNINST system variable is provided for compatibility with earlier versions of InstallShield software. It contains the command line that launches the copy of Setup.exe that was placed on the target system to perform uninstallation. The default value is:
<UNINSTALL_STRING> -uninst

If you use this command line, the installation runs the OnUninstall event when the installation is launched. For more details, review the /uninst command-line parameter information for Setup.exe. This command line is placed in the appropriate registry value by the DeinstallStart function, which is provided for compatibility with previous versions of InstallShield software. The value of this system variable is shared among object scripts and between object scripts and the main setup script. You can append your own custom command line switches to UNINST for processing by your scripts uninstallation code. If you do so, and you change the value of the system variable DISK1TARGET, be sure to change DISK1TARGET before appending to UNINST; UNINST incorporates DISK1TARGET and is automatically changed when you change DISK1TARGET.

UNINSTALLKEY
Project: This information applies to the following project types:

InstallScript InstallScript MSI

Note that project-specific differences are provided where applicable.

The UNINSTALLKEY system variable contains the name of the registry key that is used to store your uninstallation information. The registry key is placed under SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall. In an InstallScript installation, this key is placed under HKEY_USER_SELECTABLE_AUTO, which is controlled by the value of the ALLUSERS script variable. In an InstallScript MSI installation, this key is placed under HKEY_LOCAL_MACHINE if the installation is being run by an administrator; otherwise, it is placed under HKEY_CURRENT_USER.
312 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

In an InstallScript installation, the default value is INSTANCE_GUID. In an InstallScript MSI installation, the default value of UNINSTALLKEY is InstallShield_{ProductCode}. To specify a different uninstallation key, assign a new value to UNINSTALLKEY in your script, as in the following example:
UNINSTALLKEY = "Sample App";

Note that to avoid conflicts with other installed applications, be sure to use a value that is unique to your application. If the UNINSTALLKEY variable has been changed from the default value, the installation automatically creates an additional registry key for the product:

For InstallScript installationsREGDB_KEYPATH_ISUNINSTINFO ^ INSTANCE_GUID For InstallScript MSI installationsREGDB_KEYPATH_ISUNINSTINFO ^ [ProductGuid]

This key contains a single string value with the name UninstallKey (REGDB_VALUENAME_UNINSTALLKEY); the value data contains the name of the products uninstall key as determined by the UNINSTALLKEY variable. This value can be used to allow other products to find and use the uninstall information for the product without the products custom uninstall key.

UNINSTALL_DISPLAYNAME
This system variable contains the displayed name of your product in Add or Remove Programs. This value is typically the product name you specified in the General Information view. To specify a different uninstallation display name, assign a new value to UNINSTALL_DISPLAYNAME in your script before data transfer, as in the following:
UNINSTALL_DISPLAYNAME = "Sample App";

Project: UNINSTALL_DISPLAYNAME is used only in InstallScript and InstallScript MSI installation projects. Basic MSI projects use the value of the ProductName property as the product's display name in Add or Remove Programs.

UNINSTALL_STRING
Project: The following project types support UNINSTALL_STRING:

InstallScript InstallScript MSI

The UNINSTALL_STRING system variable contains the command line that launches the setup launcher, the installations executable file, which was placed on the target system to perform uninstallation. The default value is:
<DISK1TARGET>\<DISK1SETUPEXENAME> -runfromtemp -l<SELECTED_LANGUAGE>

The setup launcher automatically writes the UNINSTALL_STRING command line to the registry, unless you have hidden the Remove button (via the Disable Remove Button property) in Add or Remove Programs.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

313

Chapter 7: Variable Data System Variables

You can append your own custom command line switches to UNINSTALL_STRING for processing by your scripts uninstallation code.

UPDATEMODE
The UPDATEMODE system variable applies to InstallScript projects only. This system variable is set by the OnSetUpdateMode event handler function and is used by the OnShowUI event handler to call the appropriate UI event handlers.

WINDIR
The WINDIR system variable contains the fully qualified name of the folder that contains the main operating environment, for example C:\Windows. This system variable is read-only; if you attempt to assign a value to it, a compiler error results. The value of this system variable is shared among object scripts and between object scripts and the main setup script.

Project: During setup initialization in InstallScript installations, the value of the WINDIR variable is obtained by calling the Windows API function GetWindowsDirectory. In Basic MSI and InstallScript MSI installations, the value of the WINDIR variable is initialized based on the Windows Installer property WindowsFolder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding WINDIR variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

WINDISK
The WINDISK system variable contains the ID of the disk drive that contains the main operating environment. This drive is the one that contains the Windows programusually drive C. Note that the InstallScript engine includes the colon (:) with the drive letter.

Note: If you intend to reference the root folder of the drive specified by this variable, you must append a backslash to it (specified as two backslashes). For example, if the value of WINDISK is C:, the following statement refers to the root folder of that drive: WINDISK + "\\".

Project: During setup initialization in InstallScript installations, the value of the WINDIR variable is obtained by calling the Windows API function SHGetSpecialFolderPath with the CSIDL_WINDOWS parameter. In Basic MSI and InstallScript MSI installations, the value of the WINDIR variable is obtained by calling the InstallScript function GetDisk with WINDIR; if that fails, this variable is initialized based on the Windows Installer property WindowsVolume. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding WINDIR variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

314

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 7: Variable Data System Variables

WINSYSDIR
The WINSYSDIR system variable contains the name of the Windows system folder. This folder is used to store application extensions (DLLs), device drivers, and other Windows system files, depending on the version of Windows. On 64-bit Windows systems, this variable points to the folder that stores Windows system files that are used by 32-bit applications. This folder is named SYSWOW64. There is a different Windows system folder for system files to be used by 64-bit applications; the system variable WINSYSDIR64 provides limited access to this folder.

Project: During setup initialization in InstallScript installations on 32-bit systems, the value of the WINSYSDIR variable is obtained by calling the Windows API GetSystemFolder. During setup initialization in InstallScript installations on 64-bit systems, the value of the WINSYSDIR variable is obtained by calling the Windows API GetSystemWow64Directory from a 64-bit executable file. In Basic MSI and InstallScript MSI installations on 32-bit systems, the value of the WINSYSDIR variable is initialized based on the Windows Installer property SystemFolder. On 64-bit systems, the value is initialized based on the Windows Installer property System64Folder. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding WINSYSDIR variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

WINSYSDIR64
The WINSYSDIR64 system variable contains the name of the 64-bit Windows system folder. This folder is used to store application extensions (DLLs), device drivers, and other Windows system files, depending on the version of Windows. Although the WINSYSDIR64 variable is set to the 64-bit Windows folder, 64-bit Windows includes functionality to automatically redirect 32-bit applications (such as the InstallScript engine) to the 32-bit Windows folder. Therefore, if you are installing files to WINSYSDIR64, you must first disable file system redirection using WOW64FSREDIRECTION. Otherwise, files being installed to WINSYSDIR64 are incorrectly redirected to the 32-bit Windows system folder. Since some Windows functionality that could be used by the installation requires that redirection be enabled to work, Windows documentation recommends that you disable redirection only for as long as necessary. It is recommended that you then enable file system redirection as soon as you have completed installing the necessary files to WINSYSDIR64. The example code below shows how to disable and enable redirection before and after installing a file to the WINSYSDIR64:
Disable (WOW64FSREDIRECTION); XCopyFile (SUPPORTDIR ^ "MyFile.dll", WINSYSDIR64, COMP_NORMAL); Enable (WOW64FSREDIRECTION);

Project: During setup initialization in InstallScript installations on 64-bit systems, the value of the WINSYSDIR64 variable is obtained by calling the Windows API GetSystemFolder from a 64-bit executable file. In Basic MSI and InstallScript MSI installations on 64-bit systems, the value of the WINSYSDIR64 variable is initialized based on the Windows Installer property System64Folder. Note that deferred, commit, and rollback custom actions do
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 315

Chapter 7: Variable Data System Variables

not have access to this property. Therefore, the corresponding WINSYSDIR variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

WINSYSDISK
The WINSYSDISK system variable contains the name of the disk drive that contains the Windows system folderusually the C: drive. This folder is used to store application extensions (DLLs), device drivers, and other Windows system files, depending on the version of Windows. Note that the InstallScript engine includes the colon (:) with the drive letter. For information about the Windows system folder, see the documentation for the InstallScript system variable WINSYSDIR.

Note: If you intend to reference the root folder of the drive specified by this variable, you must append a backslash to it (specified as two backslashes). For example, if the value of WINSYSDISK is C:, the following statement refers to the root folder of that drive: WINSYSDISK + "\\".

Project: During setup initialization in InstallScript installations, the value of the WINSYSDIR variable is obtained by calling the Windows API GetSystemFolder. In Basic MSI and InstallScript MSI installations, the value of the WINSYSDIR variable is obtained by calling the InstallScript function GetDisk with WINSYSDIR; if that fails, this variable is initialized based on the Windows Installer property WindowsVolume. Note that deferred, commit, and rollback custom actions do not have access to this property. Therefore, the corresponding WINSYSDIR variable is empty in deferred, commit, and rollback custom actions. To learn more, see Accessing or Setting Windows Installer Properties Through Deferred, Commit, and Rollback Custom Actions.

316

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

8
Preprocessor Directives
Preprocessor directives are instructions to the InstallScript compiler that are executed as the script is compiled. Preprocessor directives can instruct the compiler to include other source files in the compilation, to define constants, to include or exclude statements based on compile-time conditions, and to display a user-defined error message. Although InstallScript directives are similar to directives in the C language, they are not exactly alike. Preprocessor directives begin with a pound sign (#) and can be inserted anywhere in a script. Each directive must appear on a line by itself and must not be terminated with a semicolon.

Using Preprocessor Directives

Use the following guidelines when using preprocessor directives in your script. A preprocessor directive meets the following conditions:

It does not end with a semicolon. It cannot line wrap. It must be less than 250 characters in length.

Note: The expressions used in conditional directives can include constants that have been defined with the #define directive. They cannot include variables.

Supported Boolean Operators

The following Boolean operators are supported in #if, #ifdef, #ifndef, and #elif statements:

Logical OR ( || ) Logical AND ( && ) Relational ( =, !=, >, >=, <, <= ) InstallScript-Supported Preprocessor Directives

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

317

Chapter 8: Preprocessor Directives #define

InstallScript supports the following preprocessor directives:

Table 8-1: Preprocessor Directives Preprocessor Directive #define #elif #else #endif #error #if #ifdef #ifndef #include #undef #warning Description Creates a symbolic constant. Combines #else and #if into one statement. Indicates alternatives if the test fails. Ends a preprocessor conditional directive (#if, #ifdef, #ifndef). Displays a user-defined error message. Compiles if the conditional statement is true. Compiles if a numeric constant is defined. Compiles if a numeric constant is not defined. Includes the contents of another file. Undefines a constant that was defined previously with #define. Display a compiler warning and a user-defined error message.

#define
Use #define to define a number or string constant. When you define a constant and assign it a value, InstallShield replaces the constant with that value wherever it appears. For example, the following #define statement sets the value of MAX_SIZE to 145:
#define MAX_SIZE 145

The following example declares a string constant with the #define directive:
#define STR_MESSAGE "This is a message."

Once you have defined STR_MESSAGE, you can use it anywhere in the script. A string message you want displayed in SprintfBox or MessageBox cannot be longer than 255 characters. If you want to display more than 255 characters, split your string into two or more parts before displaying it. The 255character limit includes spaces, escape sequences, and other special characters.

Note: Another way to define constants is in the Preprocessor Defines field on the Compile tab of the Setup Settings dialog box. If you add or change a preprocessor define in the Setup Settings dialog box, you must recompile your setup before the changes will take effect.

Restrictions
There are a few restrictions regarding the #define directive:

318

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 8: Preprocessor Directives #elif

InstallShield supports the use of #define to define only macros that involve the simple lexical substitution of a number or a string. You cannot define macros with expressions using multiple terms or operators. Constants you declare with a #define statement cannot begin with numbers. Many InstallShield functions use predefined constants. If you try to define one of the predefined constants, the InstallShield Script Compiler generates an error message. InstallShield assigns a value of zero (0) to an undefined constant.

#elif
The #elif compile-time statement is similar in function to the elseif run-time statement. It combines the #if and #else statements, allowing you to specify another condition. For example:
#if (A = 1) // compile if A equals 1 . . . #elif (A = 2) // compile if A equals 2 . . . #elif (B = 3) // compile if B equals 3 . . . #else // if none of the #elif conditions are true, compile // the following portion . . . #endif

Note: When using #elif, end the section with only one #endif.

#error
Use the #error directive to abort compilation and display a user-defined error message. The message to display must be entered immediately after #error and be separated from the directive by at least one space. In the example below, the constant PRODUCTID must equal 1 or 2. If the value of PRODUCTID is not within that range, the constant PRODUCTNAME is not defined and a user-defined error message is displayed.
#define PRODUCTID 1 #if (PRODUCTID = 1) #define PRODUCTNAME "Lite" #elif (PRODUCTID = 2) #define PRODUCTNAME "Professional" #endif #ifndef PRODUCTNAME #error PRODUCTID out of range.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

319

Chapter 8: Preprocessor Directives #if. . .#else. . .#endif

#endif

#if. . .#else. . .#endif

Use the #if statement to select which lines to compile. You can switch various sections of the installation on and off, making the script more flexible. The #if statement works in the same manner as the run-time if statement:
#if (A = 1) // compile if A equals 1 . . . #else // compile . . . #endif

Keep in mind the following restrictions when using #if:

Note that the format of the #if statement is also identical to that of the run-time if statement; you must end the #if statement with the keyword #endif. You can test only numeric constants with an #if or #elif statement. InstallScript allows nesting of #if statements up to a maximum of 10 levels.

#ifdef and #ifndef

Use the #ifdef statement when you want to compile a section only if a specified expression has been defined with #define. Use #ifndef when you want to compile a section only if a specified expression has not been defined.

Example
#ifdef A // Compile if A is defined. . . . #endif #ifndef A // Skip if A is defined; otherwise compile. . . . #endif #ifdef A // Compile if A is defined. otherwise compile. . . .#endif . . .#endif#ifndef A // Skip if A is defined;

You can also use #ifdef and #ifndef with #else and #elif:
#ifdef nFilePath //statements #else //statements #endif

320

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 8: Preprocessor Directives #include

Note: Preprocessor defines can be entered in the Project Settings dialog box's Compile/Link tab's Preprocessor Defines edit box. If you add or change a preprocessor definition in the Project Settings dialog box, you must recompile your setup for the changes to take effect.

Restrictions
Keep in mind the following restrictions when using #ifdef and #ifndef statements:

You cannot place comments on the same line as #ifdef and #ifndef directives. Do not test a constant that has a value of 0 (zero) with an #ifdef or #ifndef statement. You can test only numeric constants with an #ifdef or #ifndef statement.

#include
Use the #include statement to include the contents of another script in the main installation script. When you use #include, the compiler treats the additional source script as if it were part of the main installation script. Additional scripts, or include files, may contain variable declarations, other compiler directives, and program statements. For example, you can create a separate file that contains all the user-defined constant definitions and then insert it into the script file using the #include statement. If you need to redefine any of the constants at a later date, they are all in one central location. When you compile from the InstallShield interface, InstallShield searches for include script files in the following order:
1. 2. 3.

The projects script file directory The directories that are specified in the Include Paths setting on the Compile/Link tab of the Settings dialog box The InstallShield include directory

If two include files share the same name but they are stored in different locations, InstallShield links to the one that it finds first, according to the aforementioned order. In addition, if an include file is specified by a relative path, InstallShield searches for the path relative to the aforementioned directories, in order. If the include file is not in any of these locations, specify a fully qualified file name in the #include statement. When using the #include statement, specify a file name or path by enclosing the file name or path in double quotation marks (filename). Note the following details when you are using #include directives in your script:

InstallShield does not handle paths with more than 260 characters, including the file name. InstallScript allows nesting of include files up to a maximum of eight levels. The InstallShield preprocessor does not interpret a backslash character in an #include directive as a control character; when specifying a path, use a single backslash instead of double backslashes to separate folder names.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

321

Chapter 8: Preprocessor Directives #undef

Do not include C language header files in the script. The InstallShield compiler does not recognize some of Cs constructs. Create header files using InstallScript only.

The following example shows a section of an installation script that uses the #include statement to include the contents of Support.rul and other files. Each of the source scripts referenced by the #include statements has been written for a specific purpose and is then added to the script when the script is compiled:
//The following include file contains installation-specific routines. #include "SUPPORT.RUL" // Local include file containing variable and prototype declarations. #include "DECLARE.RUL"

// Include scripts from the LIBRARY directory #include "..\LIBRARY\SYSCHK.H" // Include scripts from the DIALOGS directory. #include "..\DIALOGS\WELCOME\WELCOME.H" #include "..\DIALOGS\REGINS\REGINS.H" #include "..\DIALOGS\ICONS\ICONS.H"

#undef
Use the #undef directive to undefine a constant that was previously defined with #define. If you specify a constant with this directive that was not previously defined with the #define directive, an error will occur when you attempt to compile your script. In the following example, two constants are defined; then, the first constant is undefined if the second has been defined:
#define NORMSETUP #define BONUSPAK . . . #ifdef NORMSETUP MessageBox('Compiling for normal setup .',INFORMATION); #else MessageBox('Compiling for super setup.',INFORMATION); #endif #ifdef BONUSPAK #undef NORMSETUP #endif #ifdef NORMSETUP MessageBox('Compiling for normal setup .',INFORMATION); #else MessageBox('Compiling for super setup.',INFORMATION); #endif

322

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 8: Preprocessor Directives #warning

#warning
Use the #warning directive to display a compiler warning and a user-defined error message. The message to be displayed must be entered immediately after #warning and be separated from the directive by at least one space. In the example below, the constant PRODUCTID must equal 1 or 2. If the value of PRODUCTID is not within that range, the constant PRODUCTNAME is not defined and a user-defined warning message is displayed.
#define PRODUCTID 1 #if (PRODUCTID = 1) #define PRODUCTNAME "Lite" #elif (PRODUCTID = 2) #define PRODUCTNAME "Professional" #endif #ifndef PRODUCTNAME #warning PRODUCTID out of range. #endif

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

323

Chapter 8: Preprocessor Directives #warning

324

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

9
Event Handlers

Project: InstallScript event handlers are not available in Basic MSI projects or merge module projects. These project types use custom actions to run InstallScript.

About Event Handlers

InstallScript project installation programs are driven by the InstallScript engine, which generates a series of events in a specific order. These events trigger software handlers that execute installation instructions. For example, shortly after an installation is loaded, it generates an event called Begin, which triggers the execution of an event handler called OnBegin. This handler specifies the instructions to carry out when the Begin event occurs. Other events occur in the installation to trigger other handlers. Together, the event handlers perform the work of installing the application. InstallShield defines several types of event handlers:

Global Event Handlers Feature Event Handlers Miscellaneous Event Handlers Advanced Event Handlers

When you create an InstallScript project, InstallShield generates a set of default global event handlers, each of which is a function scripted in the InstallScript language. Likewise, when you add features to your project, InstallShield generates a set of default event handlers for that feature. You can override or customize any or all of the event handlers. It is important to note that, in an event-driven script, event-handler functions are called even if they do not explicitly appear in the InstallScript view.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

325

Chapter 9: Event Handlers

Order of Event Handlers

Global and feature event handlers are always called in a specific order; which event handlers are called depends on the type of installation (normal installation, maintenance installation, administrative installation, or patch installation). Because miscellaneous event handlers respond to events that may not happen during installation, they are not necessarily called in a specific order, if they are called at all. First-Time Installations

OnBegin OnCCPSearch OnAppSearch OnFirstUIBefore OnGeneratedMSIScript OnMoving feature Installing events OnInstallFilesActionBefore OnInstallFilesActionAfter feature Installed events OnMoved OnGeneratedMSIScript OnFirstUIAfter OnEnd

Resumed Installations OnResumeUIAfter OnResumeUIBefore

Maintenance Installations OnBegin OnMaintUIBefore OnGeneratingMSIScript OnMoving feature Installing or Uninstalling events OnInstallFilesActionBefore OnInstallFilesActionAfter feature Installed or Uninstalled events

326

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Event Handler Index

OnMoved OnGeneratedMSIScript OnMaintUIAfter OnEnd

Patch Installations OnPatchUIBefore OnGeneratingMSIScript OnMoving feature Installing or Uninstalling events OnInstallFilesActionBefore OnInstallFilesActionAfter feature Installed or Uninstalled events OnMoved OnGeneratedMSIScript OnPatchUIAfter

Event Handler Index

Event handlers are InstallScript functions that are called in response to events that occur during setup. The names of these handlers are reserved. (It is not necessary to prototype these functions in your script.)

Project: Some of the following event handlers only apply to InstallScript or InstallScript MSI projects. Some apply to both types. Refer to the Project Type column to determine which projects are supported. Table 9-1: Event Handlers Index Event Handler OnAbort OnAdminInstallUIAfter OnAdminInstallUIBefore OnAdminPatchUIAfter OnAdminPatchUIBefore OnAdvertisementAfter Project Type InstallScript, InstallScript MSI InstallScript MSI InstallScript MSI InstallScript MSI InstallScript MSI InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

327

Chapter 9: Event Handlers Event Handler Index

Table 9-1: Event Handlers Index (cont.) Event Handler OnAdvertisementBefore OnAppSearch OnBegin OnCanceling OnCCPSearch OnCheckMediaPassword OnComponentError OnCustomizeUninstInfo OnDIFxLogCallback OnEnd OnError OnException OnFileError OnFileLocked OnFileReadOnly OnFilesInUse OnFilterComponents OnFirstUIAfter OnFirstUIBefore OnGeneratedMSIScript OnGeneratingMSIScript OnHelp OnIISComponentInstalled OnIISInitialize OnIISUninitialize OnIISVRootUninstalling OnInstalled Project Type InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript InstallScript InstallScript, InstallScript MSI InstallScript MSI InstallScript MSI InstallScript InstallScript InstallScript InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI

328

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Event Handler Index

Table 9-1: Event Handlers Index (cont.) Event Handler OnInstalledFile OnInstalledFontFile OnInstallFilesActionAfter OnInstallFilesActionBefore OnInstalling OnInstallingFile OnInternetError OnLaunchAppAndWaitCallback OnLogonUserSetMsiProperties OnMaintUIAfter OnMaintUIBefore OnMD5Error OnMoved OnMoveData OnMoving OnMsiSilentInstall OnNetApiCreateUserAccount OnNextDisk OnOutOfDiskSpace OnPatchUIAfter OnPatchUIBefore OnRebooted Project Type InstallScript InstallScript InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript InstallScript InstallScript, InstallScript MSI InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript InstallScript, InstallScript MSI InstallScript InstallScript, InstallScript MSI InstallScript MSI InstallScript, InstallScript MSI InstallScript InstallScript MSI InstallScript MSI InstallScript MSI InstallScript InstallScript MSIif the InstallScript user interface (UI) style is the traditional style (which uses the InstallScript engine as an external UI handler) OnRemovingSharedFile OnResumeUIAfter OnResumeUIBefore InstallScript InstallScript MSI InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

329

Chapter 9: Event Handlers Event Handler Index

Table 9-1: Event Handlers Index (cont.) Event Handler OnRMFilesInUse OnSelfRegistrationError OnSetTARGETDIR OnSetUpdateMode OnShowUI OnSQLBatchScripts OnSQLComponentInstalled OnSQLComponentInstalled OnSQLComponentUninstalled OnSQLComponentUninstalled OnSQLLogin OnSQLServerInitialize OnSQLServerInitializeMaint OnUninstall OnUnInstalled OnUninstalledFile OnUnInstalling OnUninstallingDIFxDriverFile OnUninstallingFile OnUninstallingFontFile OnUpdateUIAfter OnUpdateUIBefore OnWarning OnXMLComponentInstalled OnXMLComponentUninstalling OnXMLInitialize OnXMLUninitialize Project Type InstallScript MSI InstallScript InstallScript InstallScript InstallScript InstallScript InstallScript InstallScript InstallScript InstallScript InstallScript InstallScript InstallScript InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript InstallScript, InstallScript MSI InstallScript InstallScript InstallScript InstallScript InstallScript InstallScript MSI InstallScript InstallScript InstallScript InstallScript

330

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Component Event Handlers

Component Event Handlers

Windows Installer installations use featuresnot componentsas the highest level of organization in your project. Therefore, component event handlers have been replaced with feature event handlers. In addition, all supported component functions now have feature equivalents that should be used. For more information, see Feature Functions and Feature Event Handlers.

Global Event Handlers

Global event handlers carry out processes required before and after feature installation and uninstallation. They include event handlers in the following categories:
Table 9-2: Global Event Handlers Categories Category Initialization Handlers Before Move Data Handlers Description Event handlers that are called directly by the installation engine. Event handlers that are triggered before features are installed or uninstalled on the target computer. Event handlers that are triggered immediately before and immediately after features are installed or uninstalled on the target computer. Event handlers that are triggered after features are installed or uninstalled on the target computer.

Move Data Handlers

After Data Move Handlers

Initialization Handlers
The following event handlers are called directly by the installation engine in InstallScript projects:
Table 9-3: Initialization Handlers Event Handler OnCheckMediaPassword Project Type InstallScript Description Called directly by the framework during initiation to query the end user for the installation media's password if the password is not already in the installation log file (as it is if the installation is running as a maintenance installation or uninstallation) and you selected the "Show Password dialog box during setup initialization" check box in the Release Wizard's Password panel or set the Show Password Dialog property to Yes in the Releases view. Called directly by the framework to filter out components in each feature by language and platform. Override this event to perform custom filtering. This event handler is obsolete.

OnFilterComponents

InstallScript, InstallScript MSI

OnIISCheckRequirements

InstallScript

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

331

Chapter 9: Event Handlers Global Event Handlers

Table 9-3: Initialization Handlers Event Handler OnSetTARGETDIR Project Type InstallScript Description Called directly by the framework during initialization to initialize TARGETDIR to its default value. Called directly by the framework during initialization to set the UPDATEMODE system variable appropriately to control which UI events are called by OnShowUI.

OnSetUpdateMode

InstallScript

OnCheckMediaPassword

Project: This information applies to InstallScript projects.

The OnCheckMediaPassword event handler function is called directly by the setup engine. The handler's default code queries the end user for the setup's password if the password is not already in the setup log file (as it is if the setup is running as a maintenance setup or uninstallation) and you checked the "Show Password dialog box during setup initialization" check box in the Release Wizard's Password panel or set Show Password Dialog to Yes in the Release property sheet. This event handler is called (when appropriate) in any setup, including a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnCheckMediaPassword ( );

Parameters
None.

Return Values
None.

OnFilterComponents

Project: This information applies to the following project types:

InstallScript InstallScript MSI

The OnFilterComponents event handler is called directly by the InstallScript engine to handle feature filteringthat is, the including and excluding of features components in the file transfer based on their Language and Operating System settings.

Syntax
OnFilterComponents ( );

332

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

Parameters
None.

Return Values
None.

Additional Information
By default, OnFilterComponents calls FeatureFilterLanguage to exclude all components with languages other than the one specified by the SELECTED_LANGUAGE system variable, and calls FeatureFilterOS to exclude all components with operating systems other than the one specified by the SYSINFO variables nISOSL member. This event handler is not called in an installation that uses a procedural script (a script with a programendprogram block).

OnSetTARGETDIR

Project: This information applies to InstallScript projects.

The OnSetTARGETDIR event handler function is called directly by the setup engine to set the value of the system variable TARGETDIR. This event handler is called in any setup, including a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnSetTARGETDIR ( );

Parameters
None.

Return Values
None.

Additional Information
By default, in a first installation OnSetTARGETDIR sets TARGETDIR to the value that you specified in the TARGETDIR setting in the General Information view, orif you did not specify a value in InstallShieldto <FOLDER_APPLICATIONS>\<IFX_COMPANY_NAME>\<IFX_PRODUCT_NAME>. <FOLDER_APPLICATIONS>, <IFX_COMPANY_NAME>, and <IFX_PRODUCT_NAME> are texts substitutions whose values are resolved when TARGETDIR is referenced; that is, if you change the value of the system variable IFX_COMPANY_NAME or IFX_PRODUCT_NAME after OnSetTARGETDIR has been called, that change is reflected in subsequent references to TARGETDIR. A maintenance installation or uninstallation initializes TARGETDIR to the value that is stored in the log file, and by default OnSetTARGETDIR does not modify the value of TARGETDIR.
ISP-1800-RG00 333

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

OnSetUpdateMode

Project: This information applies to InstallScript projects.

The OnSetUpdateMode event handler function is called directly by the setup engine to determine whether the setup is an update to an existing installation and set the value of the system variable UPDATEMODE accordingly. This event handler is called (when appropriate) in any setup, including a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnSetUpdateMode ( );

Parameters
None.

Return Values
None.

Before Move Data Handlers

The following event handlers are triggered before files are transferred to the target computer. Most of these events are also triggered during a maintenance setup.
Table 9-4: Before Move Data Handlers Event Handler OnBegin Project Type InstallScript InstallScript MSI Description In InstallScript projects: Called directly by the framework after Initialization events. In InstallScript MSI projects: Responds to the Begin event, the first redefinable event in a setup. OnAppSearch InstallScript InstallScript MSI In InstallScript projects: Called directly by the framework after OnBegin. In InstallScript MSI projects: Responds to the Application Search event. Code this handler in installations that must search for a specific application on the target computer. OnCCPSearch InstallScript InstallScript MSI In InstallScript projects: Called directly by the framework afterAppSearch. In InstallScript MSI projects: Responds to the Upgrade Compliance event. Code this handler in installations that must search for an application whose presence qualifies the end user to install your application.

334

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

Table 9-4: Before Move Data Handlers Event Handler OnFilterComponents Project Type InstallScript Description Called directly by the framework to filter out components in each feature by language and platform. Override this event to perform custom filtering. In InstallScript projects: Called by the framework when the setup is running in first install mode. By default, this event displays UI allowing the end user to specify installation parameters. In InstallScript MSI projects: Responds to the First UI Before event by displaying dialogs that gather information from the end user for the first installation of an application. OnMaintUIBefore InstallScript InstallScript MSI In InstallScript projects: Called by OnShowUI when the installation is running in maintenance mode. OnShowUI can be customized to control whether this event is called. In InstallScript MSI projects: Responds to the MaintenanceUIBefore event by displaying dialogs that gather information from the end user for a maintenance installation of an application. OnUpdateUIBefore InstallScript Called by OnShowUI when the setup is running in update mode. By default this event displays UI that allows the end user to update the application to the current version. In InstallScript MSI projects: Responds to the First UI Before event. This event handler function creates a dialog which is used by the script to specify SQL login credentials. These credentials include the login ID and password. Called by OnFirstUIBefore to establish any connections necessary for SQL Server support. This function will initialize the SQL Server runtime and attempt to make any necessary SQL Server connections displaying a login dialog for each one. Called by OnMaintUIBefore to establish any connections necessary for SQL Server support. The OnIISInitialize event is called by OnFirstUIBefore to initialize the IIS run time. You should note that this event will not be called automatically in a program...endprogram style setup. The OnXMLInitialize event is called by OnFirstUIBefore to initialize the XML runtime.

OnFirstUIBefore

InstallScript InstallScript MSI

OnSQLLogin

InstallScript MSI

OnSQLServerInitialize

InstallScript

OnSQLServerInitializeMaint

InstallScript

OnIISInitialize

InstallScript

OnXMLInitialize

InstallScript

Note: This event will not be called automatically in a program...endprogram style setup.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

335

Chapter 9: Event Handlers Global Event Handlers

OnAppSearch
The OnAppSearch event handler responds to the Application Search event. Code this handler in setups that must search for a specific application on the target computer. Your code might, for example, call FindFile to locate a key file, or RegDBKeyExist to search for a registry entry. The following OnAppSearch function aborts the installation if a file called Notepad.exe is not available in the user's Windows or WinNT folder, or in a subdirectory of it.
function OnAppSearch( ) NUMBER nResult; STRING svIgnore; begin nResult = FindAllFiles(WindowsFolder, "Notepad.exe", svIgnore, RESET); if (nResult < 0) then MessageBox("Unable to find a qualifying program. " + "Setup will now exit.", SEVERE); abort; endif; end;

Note: This event handler is not executed during a maintenance setup or uninstallation.

OnBegin
The OnBegin event handler responds to the Begin event, the first redefinable event in a setup. Code that must be executed before anything else in the script should be included in this handler. For example, you can verify that the user's machine meets your product's system requirements here. OnBegin is prototyped for you when you include iswi.h or ifx.h in your script. Define OnBegin in your script as in the following example:
#include "iswi.h" function OnBegin( ) // local variables begin // beginning code end;

For example, an OnBegin function that verifies a particular registry key exists before continuing the installation might appear as follows:
// abort installation if HKLM\Software\InstallShield does not exist function OnBegin( ) NUMBER nReturn; begin // set the root key RegDBSetDefaultRoot(HKEY_LOCAL_MACHINE); // check for the existence of the subkey nReturn = RegDBKeyExist("Software\\InstallShield");

336

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

if (nReturn < 0) then MessageBox("Your system does not meet the system requirements. " + "Setup will now exit.", SEVERE); abort; endif; end;

Code in this event handler is always executed, even during a maintenance setup or uninstallation, unless you place it inside the following if-then structure:
if (!MAINTENANCE) then // non-maintenance code endif;

The setup sets the system variable MAINTENANCE equal to FALSE the first time the setup is run, and TRUE every time the setup is run thereafter.

OnCCPSearch
The OnCCPSearch event handler responds to the Upgrade Compliance event. Code this handler in setups that must search for an application whose presence qualifies the end user to install your application. Your code might, for example, call FindFile to locate a specific file. Note that this event handler is not executed during a maintenance setup or uninstallation.

OnFirstUIBefore
The OnFirstUIBefore event handler responds to the First UI Before event. It performs tasks that must take place before the installation of features for a first-time installation of an application. Typically, this handler calls InstallScript functions for the following tasks:

To set up the screen. To display dialogs that welcome the end user, display the software license, and show other information about the software to be installed. To get information from the end userincluding user registration, the destination path (TARGETDIR in InstallScript projects and INSTALLDIR in InstallScript MSI projects), and the setup type.

OnIISInitialize
The OnIISInitialize is called before OnMoving. You can override this for similar purposes as OnIISVRootUninstalling, as well as add code that checks the version of IIS or makes custom IIS modifications before installing the web sites and virtual roots.

OnMaintUIBefore
The OnMaintUIBefore event handler responds to the Maintenance UI Before event. It performs tasks that must take place before the reinstallation of features for a maintenance installation of an application.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

337

Chapter 9: Event Handlers Global Event Handlers

OnSQLComponentInstalled
The OnSQLComponentInstalled event is called after each component is installed so any SQL scripts attached to that component can be run. SQLComponentInstalled is called after each component is installed so any SQL scripts attached to that component can be run.

OnSQLComponentUninstalled
The SQLComponentUninstalled event is called after each component is uninstalled so any SQL scripts attached to that component can be run. The SQLComponentUninstalled event is called after each component is uninstalled so any SQL scripts attached to that component can be run. szComponent will have the name of the component that has been installed.

OnSQLLogin

Project: This information applies to InstallScript MSI projects.

The OnSQLLogin event responds to the First UI Before event. This event handler function creates a dialog which is used by the script to specify SQL login credentials. These credentials include the login ID and password.

Note: If you want to call a SQL built-in function before the OnSQLLogin event gets called, you need to first call the SQLRTInitialize2 function. This is applicable to all SQL-related functions. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

OnSQLServerInitialize

Project: This information applies to InstallScript projects.

The OnSQLServerInitialize event is called by OnFirstUIBefore to establish any connections necessary for SQL Server support. This function will initialize the SQL Server runtime and attempt to make any necessary SQL Server connections, displaying a login dialog for each one. Parameter nBtn indicates whether NEXT or BACK was the result of the previously displayed dialog. It is for information purposes only. If you are working on a script that had overridden OnFirstUIBefore when you upgraded to a newer version of InstallShield and your script is not calling OnSQLServerInitialize, then you should add the OnFirstUIBefore code to your script file.

Note: If you want to call a SQL built-in function before the OnSQLServerInitialize event gets called, you need to first call the SQLRTInitialize2 function. This is applicable to all SQL-related functions. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

338

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

OnSQLServerInitializeMaint

Project: This information applies to InstallScript projects.

The OnSQLServerInitializeMaint event is called by OnMaintUIBefore to establish any connections necessary for SQL Server support. This function will initialize the SQL Server runtime and attempt to make any necessary SQL Server connections using login credentials stored in the log file.

Note: This event will not be called automatically in a program.

OnUpdateUIBefore
The OnUpdateUIBefore event handler function is called by the OnShowUI event handler to display the pre-file-transfer user interface for an update setup. This event handler is not called in a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnUpdateUIBefore ( );

Parameters
None.

Return Values
None.

OnXMLInitialize
The OnXMLInitialize event is called by OnFirstUIBefore to initialize the XML run time. You should note that this event will not be called automatically in a program...endprogram style setup.

Move Data Handlers

The following event handlers are triggered immediately before, during, or immediately after the installation or uninstallation of all features on the target computer:
Table 9-5: Move Data Handlers Event Handler OnMoveData Project Type InstallScript Description Called by OnShowUI to transfer files. The event handler's default code calls FeatureTransferData to transfer the files.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

339

Chapter 9: Event Handlers Global Event Handlers

Table 9-5: Move Data Handlers (cont.) Event Handler OnMoved Project Type InstallScript InstallScript MSI Description In InstallScript projects: Called directly by the framework after FeatureTransferData is called in the script and after data transfer. In InstallScript MSI projects: Responds to the Moved event that is generated just after all features are installed or uninstalled on the target computer. OnCustomizeUninstInfo InstallScript Called by OnMoveData to customize the uninstall information after calling MaintenanceStart. In InstallScript projects: Called as a result of the installation calling FeatureTransferData or Feature MoveData. The event is called before any file transfer operations occur. In InstallScript MSI projects: Called just before the action GenerateMSIScript is executed. OnInstallingFile InstallScript Called when a file is about to be installed as a result of FeatureTransferData or FeatureMoveData. Called when a driver installed or preinstalled by the DIFxDriverPackageInstall or DIFxDriverPackagePreinstall functions is uninstalled with uninstall logging enabled. Called when a file is about to be uninstalled as a result of FeatureTransferData or FeatureMoveData. Called when a font file logged by RegisterFontResource is uninstalled. Called after a file is installed as a result of FeatureTransferData or FeatureMoveData. Called after a file is installed that is listed in the media as a font file. Called after a file is uninstalled as a result of FeatureTransferData or FeatureMoveData. Called after each component is installed so any SQL scripts attached to that component can be run. SQLComponentInstalled is called after each component is installed so any SQL scripts attached to that component can be run. Called after each component is uninstalled so any SQL scripts attached to that component can be run. The SQLComponentUninstalled event is called after each component is uninstalled so any SQL scripts attached to that component can be run. Called automatically by the framework after file transfer.

OnMoving

InstallScript InstallScript MSI

OnUninstallingDIFxDriverFile

InstallScript

OnUninstallingFile

InstallScript

OnUninstallingFontFile

InstallScript

OnInstalledFile

InstallScript

OnInstalledFontFile

InstallScript

OnUninstalledFile

InstallScript

OnSQLComponentInstalled

InstallScript

OnSQLComponentUninstalled

InstallScript

OnSQLBatchScripts

InstallScript

340

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

Table 9-5: Move Data Handlers (cont.) Event Handler OnIISComponentInstalled Project Type InstallScript Description IISComponentInstalled is called after each component is installed so that any IIS information attached to that component can be installed. Called before each IISVRoot is removed. ISXMLComponentInstall is called after each component is installed so that any XML information attached to that component can be installed. XMLComponentUninstalling is called before each .xml file is removed. Called before OnMoving event. This event handler function does nothing unless NetApiRT.obl is added before Isrt.obl in the list of linked libraries. Responds to the MSI standard action LaunchConditions after it is executed. Responds to the MSI standard action LaunchConditions before it is executed. Responds to the InstallFiles event handler function before it is called. Responds to the InstallFiles event handler function after it is called.

OnIISVRootUninstalling OnXMLComponentInstalled

InstallScript InstallScript

OnXMLComponentUninstalling

InstallScript

OnNetApiCreateUserAccount

InstallScript

OnGeneratedMSIScript

InstallScript MSI

OnGeneratingMSIScript

InstallScript MSI

OnInstallFilesActionBefore

InstallScript MSI

OnInstallFilesActionAfter

InstallScript MSI

OnCustomizeUninstInfo
The OnCustomizeUninstInfo event handler function is called by OnMoveData to customize the uninstall information after calling MaintenanceStart.

Syntax
OnCustomizeUninstInfo ( );

Parameters
None.

Return Values
None.

OnGeneratedMSIScript
The OnGeneratedMSIScript event handler marks the end of immediate execution, meaning that Windows Installer has finished generating its internal installation script.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

341

Chapter 9: Event Handlers Global Event Handlers

OnGeneratingMSIScript
The OnGeneratingMSIScript event handler responds to the MSI standard action LaunchConditions before it is executed.

OnIISComponentInstalled
The OnIISComponentInstalled event handler function is called after each component is installed so any IIS information attached to that component can be installed.

Syntax
OnIISComponentInstalled ( szComponent );

Parameters
Table 9-6: OnIISComponentInstalled Parameters Parameter szComponent Description This parameter will have the name of the component that has been installed.

Return Values
This event handler function should return ISERR_SUCCESS currently in all cases.

OnIISVRootUninstalling
The OnIISVRootUninstalling event is called before each Virtual Directory is removed. You can check conditions related to IIS in your script, and then call abort() to stop the setup.

OnInstalledFile
The OnInstalledFile event handler function is called after a file is installed as a result of FeatureTransferData or FeatureMoveData.

Syntax
OnInstalledFile ( szFilename );

342

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

Parameters
Table 9-7: OnInstalledFile Parameters Parameter szFilename Description Specifies the fully qualified file name of the file that was transferred.

Return Values
None.

OnInstalledFontFile
The OnInstalledFontFile event handler function is called after a file is installed that is listed in the media as a font file.

Syntax
OnInstalledFontFile ( pFontFileInfo );

Parameters
Table 9-8: OnInstalledFontFile Parameters Parameter pFontFileInfo Description Pointer to a _FONTFILEINFO structure that gives information about the font file that is being installed.

Return Values
None.

OnInstallFilesActionBefore
The OnInstallFilesActionBefore event handler is called just before the standard Windows Installer action InstallFiles is performed.

OnInstallFilesActionAfter
The OnInstallFilesActionAfter event handler is called just after the standard Windows Installer action InstallFiles is performed.

OnInstallingFile
The OnInstallingFile event handler function is called when a file is about to be installed as a result of FeatureTransferData or FeatureMoveData.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

343

Chapter 9: Event Handlers Global Event Handlers

Code in this event handler is always executed, even during a maintenance setup, unless you place it inside the following if-then structure:
if !MAINTENANCE then \\ non-maintenance code endif;

Syntax
OnInstallingFile ( szFilename );

Parameters
Table 9-9: OnInstallingFile Parameters Parameter szFilename Description Specifies the fully qualified file name of the file that is about to be transferred.

Return Values
None.

OnMoved
In InstallScript projects, OnMoved is called as a result of the installation calling FeatureTransferData or Feature MoveData. The event is called when all file transfer operations are completed except for batch self-registration. In InstallScript MSI projects, OnMoved is called just before the action GenerateMSIScript is executed. Code in this event handler is always executed, even during a maintenance setup or uninstallation, unless you place it inside the following if-then structure:
if (!MAINTENANCE) then // non-maintenance code endif;

OnMoveData
The OnMoveData event handler function is called by the OnShowUI event handler to handle the file transfer. By default, OnMoveData calls FeatureTransferData to transfer the files. This event handler is not called in a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnMoveData ( );

Parameters
None.

344

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

Return Values
None.

OnMoving
In InstallScript projects, OnMoving is called as a result of the installation calling FeatureTransferData or Feature MoveData. The event is called before any file transfer operations occur. In InstallScript MSI projects, OnMoving is called just before the action GenerateMSIScript is executed. Code in this event handler is always executed, even during a maintenance setup, unless you place it inside the following if-then structure:
if !MAINTENANCE then \\ non-maintenance code endif;

OnNetApiCreateUserAccount
The OnNetApiCreateUserAccount event handler function is called before the OnMoving event. This event handler function does nothing unless you add NetApiRT.obl before Isrt.obl in the list of linked libraries.

Syntax
OnNetApiCreateUserAccount()

Parameters
None

Return Values
This event handler function should always return ISERR_SUCCESS.

Additional Information

Task

To add NetApiRT.obl to the list of linked libraries: 1. 2.

On the Build menu, click Settings. The Settings dialog box opens. In the Libraries (.obl) box, enter NetApiRT.obl. Note that it must be listed before Isrt.obl.

The path to NetApiRT.obl is as follows:

<ISProductFolder>\Script\ISRT\Lib\NetApiRT.obl

OnSQLBatchScripts
The OnSQLBatchScripts event is called automatically by the framework after file transfer.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

345

Chapter 9: Event Handlers Global Event Handlers

OnSQLComponentInstalled
The OnSQLComponentInstalled event is called after each component is installed so any SQL scripts attached to that component can be run. SQLComponentInstalled is called after each component is installed so any SQL scripts attached to that component can be run.

OnSQLComponentUninstalled
The SQLComponentUninstalled event is called after each component is uninstalled so any SQL scripts attached to that component can be run. The SQLComponentUninstalled event is called after each component is uninstalled so any SQL scripts attached to that component can be run. szComponent will have the name of the component that has been installed.

OnUninstalledFile
The OnUninstalledFile event handler function is called after a file is uninstalled as a result of FeatureTransferData or FeatureMoveData.

Syntax
OnUninstalledFile ( szFilename );

Parameters
Table 9-10: OnUninstalledFile Parameters Parameter szFilename Description Specifies the fully qualified file name of the file that was uninstalled.

Return Values
None.

OnUninstallingFile
The OnUninstallingFile event handler function is called when a file is about to be uninstalled as a result of FeatureTransferData or FeatureMoveData. Code in this event handler is always executed, even during a maintenance setup, unless you place it inside the following if-then structure:
if !MAINTENANCE then \\ non-maintenance code endif;

Syntax
OnUninstallingFile ( szFilename );

346

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

Parameters
Table 9-11: OnUninstallingFile Parameter szFilename Description Specifies the fully qualified file name of the file that is about to be uninstalled.

Return Values
None.

OnUninstallingDIFxDriverFile
The OnUninstallingDIFxDriverFile event handler function is called when a driver installed or preinstalled by the DIFxDriverPackageInstall or DIFxDriverPackagePreinstall functions is uninstalled with uninstall logging enabled. By default, the event uninstalls the driver using the DIFxDriverPackageUninstall function.

Syntax
OnUninstallingDIFxDriverFile ( byval string szDriver );

Parameters
Table 9-12: OnUninstallingDIFxDriverFile Parameter szDriver Description The complete path and file of the installed driver file.

Return Values
None.

OnUninstallingFontFile
The OnUninstallingFontFile event handler function is called when a font file logged by RegisterFontResource is uninstalled.

Syntax
OnUninstallingFontFile ( pFontFileInfo );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

347

Chapter 9: Event Handlers Global Event Handlers

Parameters
Table 9-13: OnUninstallingFontFile Parameter pFontFileInfo Description Pointer to a _FONTFILEINFO structure that gives information about the font file that is being uninstalled.

Return Values
None.

OnXMLComponentInstalled
OnXMLComponentInstalled is the event handler function associated with the ISXMLComponentInstall event. The ISXMLComponentInstall event is called after each component is installed so that any XML information attached to that component can be installed.

Syntax
OnXMLComponentInstalled ( szComponent );

Parameters
Table 9-14: OnXMLComponentInstalled Parameter szComponent Description This parameter will have the name of the component that has been installed.

Return Values
This event handler function should return ISERR_SUCCESS currently in all cases.

OnXMLComponentUninstalling
OnXMLComponentUninstalling is the event handler function associated with the XMLRTComponentUninstall event. The XMLRTComponentUninstall event is called before each .xml file is removed.

Syntax
OnXMLComponentUninstalling ( szXmlComponent )

348

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Global Event Handlers

Parameters
Table 9-15: OnXMLComponentUninstalling Parameter szXmlComponent Description This parameter will have the name of the component that has been installed.

Return Values
This event handler function should return ISERR_SUCCESS currently in all cases.

After Data Move Handlers

The following event handlers are triggered after files and other data are transferred to the target computer:
Table 9-16: After Data Move Handlers Event Handler OnIISUninitialize Project Type InstallScript Description The OnIISUninitialize event is called by OnMoveDataAfter to initialize the IIS runtime. This event will not be called automatically in a program...endprogram style setup. The OnXMLUninitialize event is called by OnMoveDataAfter to initialize the XML runtime. This event will not be called automatically in a program...endprogram style setup. In InstallScript projects: The OnFirstUIAfter event called by OnShowUI after the file transfer of the setup when the setup is running in first install mode. By default this event displays UI that informs the end user that the setup has been completed successfully. You should note that this event will not be called automatically in a program...endprogram style setup. In InstallScript MSI projects: Responds to the First UI After event. OnMaintUIAfter InstallScript InstallScript MSI In InstallScript projects: The OnMaintUIAfter event called by OnShowUI after the file transfer of the setup when the setup is running in maintenance mode. By default this event displays UI that informs the end user that the maintenance setup has been completed successfully. You should note that this event will not be called automatically in a program...endprogram style setup. In InstallScript MSI projects: Responds to the Maintenance UI After event.

OnXMLUninitialize

InstallScript

OnFirstUIAfter

InstallScript InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

349

Chapter 9: Event Handlers Global Event Handlers

Table 9-16: After Data Move Handlers (cont.) Event Handler OnUpdateUIAfter Project Type InstallScript Description The OnUpdateUIAfter event called by OnShowUI after the file transfer of the setup when the setup is running in update mode. By default this event displays UI that informs the end user that the maintenance setup has been completed successfully. This event is not automatically called in a program. In InstallScript projects: The OnEnd event is called at the end of the setup. This event is not called if the setup is aborted. In InstallScript MSI projects: Responds to the End event, the last redefinable event in a setup.

OnEnd

InstallScript InstallScript MSI

OnIISUninitialize
The OnIISUninitialize event is called by OnMoveDataAfter to initialize the IIS runtime. This event will not be called automatically in an endprogram style installation.

OnXMLUninitialize
The OnXMLUninitialize event is called by OnMoveDataAfter to initialize the XML runtime. This event will not be called automatically in an endprogram style installation.

OnFirstUIAfter
The OnFirstUIAfter event handler responds to the First UI After event. It performs tasks that must take place after the installation of features for a first installation of an application.

OnMaintUIAfter
The OnMaintUIAfter event handler responds to the Maintenance UI After event. It performs tasks that must take place after the reinstallation of features for a maintenance installation of an application.

OnUpdateUIAfter
The OnUpdateUIAfter event handler function is called by the OnShowUI event handler to display the post-file-transfer user interface for an update setup. This event handler is not called in a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnUpdateUIAfter ( );

350

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Feature Event Handlers

Parameters
None.

Return Values
None.

OnEnd
The OnEnd event handler responds to the End event, the last redefinable event in a setup. You can place any required cleanup code in the OnEnd function. OnEnd is prototyped for you when you include ifx.h or iswi.h in your script. Define OnEnd in your script as in the following example:
#include "iswi.h" function OnEnd( ) // local variables begin // cleanup code end;

Code in this event handler is always executed, even during a maintenance setup, unless you place it inside the following if-then structure:
if !MAINTENANCE then \\ non-maintenance code endif;

Feature Event Handlers

Feature event handlers carry out processes required just before and just after the installation or uninstallation of a single feature. The number of feature events and handlers depends on the number of features in your project. To create an event handler function for a feature, select the feature name from the left event-category list, and select the event you want from the right event list. InstallShield creates a second InstallScript file, called FeatureEvents.rul, in the InstallScript view. Note that if you change the default feature event handler code in FeatureEvents.rul, you must put the following statement in Setup.rul to include your changes in the installation:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

351

Chapter 9: Event Handlers Feature Event Handlers

#include "FeatureEvents.rul"

Following is a list of the feature event handlers.

Table 9-17: Feature Event Handlers Event Handler OnInstalled Project Type InstallScript InstallScript MSI Description In InstallScript projects: Runs in response to the Installed event that is generated just after the applicable feature is installed on the target system. In InstallScript MSI projects: Runs just after Windows Installer transfers the files to the target system. OnInstalling InstallScript InstallScript MSI In InstallScript projects: Runs in response to the Installing event that is generated just before the feature is installed on the target system. In InstallScript MSI projects: Runs just before Windows Installer transfers the files to the target system. OnUnInstalled InstallScript InstallScript MSI In InstallScript projects: Runs in response to the UnInstalled event that is generated just after the feature is removed from the target system. In InstallScript MSI projects: Runs just after Windows Installer removes the files from the target system. OnUnInstalling InstallScript InstallScript MSI In InstallScript projects: Runs in response to the UnInstalling event that is generated just before the feature is removed from the target system. In InstallScript MSI projects: Runs just before Windows Installer removes the files from the target system.

Project: Because Windows Installer controls the installation of features in InstallScript MSI installations, the order in which feature event-handler functions are called cannot be specified. In addition, feature events are not launched until all features are copied to the target system. Also note that feature-uninstallation event handlers (OnUnInstalling and OnUnInstalled) are not called during rollback.

OnInstalled
Project: This information applies to the following project types:

InstallScript InstallScript MSI

In InstallScript projects, the OnInstalled feature event handler runs in response to the Installed event that is generated just after the applicable feature is installed on the target system.

352

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Feature Event Handlers

In InstallScript MSI projects, the OnInstalled feature event handler runs just after Windows Installer transfers the files to the target system. The OnInstalled feature event handler is listed in the InstallScript code in the following format:
MyFeatureName_Installed()

Project: Because Windows Installer controls the installation of features in InstallScript MSI installations, the order in which feature event-handler functions are called cannot be specified. In addition, feature events are not launched until all features are copied to the target system. Also note that feature-uninstallation event handlers (OnUnInstalling and OnUnInstalled) are not called during rollback.

OnInstalling
Project: This information applies to the following project types:

InstallScript InstallScript MSI

In InstallScript projects, the OnInstalling feature event handler runs in response to the Installing event that is generated just before the feature is installed on the target system. In InstallScript MSI projects, the OnInstalling feature event handler runs just before Windows Installer transfers the files to the target system. The OnInstalling feature event handler is listed in the InstallScript code in the following format:
MyFeatureName_Installing()

Project: Because Windows Installer controls the installation of features in InstallScript MSI installations, the order in which feature event-handler functions are called cannot be specified. In addition, feature events are not launched until all features are copied to the target system. Also note that feature-uninstallation event handlers (OnUnInstalling and OnUnInstalled) are not called during rollback.

OnUnInstalled
Project: This information applies to the following project types:

InstallScript InstallScript MSI

In InstallScript projects, the OnUnInstalled feature event handler runs in response to the UnInstalling event that is generated just before the feature is removed from the target system. In InstallScript MSI projects, the OnUnInstalled feature event handler runs just before Windows Installer removes the files from the target system.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

353

Chapter 9: Event Handlers Miscellaneous Event Handlers

The OnUnInstalled feature event handler is listed in the InstallScript code in the following format:
MyFeatureName_UnInstalled()

Project: Because Windows Installer controls the installation of features in InstallScript MSI installations, the order in which feature event-handler functions are called cannot be specified. In addition, feature events are not launched until all features are copied to the target system. Also note that feature-uninstallation event handlers (OnUnInstalling and OnUnInstalled) are not called during rollback.

OnUnInstalling
Project: This information applies to the following project types:

InstallScript InstallScript MSI

In InstallScript projects, the OnUnInstalling feature event handler runs in response to the UnInstalling event that is generated just before the feature is removed from the target system. In InstallScript MSI projects, the OnUnInstalling feature event handler runs just before Windows Installer removes the files from the target system. The OnUnInstalling feature event handler is listed in the InstallScript code in the following format:
MyFeatureName_UnInstalling()

Project: Because Windows Installer controls the installation of features in InstallScript MSI installations, the order in which feature event-handler functions are called cannot be specified. In addition, feature events are not launched until all features are copied to the target system. Also note that feature-uninstallation event handlers (OnUnInstalling and OnUnInstalled) are not called during rollback.

Miscellaneous Event Handlers

Miscellaneous event handlers are triggered by unscheduled events during an installation, such as the end user exiting the installation.
Table 9-18: Miscellaneous Event Handlers Event Handler OnAbort Project Type InstallScript, InstallScript MSI Description In InstallScript projects: The OnAbort event handler is called when a setup is aborted via the abort keyword. In InstallScript MSI projects: Responds to the Abort event generated by InstallScript's abort command. OnAdminInstallUIAfter InstallScript MSI Responds to the Admin Install UI After event.

354

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

Table 9-18: Miscellaneous Event Handlers (cont.) Event Handler OnAdminInstallUIBefore Project Type InstallScript MSI Description Responds to the Admin Install UI Before event by displaying dialogs that gather information from the end user for an administrative installation of an application. Called after the file transfer of an administrative patch. Called before the file transfer of an administrative patch. Responds to the Advertisement After event. Responds to the Advertisement After Before event. InstallScript projects: The OnCanceling event is sent when the installation is cancelled, usually as result of the end user clicking the Cancel button of a dialog or pressing the Esc key. Calling Do(EXIT) will also trigger this event. In InstallScript MSI projects: Responds to the Cancel event generated when the end user clicks the Cancel button in a builtin dialog. OnComponentError InstallScript, InstallScript MSI In InstallScript projects: The OnComponentError event is called by the framework when the call to FeatureTransferData or FeatureMoveData returns an error. In InstallScript MSI projects: Responds to general file-transfer errors. OnDIFxLogCallback InstallScript Called when a DIFx-related event occurs that is logged by the built-in DIFx callback functionality. This event is called when MSI sends an INSTALLMESSAGE_ERROR message. Responds to exceptions generated by a procedural script. The OnFileError event is sent when an unknown error occurs during the installation or uninstallation of a file. The OnFileLocked event is called when a file that is in use by another application needs to be installed or uninstalled unless the files are in a file group which is potentially marked as locked or shared. In that case, the file will be installed or uninstalled after reboot. The OnFileReadOnly event is called when a read-only file needs to be installed or uninstalled. The OnFilesInUse event handler is called in when the Windows Installer sends an INSTALLMESSAGE_FILESINUSE message to the installation. By default, the OnFilesInUse event handler displays the SdFilesInUse dialog.

OnAdminPatchUIAfter OnAdminPatchUIBefore OnAdvertisementAfter OnAdvertisementBefore OnCanceling

InstallScript MSI InstallScript MSI InstallScript MSI InstallScript MSI InstallScript, InstallScript MSI

OnError

InstallScript MSI

OnException OnFileError

InstallScript MSI InstallScript

OnFileLocked

InstallScript

OnFileReadOnly

InstallScript

OnFilesInUse

InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

355

Chapter 9: Event Handlers Miscellaneous Event Handlers

Table 9-18: Miscellaneous Event Handlers (cont.) Event Handler OnHelp Project Type InstallScript, InstallScript MSI Description In InstallScript projects: The OnHelp event is called when the end user presses F1 or Do(HELP) is called. In InstallScript MSI projects: Responds to the Help event generated when the end user presses the F1 key. OnInternetError InstallScript The OnInternetError is called when an error occurs while installing a file from the Internet. The OnLaunchAppAndWaitCallback is called while the installation is waiting for an application to launch if LAAW_OPTION_USE_CALLBACK was specified when calling the LaunchAppAndWait function. The OnLogonUserSetMsiProperties event handler sets the Windows Installer properties for the logon user support that is described for InstallScript MSI projects in Adding the Ability to Create or Set an Existing User Account. The OnMD5Error event is called when the MD5 signature of a file being installed does not match the MD5 value stored in the InstallShield CAB file. (The MD5 is calculated when the media is built.) Responds to the MSI Silent Install event generated when a user runs an InstallScript MSI project's .msi package in silent mode. The OnNextDisk event is called during file transfer when the setup cannot find a data file that is needed. An example of this occurrence is during a multiple floppy or CD install when the next disk is needed. Responds to the target system running out of free disk space. Responds to the Patch UI After event. Responds to the Patch UI Before event by displaying dialogs for a patch installation. In InstallScript projects: The OnRebooted event is called when the setup is run automatically after rebooting the system. This is the only event that will be called in this case. In InstallScript MSI projects: Responds to the Rebooted event that the installation generates when it restarts after the target system is rebooted.

OnLaunchAppAndWaitCall back

InstallScript, InstallScript MSI

OnLogonUserSetMsiPrope rties

InstallScript MSI

OnMD5Error

InstallScript

OnMsiSilentInstall

InstallScript MSI

OnNextDisk

InstallScript

OnOutOfDiskSpace OnPatchUIAfter OnPatchUIBefore

InstallScript MSI InstallScript MSI InstallScript MSI

OnRebooted

InstallScript, InstallScript MSI (if the InstallScript user interface (UI) style is the traditional style, which uses the InstallScript engine as an external UI handler)

Important: This event is not called in an InstallScript MSI installation in which the InstallScript UI style is the new style (which uses the InstallScript engine as an embedded UI handler). To learn more, see Using the InstallScript Engine as an External vs. Embedded UI Handler for InstallScript MSI Installations.
356 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

Table 9-18: Miscellaneous Event Handlers (cont.) Event Handler OnRemovingSharedFile Project Type InstallScript Description The OnRemovingSharedFile event is called during file transfer when a shared file is being uninstalled and the reference count for the file has reached zero. Responds to the Resume UI After event. Responds to the Resume UI Before event. The OnRMFilesInUse event handler is called when the Restart Manager is enabled and Windows Installer 4.0 sends an INSTALLMESSAGE_RMFILESINUSE message to the installation. By default, the OnRMFilesInUse event handler displays the SdRMFilesInUse dialog. OnSelfRegistrationError InstallScript The OnSelfRegistrationError event handler is called directly by the framework when a call to Do(SELFREGISTRATIONPROCESS) fails to register files successfully. Responds to the Warning event generated when the Windows Installer service sends an INSTALLMESSAGE_WARNING message to the installation's user interface.

OnResumeUIAfter OnResumeUIBefore OnRMFilesInUse

InstallScript MSI InstallScript MSI InstallScript MSI

OnWarning

InstallScript MSI

OnAbort
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The OnAbort event handler responds to the Abort event that is generated by the InstallScript abort statement, which uninstalls any changes made to the target system and then exits. In the event handler, you can place any additional cleanup code that you require, such as deleting temporary files created by your installation.

OnAdminInstallUIAfter
Project: This information applies to InstallScript MSI projects.

The OnAdminInstallUIAfter event handler responds to the Admin Install UI After event. It performs tasks that must take place after data transfer for an administrative installation of an application. To perform an administrative installation, the user launches Setup.exe with the /a switch. Typically, this handler calls SdFinishEx to inform the user that the administrative installation is complete.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

357

Chapter 9: Event Handlers Miscellaneous Event Handlers

OnAdminInstallUIBefore
Project: This information applies to InstallScript MSI projects.

The OnAdminInstallUIBefore event handler responds to the Admin Install UI Before event. It performs tasks that must take place before data transfer for an administrative installation of an application. To perform an administrative installation, the user launches Setup.exe with the /a switch. Typically, this handler calls the SdWelcome and AdminAskPath functions to welcome the administrative user and prompt for a destination directory.

OnAdminPatchUIAfter
Project: This information applies to InstallScript MSI projects.

The AdminPatchUIAfter event called after the file transfer of an admin patch setup. By default this event displays UI that informs the end user that the installation has been completed successfully.

OnAdminPatchUIBefore
Project: This information applies to InstallScript MSI projects.

The OnAdminInstallUIBefore event is called before the file transfer in an admin patch setup. By default this event displays UI allowing the end user to specify installation parameters.

OnAdvertisementAfter
Project: This information applies to InstallScript MSI projects.

The OnAdvertisementAfter event handler responds to the Advertisement After event. It performs tasks that must take place after an advertised installation, which occurs when the user runs Setup.exe with the /j argument.

OnAdvertisementBefore
Project: This information applies to InstallScript MSI projects.

The OnAdvertisementBefore event handler responds to the Advertisement Before event. It performs tasks that must take place before an advertised installation, which occurs when the user runs Setup.exe with the /j argument.
358 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

OnCanceling
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The OnCanceling event handler responds to the Cancel event that is generated when the end user clicks the Cancel button in one of the built-in InstallScript dialogs.
function OnCanceling( ) begin if (YES = AskYesNo( "Are you sure you want to cancel the setup?", YES)) then abort; endif; end;

OnComponentError
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The OnComponentError event handler responds to the ComponentError event that is generated when the installation encounters a general file-transfer error. The default OnComponentError implementation uses properties of an ErrorInfo object that is declared in OnComponentError and assigned a value by the following statement:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

359

Chapter 9: Event Handlers Miscellaneous Event Handlers

set ErrorInfo = ComponentErrorInfo( );

Table 9-19: OnComponentError Parameters Property ErrorInfo.Feature Description An object whose properties provide information about the feature that was being transferred when the error occurred. If the error is not associated with a particular feature, or the feature cannot be identified, this property is not set; test for this case by checking the value of IsObject(ErrorInfo.Feature). A string describing the file transfer error. This string may be null (""). The display name of the feature that was being transferred when the error occurred. If you did not specify a display name for this feature, this string is null (""). The name of the feature that was being transferred when the error occurred. A string-formatted description of ErrorInfo.LastError. For a file-related error: The path and name of the file that encountered an error while the installation attempted to transfer it. The name of the component that is being transferred when the error occurs. The numeric code for the file-transfer error.

ErrorInfo.Feature.Description ErrorInfo.Feature.DisplayName

ErrorInfo.Feature.Name

ErrorInfo.FileError.Description ErrorInfo.FileError.File

ErrorInfo.FileGroup

ErrorInfo.LastError

OnDIFxLogCallback
Project: This information applies to InstallScript projects.

The OnDIFxLogCallback event handler is called when a DIFx-related event occurs that is logged by the built-in DIFx callback functionality. See the Windows documentation on DIFXAPISetLogCallback for more information.

Note: This event is not supported for 64-bit drivers and is not called as a result of installing a 64-bit driver.

Syntax
OnDIFxLogCallback ( byval number nEventType, byval number nError, byval string szDescription );

360

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

Parameters
Table 9-20: OnDIFxLogCallback Parameters Parameter nEventType Description The event type as documented in the DIFxAPI. The following values are available:

nError

DIFXAPI_SUCCESSA success event that logs a message that indicates an operation succeeded. DIFXAPI_INFOAn information event that logs a message that describes the context or progress of an operation. DIFXAPI_WARNINGA warning event that logs a message about a possible problem that is not a fatal error. DIFXAPI_ERRORAn error event that logs a message about a fatal error.

Specifies a Win32 error code that is associated with an event if one exists; otherwise, zero. A string that describes the event.

szDescription

Return Values
None.

OnError
Project: This information applies to InstallScript MSI projects.

This event is called when Windows Installer sends an INSTALLMESSAGE_ERROR message.

OnException
Project: This information applies to InstallScript MSI projects.

The OnException event handler responds to exceptions that are generated by a procedural script (one that uses an explicit program...endprogram block). The default implementation displays the error number, source, and description that are stored in the Err Object. Note that OnException is not called in an event-based script. For an event-based script, you must implement your own try...catch...endcatch blocks to catch exceptions.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

361

Chapter 9: Event Handlers Miscellaneous Event Handlers

OnFileError
Project: This information applies to InstallScript projects.

The OnFileError event handler responds to the FileError event that is generated when the setup encounters a file error that does not generate any other file error event (for example, FileLocked or FileReadOnly). When creating an InstallShield object, note that this event is not triggered in an object. This event handler is called (when appropriate) in any setup, including a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnFileError ( szFilename, nError );

Parameters
Table 9-21: OnFileError Parameters Parameter szFilename nError Description Specifies the fully qualified file name of the file for which the error occurred. Specifies the value returned by the Windows API function GetLastError when the error occurred.

Return Values
Table 9-22: OnFileError Return Values Return Value ERR_IGNORE Description Returned to the setup by the OnFileError event handler to request that the setup ignore the failure to install or uninstall the file specified in OnFileErrors first argument and continue without performing the operation. Returned to the setup by the OnFileError event handler to request that the setup attempt again to install or uninstall the file specified in OnFileErrors first argument. Returned to the setup by the OnFileError event handler to request that the setup be aborted.

ERR_RETRY

ERR_ABORT

OnFileLocked
Project: This information applies to InstallScript projects.

362

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

The OnFileLocked event handler responds to the FileLocked event that is generated when the setup encounters a locked (in use) file that must be deleted or overwritten. When creating an InstallShield object, note that this event is not triggered in an object. This event handler is not called for files that are in components whose Potentially Locked property is set to Yes. In this case the file operation is automatically performed after reboot. This event handler is called (when appropriate) in any setup, including a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnFileLocked ( szFilename );

Parameters
Table 9-23: OnFileLocked Parameters Parameter szFilename Description Specifies the fully qualified file name of the locked file.

Return Values
Table 9-24: OnFileLocked Return Values Return Value ERR_IGNORE Description Returned to the setup by the OnFileLocked event handler to request that the setup ignore the failure to install or uninstall the file specified in OnFileLockeds argument and continue without performing the operation. Returned to the setup by the OnFileLocked event handler to request that the setup attempt again to install or uninstall the file specified in OnFileLockeds argument. Returned to the setup by the OnFileLocked event handler to request that the setup be aborted. Returned to the setup by the OnFileLocked event handler to request that the setup perform the operation on the file after the target system is rebooted.

ERR_RETRY

ERR_ABORT

ERR_PERFORM_AFTER_REB OOT

OnFileReadOnly
Project: This information applies to InstallScript projects.

The OnFileReadOnly event handler responds to the ReadOnly event that is generated when a file that must be deleted or overwritten is set to Read Only. When creating an InstallShield object, note that this event is not triggered in an object. This event handler is called (when appropriate) in any setup, including a setup that uses a procedural script (a script with a programendprogram block).

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

363

Chapter 9: Event Handlers Miscellaneous Event Handlers

Syntax
OnFileReadOnly ( szFilename );

Parameters
Table 9-25: OnFileReadOnly Parameters Parameter szFilename Description Specifies the fully qualified file name of the read-only file.

Return Values
Table 9-26: OnFileReadyOnly Return Values Return Value ERR_YES Description Returned to the setup by the OnRemovingSharedFile event handler to request that the setup perform the operation on the file. Returned to the setup by the OnRemovingSharedFile event handler to request that the setup not perform the operation on the file.

ERR_NO

OnFilesInUse
Project: This information applies to InstallScript MSI projects.

The OnFilesInUse event handler is called in an InstallScript MSI installation when the Windows Installer sends an INSTALLMESSAGE_FILESINUSE message to the installation. The szMessage parameter contains the string that the Windows Installer provides. This parameter indicates the files that are in use. The SdFilesInUse function parses this string appropriately. By default, the OnFilesInUse event handler displays the SdFilesInUse dialog. The event handler returns the value that the dialog returns, and the value is then passed back to the Windows Installer to indicate how the message was handled and what action the Windows Installer should take.

Syntax
OnFilesInUse (szMessage);

364

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

Parameters
Table 9-27: OnFilesInUse Parameters Parameter szMessage Description String provided by the Windows Installer indicating the files that are in use. The SdFilesInUse function parses this string.

Return Values
Table 9-28: OnFilesInUse Return Values Return Value IDCANCEL IDRETRY Description Indicates that the installation should be cancelled. Indicates that the Windows Installer should recheck for in-use files and send the INSTALLMESSAGE_FILESINUSE message if it still needed. Indicates that the Windows Installer should ignore the fact that the files are in use and should continue the installation.

IDIGNORE

OnHelp
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The OnHelp event handler responds to the Help event generated when the end user presses the F1 key.
function OnHelp( ) begin /* Assumes that MySetupHelp.chm is located in the Support Files/Billboards view. */ LaunchAppAndWait( WINDIR ^ "Hh.exe", SUPPORTDIR ^ "MySetupHelp.chm", NOWAIT ); end;

OnInternetError
Project: This information applies to InstallScript projects.

The OnInternetError event handler responds to the FileError event that is generated when the setup encounters a file error that does not generate any other file error event (for example, FileLocked or FileReadOnly). When creating an InstallShield object, note that this event is not triggered in an object.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

365

Chapter 9: Event Handlers Miscellaneous Event Handlers

This event handler is called (when appropriate) in any setup, including a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnInternetError ( hInternet, szFilename, nError );

Parameters
Table 9-29: OnInternetError Parameters Parameter hInternet szFilename nError Description Internal handleignore. Specifies the fully qualified file name of the file for which the error occurred. Specifies the value returned by the Windows API function GetLastError when the error occurred.

Return Values
Table 9-30: OnInternetError Return Values Return Value ERR_IGNORE Description Returned to the setup by the OnInternetError event handler to request that the setup ignore the failure to install or uninstall the file specified in OnInternetErrors second argument and continue without performing the operation. Returned to the setup by the OnInternetError event handler to request that the setup attempt again to install or uninstall the file specified in OnInternetErrors second argument. Returned to the setup by the OnInternetError event handler to request that the setup be aborted.

ERR_RETRY

ERR_ABORT

OnLaunchAppAndWaitCallback
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The OnLaunchAppAndWaitCallback event handler is called while the installation is waiting for an application to launch if LAAW_OPTION_USE_CALLBACK was specified when calling the LaunchApplication function. The event is called in the intervals determined by the amount of time specified in the LAAW_PARAMETERS.nCallbackInterval parameter.

366

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

If the installation contains multiple LaunchApplication calls in which LAAW_OPTION_USE_CALLBACK was specified, the same event is called during each wait. In this case, use the LAAW_PARAMETERS.szCommandLineResult parameter to determine which call is currently being executed. You can return LAAW_CALLBACK_RETURN_CONTINUE_TO_WAIT to continue waiting or LAAW_CALLBACK_RETURN_END_WAIT to end the wait immediately.
function number OnLaunchAppAndWaitCallback( ) begin return LAAW_CALLBACK_RETURN_CONTINUE_TO_WAIT; end;

Note: This event handler appears in installations and object projects. Any specified override for this event applies on to the script in which it is overwritten. An override in the main installation script does not affect contained objects and an override in an object project has no effect on the main installation script.

OnLogonUserSetMsiProperties
Project: This information applies to InstallScript MSI projects.

The OnLogonUserSetMsiProperties event handler sets the Windows Installer properties for the logon user support that is described for InstallScript MSI projects in Adding the Ability to Create or Set an Existing User Account. Specifically, OnLogonUserSetMsiProperties sets the following

The Windows Installer property IS_NET_API_LOGON_USERNAME is set to the InstallScript variable IFX_NETAPI_USER_ACCOUNT The Windows Installer property IS_NET_API_LOGON_PASSWORD is set to the InstallScript variable IFX_NETAPI_PASSWORD The Windows Installer property IS_NET_API_LOGON_GROUP is set to the InstallScript variable IFX_NETAPI_GROUP.

The IFX_NETAPI_* variables are set to the values of the input fields in the SdLogonUserInformation and related dialogs.

OnMD5Error
Project: This information applies to InstallScript projects.

The OnMD5Error event handler responds to the MD5Error event that is generated during MD5 checking when the setup extracts a file whose MD5 hash value does not correspond to the value stored in the setup header file. When creating an InstallShield object, note that this event is not triggered in an object. This event handler is called (when appropriate) in any setup, including a setup that uses a procedural script (a script with a programendprogram block).

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

367

Chapter 9: Event Handlers Miscellaneous Event Handlers

Tip: MD5 checking can detect corrupted files, which is useful during Internet setups; not doing MD5 checking can make file transfer proceed faster. You can enable or disable MD5 checking with the Advanced button in the Release Wizard's General Options panel, or with the Setup.ini file's [Startup] section's CheckMD5 key.

Syntax
OnMD5Error ( szFilename );

Parameters
Table 9-31: OnMD5Error Parameters Parameter szFilename Description Specifies the fully qualified file name of the file that generated the MD5 error.

Return Values
Table 9-32: OnMD5Error Return Values Return Value ERR_IGNORE Description Returned to the setup by the OnMD5Error event handler to request that the setup ignore the failure to install or uninstall the file specified in OnMD5Errors argument and continue without performing the operation. Returned to the setup by the OnMD5Error event handler to request that the setup attempt again to install or uninstall the file specified in OnMD5Errors argument. Returned to the setup by the OnMD5Error event handler to request that the setup be aborted.

ERR_RETRY

ERR_ABORT

Additional Information
An MD5Error event will be generated at run time if, after running the media builder, you replace an uncompressed file in a disk image folder. You can modify the default OnMD5Error code to automatically handle this MD5Error event rather than display a dialog. For example, to automatically ignore the MD5Error event for the file ReplacedAfterBuild.txt, which is installed to TARGETDIR, add the following lines at the beginning of the OnMD5Error code:
if szFilename = TARGETDIR ^ "ReplacedAfterBuild.txt" then return ERR_IGNORE; endif;

OnMsiSilentInstall
Project: This information applies to InstallScript MSI projects.

368

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

An installation program created by an InstallScript MSI project requires the end user to run Setup.exe. The OnMsiSilentInstall event handler responds to the end user attempting to run an InstallScript MSI projects .msi database in silent mode with the /q option to MsiExec.exe. The default implementation is to display an error message and then abort the installation.

OnNextDisk
Project: This information applies to InstallScript projects. Because the Windows Installer handles disk prompts, this event is not supported for InstallScript MSI projects.

The OnNextDisk event handler responds to the NextDisk event that occurs in a multi-disk setup when the next disk in the sequence is required to continue the setup.

Return Values
Table 9-33: OnNextDisk Return Values Return Value ERR_RETRY Description Returned to the setup by the OnNextDisk event handler to request that the setup search again for the file specified in OnNextDisk's first argument. Returned to the setup by the OnNextDisk event handler to request that the setup be aborted.

ERR_ABORT

OnOutOfDiskSpace
Project: This information applies to InstallScript MSI projects.

The OnOutOfDiskSpace event handler responds to the Out Of Disk Space event. The default implementation of OnOutOfDiskSpace displays the SdDiskSpace2 dialog, and then aborts the installation.

OnPatchUIAfter
Project: This information applies to InstallScript MSI projects.

The OnPatchUIAfter event handler is called after data transfer for a patch installation. The default implementation of OnPatchUIAfter calls the SdFinishEx function.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

369

Chapter 9: Event Handlers Miscellaneous Event Handlers

OnPatchUIBefore
Project: This information applies to InstallScript MSI projects.

The OnPatchUIBefore event handler is called when the user launches a patch installation. The default implementation of OnPatchUIBefore calls the SdPatchWelcome dialog function.

OnRebooted
Project: This information applies to the following project types:

InstallScript InstallScript MSIif the InstallScript user interface (UI) style is the traditional style (which uses the InstallScript engine as an external UI handler)

This information does not apply to InstallScript MSI projects in which the InstallScript UI style is the new style (which uses the InstallScript engine as an embedded UI handler). To learn more, see Using the InstallScript Engine as an External vs. Embedded UI Handler for InstallScript MSI Installations.

The OnRebooted event handler responds to the Rebooted event that the installation generates when it restarts after the target system is rebooted. When the installation restarts after reboot, OnRebooted is the only event handler it calls.

OnRemovingSharedFile
Project: This information applies to InstallScript projects.

The OnRemovingSharedFile event handler responds to the RemovingSharedFile event that occurs during uninstallation when a file that might be shared with other applications is about to be removed. When creating an InstallShield object, note that this event is not triggered in an object. This event handler is called (when appropriate) in any setup, including a setup that uses a procedural script (a script with a programendprogram block).

Syntax
OnRemovingSharedFile ( szFilename );

370

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

Parameters
Table 9-34: OnRemovingSharedFile Parameters Parameter szFilename Description Specifies the fully qualified file name of the shared file.

Return Values
Table 9-35: OnRemovingSharedFile Return Values Return Value ERR_YES Description Returned to the setup by the OnRemovingSharedFile event handler to request that the setup remove the file. Returned to the setup by the OnRemovingSharedFile event handler to request that the setup not remove the file.

ERR_NO

OnResumeUIAfter
Project: This information applies to InstallScript MSI projects.

The OnResumeUIAfter event handler responds to the Resume UI After event. It performs tasks that must take place after an application's reinstallation or minor upgrade. The OnResumeUIAfter and OnResumeUIBefore event handlers are called only when all of the following conditions apply:

The application is already installed on the target machine. A patch is not being run. One of the following properties is set at the command line or in the CmdLine property of Setup.ini:

ADDDEFAULT ADDLOCAL ADDSOURCE ADVERTISE COMPADDLOCAL COMPADDSOURCE FILEADDDEFAULT FILEADDLOCAL FILEADDSOURCE

ISP-1800-RG00 371

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

REINSTALL REMOVE

OnResumeUIBefore
Project: This information applies to InstallScript MSI projects.

The OnResumeUIBefore event handler responds to the Resume UI Before event. It performs tasks that must take place before an application's reinstallation or minor upgrade. The OnResumeUIBefore and OnResumeUIAfter event handlers are called only when all of the following conditions apply:

The application is already installed on the target machine. A patch is not being run. One of the following properties is set at the command line or in the CmdLine property of Setup.ini:

ADDDEFAULT ADDLOCAL ADDSOURCE ADVERTISE COMPADDLOCAL COMPADDSOURCE FILEADDDEFAULT FILEADDLOCAL FILEADDSOURCE REINSTALL REMOVE

OnRMFilesInUse
Project: This information applies to InstallScript MSI projects.

The OnRMFilesInUse event handler is called in an InstallScript MSI installation when the Restart Manager is enabled and Windows Installer 4.0 sends an INSTALLMESSAGE_RMFILESINUSE message to the installation.

372

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Miscellaneous Event Handlers

Note that the INSTALLMESSAGE_RMFILESINUSE message is not sent if the Restart Manager is unavailable or disabled. For more information, see MSIRESTARTMANAGERCONTROL Property in the Windows Installer Help Library. If the Restart Manager is unavailable or disabled, or if the target system has Windows Installer 3.x or earlier, Windows Installer sends an INSTALLMESSAGE_FILESINUSE message to the installation. By default, the OnRMFilesInUse event handler displays the SdRMFilesInUse dialog. The event handler returns the value that the dialog returns, and the value is then passed back to the Windows Installer to indicate how the message was handled and what action the Windows Installer should take.

Syntax
OnRMFilesInUse (szMessage);

Parameters
Table 9-36: OnRMFilesInUse Parameters Parameter szMessage Description String provided by the Windows Installer indicating the files that are in use. The SdRMFilesInUse function parses this string.

Return Values
Table 9-37: OnRMFilesInUse Return Values Return Value IDCANCEL IDRETRY Description Indicates that the installation should be cancelled. Indicates that the Windows Installer should recheck for in-use files and send the INSTALLMESSAGE_RMFILESINUSE message if it still needed.

Note: Unlike the SdFilesInUse dialog, the SdRMFilesInUse dialog does not return this value. IDIGNORE Indicates that the Windows Installer should ignore the fact that the files are in use and should continue the installation. Indicates that the Windows Installer should use the Restart Manager to attempt to shut down running applications that are locking files. For more information, see INSTALLMESSAGE_RMFILESINUSE in the Windows Installer Help Library.

IDOK

OnSelfRegistrationError
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

373

Chapter 9: Event Handlers Miscellaneous Event Handlers

The OnSelfRegistrationError event handler is called directly by the framework when a call to Do(SELFREGISTRATIONPROCESS) fails to register files successfully.

Syntax
OnSelfRegistrationError ( );

Parameters
None.

Return Values
None.

Additional Information
The default OnSelfRegistrationError code uses the following properties of the global FileRegistrar object:
Table 9-38: Global FileRegistar Object Properties Property FileRegistrar.Errors.Count FileRegistrar.Errors(i) Description The number of self-registering files that were not registered. An object whose properties provide information about the i-th unregistered file. (i runs from 1 to the value of FileRegistrar.Errors.Count.) The name of the i-th unregistered file. A string describing the error that occurred when the setup attempted to register the i-th unregistered file. This string may be null (""). The numeric code for the error that occurred when the setup attempted to register the i-th unregistered file.

FileRegistrar.Errors(i).File FileRegistrar.Errors(i).Description

FileRegistrar.Errors(i).LastError

OnWarning
Project: This information applies to InstallScript MSI projects.

The OnWarning event handler responds to the Warning event, which is raised when the Windows Installer service sends a INSTALLMESSAGE_WARNING message.

374

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 9: Event Handlers Advanced Event Handlers

Advanced Event Handlers

Advanced event handlers are triggered under special circumstances.
Table 9-39: Advanced Event Handlers Event Handler OnShowUI Project Type InstallScript Description Called directly by the installation engine to initiate the user interface and file transfer. The OnUninstall event handler is called when the installation is run with the /uninst parameter. This is the only event that is called when the /uninst parameter is used. The default code for the OnUninstall event uninstalls a previously installed product.

OnUninstall

InstallScript, InstallScript MSI

OnShowUI
This function drives the UI sequence and file transfer of the setup. The OnShowUI event is called directly by the framework to initiate the UI sequence and file transfer of the setup. By default this event displays UI that informs the end user that the maintenance setup has been completed successfully. You should note that this event will not be called automatically in program...endprogram style setup.

Syntax
OnShowUI ( );

Parameters
None.

Return Values
None.

Additional Information
You can easily convert a procedural script to an event-based script by performing the following steps. If you do this, neither the user interface event handlers (OnFirstUIBefore, OnMaintUIBefore, OnUpdateUIBefore, OnFirstUIAfter, OnMaintUIAfter, and OnUpdateUIAfter) nor OnMoveData are called; but all other feature event handlers are called as appropriate, and you can use InstallShield objects in your installation.

Task

To convert a procedure script to an event-based script: 1. 2.

Open your project in InstallShield; when you are prompted to convert it, click Yes. Open the script and change the following line:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

375

Chapter 9: Event Handlers Advanced Event Handlers

program

to this:
function OnShowUI begin

3.

Also change the following line:

endprogram

to this:
end

4.

If you are planning to display any custom objects that include a user interface (objects provided with InstallShield do not), add a call to ShowObjWizardPages to your dialog sequence at the location where you want any object UI to be shown:
ShowObjWizardPages( nResult );

This function can be called before or after file transfer; the appropriate object event is called based on whether or not file transfer has occurred and on the value of the MAINTENANCE system variable.
5.

Make the changes needed to compile the script in InstallShield.

You can also customize the OnBegin and OnEnd events if you wish.

Why This Works

In InstallShield, most installation events are driven by the main UI event, OnShowUI. When you replace the default code in this event with the your programendprogram block's code, you are basically providing a custom UI sequence. Note that since OnShowUI is called in all cases when the installation is run, your installation will act just like it did when it was a programendprogram script.

OnUninstall
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The OnUninstall event is called when the installation is run with the /uninst parameter. This is the only event that is called when the /uninst parameter is used. The default code for the OnUninstall event uninstalls a previously installed product.

376

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

10
Functions
A function is a named set of instructions that operate together to perform a specific task.

Function Characteristics
Every function has the following characteristics:

A function is named. Each function has a unique name. When you call the function by name, you know which set of instructions will run, and you can be sure of consistent results. You can also call a function from within another function. A function is independent. In most cases, any function can perform its instructions without interfering with other parts of the program. A function performs a certain task. A task is any single job that the script must perform, such as displaying a bitmap, compressing a file, or creating a folder. A function can return a value to the script. When the script executes, it performs the instructions of the function. Based on the result of the instructions, a function can return information to the script.

Function Types
InstallShield allows you to use three types of functions in your setup script:
Table 10-1: Function Types Function Type Built-in functions Description Functions supplied by InstallShield or included for Sd dialogs. Functions that you create. Functions that you can call in a DLL.

User-defined functions DLL-called functions

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

377

Chapter 10: Functions Using Built-In Functions

Note: Like the C programming language, InstallScript does not support nested function blocks.

Using Built-In Functions

InstallShield has several hundred built-in functions that you can use in your setup scripts to create program groups and items, manipulate folders, work with lists, monitor the status of the setup, create dialogs, manipulate files, and much more. Because the InstallShield Script Compiler already recognizes these function names, you do not have to declare them before you can use them.

Learning About Function Names and Formats

In order call a built-in function, you must know both its name and its format. To find a function that will fit your requirements, review Built-In Functions by Category, which describes each of the major categories of available functions. Click a category link to view a list of functions and descriptions that pertain to that category. All of the built-in functions are listed alphabetically in the Built-in Functions sections. To display a complete description of any function in that list, click its name. The help topic for that function provides the functions format. For example, AskYesNo is a built-in function that displays a query in a dialog and then waits for the end user to respond by clicking a button, either Yes or No. AskYesNo has the following format:
AskYesNo (szQuestion, nDefault);

The format shows the correct spelling of the function name, which is followed by the function's parameter list, enclosed in parentheses. In the help topic for a built-in function, each parameter is expressed in Hungarian notation, which indicates the type of data that must be passed in that position. AskYesNo requires two parameters: the first parameter is a string; the second is a number.

Note: Like C, InstallScript is case sensitive. Be sure to pay close attention to the capitalization of letters in the built-in function names.

Using Built-In Functions in Your Script

To use a built-in function in your script, pass the required number of parameters, and make sure that the data you pass in each parameter is the type indicated for that position. If you pass the incorrect number of parameters, or if you pass the wrong type of data in any parameter positions, the script will not compile. The specific documentation for each built-in function provides a description of its parameters. For AskYesNo, szQuestion is the question to be displayed in the dialog and nDefault indicates which button to preselectYes or No. One of two predefined constants can be passed in nDefault: YES or NO. Consider a dialog in which the Yes button is preselected. To display this dialog, call AskYesNo as shown below:

378

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Built-In Functions by Category

AskYesNo ("Installation Complete. Would you like to view the ReadMe file now?", YES);

Note: String literals passed as parameters must be enclosed in single or double quotation marks, for example: Please wait while files are transferred, or 'This is a string', or C:\\Myfolder\\Myfile.ext.

Troubleshooting
Note the following:

InstallScript functions do not allow you to pass an assignment statement as a parameter. In addition, you cannot use the && or || operators within an argument to a function. An autosized string variable that is passed by reference to a function will not be autosized within the called function. If the function attempts to assign a value whose length is greater than the current size of that parameter, run-time error 401 occurs. To avoid this error, declare strings with a specific size when they are to be passed by reference to a function.

Built-In Functions by Category

The following categories of functions are available in the InstallScript language.
Table 10-2: Built-In Functions by Category Function Category Batch File Functions Component Functions Description Work with batch files. In InstallShield, feature functions replace the component functions that were used in InstallShield Professional. Modify the default system configuration file. Install and uninstall device drivers using DIFx. Create InstallScript dialogs and message boxes. Customize InstallScript dialogs, and modify the text, controls, and behavior of InstallScript dialogs. Call functions in dynamic-link libraries, call Windows APIs, launch another application or setup script, and load or unload a .dll file into memory. Control file media. Also create and process script-created feature sets. Work with text files, binary files, and folders. Enables you to use FlexNet Connect to notify end users about updates that are available for your product. Provide data about resources that are available in the operating environment: disk space, memory, and operating mode.

Configuration File Functions Device Driver Functions Dialog Functions Dialog Customization Functions

Extensibility Functions

Feature Functions File and Folder Functions FlexNet Connect Functions

Information Functions

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

379

Chapter 10: Functions Built-In Functions by Category

Table 10-2: Built-In Functions by Category (cont.) Function Category Initialization File Functions Description Obtain information from and copy information to the initialization and profile files. Implement lists in a setup script. Obtain information from and copy information to the log file's custom logging section. Create long file names from short file names, convert short file names to long file names, and place double quotation marks around long file names so that operating systems that handle long file names can recognize them. Serve various purposes, such as low-level hardware interface, feature creation and manipulation, and user output. Initialize objects, as well as obtain and set object status information. Work with strings that contain search paths. The path string functions work on a unique temporary string variable known as the path buffer. Access the registry, read, create and delete registry keys, and establish registry-related parameters for uninstallation. Handle shared or locked files. Create program folders, delete existing program folders, and add items to existing program folders. Set up the minimum required registry keys and values. The special registryrelated functions work only with the per application paths key, the application uninstallation key, or the application information key. Perform SQL tasks such as connect to a catalog, create SQL-related dialogs, and obtain SQL run-time errors. Manipulate string variables and literals. String functions behave similarly to the standard C language functions. The return values also follow the C language convention. Associate a string with another stringfor example, associating "<MYTEXTSUB>" with "My Text Sub Value"and of replacing the former string with the latter in other stringsfor example, changing "This string demonstrates text substitution <MYTEXTSUB>" to "This string demonstrates text substitution My Text Sub Value". Perform services required for the uninstallation and/or maintenance setup of an installed application. Customize certain error messages and titles of error boxes. Note that several internal error messages that may be encountered during the development of the setup cannot be modified using user interface functions.

List Processing Functions Log File Functions

Long File Name Functions

Miscellaneous Functions

Object Functions Path Buffer Functions

Registry Functions

Shared and Locked File Functions Shell Functions

Special Registry-Related Functions

SQL Functions

String Functions

Text Substitutions

Uninstallation Functions

User Interface Functions

380

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Batch File Functions

Table 10-2: Built-In Functions by Category (cont.) Function Category Version-Checking Functions Description Obtain a specific file's version, find a file and get its version, or search for an existing file and try to install a newer version of the file. The functions work with either compressed or uncompressed files. Exported by the Windows Installer engine. These functions enable you to query and manipulate properties of a running installation.

Windows Installer Functions

Batch File Functions

When you work with batch and configuration files, you can treat the files as normal text files, or you can use InstallScript functions designed specifically to modify batch and configuration files.

Ez and Advanced Batch Functions

There are two classes of InstallScript batch file functionsEz and advanced. Ez functions are quick and easy to use because they have many preprogrammed features. If you need greater flexibility and control over the changes you need to make to configuration and batch files, use the advanced functions.

Return Value
InstallShield does not display a message if a batch function fails, but returns a value that is less than zero (< 0). The return value indicates whether the function performed successfully. You can check the return value and display a message based on the result.

Ez Batch File Functions

Ez batch file functions make modifications to the default batch file. Unless changed by a call to BatchSetFileName, the default batch file is the Autoexec.bat file that was executed by the system during the boot sequence. It is important to note that each Ez batch file function opens the default batch file and then saves it automatically after making the specified modification. You do not make calls to open or save when using Ez batch file functions.
Table 10-3: Ez Batch File Functions Function EzBatchAddPath Description Modifies the default batch file by adding a directory to the search path in a PATH command or to the value assigned to an environment variable. Adds a line of text to the default batch file. Replaces a statement in the default batch file.

EzBatchAddString EzBatchReplace

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

381

Chapter 10: Functions Component Functions

Advanced Batch File Functions

Advanced batch file functions differ from Ez batch file functions in that they provide greater flexibility and more control over batch files. Use these functions when you need to make more extensive or complex changes to a batch file. To edit a batch file with these advanced functions, you must first load the file into memory by calling BatchFileLoad. When modifications to the batch file are complete, you must then save the file by calling BatchFileSave. When an InstallScript custom action initializes, InstallShield selects the target system's startup batch file (Autoexec.bat) as the default batch file; unless changed by a call to BatchSetFileName this is the file that BatchFileLoad reads into memory if no other file name is specified. To determine the fully qualified name of the default batch file, call BatchGetFileName.
Table 10-4: Advanced Batch File Functions Function BatchAdd BatchDeleteEx BatchFileLoad BatchFileSave BatchFind BatchGetFileName BatchMoveEx BatchSetFileName Description Adds an environment variable to a batch file. Deletes a line in the batch file. Loads a batch file into memory for editing with advanced batch functions. Saves a batch file that has been loaded with BatchFileLoad. Finds items in a batch file. Retrieves the fully qualified file name of the default batch file. Moves an item within a batch file. Specifies a batch file to be the default batch file.

Related Function
Table 10-5: Related Function Function SdShowFileMods Description Creates a dialog that displays proposed file changes and offers options on how to proceed.

Component Functions
Because a Windows Installer-based installation uses features as the highest level of organization in installation projects, and not components, component-related functions are deprecated in InstallShield. All supported component functions now have corresponding feature functions that should be used in your script.

382

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Configuration File Functions

For example, the ComponentAddItem function is now FeatureAddItem. For more information and a list of available feature-related functions, see Feature Functions

Configuration File Functions

Configuration file functions modify the default system configuration file. There are two types of configuration file functions:

Ez Config.sys File Functions Advanced Configuration File Functions

Ez Config.sys File Functions

Ez configuration file functions modify the default system configuration file. Unless changed by a call to ConfigSetFileName, that file is the Config.sys file that was executed by the system during the boot sequence.
Table 10-6: Ez Configuration File Functions Function EzConfigAddDriver EzConfigAddString EzConfigGetValue Description Adds a device driver statement to the default system configuration file. Adds a statement or line of text to the default system configuration file. Retrieves the value of a system configuration file parameter, such as FILES or BUFFERS. Sets the value of a system configuration file parameter, such as FILES or BUFFERS.

EzConfigSetValue

Note: Each of these functions opens the default system configuration file, performs its assigned task, and then saves the file back to disk. It is not necessary to load and save the configuration file as with the advanced configuration file functions.

Advanced Configuration File Functions

The advanced configuration file functions provide the advanced developer greater flexibility and more control over system configuration files than do the Ez configuration file functions. To access and edit a system configuration file with these advanced functions, start by calling ConfigFileLoad. When you are

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

383

Chapter 10: Functions Device Driver Functions

finished editing the system configuration file, call ConfigFileSave to save your changes. Note that the functions ConfigGetFileName and ConfigSetFileName can be used with both advanced and Ez configuration file functions.
Table 10-7: Advanced Configuration File Functions Function ConfigAdd Description Adds a statement to a system configuration file that has been loaded in memory. Deletes an item from a system configuration file. Loads a system configuration file into memory for editing. Saves a system configuration file that has been loaded into memory with ConfigFileLoad. Searches for an item in a system configuration file. Retrieves the fully qualified name of default system configuration file. Retrieves a value from a system configuration file. Moves an item within a system configuration file. Specifies the fully qualified file name of a system configuration file. Sets a value in a system configuration file.

ConfigDelete ConfigFileLoad ConfigFileSave

ConfigFind ConfigGetFileName ConfigGetInt ConfigMove ConfigSetFileName ConfigSetInt

Related Function
Table 10-8: Related Function Function SdShowFileMods Description Creates a dialog displaying proposed file changes and offering options on how to proceed.

Device Driver Functions

The functions below handle installing and uninstalling device drivers using Windows Driver Install Frameworks (DIFx). For more information on DIFx and DIFxAPI, see the MSDN Library.
Table 10-9: Device Driver Functions Function DIFxDriverPackageGetPath Description Retrieves the path to the .inf file for driver package after a driver package is preinstalled in the driver store.

384

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Dialog Functions

Table 10-9: Device Driver Functions (cont.) Function DIFxDriverPackageInstall Description Preinstalls a driver package in the driver store and then installs the driver in the system. Preinstalls a driver package for a Plug and Play (PnP) function driver in the driver store and installs the .inf file for the driver package in the system .inf file directory. Uninstalls the specified driver package from the system and removes the driver package from the driver store.

DIFxDriverPackagePreinstall

DIFxDriverPackageUninstall

Dialog Functions
Some of the following functions create simple dialogs, such as Yes/No dialogs and message boxes. Several functions let you easily display various types of common dialogs. Other functions are script dialog (Sd) functions. Sd dialogs are created using special InstallScript definition functions that create a dialog with custom input. The dialogs then automatically return values to the script based on the selected action.

Note: Dialogs that have a Cancel button do not return a CANCEL value when that button is clicked. Instead, the OnCanceling event handler is called. Table 10-10: Dialog Functions Function AdminAskPath Project Type InstallScript MSI Description Displays a dialog that prompts the end user to enter the path to a destination location for an administrative installation (when the end user runs an InstallScript MSI projects Setup.exe file with the /a argument). Presents a dialog that requests destination path information.

AskDestPath

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI Basic MSI, InstallScript, InstallScript MSI

AskOptions

Presents a dialog that prompts the end user to select options by using check boxes or radio buttons. Presents a dialog that prompts the end user to enter a path.

AskPath

AskText

Presents a dialog that prompts the end user to enter text.

AskYesNo

Presents a message box that prompts the end user to respond to a question by clicking on a Yes or No button.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

385

Chapter 10: Functions Dialog Functions

Table 10-10: Dialog Functions (cont.) Function EnterDisk Project Type Basic MSI, InstallScript, InstallScript MSI Basic MSI, InstallScript, InstallScript MSI Description Presents a message box that prompts the end user for a specific disk.

EnterDiskError

Checks whether a specified path and file exists. The function displays an appropriate error message box if the file does not exist in the specified path; then it returns success or failure, depending on whether the specified file exists. Displays a dialog that enables the end user to specify a user name and password. Note that the dialog does not validate or use the specified information. In addition, the dialog does not perform any error checking for the specified information. Displays a dialog that queries the end user for a password; the characters that the end user types in the edit box are displayed as asterisks (*). Presents a dialog that enables end users to select features and specify a destination location. Presents a message in a message box.

EnterLoginInfo

InstallScript, InstallScript MSI

EnterPassword

InstallScript, InstallScript MSI

FeatureDialog

InstallScript, InstallScript MSI Basic MSI, InstallScript, InstallScript MSI Basic MSI, InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI

MessageBox

MessageBoxEx

Presents a message in a message box.

RebootDialog

Presents a message box that enables end users to choose to restart the computer. Creates a dialog that enables end users to select an alternate destination path. Creates a dialog that enables end users to select an alternate destination path. Creates a dialog that has greater flexibility than the standard AskOptions function. Presents a dialog that enables end users to select and deselect items from a list. Displays a bitmap on a dialog.

SdAskDestPath

SdAskDestPath2

SdAskOptions

SdAskOptionsList

SdBitmap

SdConfirmNewDir

Displays a message box that prompts the user to confirm the folder selection. Displays a message box that prompts the end user to confirm the information that was entered in dialogs presented by SdRegisterUser or SdRegisterUserEx.

SdConfirmRegistration

386

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Dialog Functions

Table 10-10: Dialog Functions (cont.) Function SdCustomerInformation Project Type InstallScript, InstallScript MSI Description Displays a dialog that enables the end user to specify the user name and company name for the product being installed. The dialog may also include radio buttons that let the end user specify whether the product should be installed for all users or only the current user. Displays a dialog that enables the end user to specify the user name, company name, and serial number for the product being installed. The dialog may also include radio buttons that let the end user specify whether the product should be installed for all users or only the current user. Displays a dialog that shows either of the following:

SdCustomerInformationEx

InstallScript, InstallScript MSI

SdDiskSpace2

InstallScript, InstallScript MSI

A list view of volumes, required space, available space, and the difference between available space and required space. A warning message indicating that the target system does not have enough available space for the installation to take place. The dialog also displays a list view of volumes, required space, available space, and the difference between available space and required space.

SdDiskSpaceRequirements

InstallScript, InstallScript MSI

Displays a list of volumes, required space, available space, and the difference between available and required space. SdDiskSpace2 supersedes this function.

SdDisplayTopics

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI

Displays a list of topics.

SdExceptions

Displays a message box informing the end user that a shared, locked (in use), or read-only file has been encountered. Displays a dialog that enables end users to select features to install and a destination folder. Displays a dialog that enables end users to select folders, features, and subfeatures to install. Displays a dialog that enables end users to select features to install and a destination folder. Displays a dialog that enables the end user to select the features and subfeatures to install. Additional information about disk space is also provided to help determine the best location for the installation. Displays a dialog with a tree control that enables end users to select the features and subfeatures to install. Additional information about disk space is also provided to help determine the best location for the installation.

SdFeatureDialog

SdFeatureDialog2

SdFeatureDialogAdv

SdFeatureMult

SdFeatureTree

InstallScript, InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

387

Chapter 10: Functions Dialog Functions

Table 10-10: Dialog Functions (cont.) Function SdFilesInUse Project Type InstallScript MSI Description Displays a dialog that includes a list box containing a list of the applications that are open and are locking files. Displays a dialog that informs the end user that the setup is complete and offers a choice of options, such as whether to view an information file or launch an application. Displays a dialog informing the end user that the installation is complete. Displays a dialog that informs the user that the setup is complete and offers a choice of options for restarting Windows and the computer. Displays a dialog that indicates that the installation is complete. The dialog includes the option to check for application updates.

SdFinish

InstallScript, InstallScript MSI

SdFinishEx

InstallScript, InstallScript MSI InstallScript, InstallScript MSI

SdFinishReboot

SdFinishUpdate

InstallScript, InstallScript MSI

Note: SdFinishUpdate does not check for updates; to check for updates, add FlexNet Connect API calls in your InstallScript code. For more information, see the FlexNet Connect SDK documentation. SdFinishUpdateEx InstallScript, InstallScript MSI Displays a dialog that indicates that the installation is complete. The dialog includes the option to check for application updates.

Note: SdFinishUpdateEx does not check for updates; to check for updates, add FlexNet Connect API calls in your InstallScript code. For more information, see the FlexNet Connect SDK documentation. SdFinishUpdateReboot InstallScript, InstallScript MSI Displays a dialog that indicates that the installation is complete. The dialog gives the end user the option to restart the system and to check for application updates.

Note: SdFinishUpdateReboot does not check for updates; to check for updates, add FlexNet Connect API calls in your InstallScript code. For more information, see the FlexNet Connect SDK documentation.

388

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Dialog Functions

Table 10-10: Dialog Functions (cont.) Function SdLicense Project Type InstallScript, InstallScript MSI Description Displays a dialog that contains a license agreement in a multiline edit field. The license agreement is stored in a text file identified in the parameter szLicenseFile. The dialog shows a question in a static text field. The end user responds by clicking the Yes or No button. The SdLicenseEx function supersedes this function. SdLicense2 InstallScript, InstallScript MSI Displays a dialog that contains a license agreement in a multiline edit field. The license agreement is stored in a text file identified in the parameter szLicenseFile. The dialog displays two radio buttons (one for accepting the terms of the license agreement, and one for not accepting them). The Next button becomes enabled when the end user clicks the appropriate button to accept the terms of the license agreement. The SdLicense2Ex function supersedes this function. SdLicense2Ex InstallScript, InstallScript MSI Displays a dialog that contains a license agreement in a multiline edit field. The license agreement is stored in a text file (.txt) or a rich text file (.rtf) identified in the parameter szLicenseFile. The dialog displays two radio buttons (one for accepting the terms of the license agreement, and one for not accepting them). The Next button becomes enabled when the end user clicks the appropriate button to accept the terms of the license agreement. SdLicense2Rtf InstallScript, InstallScript MSI Displays a dialog that contains a license agreement in a multiline edit field. The license agreement is stored in a text or richtext format (RTF) file identified in the parameter szLicenseFile. The dialog displays two radio buttons (one for accepting the terms of the license agreement, and one for not accepting them). The Next button becomes enabled when the end user clicks the appropriate button to accept the terms of the license agreement. The SdLicense2Ex function supersedes this function. SdLicenseEx InstallScript, InstallScript MSI Displays a dialog that contains a license agreement in a multiline edit field. The license agreement is stored in a text file (.txt) or a rich text file (.rtf). The dialog shows a question in a static text field. The end user responds by clicking the Yes or No button.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

389

Chapter 10: Functions Dialog Functions

Table 10-10: Dialog Functions (cont.) Function SdLicenseRtf Project Type InstallScript, InstallScript MSI Description Displays a dialog that contains a license agreement in a multiline edit field. The license agreement is stored in a text or richtext format (RTF) file identified in the parameter szLicenseFile. The dialog shows a question in a static text field. The end user responds by clicking the Yes or No button. The SdLicenseEx function supersedes this function. SdLogonUserBrowse InstallScript, InstallScript MSI InstallScript, InstallScript MSI Displays a message box that enables end users to select a domain or server and a user name. Displays a dialog that enables end users to enter new user information after the end user clicks the New User Information button on the SdLogonUserInformation dialog. Displays a dialog that prompts the end user for existing user account information or new user information if an account is to be created during the installation. Displays a dialog that enables end users to select a group from a specified server and populate the Group field in the SdLogonUserCreateUser dialog. Displays a dialog that enables end users to browse for the domain or server with which the user account is associated. Displays a dialog that enables end users to browse and select an existing user for a specified domain or server. Displays a dialog with user-defined buttons that provide an end user with various options. When triggered by the Windows Installers INSTALLMESSAGE_OUTOFDISKSPACE message, this dialog displays a message indicating that the target system is out of disk space. SdDiskSpace2 supersedes this function. SdPatchWelcome InstallScript MSI Creates a dialog that displays a welcome message to end users during a patch installation. Displays a dialog that enables the end user to specify the user name and company name for the product being installed. Displays a dialog that enables the end user to specify the user name, company name, and serial number for the product being installed.

SdLogonUserCreateUser

SdLogonUserInformation

InstallScript, InstallScript MSI

SdLogonUserListGroups

InstallScript, InstallScript MSI

SdLogonUserListServers

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript MSI

SdLogonUserListUsers

SdOptionsButtons

SdOutOfDiskSpace

SdRegisterUser

InstallScript, InstallScript MSI InstallScript, InstallScript MSI

SdRegisterUserEx

390

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Dialog Functions

Table 10-10: Dialog Functions (cont.) Function SdRMFilesInUse Project Type InstallScript MSI Description Displays a dialog that includes a list box containing a list of the applications that are open and are locking files. The dialog also includes two radio buttons that allow end users to specify whether the installation should attempt to use the Restart Manager to shut down the applications that are locking files or attempting to overwrite the locked files (which most likely results in the need for a reboot to complete the installation). Presents a dialog that enables end users to select a folder from a list of program folders. Displays a dialog to inform the end user that the installation was interrupted before it could be completed. Displays a dialog that enables the end user to select one of the three standard setup types: Typical, Compact, or Custom. Displays a dialog that enables end users to select one of the two standard setup types: Typical or Custom. Displays a dialog that enables end users to select standard or custom setup types. Displays a general-purpose dialog from a resource DLL. You cannot receive any input from the end user when showing a dialog with SdShowAnyDialog. Displays a dialog that has one single-line edit field and other static controls. Displays a dialog that has two single-line edit fields and other static controls. Displays a dialog that has three single-line edit fields and other static controls. Presents a dialog that previews the changes that may be made to a file and enables end users to approve the changes, reject the changes, or request that the changes be written to a file. Displays a scrollable list of messages in a dialog.

SdSelectFolder

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript MSI

SdSetupCompleteError

SdSetupType

SdSetupType2

SdSetupTypeEx

SdShowAnyDialog

InstallScript, InstallScript MSI

SdShowDlgEdit1

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI

SdShowDlgEdit2

SdShowDlgEdit3

SdShowFileMods

SdShowInfoList

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI

SdShowMsg

Displays a message in a small window.

SdStartCopy

Presents a dialog that displays the options and settings that have been specified by the end user. Presents a dialog that informs the end user that the file transfer process is about to begin. The user can click the Back button to return to previous dialogs in order to change settings as required.

SdStartCopy2

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

391

Chapter 10: Functions Dialog Functions

Table 10-10: Dialog Functions (cont.) Function SdWelcome Project Type InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI Basic MSI, InstallScript, InstallScript MSI InstallScript, InstallScript MSI Description Displays a general-purpose greeting.

SdWelcomeMaint

Displays a dialog for use at the beginning of a maintenance setup. Presents a dialog that enables end users to select a folder. SelectDir creates the folder if it does not exist. Presents a dialog that enables end users to select a folder.

SelectDir

SelectDirEx

SelectFolder

Presents a dialog that enables end users to select a folder from a list of program folders. Presents a dialog that enables the end user to select a typical, compact, or custom setup. Presents a dialog that enables the end user to select one of the two standard setup types: Complete or Custom. Returns a formatted string composed of one or more character, numeric, or string values.

SetupType

SetupType2

SprintfBox

SQLBrowse

Creates a dialog that enables the end user to bring up a list of all SQL Servers available on the network. SQLBrowse2 supersedes this function.

SQLBrowse2

InstallScript, InstallScript MSI

Creates a dialog that lets an end user display a list of all database servers that are available on the network for the database technologies specified for a connection. Creates a dialog that is used by the script to specify SQL login credentials. These credentials include the login ID and password. Creates a dialog to specify a server to target.

SQLServerLogin

InstallScript, InstallScript MSI

SQLServerSelect

InstallScript, InstallScript MSI InstallScript, InstallScript MSI

SQLServerSelectLogin

Creates a login dialog that enables the targeted end user to specify which SQL Server should to be used for the current connection, as well as which login credential should be used. The dialog displays a combo box that contains a list of SQL Servers accessed through DSNs. The end user can type a server name in the combo box or click the Browse button next to the combo box; clicking this button displays a list of all SQL Servers that are available on the network. SQLServerSelectLogin2 supersedes this function.

392

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Dialog Customization Functions

Table 10-10: Dialog Functions (cont.) Function SQLServerSelectLogin2 Project Type InstallScript, InstallScript MSI Description Creates a login dialog that is used by the default script. It lets the targeted end user specify which SQL Server should be used for the current connection, as well as which login credential should be used. The dialog displays a combo box that contains a list of SQL Servers accessed through DSNs. The end user can type a server name in the combo box or click the Browse button next to the Server Name combo box; clicking this button displays a list of all SQL Servers that are available on the network. This function also optionally shows the connection name that is associated with the connection information. In addition, it optionally enables end users to specify which database catalog should be used for the current connection. SQLServerSelectLoginEx InstallScript, InstallScript MSI Creates a login dialog that is used by the default script. It lets the targeted end user specify which SQL Server should be used for the current connection, as well as which login credential should be used. The dialog displays a combo box that contains a list of SQL Servers accessed through DSNs. The end user can type a server name in the combo box or click the Browse button next to the Server Name combo box; clicking this button displays a list of all SQL Servers that are available on the network. This function also shows the connection name that is associated with the connection information. SQLServerSelectLogin2 supersedes this function. Welcome InstallScript, InstallScript MSI Presents a dialog that displays welcome information.

Dialog Customization Functions

Use the following functions to create and customize new InstallScript dialogs, and to modify the text, controls, and behavior of InstallScript dialogs. Some of the functions handle custom dialog processing. Any Windows dialog that you can create can be used in a setup script. The dialogs can have single and multiline edit boxes, single and multiselection list boxes, combo boxes, radio buttons, check boxes, and push buttons as standard controls. For more complex controls, advanced functions such as CmdGetHwndDlg, LOWORD, and HIWORD are provided.
Table 10-11: Dialog Customization Functions Function CmdGetHwndDlg CtrlClear Description Retrieves the handle of a dialog. Deletes the contents of an edit, static, list box, or combo box control.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

393

Chapter 10: Functions Dialog Customization Functions

Table 10-11: Dialog Customization Functions (cont.) Function CtrlDir CtrlGetCurSel CtrlGetDlgItem CtrlGetMLEText CtrlGetMultCurSel CtrlGetState CtrlGetSubCommand CtrlGetText CtrlGetUrlForLinkClicked CtrlPGroups CtrlSelectText CtrlSetCurSel CtrlSetFont CtrlSetList CtrlSetMLEText CtrlSetMultCurSel CtrlSetState CtrlSetText DefineDialog DialogSetFont DialogSetInfo EndCurrentDialog EndDialog EzDefineDialog GetCurrentDialogName Description Fills a list box or combo box with either a directory listing or a file listing. Returns the selected item from a list box or combo box. Retrieves the window handle of a control in a custom dialog. Retrieves the text from a multi-line edit or static field. Returns the selected items from a multi-selection list box. Retrieves the state of a radio button, check box, or push button control from a dialog. Retrieves the operation performed on the control after a WaitOnDialog function call. Retrieves the text from an edit field, a static field, or the edit field of a combo box. Retrieves the URL for a link that an end user clicked. Retrieves a list of program group names that exist on the target system. Selects the text displayed in an edit field. Finds and sets the current selection in a list box or combo box. Specifies a font for a control in the dialog. Places the contents of a list into a list box or combo box. Sets the text in a multi-line edit field. Sets the current selection in a multi-selection list box. Sets the current state of a check box, radio button, or push button control. Sets the text in an edit field, a static text field, or the edit field of a combo box. Registers a custom dialog with InstallShield. Sets the font for dialogs displayed during the setup. Changes display elements in the dialogs presented by some built-in dialog functions. Closes the currently displayed dialog by calling EndDialog. Closes a custom dialog. Registers a custom dialog with InstallShield. Retrieves the name of the currently displayed dialog as it was specified in the call to EzDefineDialog when the dialog was defined. Retrieves the handle of a font. Retrieves the high-order word from a 32-bit integer.

GetFont HIWORD

394

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Extensibility Functions

Table 10-11: Dialog Customization Functions (cont.) Function LOWORD ReleaseDialog SdGeneralInit Description Retrieves the low-order word from a 32-bit integer. Frees the memory associated with a dialog. Provides standard dialog initialization, including setting the enable or disable state of the Next, Back, and Cancel buttons. This function also replaces all %P, %VS, and %VI instances on static controls with control IDs 700 through 724, and 202. Prepares a setup for calls to Sd dialog functions. Returns the string value associated with a specified resource ID. Creates a section name for a custom dialog. This section name is used in writing to and reading from an .iss file, which is used by InstallShield Silent. Inserts your product name in certain static fields of the script dialogs. Replaces any occurrences of the %P, %VS, and %VI placeholders with the values of the system variables IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and IFX_INSTALLED_DISPLAY_VERSION. You can use this function before calling a function, such as MessageBox, that does not automatically perform this replacement before displaying strings. Instructs InstallShield Silent to read the .iss file dialog data for a custom dialog. Instructs InstallShield Silent to write to the .iss file dialog data for a custom dialog. Presents a custom dialog.

SdInit SdLoadString SdMakeName

SdProductName SdSubstituteProductInfo

SilentReadData SilentWriteData WaitOnDialog

Extensibility Functions
Extensibility functions allow you to call functions in dynamic-link libraries, call Windows APIs, or launch another application or setup script. The UseDLL and UnUseDLL functions allow you to load or unload a DLL into memory and make use of the DLL. The LaunchApp and LaunchAppAndWait functions allow you to launch another Windows or DOS application while the script is still executing.
Table 10-12: Extensibility Functions Function CallDLLFx Delay LaunchApp LaunchAppAndWait Description Calls a function from an external DLL. Delays the execution of the setup script. Launches another program. LaunchApplication supersedes this function. Launches another program and waits for that program to terminate. LaunchApplication supersedes this function.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

395

Chapter 10: Functions Feature Functions

Table 10-12: Extensibility Functions (cont.) Function LaunchAppAndWaitInitSt artupInfo LaunchApplication Description Initializes the LAAW_STARTUPINFO and LAAW_PARAMETERS system variables to the appropriate default values. LaunchApplicationInit supersedes this function. Uses either the Windows API function CreateProcess or the Windows API function ShellExecuteEx to launch the specified application. After the application is launched, the installation can optionally call WaitForApplication to wait for the application to terminate. Initializes the LAAW_STARTUPINFO and LAAW_PARAMETERS system variables to the appropriate default values. This function is called automatically during installation initialization. Unloads a DLL from memory. Loads a DLL into memory. Waits for a running application to terminate before returning.

LaunchApplicationInit

UnUseDLL UseDLL WaitForApplication

Feature Functions
The functions below allow you to control file media and to create and process script-created feature sets.
Table 10-13: Feature Functions Function FeatureAddCost Project Type InstallScript Description Specifies that the feature includes additional installation operations that should be accounted for when updating the progress bar during the installation.

Note: This function is supported only for file media. Use FeatureGetData or FeatureSetData to set the size of scriptcreated features. FeatureAddItem InstallScript, InstallScript MSI InstallScript Adds a new feature to a script-created feature set.

FeatureAddUninstallCost

Specifies that the feature includes additional uninstallation operations that must be accounted for when updating the progress bar during uninstallation. Determines if enough free disk space exists for the selected features. Presents a dialog that enables end users to select features and specify a destination location. Returns additional error information when a feature function fails.

FeatureCompareSizeRequir ed FeatureDialog

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI

FeatureError

396

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Feature Functions

Table 10-13: Feature Functions (cont.) Function FeatureErrorInfo Project Type InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI Description Returns additional error information when a feature function fails. Builds a list of the files in a component associated with the specified feature. Retrieves information on file in the file media that is referenced within the function. Enables and disables filtering based on language.

FeatureFileEnum

FeatureFileInfo

FeatureFilterLanguage

FeatureFilterOS

Enables and disables filtering based on operating system (OS).

FeatureGetCost

Retrieves the total space, in kilobytes (KB), required on the target drive for the specified feature. FeatureGetCostEx supersedes this function.

FeatureGetCostEx

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI

Retrieves the cost of the specified feature (in bytes) using the nvCostHigh and nvCostLow parameters. Retrieves information about a feature.

FeatureGetData

FeatureGetItemSize

Determines the size of a specified feature.

FeatureGetTotalCost

Determines the total space required for the feature installations and uninstallations that have been specified. FeatureGetCostEx supersedes this function.

FeatureInitialize

InstallScript

Supported only for compatibility with scripts created in earlier versions of InstallShield. It is recommended that you avoid using multiple file media libraries in InstallShield. Determines if the specified feature has been selected by the end user. Creates a list of the features in a file media library or a scriptcreated feature set. Called automatically during the initialization of any installation for which a valid log file exists. Transfers and decompresses files associated with selected features in the file media.

FeatureIsItemSelected

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript

FeatureListItems

FeatureLoadTarget

FeatureMoveData

InstallScript

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

397

Chapter 10: Functions Feature Functions

Table 10-13: Feature Functions (cont.) Function FeaturePatch Project Type InstallScript Description Called only in installations that use differential media. This function causes the next call to FeatureTransferData or FeatureMoveData to reinstall all features that are already installed when FeatureTransferData is called, including all of the maintenance/uninstallation feature's files except for Data1.hdr, Data1.cab, and Layout.bin. Configures the setup so that the next call to FeatureTransferData performs the file transfer that was specified the last time the setup was run. Configures the setup so that the next call to FeatureTransferData uninstalls the setup. Called during an update installation to force the removal of all features that are not in the current media but were installed previously, as recorded in the setup log file. Used during a maintenance installation to force the removal of all features that are in the current media and were installed previously. This function is generally called when the user selects the Remove option on the SdWelcomeMaint dialog. Called during an update installation to force the removal of all features that were installed previouslyboth those that are in the current media, and those that are not in the current media but are recorded in the setup log file. Retrieves the current values of all text substitutions used by the installation project and stores them in the installation log file. Selects or deselects features.

FeatureReinstall

InstallScript, InstallScript MSI

FeatureRemoveAll

InstallScript, InstallScript MSI InstallScript

FeatureRemoveAllInLogOnly

FeatureRemoveAllInMedia

InstallScript

FeatureRemoveAllInMediaAn InstallScript dLog

FeatureSaveTarget

InstallScript, InstallScript MSI

FeatureSelectItem

InstallScript, InstallScript MSI InstallScript

FeatureSelectNew

Sets the selection status of all new features to either selected or unselected. Sets properties and data for the specified feature.

FeatureSetData

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript, InstallScript MSI

FeatureSetTarget

Specifies a user-defined variable for a file media library.

FeatureSetupTypeEnum

Enumerates the setup types associated with the specified file media library. Retrieves data associated with a specified setup type that has been created in the InstallShield interface. Selects all features associated with the specified setup type.

FeatureSetupTypeGetData

FeatureSetupTypeSet

398

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Feature Functions

Table 10-13: Feature Functions (cont.) Function FeatureSpendCost Project Type InstallScript Description Updates the progress bar for a certain amount of cost that has been spent by an event external to the installation. Updates the progress bar for a certain amount of uninstallation cost that has been spent by an event external to the installation. Sets the current setup type to the standard setup type specified by nSetupType. Calculates the total size, in bytes, of selected features and subfeatures.

FeatureSpendUninstallCost

InstallScript

FeatureStandardSetupTypeS InstallScript, et InstallScript MSI FeatureTotalSize InstallScript, InstallScript MSI InstallScript, InstallScript MSI (if the InstallScript user interface (UI) style is the traditional style, which uses the InstallScript engine as an external UI handler)

FeatureTransferData

Important: This function does not apply to InstallScript MSI projects in which the InstallScript UI style is the new style (which uses the InstallScript engine as an embedded UI handler). To learn more, see Using the InstallScript Engine as an External vs. Embedded UI Handler for InstallScript MSI Installations. In an event-based script, installs or uninstalls features appropriately based on their selection state and whether they are currently installed.

FeatureUpdate

InstallScript

Configures the installation so that the next call to FeatureTransferData or FeatureMoveData reinstalls all features that are already installed. Validates the password of the file media library or of a specified feature. Displays a dialog that enables end users to select one of the three standard setup types: Typical, Compact, or Custom. Displays a dialog that enables the end user to select one of the two standard setup types: Typical or Custom. Displays a dialog that enables the end user to select the setup type when you specify setup types beyond Complete and Custom.

FeatureValidate

InstallScript

SdSetupType

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript MSI

SdSetupType2

SdSetupTypeEx

Script-Created Feature Set vs. File Media Library

You can create features at run time by calling the FeatureAddItem function in your setup script. These script-created features reside only in memory and have no direct connection to a file media library. Unlike the information stored in a file media library, script-created features are notand cannot be directly associated with components or a setup type.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

399

Chapter 10: Functions Feature Functions

However, script-created features provide a convenient way of displaying feature-like options for the end user. After the end user makes feature selections in feature dialogs, you can test the script-created features' selection status and use the result as the basis for carrying out some action. For example, you might want to install files with XCopyFile or VerUpdateFile, select features in the file media library, or create or edit a file.

Building a Script-Created Feature

To build a new script-created feature, call the FeatureAddItem function. Then, set and access properties for the script-created feature using the InstallScript feature functions much as you would for features in a file media library (exceptions noted below).

Referring to Script-Created Feature Sets

Script-created features are often referred to collectively as a "script-created feature set." The reason is that they are often handled just like file media library features by feature functions. You must treat all features as a set when you pass their media name to the feature functions.

Note: You create the media name in the first parameter of FeatureAddItem. Use this value when you create features and subfeatures as part of the same "script-created feature set" and when you refer to existing script-created features in your script.

Using Feature Functions

Since the two types of features are so different, you call some of the feature functions differently depending on whether you are working with a script-created feature or a feature in a file media library. File Media Library and Script-Created Feature Set Functions These functions can be used on both a feature in a file media library or on a script-created feature:

FeatureGetData FeatureSetData

File Media Library Functions

These functions work only with features in a file media library, but not with script-created features:

FeatureCompareSizeRequired FeatureFilterLanguage FeatureFilterOS FeatureSetTarget FeatureSetupTypeEnum FeatureSetupTypeGetData FeatureSetupTypeSet FeatureTransferData

400

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions File and Folder Functions

Script-Created Feature Set Function

The FeatureAddItem function works exclusively with script-created feature sets.

File Media Library

The file media library contains your products files and all the information that you entered in the InstallShield interface about your installations component, feature, and setup type settings. The file media library is created when you create a release for your project. It is defined by Data1.hdr, the InstallScript header file. It also has a media name, the default value of which is contained in the MEDIA system variable. You can set and access information in your file media library using the InstallScript feature functions.

Note: Some InstallScript feature functions are specifically reserved for use with script-created features.

File and Folder Functions

File and folder functions provide a comprehensive way to work with text files, binary files, and folders. Many of the functions use the variables TARGETDIR (in InstallScript projects), INSTALLDIR (in InstallScript MSI and Basic MSI projects) and SRCDIR as the paths and accept only file names as parameters. Wild-card characters are also accepted where appropriate.
Table 10-14: File and Folder Functions Function ChangeDirectory CloseFile CopyFile CreateDir CreateFile DeleteDir DeleteFile ExistsDir ExistsDisk FileCompare FileDeleteLine FileGrep Description Makes the specified directory the current directory. Closes an open file. Copies a file from one folder to another. Creates a new folder. Creates a file with the specified file name. Deletes a folder. Deletes a file. Determines whether or not the specified directory exists. Determines whether or not the specified disk exists. Compares one file with another. Deletes a line in a text file. Searches a text file for specified text.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

401

Chapter 10: Functions File and Folder Functions

Table 10-14: File and Folder Functions (cont.) Function FileInsertLine FindAllDirs FindAllFiles FindFile GetFileInfo GetLine GetTempFileNameIS Description Inserts a line in a text file. Finds all subfolders under the specified folder. Finds all files in the specified folder and its subfolders that match a file specification. Finds the first file in the specified folder that matches a file specification. Retrieves a file's attributes, date, time, and size. Retrieves a line of text from an open file. Calls the Windows API GetTempFileName to create a temporary file and perform related actions. Note that unlike GetTempFileName, GetTempFileNameIS creates the folder specified by szPathName if it does not already exist. Provides file and path checking services, searches for a math coprocessor, tests for administrator privileges, determines whether a particular version of the .NET Framework or a language pack is present on the target system, determines whether Microsoft Windows is running from a shared copy on a network, and more. Opens an existing file. Sets the mode in which files will be opened with the OpenFile function. Reads the specified number of bytes from a binary file. Renames a file. Positions the file pointer in a binary file. Sets the attributes, date, and time of a file. Sets permissions for a file, a folder, or a registry key. The file, folder, or registry key can be installed as part of your installation, or it can be already present on the target system. Writes a specified number of bytes to a binary file at the current file pointer location. Writes a string to a text file. Copies one or more files from a source folder to a target folder, including subfolders if specified.

Is

OpenFile OpenFileMode ReadBytes RenameFile SeekBytes SetFileInfo SetObjectPermissions

WriteBytes WriteLine XCopyFile

402

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions FlexNet Connect Functions

Related Function
Table 10-15: Related Function Function SelectDir Description Presents a dialog that enables end users to select a folder. SelectDir creates the folder if it does not exist.

FlexNet Connect Functions

A number of built-in InstallScript functions support FlexNet Connect, which was previously called Update Service.
Table 10-16: FlexNet Connect Functions Function GetUpdateStatus Project Type Basic MSI, InstallScript MSI, InstallScript Basic MSI, InstallScript MSI, InstallScript Basic MSI, InstallScript MSI, InstallScript Description This function is obsolete.

GetUpdateStatusReboot

This function is obsolete.

SdFinishUpdate

Displays a dialog that indicates that the installation is complete. The dialog includes the option to check for application updates. SdFinishUpdateEx supersedes this function.

Note: SdFinishUpdate does not check for updates; to check for updates, add FlexNet Connect API calls in your InstallScript code. For more information, see the FlexNet Connect SDK documentation. SdFinishUpdateEx Basic MSI, InstallScript MSI, InstallScript Displays a dialog that indicates that the installation is complete. The dialog includes the option to check for application updates.

Note: SdFinishUpdateEx does not check for updates; to check for updates, add FlexNet Connect API calls in your InstallScript code. For more information, see the FlexNet Connect SDK documentation.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

403

Chapter 10: Functions FlexNet Connect Functions

Table 10-16: FlexNet Connect Functions (cont.) Function SdFinishUpdateReboot Project Type Basic MSI, InstallScript MSI, InstallScript Description Displays a dialog that indicates that the installation is complete. The dialog gives the end user the option to restart the system and to check for application updates.

Note: SdFinishUpdateReboot does not check for updates; to check for updates, add FlexNet Connect API calls in your InstallScript code. For more information, see the FlexNet Connect SDK documentation. SetUpdateStatus Basic MSI, InstallScript MSI, InstallScript Basic MSI, InstallScript MSI, InstallScript InstallScript This function is obsolete.

SetUpdateStatusReboot

This function is obsolete.

UpdateServiceCheckForUpdate s

This function is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

UpdateServiceCreateShortcut

InstallScript

This function is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

UpdateServiceEnableUpdateMa nagerInstall

InstallScript

This function is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

UpdateServiceGetAgentTarget

InstallScript

This function is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

UpdateServiceOnEnabledState Change

InstallScript

This function is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

UpdateServiceRegisterProduct

InstallScript

This function is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

UpdateServiceRegisterProduct Ex

InstallScript

This function is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

404

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Information Functions

Table 10-16: FlexNet Connect Functions (cont.) Function UpdateServiceSetHost Project Type InstallScript Description This function is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base. UpdateServiceSetLanguage InstallScript This function is obsolete. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Information Functions
The following information functions provide data about resources that are available in the operating environment: disk space, memory, and operating mode.
Table 10-17: Information Functions Function GetDiskInfo GetDiskSpace GetDiskSpaceEx GetEnvVar GetExtendedErrInfo GetExtents GetMemFree GetSystemInfo GetTrueTypeFontFileInfo GetValidDrivesList GetWindowHandle Is Description Gets information about a specified disk drive. Returns the number of bytes available (unused) on the specified disk (up to 2 gigabytes). Returns the amount of free space on a disk in bytes, kilobytes, megabytes, or gigabytes. Returns the current value of an environment variable. Returns the error information that was set by SetExtendedErrInfo. Returns the dimensions of the screen. This function is obsolete and should not be used. Retrieves system information. Returns information about a particular TrueType font file. Returns a listing of all available drives on the target system. Returns the handle of the main installation window. Provides file and path checking services, searches for a math coprocessor, tests for administrator privileges, determines whether a particular version of the .NET Framework or a language pack is present on the target system, determines whether Microsoft Windows is running from a shared copy on a network, and more. Sets error information, which can be retrieved by GetExtendedErrInfo. Sets the values of the system variables IFX_COMPANY_NAME, IFX_PRODUCT_NAME, IFX_PRODUCT_VERSION, and IFX_PRODUCT_KEY.

SetExtendedErrInfo SetInstallationInfo

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

405

Chapter 10: Functions Initialization File Functions

Initialization File Functions

Initialization file functions obtain information from and copy information to the initialization and profile files. An initialization file is a special ASCII file that contains key name-value pairs. The key name-value pairs represent run-time options for applications. You can also access and update private initialization file and system initialization files. The following list briefly describes each initialization file function.
Table 10-18: Initialization File Functions Function AddProfString GetProfInt GetProfString GetProfStringList ReplaceProfString WriteProfInt WriteProfString Description Adds a non-unique key to a section of the .ini file. Returns an integer from an .ini file. Returns a string from an .ini file. Retrieves lists of key names and string values from an .ini file. Replaces a string in a profile ( .ini) file. Writes a string with an integer value to an .ini file. Writes a string to an .ini file.

Related Function
Table 10-19: Related Function Function SdShowFileMods Description Creates a dialog displaying proposed file changes and offering options on how to proceed.

List Processing Functions

Lists are used to store groups of related information. In InstallScript, there are two types of lists: string lists and number lists. Two sets of functions are provided to work with lists, one for each list type. List functions that end with "Item" operate with number lists. List functions that end with "String" operate with string lists. You cannot use number list functions on string lists and vice versa. Below are the functions to implement lists in a setup script.
Table 10-20: List Processing Functions Function ListAddItem ListAddString Description Adds an item to a list. Adds a string to a list.

406

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Log File Functions

Table 10-20: List Processing Functions (cont.) Function ListCount ListCreate ListCurrentItem ListCurrentString ListDeleteItem ListDeleteString ListDestroy ListFindItem ListFindKeyValueString Description Returns the number of string or numeric elements in a specified list. Creates a new string or number list. Returns the current item in a list. Returns the current string in a list. Deletes the current item in a list. Deletes the current string in a list. Destroys a list. Makes the specified item the current item in a numeric list. Searches a string or number list for a specified value. It returns a value from an additional list that corresponds with the position of the found string in the first list. Makes the specified item the current item in a string list. Retrieves the first element from a number list. Retrieves the first string from a string list. Retrieves the element after the current element from a number list. Retrieves the element after the current element from a string list. Reads a text file into a list. Sets the current element of a number list. Sets the current element of a string list. Uses an index to set the current element of a list. Indicates whether the specified list is valid. Indicates whether the specified list is valid and is of the specified type. Writes a string list to a file. Writes or appends a string list to a text file as Unicode or ANSI, depending on the constants that you provide for the nOptions parameter.

ListFindString ListGetFirstItem ListGetFirstString ListGetNextItem ListGetNextString ListReadFromFile ListSetCurrentItem ListSetCurrentString ListSetIndex ListValid ListValidType ListWriteToFile ListWriteToFileEx

Log File Functions

Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

407

Chapter 10: Functions Long File Name Functions

Log file functions obtain information from and copy information to the custom logging section of the log file. Custom log file entries do not affect maintenance or uninstallation of the application unless you add code to the script to read custom values and perform actions based on those values. The log file functions cannot read data from or write data to the maintenance/uninstallation section of the log file (that is, the section where the setup automatically writes data, such as the files that are installed and the registry entries that are created, and from which it automatically reads data during maintenance or uninstallation). The following list briefly describes each log file function.
Table 10-21: Log File Functions Function LogReadCustomNumber LogReadCustomString LogWriteCustomNumber LogWriteCustomString Description Reads numeric data from the log file's custom logging section. Reads string data from the log file's custom logging section. Writes numeric data to the log file's custom logging section. Writes string data to the log file's custom logging section.

Long File Name Functions

The following functions create long file names from short file names, convert short file names to long file names, and place double quotation marks around long file names so that operating systems that handle long file names can recognize them.
Table 10-22: Log File Name Functions Function LongPathFromShortPath LongPathToQuote LongPathToShortPath Description Creates a long file name from a short file name. Inserts or removes double quotation marks around a long file name. Creates a short file name from a long file name.

Miscellaneous Functions
The following functions serve various purposes, such as low-level hardware interface, feature creation and manipulation, and user output.
Table 10-23: Miscellaneous Functions Function Do DoInstall FormatMessage Description Executes the currently defined EXIT and HELP handlers. Launches another InstallShield installation. Returns a string error message for a large negative error code.

408

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Object Functions

Table 10-23: Miscellaneous Functions (cont.) Function Handler HandlerEx ISCompareServicePack Description This function is obsolete. Use HandlerEx instead. Specifies a label to branch to in response to exit and help events. Compares the Service Pack number installed on the target OS to a specified Service Pack number. Checks whether a variable of type VARIANT has been initialized. Produces a standard warning beep. Resizes an InstallScript array. Sends a Windows message to another window or application. Sets permissions for a file, a folder, or a registry key. Returns the size of an InstallScript array. Returns a formatted string composed of one or more character, numeric, or string values. Writes a message directly to the Windows Installer log file. Streams a binary key with a file. Reboots the computer. Initializes or reinitializes internal lists used by the VarSave and VarRestore functions. Calling this function effectively clears any information stored by previous VarSave calls and not yet used by subsequent VarRestore functions. Restores the values of the system variables SRCDIR, TARGETDIR (in InstallScript projects), and INSTALLDIR (in Basic MSI and InstallScript projects) that were saved by the last call to VarSave. Saves the current value of the system variables SRCDIR, TARGETDIR (in InstallScript projects), and INSTALLDIR (in Basic MSI and InstallScript projects).

IsEmpty MessageBeep Resize SendMessage SetObjectPermissions SizeOf Sprintf

SprintfMsiLog StreamFileFromBinary System VarInit

VarRestore

VarSave

Object Functions
The object functions are available to assist you with initializing objects, as well as obtaining and setting status information for objects.
Table 10-24: Object Functions Function CoCreateObject Description Initializes a COM object and returns a reference that can be assigned to a variable of type OBJECT by using the set keyword.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

409

Chapter 10: Functions Path Buffer Functions

Table 10-24: Object Functions (cont.) Function CoCreateObjectDotNet Description The CoCreateObjectDotNet function has been deprecated. Calling this function is the same as calling the DotNetCoCreateObject function with a null string ("") for the szAppDomain parameter. For more information, see DotNetCoCreateObject. CoGetObject Returns a reference to the specified COM object (as Visual Basic's GetObject function does); that reference can be assigned to a variable of type OBJECT by using the set keyword. Calls functions in .NET assemblies without the assembly being registered for COM interoperability. This function, unlike the CoCreateObjectDotNet function, lets you specify the .NET application domain in which the .NET assemblies should be loaded and run.

DotNetCoCreateObject

DotNetUnloadAppDomain Unloads the specified .NET application domain and releases any assemblies that are currently loaded into the specified application domain. GetObject Initializes an object and returns a reference that can be assigned to a variable of type OBJECT by using the set keyword. Finds the installation's or object's subobject that is specified by nIndex and returns a reference that can be assigned to a variable of type OBJECT by using the set keyword. Returns the number of subobjects contained by the object or installation. Retrieves the current status of the object; that is, the current value of Status.Number. Checks whether a variable of type OBJECT has been assigned a reference to a valid object, using the CreateObject or GetObject functions. Called in an object script to set the object's Status.Number and Status.Description properties. Called in an object script to set the object's status properties.

GetObjectByIndex

GetObjectCount GetStatus IsObject

SetStatus

SetStatusEx

Path Buffer Functions

The path buffer functions are available to assist you in working with strings that contain search paths. The path string functions work on a unique temporary string variable known as the path buffer. The path buffer is defined internally within InstallShieldall the path string functions act on the contents of the path buffer.

410

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Registry Functions

Path functions assist you in manipulating and building path strings. After you have created a path string, you can save it to the appropriate file.
Table 10-25: Path Buffer Functions Function PathAdd PathDelete PathFind Description Adds a path to the search path in the path buffer. Deletes a directory from the path buffer. Finds a specific path in the path buffer or any path that includes a specified name. Retrieves the current value of the path buffer. Rearranges the path buffer. Assigns a value to the path buffer.

PathGet PathMove PathSet

Registry Functions
The following functions allow you to access the registry, read, create and delete registry keys, and establish registry-related parameters for uninstallation.
Table 10-26: Registry Functions Function CreateInstallationInfo Description Creates an application information key and a per application paths key for the program you are installing. Creates one or all of the sets of registry entries specified in the Resources pane's Registry Entries folder. This function is obsolete. If you want to check whether a file is locked during uninstallation, write script code that calls the Is function with the FILE_LOCKED constant for the nIsFlag parameter and that responds as needed. DeinstallStart InstallationInfo MaintenanceStart This function is obsolete. This function is obsolete. Use the CreateInstallationInfo function instead. Enables uninstallation functionality by creating the <PRODUCT_GUID> registry keys. Opens a connection to a remote registry. Copies the registry keys and values under the key specified by szSourceKey to the key specified by szTargetKey.

CreateRegistrySet

DeinstallSetReference

RegDBConnectRegistry RegDBCopyKeys

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

411

Chapter 10: Functions Registry Functions

Table 10-26: Registry Functions (cont.) Function RegDBCopyValues Description Copies the registry values under the key specified by szSourceKey to the key specified by szTargetKey. Creates a key in the registry. Also enables you to associate a class object with a registry key (advanced users only). Deletes values under the per application paths key or the application uninstallation key, depending on the value of nItem. Deletes the specified key from the registry. Deletes a value from a specified registry key. Closes the connection to a remote registry. Retrieves a value from under the application information key. Returns the root key that is used by the general registry-related functions. Retrieves values under the per-application paths key or the application uninstallation key. Retrieves a value from under a key in the registry. Gets the registered command line for the uninstallation that is specified by szUninstallKey and returns the command line in svUninstCmdLine. Checks that a registry key exists. Queries a key for its subkeys and value names. Returns the number of subkeys or values under a specified key. Returns the number of strings contained in the multistring value specified by a certain value under a specified key. Sets a value under the application information key. Sets the root key. Assign values under the per application paths key or the application uninstallation key. Sets registry entries. Specifies company and product information for use by CreateInstallationInfo. Sets permissions for a file, a folder, or a registry key.

RegDBCreateKeyEx

RegDBDeleteItem

RegDBDeleteKey RegDBDeleteValue RegDBDisConnectRegistry RegDBGetAppInfo RegDBGetDefaultRoot

RegDBGetItem

RegDBGetKeyValueEx RegDBGetUninstCmdLine

RegDBKeyExist RegDBQueryKey RegDBQueryKeyCount RegDBQueryStringMultiStringCount

RegDBSetAppInfo RegDBSetDefaultRoot RegDBSetItem

RegDBSetKeyValueEx SetInstallationInfo

SetObjectPermissions

412

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Shared and Locked File Functions

Shared and Locked File Functions

A shared file is a file, such as a .dll, .vbx, or driver that can be used by more than one application. InstallShield protects shared files from being removed during uninstallation. Functions using the SHAREDFILE option consider all files to be shared files, and therefore increment registry reference counters for all files involved. InstallShield increments the registry reference counter by one if the file exists in the target directory and it has a reference count greater than 0. If the shared file does not exist in the target directory and it has no reference counter, InstallShield creates the counter and sets it to 1. If the shared file already exists in the target directory but has no reference counter, InstallShield creates the counter and initializes it to 2 as a precaution against accidental removal during uninstallation. Shared files should not be updated when they are locked. Some InstallShield file transfer functions use the SHAREDFILE option so that .dll and .exe files that are locked during file transfer can be recorded and updated when Windows or the system restarts. InstallShield considers a file locked when it is in use by an application or the system. Locked files are not necessarily shared files. The following functions handle shared or locked files:
Table 10-27: Shared and Locked File Functions Function Is Description Provides file and path checking services, searches for a math coprocessor, tests for administrator privileges, determines whether a particular version of the .NET Framework or a language pack is present on the target system, determines whether Microsoft Windows is running from a shared copy on a network, and more. Presents a dialog with which the end user can choose to restart Windows or reboot the computer. Presents a dialog stating that the installation is complete and allowing the end user to choose to restart Windows or reboot the computer. Sets permissions for a file, a folder, or a registry key. Updates files using version resource information. Allows updating of locked .dll and .exe files and incrementing of registry reference counters for all files involved. Copies files and subdirectories from the source directory to the target directory. Combines shared file and locked file handling by causing XCopyFile to treat all files as shared, and to record locked .dll and .exe files for update when Windows or the system restarts.

RebootDialog

SdFinishReboot

SetObjectPermissions VerUpdateFile

XCopyFile

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

413

Chapter 10: Functions Shell Functions

Shell Functions
Shell functions create program folders, delete existing program folders, and add items to existing program folders. At the end of the setup, add the application to the appropriate program folder to allow the user to access your software immediately. The following functions also support various icon options.
Table 10-28: Shell Functions Function AddFolderIcon Description Adds a shortcut or program folder to locations such as the desktop or the Programs menu on the Start menu. Creates a program folder. Removes an icon or shortcut from a program folder. Removes a program folder from the target system. Retrieves all subfolder names and shortcuts in the specified folder. Sets the value of the ALLUSERS system variable. Returns information about a specified program item or subfolder. Returns the name of the current shell manager. Replaces an icon in a specified folder. Presents a dialog that enables end users to select a folder from a list of program folders. Displays the specified program folder.

CreateProgramFolder DeleteFolderIcon DeleteProgramFolder GetFolderNameList ProgDefGroupType QueryProgItem QueryShellMgr ReplaceFolderIcon SelectFolder

ShowProgramFolder

Special Registry-Related Functions

The special registry-related functions are designed to make it easier for script writers to set up the minimum required registry keys and values. The special registry-related functions work only with the per application paths key, the application uninstallation key, or the application information key, as shown below. Refer to the individual function descriptions for more details.

Per Application Paths Key

<root key>\Software\Microsoft\Windows\CurrentVersion\App Paths\<per application paths key>

414

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Special Registry-Related Functions

This key is referred to as the per application paths key, or App Paths key. The per application paths key stores path information enabling Windows to find your application's executable files. The root key is HKEY_CURRENT_USER if the ALLUSERS system variable is FALSE or you have called ProgDefGroupType(PERSONAL), or HKEY_LOCAL_MACHINE otherwise.
Table 10-29: Per Application Paths Key Function CreateInstallationInfo Description Uses the name of the application executable file to prepare for the creation of the per application paths key. The key is not created until RegDBSetItem is called (see below). If you use an event-based script, the CreateInstallationInfo function is called by the default OnMoveData event handler code. RegDBDeleteItem Deletes the per application paths key and the value of [Path] or of [DefaultPath] under that key. Retrieves the value of [Path] or of [DefaultPath] under the per applications path key. Results in the creation of the per application paths key, and sets the value of [Path] or of [DefaultPath] under that key.

RegDBGetItem

RegDBSetItem

Application Uninstallation Key

<rootkey>\Software\Microsoft\Windows\CurrentVersion\Uninstall\<INSTANCE_GUID>

This key is referred to as the application uninstallation key. The application uninstallation key stores information enabling uninstallation functionality. The root key is HKEY_CURRENT_USER if the ALLUSERS system variable is FALSE or you have called ProgDefGroupType(PERSONAL), or HKEY_LOCAL_MACHINE otherwise.
Table 10-30: Application Uninstallation Key Function MaintenanceStart Description Creates the application uninstallation key and sets the [UninstallString], [DisplayName] (the name displayed in Add or Remove Programs), and [LogFile] values under that key. In an event-based script, MaintenanceStart is called in the default OnMoveData event handler code. RegDBDeleteItem Deletes the value of [DisplayName] (the name displayed in Add or Remove Programs) under the application uninstallation key. Retrieves the value of [DisplayName] under the application uninstallation key. Sets the value of [DisplayName] (the name displayed in Add or Remove Programs) under the application uninstallation key. This value is also set by MaintenanceStart (which, if you use an eventbased script, is called in the default OnMoveData event handler code).

RegDBGetItem

RegDBSetItem

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

415

Chapter 10: Functions SQL Functions

Application Information Key

<root key>\Software\<company key>\<product key>\<version key>

This key is referred to as the application information key. Your installation should create an application information key for each application it installs. The application information key stores information about the application. The root key is HKEY_CURRENT_USER if the ALLUSERS system variable is FALSE or you have called ProgDefGroupType(PERSONAL), or HKEY_LOCAL_MACHINE otherwise.
Table 10-31: Application Information Key Function CreateInstallationInfo Description Uses the company name, product name, and product version number to create the application information key. No values are set under the key until you call the RegDBSetAppInfo function (see below). If you use an event-based script, the CreateInstallationInfo function is called by the default OnMoveData event handler code. RegDBGetAppInfo RegDBSetAppInfo Retrieves a value from under the application information key. Sets a value under the application information key.

SQL Functions
The SQL functions enable you to perform tasks such as connect to a catalog, create SQL-related dialogs, and obtain SQL run-time errors.

Tip: For information on SQL support and SQL-related InstallScript functions, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects. Table 10-32: SQL Functions Function SQLBrowse Project Type InstallScript, InstallScript MSI Description Creates a dialog that enables the end user to bring up a list of all SQL Servers available on the network. SQLBrowse2 supersedes this function. SQLBrowse2 InstallScript, InstallScript MSI Creates a dialog that lets an end user display a list of all database servers that are available on the network for the database technologies specified for a connection. Creates a dialog that lets the end user display a list of all database catalogs available on the specified database server. This function calls SQLRTGetDatabases, which uses SQLRT.dll for InstallScript projects and ISSQLSRV.dll for InstallScript MSI projects.

SQLDatabaseBrowse

InstallScript, InstallScript MSI

416

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions SQL Functions

Table 10-32: SQL Functions (cont.) Function SQLRTComponentInstall Project Type InstallScript Description Executes the SQL script that is associated with the specified component if the script is scheduled to run during installation. Executes the SQL script that is associated with the specified component if the script is scheduled to run during uninstallation. Establishes a connection using the specified credential. SQLRTConnect2 supersedes this function. SQLRTConnect2 InstallScript Establishes a connection. This function must be called before file transfer if the connection is to be used to run scripts during installation. SQLRTConnect2 returns the database server name when it fails to establish the connection. It uses SQLRT.dll so it can be called only after SQLRTInitialize2 has already been called. Establishes a connection to a specific catalog. Executes all of SQL scripts scheduled to run during rollback. Returns the list of components that are associated with SQL scripts that need to be run when batch mode is enabled. For details about batch mode, see Specifying the Order for Running Multiple SQL Scripts That Are Associated with a Connection. SQLRTGetBatchMode SQLRTGetBrowseOption InstallScript InstallScript Returns whether batch mode is enabled or disabled. Returns the current value of the browse option for the SQL Server browse combo box and list box controls, which can display local servers, remote servers, server aliases, or a combination of these types. Retrieves the last error while executing a SQL script that is associated with the component. SQLRTGetComponentScriptError2 supersedes this function. SQLRTGetComponentScriptError2 InstallScript Retrieves the last error while executing a SQL script that is associated with the component. This function takes several parameters (szScriptName, szTechnology, szServer, and szDB) that the SQLRTGetComponentScriptError function does not. SQLRTGetConnectionAuthentication InstallScript, InstallScript MSI Gets the default SQL Server connection authentication type.

SQLRTComponentUninstall

InstallScript

SQLRTConnect

InstallScript

SQLRTConnectDB SQLRTDoRollbackAll

InstallScript InstallScript

SQLRTGetBatchList

InstallScript

SQLRTGetComponentScriptError

InstallScript

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

417

Chapter 10: Functions SQL Functions

Table 10-32: SQL Functions (cont.) Function SQLRTGetConnectionInfo Project Type InstallScript, InstallScript MSI Description Retrieves strings containing the connection information (the default server, database, default user name, and default password). Retrieves a string list of connections that are present in the settings file. Returns a list of database catalogs that are available on the specified database server. Returns the descriptive message of the last error encountered by the SQL run time when a connection is being opened. Returns the text of the last error encountered by the SQL run time. SQLRTGetLastError2 supersedes this function. SQLRTGetLastError2 InstallScript Returns detailed information about the last error encountered by the SQL run time and loads the proper SQL error message. Returns the descriptive message of the last error encountered by the SQL run time when a SQL script is executing. Returns a list of database servers on the network for all database technologies included in the installation. SQLRTGetServers2 supersedes this function. SQLRTGetServers2 InstallScript, InstallScript MSI Returns a list of database servers for the database technologies that are specified for a connection. When szConnection is empty, this function behaves as SQLRTGetServers. Loads the SQLRT.dll and initializes it using the settings file. This function must be the first function called in SQLRT. SQLRTInitialize2 supersedes this function. SQLRTInitialize2 InstallScript, InstallScript MSI Loads the SQLRT.dll file for InstallScript projects and the ISSQLSRV.dll file for InstallScript MSI projects, and it uses the settings file to initialize the .dll file. This function must be the first function called in SQLRT or ISSQLSRV. SQLRTPutConnectionAuthentication InstallScript, InstallScript MSI Sets the default SQL Server connection authentication type.

SQLRTGetConnections

InstallScript, InstallScript MSI InstallScript, InstallScript MSI InstallScript

SQLRTGetDatabases

SQLRTGetErrorMessage

SQLRTGetLastError

InstallScript

SQLRTGetScriptErrorMessage

InstallScript

SQLRTGetServers

InstallScript, InstallScript MSI

SQLRTInitialize

InstallScript

418

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions SQL Functions

Table 10-32: SQL Functions (cont.) Function SQLRTPutConnectionInfo Project Type InstallScript, InstallScript MSI Description Sets the connection information (the default server, default user name, and default password) so that it is available in the future. This is useful in situations when you need to recall what a user previously entered, like use of the Back button. SQLRTPutConnectionInfo2 supersedes this function. SQLRTPutConnectionInfo2 InstallScript, InstallScript MSI Sets the connection information (the default server, default database catalog, default user name, and default password) so that it is available in the future. This is useful in situations when you need to recall what an end user previously entered, like use of the Back button. Tests connections specified in the installation. Specifies whether the SQL Server browse combo box and list box controls should show local servers, remote servers, server aliases, or a combination of these types. Tests all of the connections specified in the installation using the specified credential. SQLRTTestConnection2 supersedes this function. SQLRTTestConnection2 SQLServerLogin InstallScript MSI InstallScript, InstallScript MSI Establishes a connection. Creates a dialog that is used by the script to specify SQL login credentials. These credentials include the login ID and password. Creates a dialog to specify a server to target.

SQLRTServerValidate SQLRTSetBrowseOption

InstallScript MSI InstallScript

SQLRTTestConnection

InstallScript MSI

SQLServerSelect

InstallScript, InstallScript MSI InstallScript, InstallScript MSI

SQLServerSelectLogin

Creates a login dialog that enables the targeted end user to specify which SQL Server should to be used for the current connection, as well as which login credential should be used. The dialog displays a combo box that contains a list of SQL Servers accessed through DSNs. The end user can type a server name in the combo box or click the Browse button next to the combo box; clicking this button displays a list of all SQL Servers that are available on the network. SQLServerSelectLogin2 supersedes this function.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

419

Chapter 10: Functions String Functions

Table 10-32: SQL Functions (cont.) Function SQLServerSelectLogin2 Project Type InstallScript, InstallScript MSI Description Creates a login dialog that is used by the default script. It lets the targeted end user specify which SQL Server should be used for the current connection, as well as which login credential should be used. The dialog displays a combo box that contains a list of SQL Servers accessed through DSNs. The end user can type a server name in the combo box or click the Browse button next to the Server Name combo box; clicking this button displays a list of all SQL Servers that are available on the network. This function also optionally shows the connection name that is associated with the connection information. In addition, it optionally enables end users to specify which database catalog should be used for the current connection. SQLServerSelectLoginEx InstallScript, InstallScript MSI Creates a login dialog that is used by the default script. It lets the targeted end user specify which SQL Server should be used for the current connection, as well as which login credential should be used. The dialog displays a combo box that contains a list of SQL Servers accessed through DSNs. The end user can type a server name in the combo box or click the Browse button next to the Server Name combo box; clicking this button displays a list of all SQL Servers that are available on the network. This function also shows the connection name that is associated with the connection information. SQLServerSelectLogin2 supersedes this function.

String Functions
The string functions provide the ability to manipulate string variables and literals. String functions behave similarly to the standard C language functions. The return values also follow the C language convention.
Table 10-33: String Functions Function CopyBytes GetCArrayFromISArray Description Copies a specified number of bytes from one string to another. Returns a pointer to an array of pointers that point to the actual data of the specified array. This function does not allocate any additional memory, but it returns a pointer to the data in the existing array.

420

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions String Functions

Table 10-33: String Functions (cont.) Function GetCHARArrayFromISStringArray Description Returns a pointer to an array of pointers to ANSI character strings that corresponds to the wide character strings that are contained in the specified array. Deletes the drive designation from a path or fully qualified file name. Retrieves the disk drive designation from a path or fully qualified file name. Converts a number to a string. Retrieves the drive, path, file name, or extension from a path. Adds a trailing backslash to a path specification if it does not already have one. Compares one string to another. Returns the appropriate display string for the InstallScript size unit constant that is specified. Finds a string in another string. Determines whether the string passed in the parameter szFindMe is found within the string passed in the parameter szString; the function begins its search at the location specified by nStart. Gets a token from a string based on specified delimiters. Returns the number of bytes in a string. Returns the number of characters in a string. Extracts list items from a specified string list and places them into the string that is specified by svString. Removes the last backslash in a path string. Searches svResult, beginning at the location specified by nStart, and replaces all found instances of szFind with szReplace. Returns a substring from a string. Returns the first character of a string as data of type CHAR. Converts all alphabetic characters in string to lowercase. Converts a string to a number. Converts a string to a numberfor example, 0x1A to 26. Converts all alphabetic characters in string to uppercase.

GetDir GetDisk

NumToStr ParsePath StrAddLastSlash

StrCompare StrConvertSizeUnit

StrFind StrFindEx

StrGetTokens StrLength StrLengthChars StrPutTokens

StrRemoveLastSlash StrReplace

StrSub STRTOCHAR StrToLower StrToNum StrToNumHex StrToUpper

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

421

Chapter 10: Functions Text Substitutions

Table 10-33: String Functions (cont.) Function StrTrim Description Removes the leading and trailing spaces and tabs from a string.

Text Substitutions
Project: This information applies to InstallScript projects.

Text substitution consists of associating a string with another stringfor example, associating "<MYTEXTSUB>" with "My Text Sub Value"and of replacing the former string with the latter in other stringsfor example, changing "This string demonstrates text substitution <MYTEXTSUB>" to "This string demonstrates text substitution My Text Sub Value". A text-substitution association can be either globalthat is, applying to the scripts of the main installation and any included objectsor localthat is, applying only to the script file in which it occurs, any script files that are included in that script by using the #include preprocessor directive, and any script files in which that script is included. A local text-substitution association that is defined in an object script applies only to that object, not to the main installation or any other objects that are included in the installation; a local text-substitution association that is defined in the main installation script applies only to the main installation, not to any objects that are included in the installation. A text-substitution association can be embedded in another text-substitution association; for example, "<MYTEXTSUB1>" can be associated with "My Text Sub 1 Value" and "<MYTEXTSUB2>" with "Text Sub <MYTEXTSUB1> Embedded". InstallScript includes the following functions for using text substitutions:
Table 10-34: Text Substitutions Functions Function TextSubGetValue TextSubParseTextSub TextSubSetValue TextSubSubstitute Description Retrieves the text-substitution string that is associated with the specified string. Locates the first text substitution in the specified string. Creates a text-substitution association between the specified strings. Performs text substitution on the specified string variable.

422

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Uninstallation Functions

Uninstallation Functions
The following functions perform services required for the uninstallation and/or maintenance setup of an installed application.
Table 10-35: Uninstallation Functions Function FeatureGetTotalCost Description Determines the total space required for the feature installations and uninstallations that have been specified. Performs the feature installations and uninstallations that have been specified. Creates registry keys based on a company name, product name, and product version number. Retrieves values under the per application paths key or the application uninstallation key. Assign values under the per application paths key or the application uninstallation key.

FeatureTransferData

InstallationInfo

RegDBGetItem

RegDBSetItem

User Interface Functions

User interface functions allow you to customize certain error messages and titles of error boxes. However, several internal error messages that may be encountered during the development of the setup cannot be modified using user interface functions.
Table 10-36: Visual Interface Functions Function Disable Enable FindWindow PlaceBitmap PlaceWindow PlayMMedia Description Disables the display of a user interface object. Enables the display of a user interface object. Retrieves the handle to a window. Inserts an image into the installation window. Sets the position of user interface objects. Plays an Adobe Flash application file (.swf), an AVI file, or a sound file (MIDI or WAVE). Returns a custom color value based on the specified red, green and blue values. Changes the color of various user-interface elements. Creates custom dialog titles.
ISP-1800-RG00 423

RGB

SetColor SetDialogTitle
InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Version-Checking Functions

Table 10-36: Visual Interface Functions (cont.) Function SetDisplayEffect SetErrorMsg Description Sets the display effect for bitmap and metafile images. When a disk error occurs, this function sets the corresponding error message that is displayed by the EnterDiskError function. When a disk error occurs, this function sets the title bar for the error message that is displayed by the EnterDiskError function. Sets the font type and style. Sets the text for the status window and sets the initial percentage completed value that is displayed in the progress indicator. Sets the text and color of the title in the main window. Specifies the size of most user interface objects. Sets the percent complete to display in the progress indicator after the next file transfer operation.

SetErrorTitle

SetFont SetStatusWindow

SetTitle SizeWindow StatusUpdate

Version-Checking Functions
The following functions allow you to access version information present on Windows systems. In order to use the functions, you need to know background information about version resources. Review the Microsoft Windows Programmers Reference, Volume 4: Resources manual to gain a better understanding of the version resource. The descriptions of the functions assume that you are completely familiar with the concepts behind the version resource. The following functions obtain a specific files version, find a file and get its version, or search for an existing file and try to install a newer version of the file. The functions work with either compressed or uncompressed files.
Table 10-37: Version-Checking Functions Function VerCompare VerFindFileVersion VerGetFileVersion VerSearchAndUpdateFile Description Compares two strings containing version information. Searches for the specified file and retrieves its version and location. Retrieves the version of a specified file. Replaces an existing file with a more recent version. If the specified file does not exist, the more recent version is installed. Replaces an existing file with a more recent version. If the specified file does not exist, the more recent version is installed.

VerUpdateFile

424

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Windows Installer Functions

Windows Installer Functions

Windows Installer functions, or APIs, are functions exported by the Windows Installer engine. They enable you to query and temporarily manipulate tables of a running installation. One common use for adding temporary records to a running database is to populate user-interface elements with data not available until run time. For example, you can use Windows Installer APIs to populate a ListBox control in dialog with a list of mapped network drives, user accounts, directory names, or other data that can be discovered only while an installation is running on a particular target system. For more information about any Windows Installer function, see the Windows Installer Help.

Windows Installer API Functions

You can call Windows Installer API functions from the main script and from within an InstallScript custom action. InstallScript supports these Windows Installer API functions:

Note: Most Windows Installer API functions take a handle to the currently running database as an argument. For an InstallScript custom action, the database handle is the HWND argument passed to the custom action. In an event-handler function, you can use the global variable ISMSI_HANDLE, which stores the handle to the running .msi database. Table 10-38: Windows Installer API Functions MsiApplyPatch MsiCloseHandle MsiCreateTransformSummaryInfo MsiDatabaseApplyTransform MsiDatabaseExport MsiDatabaseGenerateTransform MsiDatabaseGetPrimaryKeys MsiDatabaseImport MsiDatabaseIsTablePersistent MsiDatabaseMerge MsiDatabaseOpenView MsiDoAction MsiEnumComponentCosts MsiEvaluateCondition MsiGetLanguage MsiGetLastErrorRecord MsiGetMode MsiGetProperty MsiGetSourcePath MsiGetSummaryInformation MsiGetTargetPath MsiInstallProduct MsiOpenDatabase MsiOpenPackage MsiPreviewBillboard MsiPreviewDialog MsiProcessMessage MsiRecordClearData MsiRecordSetInteger MsiRecordSetStream MsiRecordSetString MsiSequence MsiSetComponentState MsiSetFeatureAttributes MsiSetFeatureState MsiSetInstallLevel MsiSetMode MsiSetProperty MsiSetTargetPath MsiSummaryInfoGetProperty MsiSummaryInfoSetProperty MsiVerifyDiskSpace

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

425

Chapter 10: Functions Windows Installer Functions

Table 10-38: Windows Installer API Functions (cont.) MsiFormatRecord MsiGetActiveDatabase MsiGetComponentState MsiGetFeatureCost MsiGetFeatureState MsiGetFeatureValidStates MsiRecordDataSize MsiRecordGetFieldCount MsiRecordGetInteger MsiRecordGetString MsiRecordIsNull MsiRecordReadStream MsiViewClose MsiViewExecute MsiViewFetch MsiViewGetColumnInfo MsiViewGetError

Windows Installer API Functions by Category

This section includes the function signatures for the Windows Installer API functions available in InstallScript. See the Windows Installer Help for information about a function's usage, parameters, return values, and sequencing restrictions.

426

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Windows Installer Functions

MSI Property and Mode Functions

Table 10-39: MSI Property and Mode Functions Function prototype INT MsiSetProperty(HWND, BYVAL STRING, BYVAL STRING); prototype INT MsiGetProductInfo(BYVAL STRING, BYVAL STRING, BYVAL STRING, BYREF INT); prototype INT MsiGetProperty(HWND, BYVAL STRING, BYREF STRING, BYREF INT); prototype INT MsiGetLanguage(HWND); prototype BOOL MsiGetMode(HWND, INT); prototype INT MsiSetMode(HWND, INT, BOOL); Description Sets the value of a Windows Installer property. Creates the property if it does not exist. (For an example, see Getting or Setting Properties.) Returns product information for published and installed products.

Gets the value of a Windows Installer property. Returns a null string ("") if the property does not exist.

Returns the numeric language ID for the running installation. Returns an internal boolean Installer state.

Sets an internal boolean Installer state.

Feature and Component Functions

Table 10-40: Feature and Component Functions Function prototype INT MsiGetFeatureState(HWND, BYVAL STRING, BYREF INT, BYREF INT); prototype INT MsiSetFeatureState(HWND, BYVAL STRING, INT); prototype INT MsiSetFeatureAttributes(HWND, BYVAL STRING, INT); prototype INT MsiGetFeatureValidStates(HWND, BYVAL STRING, BYREF INT); prototype INT MsiGetComponentState(HWND, BYVAL STRING, BYREF INT, BYREF INT); prototype INT MsiSetComponentState(HWND, BYVAL STRING, INT); Description Gets the installation state and action state of a feature.

Sets the installation state of a feature.

Sets the attributes for a feature.

Returns a set of bit flags representing the valid installation states of a feature.

Gets the installation state and action state of a component.

Sets the installation state of a component.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

427

Chapter 10: Functions Windows Installer Functions

Table 10-40: Feature and Component Functions (cont.) Function prototype INT MsiGetFeatureCost(HWND, BYVAL STRING, INT, INT, BYREF INT); prototype INT MsiSetInstallLevel(HWND, INT); Description Returns the disk cost of a feature (in units of 512 bytes), and optionally its parent and child features. Sets the install level for the entire product.

Directory Functions
Table 10-41: Directory Functions Function prototype INT MsiGetSourcePath(HWND, BYVAL STRING, BYREF STRING, BYREF INT); prototype INT MsiGetTargetPath(HWND, BYVAL STRING, BYREF STRING, BYREF INT); prototype INT MsiSetTargetPath(HWND, BYVAL STRING, BYVAL STRING); prototype INT MsiVerifyDiskSpace(HWND); Description Returns the full source path for a directory listed in the Directory table. (The Directory table is exposed in the Direct Editor.)

Returns the full target path for a directory listed in the Directory table.

Sets the full target path for a directory listed in the Directory table.

Verifies if sufficient disk space exists for the current installation.

Database Functions
With the exception of MsiGetActiveDatabase, the first HWND argument in most of these functions is a handle to a specific database view or record.
Table 10-42: Database Functions Function prototype INT MsiEvaluateCondition(HWND); prototype INT MsiGetActiveDatabase(HWND); prototype INT MsiDatabaseApplyTransform(HWND, BYVAL STRING, INT); prototype INT MsiDatabaseExport(HWND, BYVAL STRING, BYVAL STRING, BYVAL STRING); Description Evaluates a conditional expression that contains property names and values. Obtains a handle to the running .msi database, which you can use to open database views. Applies a transform to a database. A transform is a way of recording changes to a database without altering the original database.

Exports an installer table from an open database to a text archive file.

428

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Windows Installer Functions

Table 10-42: Database Functions (cont.) Function prototype INT MsiDatabaseGenerateTransform(HWND, BYVAL STRING, INT, INT); prototype INT MsiDatabaseGetPrimaryKeys(HWND, BYVAL STRING, BYREF HWND); prototype INT MsiDatabaseImport(HWND, BYVAL STRING, BYVAL STRING); prototype INT MsiDatabaseIsTablePersistent(HWND, BYVAL STRING); prototype INT MsiDatabaseMerge(HWND, HWND, BYVAL STRING); prototype INT MsiDatabaseOpenView(HWND, BYVAL STRING, BYREF INT); prototype INT MsiFormatRecord(HWND, HWND, BYREF STRING, BYREF INT); prototype INT MsiViewModify(HWND, INT, HWND); prototype INT MsiOpenDatabase(BYVAL STRING, BYVAL STRING, BYREF HWND); prototype INT MsiViewClose(HWND); prototype INT MsiViewExecute(HWND, HWND); prototype INT MsiViewFetch(HWND, BYREF HWND); prototype INT MsiRecordGetString(HWND, INT, BYREF STRING, BYREF INT); prototype INT MsiRecordSetString(HWND, INT, BYVAL STRING); prototype INT MsiRecordReadStream(HWND, INT, CHAR, POINTER); Description Generates a transform file of differences between two databases. A transform is a way of recording changes to a database without altering the original database. Returns a record containing the names of all the primary key columns for a specified table. This function returns a handle that should be closed using MsiCloseHandle. Imports an installer text archive table into an open database.

Returns an enumeration describing the state of a particular table.

Merges two databases together, allowing duplicate rows.

Prepares a database query, creating a view object.

Formats record field data and properties using a format string.

Modifies a database record. For a running installation, only temporary database changes are allowed. Opens a database file for data access. This function returns a handle that should be closed using MsiCloseHandle. Closes an executed database view. Executes a SQL query.

Fetches a record for the current database view.

Returns the string stored in a specific field of the specified record.

Sets the string stored in a specific field of the specified record.

Returns the string value of a record field.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

429

Chapter 10: Functions Windows Installer Functions

Table 10-42: Database Functions (cont.) Function prototype INT MsiRecordSetStream(HWND, INT, BYVAL BINARY); prototype INT MsiRecordGetInteger(HWND, INT); prototype INT MsiRecordSetInteger(HWND, INT, INT); prototype INT MsiViewGetColumnInfo(HWND, INT, BYREF INT); prototype INT MsiRecordGetFieldCount(HWND); prototype INT MsiCloseHandle(HWND); prototype MsiCloseAllHandles( ); Description Sets a record stream field from a file. Stream data cannot be inserted into temporary fields.

Returns the integer stored in a specific field of the specified record.

Sets the integer stored in a specific field of the specified record.

Returns a record containing database column names or definitions.

Returns the number of fields (columns) in a record.

Closes a database, view, or record handle. Closes all open handles. Provided for diagnostic purposes, and should not be called for general cleanup. Returns an error code for an error generated by MsiViewModify.

prototype INT MsiViewGetError(HWND, BYREF STRING, BYREF INT);

430

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Windows Installer Functions

Summary Information Stream Management Functions

Table 10-43: Summary Information Stream Management Functions Function prototype MsiGetSummaryInformation(HWND, BYVAL STRING, INT, BYREF HWND); prototype INT MsiSummaryInfoGetProperty(HWND, INT, BYREF INT, BYREF INT, POINTER, BYREF STRING, BYREF INT); prototype INT MsiSummaryInfoSetProperty(HWND, INT, INT, INT, POINTER, BYREF STRING); Description Obtains a handle to summary information data for an installer database. This function returns a handle that should be closed using MsiCloseHandle. Gets a single property from the summary information.

Sets a single summary information property.

Miscellaneous Functions
Table 10-44: Miscellaneous Functions Function prototype INT MsiApplyPatch(BYVAL STRING, BYVAL STRING, INT, BYVAL STRING); prototype HWND MsiCreateRecord(INT); Description For each product listed by the patch package as eligible to receive the patch, the MsiApplyPatch function invokes an installation and sets the PATCH property to the path of the patch package. Creates a new record object with the specified number of fields. This function returns a handle that should be closed using MsiCloseHandle. Executes a built-in action, custom action, or user-interface wizard action. Evaluates a conditional expression containing property names and values.

prototype INT MsiDoAction(HWND, BYVAL STRING); prototype INT MsiEvaluateCondition(HWND, BYVAL STRING); prototype INT MsiInstallProduct(BYVAL STRING, BYVAL STRING); prototype INT MsiOpenPackage(BYVAL STRING, BYREF HWND);

Installs or uninstalls a product.

Opens a package for use with the functions that access the product database. The MsiCloseHandle function must be called with the handle when the handle is no longer needed. Displays a billboard within a host control in the displayed dialog. Supplying a null billboard name removes any billboard displayed.

prototype INT MsiPreviewBillboard(HWND, BYVAL STRING, BYVAL STRING); prototype INT MsiPreviewDialog(HWND, BYVAL STRING); prototype int MsiProcessMessage(HWND, int, HWND);

Displays a dialog as modeless and inactive.

Sends an error record to the installer for processing.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

431

Chapter 10: Functions Windows Installer Functions

Table 10-44: Miscellaneous Functions (cont.) Function prototype INT MsiSequence(HWND, BYVAL STRING, INT); Description Executes another action sequence, as described in the specified table.

Windows Installer API Functions Example

/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates several Windows API functions that are used * to access the tables of the .msi database at run time and * add temporary records. * * Note: Before running this script, add a ListBox control to * the ReadyToInstall dialog, and associate the control * with the property LISTBOXPROP. * * This script populates the ListBox control in the ReadyToInstall * dialog with the current values of every property listed in * the Property table. The end user's selection for the ListBox * is stored in LISTBOXPROP. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "ifx.h" // InstallScript custom action entry point export prototype PropDisplay(HWND); function PropDisplay(hInstall) HWND hDB, hViewlist, hRecordlist; HWND hViewprop, hRecordprop; NUMBER nBuffer, r; STRING svPropname, svPropvalue; begin hDB = MsiGetActiveDatabase(hInstall); // open view into ListBox table MsiDatabaseOpenView(hDB, "SELECT * FROM `ListBox` WHERE `Property`='LISTBOXPROP'", hViewlist); MsiViewExecute(hViewlist, NULL); // open view into Property table MsiDatabaseOpenView(hDB, "SELECT * FROM `Property`", hViewprop); MsiViewExecute(hViewprop, NULL); r = 0; // for each Property record, add PROPNAME="value" record // to ListBox table while (MsiViewFetch(hViewprop, hRecordprop) != ERROR_NO_MORE_ITEMS)
432 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 10: Functions Windows Installer Functions

nBuffer = 256; // set size buffer MsiRecordGetString(hRecordprop, 1, svPropname, nBuffer); nBuffer = 256; // reset size buffer MsiGetProperty(hInstall, svPropname, svPropvalue, nBuffer); r = r + 1; hRecordlist = MsiCreateRecord(4); MsiRecordSetString(hRecordlist, 1, "LISTBOXPROP"); MsiRecordSetInteger(hRecordlist, 2, r); MsiRecordSetString(hRecordlist, 3, svPropname); MsiRecordSetString(hRecordlist, 4, svPropname + "=" + svPropvalue); // can only temporarily modify running .msi database MsiViewModify(hViewlist, MSIMODIFY_INSERT_TEMPORARY, hRecordlist); endwhile; MsiViewClose(hViewlist); MsiViewClose(hViewprop); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

433

Chapter 10: Functions Windows Installer Functions

434

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

11
Operators
An operator is a symbol that specifies a basic operation to be performed using one or two operands such as addition. The operands can be constants, variables, or function calls. In the example below, the plus sign ( + ) indicates that the variable to the immediate left and the value to the immediate right should be added.
nCounter + 1;

Operator Functionality
Most InstallScript operators correspond to operators in C and behave very much like their counterparts in that language. As in C, the function of some operators, such as + and ^ depends on the data type of the operands. For example, when a plus sign is used with numeric operands, addition is performed. When a plus sign is used with string operands, concatenation is performed.

Expressions
The combination of operator and operands is called an expression. The example above is a simple expression because it includes only one operator. Complex expressions like the one below specify multiple operations:
nPrincipal * nRate - nFee;

Evaluating Complex Expressions In complex expressions, the order in which operations are performed depends on the order of operator precedence. InstallScript operators follow the same order of precedence as C operators. As with C, you can enclose an expression within parentheses to override the order of precedence. Results Most expressions produce a new value based on the existing value of the operands. For that reasons, expressions are also referred to by the data type of the result they produce. Arithmetic expressions produce a numeric value, Boolean expressions produce TRUE or FALSE. String expressions produce a string.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

435

Chapter 11: Operators Address Operator (&)

Address Operator (&)

The address operator is a unary operator that can be used to obtain the memory address of any variable in your script. The operator itself should precede the variable name, with no intervening space. You can use the address operator to assign the address of a variable to a pointer variable or to pass the address of a variable as an argument in a function call. You can send the address to C programs and operate on them as you would any standard C pointer. In the example below, the address of a data structure is assigned to a pointer variable:
typedef DIMENSIONS begin SHORT sLength; SHORT sWidth; end; DIMENSIONS rectangle; DIMENSIONS POINTER pointerObject; begin pointerObject = &rectangle; // . . end;

Caution: If you use the address operator with a local variable, be aware that the local variable exists only during the life of the function in which it is declared. After the function returns, the address of the local variable will no longer be valid.

Append to Path Operator (^)

Use the append to path ( ^ ) operator when you are combining two paths or a path and a file name. The operator automatically checks to see if you have added the proper number of backslashes when appending a file name or a subdirectory to a path. If you type:
szStringVar = "C:\\MyPath\\" ^ "YourPath\\FileName";

the output from szStringVar is:

C:\MyPath\YourPath\FileName

If you forgot to add the backslashes after MYPATH, as shown below:

szStringVar = "C:\\MyPath" ^ "YourPath\\FileName";

the result of the operation is still valid. The InstallScript ^ operator adds the backslashes for you.

Note: Do not use the ^ operator to join strings other than paths, such as registry keys. For other types of strings, use the concatenate operator (+).

436

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 11: Operators Arithmetic Operators (+, -, *, /)

Arithmetic Operators (+, -, *, /)

Arithmetic operators perform mathematical operations such as addition and subtraction with operands. There are two types of mathematical operators, unary and binary. Unary operators perform an action with a single operand. Binary operators perform actions with two operands. In complex expressions those that include two or more operationsthe order of evaluation depends on operator precedence.

Arithmetic Operator Precedence

When the InstallScript compiler encounters a complex expressionone that includes two or more simple expressionsit evaluates those expressions one at a time.

Operator Precedence
The order in which expressions are evaluated is determined by operator precedence. The compiler evaluates arithmetic operators using the same order of precedence that the C language uses: 1. Negative ( - ) unary.

2. Multiplication and division. 3. Addition and subtraction. 4. Left to Right Processing If an expression contains two or more operators with the same precedence level, the operator to the left is processed first. For example, in the expression 15 / 3 * 7, the InstallScript compiler first performs the division (15 / 3), then multiplies the result by 7.

Using Parentheses to Affect Processing

When a lower order precedence operation must be performed first, it should be surrounded by parentheses. For example, if the addition must be performed before the multiplication in the expression 30 / 3 + 7, place parentheses around 3 + 7. The parentheses in the expression 30 / (3 + 7) cause the compiler to add 3 and 7 first, yielding 10, and then divide 30 by 10 for a final result of 3. Nested Parentheses You can nest parentheses within an expression. InstallShield allocates 20 temporary locations for calculating nested expressions. Therefore, you can nest 19 levels of operations within parentheses. The InstallShield Script Compiler performs the innermost operation first and works its way outward. Example Expression For example, in the expression 36 - (3 * ( 2 + 6 - 4) ), the InstallScript compiler first performs the operation 2 + 6, which yields 8, then subtracts 4 from 8, yielding 4, then multiplies 3 by 4, yielding 12, and finally subtracts 12 from 36, yielding 24.

Note: Within the inner parentheses, InstallShield performed the addition operation first because it was the further left of two operators with equal precedence.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

437

Chapter 11: Operators Arithmetic Operators (+, -, *, /)

Binary Arithmetic Operators

The InstallScript compiler recognizes the binary arithmetic operators listed in the following table.
Table 11-1: Binary Arithmetic Operators Symbol + Operation Addition Subtraction Example x+y x-y Description Adds two operands. Subtracts the second operand from the first operand. Multiplies two operands. Divides the first operand by the second operand. Because InstallShield does not have floatingpoint data types, the fractional part of the answer is dropped. For example, 5/2 = 2.5 --> 2.s % Modulus 19 % 5 Divides the first operand by the second operand and returns the remainder. For example, nResult = 19 % 5; results in nResult = 4.

* /

Multiplication Division

x*y x/y

Tip: You should include a space both before and after an arithmetic operator to make your script more readable and to maintain a consistent appearance.

Unary Arithmetic Operators

Unary operators are arithmetic operators that perform an action on a single operand. The InstallScript compiler recognizes two unary operators, negative ( - ) and positive ( + ).

Negative
The negative unary operator reverses the sign of an expression from positive to negative or from negative to positive. The net result of using the negative unary operator before an expression is the same as multiplying the expression by -1.

Positive
The positive unary operator has the same net result on an expression as multiplying that expression by 1. It does not change the sign of a negative number to positive.

438

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 11: Operators Assignment Operator

Assignment Operator
Use the assignment operator ( = ) to copy a constant, literal, variable, expression result, or function result to a variable of the same type, as shown in the example code fragment below:
STRING szName; LONG nValue; BOOL bDone; HWND hInstance; INT iStyle; LIST LISTINFO; szName = "InstallShield"; nValue = 15; bDone = FALSE; hInstance = 0; iStyle = DLG_MSG_STANDARD|DLG_CENTERED; LISTINFO = ListCreate(STRINGLIST);

InstallShield automatically sizes string variables that are declared without an explicit length, as in the example above. By default, InstallShield autosizes the string variable to 256 bytes. If you assign to that variable a string longer than 256 bytes (including the null terminator), InstallShield increases the amount of memory reserved for that string variable. If you declare a string variable with an explicit length, you must make it long enough to receive the string you assign to it. In the example below, the string literal contains 51 characters. Therefore, both szStringVarA and szStringVarB must have a declared length of at least 52, which is just large enough to accommodate the string itself and the null terminator that is added automatically to the end of the string.
STRING szStringVarA[52], szStringVarB[52]; szStringVarA = "This is a sample string that is 51 characters long."; szStringVarB = szStringVarA;

Caution: Unlike C++, InstallScript does not support multiple assignment operations in a single statement. In InstallScript, the statement a = b = c is equivalent to the C++ statement a = b == c. That is, the first operator is interpreted as an assignment operator; the second is interpreted as a relational operator. If b is equal to c, the value 1 (TRUE) is assigned to a; if b is not equal to c, the value 0 (FALSE) is assigned to a.

Bit Operators (&, |, ^, ~, <<, >>)

Bit, or bitwise, operators allow you to manipulate individual bits in a numeric variable. In order to use the operators effectively, you need to be familiar with binary notation. This topic gives you an overview of binary operators, but it does not try to teach you binary notation.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

439

Chapter 11: Operators BYREF Operator

Bit operators work like logical operators, with one exception: logical operators work with expressions, bit operators work with bits. The InstallScript compiler recognizes the bitwise operators listed in the table below:
Table 11-2: Bit Operators Symbol & Operator BitAND Explanation BitAND sets a bit in the result to 1 (TRUE) only if the bits in both operands are 1s; otherwise, the result is 0 (FALSE). Bit inclusive OR sets a bit in the result to 0 only if the bits in the operands are 0; otherwise, the result is 1. Bit exclusive OR sets a bit in the result to 1 if the corresponding bits in the operands are different (one 1, the other 0). Otherwise, the result is 0. BitNOT is a unary operator that reverses every bit in the operand, changing every 1 to a 0 and vice versa, as in the following example:
~00001100

BitOR

BitXOR

BitNOT

The result is 11110011. << Shift left Moves bits a specified number of bits to the left. For example, the expression shown below moves bits three spaces to the left:
00001100 << 3

The result is 01100000. >> Shift right Moves bits a specified number of bits to the right. For example, the expression shown below moves bits two spaces to the right:
00001100 >> 2

The result is 00000011.

Shift operations work the same way in InstallScript that they do in the C language. When you shift by two bits to the right (>> 2), the two bit values furthest to the right are lost. The other bit values are shifted to the right two places, and the sign bit is shifted into the empty bits. You can use shift operations to multiply and divide a value by a power of 2. Left-shifting an integer by n has the same effect as multiplying the number by 2 to the power of n. Right-shifting an integer by n has the same effect as dividing the number by 2 to the power of n.

BYREF Operator
By default, the parameters of a user-defined function are passed by value; that is, a copy of the data specified by each parameter is passed to the function. Because the function operates on a copy, the original data cannot be changed by the function.

440

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 11: Operators BYVAL Operator

Note: There is one exception: By default, string variables passed to DLL functions are passed by reference, so the value of the variable can be changed by the function.

When you want a user-defined function to operate directly on a variable it receives in a parameter rather than on a copy of that variable, you must specify the BYREF operator with the parameter type declaration in the function prototype, as shown below:
prototype StrInvert( BYREF STRING );

The BYREF operator indicates that the parameter is to be passed by referencethat is, the actual variable is to be passed to the function, and any changes made to that variable will be visible to the caller when the function returns. Parameters that are passed by reference are often referred to as variable parameters because they require a variable. Constants and literals cannot be passed by reference.

Using BYREF With Multiple Parameters

When a user-defined function has more than one parameter, the BYREF operator must be specified with each variable parameter. In the example below, the first and third parameters are passed by reference and the second parameter is passed by value:
prototype StrChangeChar( BYREF STRING, CHAR, BYREF BOOL);

Limitations
User-defined structure members cannot be passed by reference. Attempting to do so results in a compiler error. Instead, you must pass a pointer to the entire structure by reference and then use the structure pointer operator (->) to access or modify the data elements of the structure. An autosized string variable that is passed by reference to a function will not be autosized within the called function. If the function attempts to assign a value whose length is greater than the current size of that parameter, run-time error 401 occurs. To avoid this error, declare strings with a specific size when they are to be passed by reference to a function.

BYVAL Operator
They keyword BYVAL can be specified in the parameter specification of a function prototype to indicate a parameter that is passed by value rather than by reference, as in the example below:
prototype DisplayString( BYVAL STRING );

When a parameter is passed by value, the function receives a copy of the value and any changes it makes to that value are local to the function. By default, the parameters of a user-defined function are passed by value; so generally it is not necessary to specify this keyword in a function protytpe. (There is one exception: by default, string variables passed to DLL functions are passed by reference, so the value of the variable can be changed by the function.) When you want a user-defined function to operate directly on a variable it receives in a parameter rather than on a copy of that variable, you must specify the BYREF operator.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

441

Chapter 11: Operators Concatenate Operator (+)

Concatenate Operator (+)

Use the concatenate string operator ( + ) to join one string to the end of another. Concatenating two strings results in a new, third string. In the following example, two string constants are concatenated and the resulting string value is assigned to the string variable szThirdString; after the statement has been executed, the value of szThirdString is First string Second string.
szThirdString = "First string " + "Second string";

Operands in a concatenation expression may be string literals, string constants, or string variables. In the example below, a string constant and a string literal are concatenated. The resulting string value is assigned to szThirdString.
#define FIRST_STRING "This is the first string" STRING szThirdString; // . . . szThirdString = FIRST_STRING + "Second string";

Caution: When assigning the result of a concatenation expression to a string variable, you must ensure that the concatenated string is not too long for the string variable to which it is assigned. A statement that assigns a string to a variable of insufficient size produces run-time error 401.

Indirection Operator (*)

The indirection operator is a unary operator that can be used to obtain the value stored at the memory location referenced by a pointer variable. The indirection operator must precede the pointer variable name, with no intervening space. In the following example, nvalue is a number and pnumber is a pointer to a number. The assignment statement is used to copy to nvalue the number being pointed to by pnumber.
nvalue = *pnumber;

The indirection operator can also be used to pass a value to a function that takes a number value as a parameter, as in the following example:
somefunction(*pnumber);

The following limitations apply to the indirection operator:

The indirection operator can be used with number pointers only. The indirection operator cannot be used to assign a value to a memory location. The indirection operator cannot be used as an argument to a function whose parameter has been defined with the BYREF operator. The indirection operator cannot be used to declare a pointer. The indirection operator cannot be used to declare a variable parameter in a function declaration.

442

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 11: Operators Logical Operators (&&, ||, !)

Logical Operators (&&, ||, !)

Logical operators allow you to ask more than one relational question at the same time. For example, using a logical operator you can ask if y is greater than 7 and szFilePath contains C:\\Program Files\\Company Name. Logical operators return either a TRUE (1) or FALSE (0) value. Like relational operators, they are used most often in if and while statements. The InstallScript compiler recognizes the logical operators listed in the table below:
Table 11-3: Logical Operators Symbol && Operation AND Example exp1 && exp2 Description True only if both exp1 and exp2 are true; otherwise, false. True if either exp1 or exp2 is true; false (0) only if both are false. False if exp1 is true; true if exp1 is false.

||

OR

exp1 || exp2

NOT

!exp1

Logical operators have a lower precedence than arithmetic or relational operators. Among logical operators, the AND operator has higher precedence than the OR operator.

Caution: Unlike C++, InstallShield performs complete Boolean evaluations of logical expressions. Consider the following if statement:
if (iVar = 10) && (MyFunction( ) = 0) then MessageBox("That is so true.", INFORMATION); endif;

MyFunction will be called even if the expression to the left of the logical operator is false. To obtain the effect of short circuit Boolean evaluations (in which the expression to the right of the && is resolved only if the expression to the left of the && is true), use a nested if statement, as shown below:
if (iVar = 10) then if (MyFunction( ) = 0) then MessageBox("That is so true.", INFORMATION); endif; endif;

Member Operator (.)

Use the member operator to reference individual elements in a structure variable. The member operator must appear between the structure variable name and the element name, with no intervening space. In the example below, a literal value is assigned to each element in a structure variable.
typedef SETTINGSREC begin BOOL bSwitchOn; STRING szMssg[255]; INT nVal; end;
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 443

Chapter 11: Operators Relational Operators (<, >, =, <=, >=, !=)

SETTINGSREC settings; settings.bSwitchOn = FALSE; settings.szMssg = "Off"; settings.nVal = 0;

Relational Operators (<, >, =, <=, >=, !=)

Relational operators compare one expression to another within the context of a conditional statement, such as an if or while statement. For example, the following statement asks Is x greater than 20?:
if (x > 20) then

The answer to the questions can be only TRUE (1) or FALSE (0). The InstallScript compiler recognizes the relational operators listed in the table below:
Table 11-4: Relational Operators Symbol = > < >= Operation Equal Greater than Less than Greater than or equal to Less than or equal to Not equal to Example x=y x>y x<y x >= y Description True if x is equal to y. True if x is greater than y. True if x is less than y. True if x is greater than or equal to y.

<= !=

x <= y x != y

True if x is less than or equal to y. True if x is not equal to y.

When you use a relational operator in an if...else statement, the program will follow one of two actions:

If the expression is TRUE, statements that follow the if are executed. Statements that follow the else are not executed. If the expression is FALSE, statements that follow the if are not executed. Statements that follow the else are executed.

Relational operators have an overall lower precedence than arithmetic operators. Among just relational operators, less than, less than or equal to, greater than, and greater than or equal to have precedence over equal and not equal.

Caution: You cannot use assignment and relational operators in the same conditional expression. For example, the following will fail:
if ((listID = ListCreate (NUMBERLIST)) = LIST_NULL) then . . . endif;

444

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 11: Operators Relational Operators (<, >, =, <=, >=, !=)

Tip: Unlike C, which uses == to test for equality, InstallScript's assignment operator and relational operator use the same symbol ( = ).

Relational Operator Precedence

Relational operators have an overall lower precedence than arithmetic operators. This means that InstallShield performs all arithmetic operations before beginning to evaluate logical operations. Logical expressions are evaluated from left to right, unless the order of operations is modified by parentheses. Among relational operators the order of precedence is as follows:

First, less than ( < ), less than or equal to ( <= ), greater than ( > ), and greater than or equal to ( >= ). Then, equal to ( = ) and not equal to ( != ).

Therefore, when combining arithmetic and relational expressions, the InstallShield Script Compiler evaluates precedence in the following order: 1. Negative (minus) unary.

2. Multiplication and division. 3. Addition and subtraction. 4. Less than ( < ), less than or equal to ( <= ), greater than ( > ), and greater than or equal to ( >= ). 5. Equal to ( = ) and not equal to ( != ).

In the expression 6 + 7 > y, the InstallScript compiler adds 6 and 7 together and then compares the result (13) to y. To change the order of precedence, use parentheses. For example, in the expression 6 + (7 > y), the InstallScript compiler first determines if 7 is greater than y. If it is, then 1 (the numeric value of TRUE) is added to 6. If it is not, then 0 (the numeric value of FALSE) is added to 6. When a statement contains arithmetic, relational, and logical operators, the compiler evaluates precedence in the following order: 1. Negative (minus) unary has first precedence.

2. Multiplication and division have second precedence. 3. Addition and subtraction have third precedence. 4. NOT ( ! ) has fourth precedence. 5. Less than ( < ), less than or equal to ( <= ), greater than ( > ), and greater than or equal to ( >= ) have fifth precedence.

6. Equal to ( = ) and not equal to ( != ) have sixth precedence. 7. AND ( &&) has seventh precedence.

8. OR ( || ) has eighth precedence. Use logical operators in if and while statements the same way you used relational operators. The example below adds nExampleSize and nHelpSize if bInstallExample and bInstallHelp are true.
if (bInstallExample && bInstallHelp) then nTotalSize = nExampleSize + nHelpSize;
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 445

Chapter 11: Operators String Operators (^, +, %)

endif;

The next example sets bPublicFile to TRUE if either bInstallProgram1 or bInstallProgram2 is TRUE.
if (bInstallProgram1 || bInstallProgram2) then bPublicFile = TRUE; endif;

Note: You cannot use the && or || operators within an argument to a function. Instead, follow the above example and assign the value of the logical expression to a Boolean variable and then call the function with the variable as an argument.

String Operators (^, +, %)

The string operators allow you to directly manipulate strings without the use of functions. Note that string operators are not case-sensitive. The InstallScript compiler supports the following string operations:
Table 11-5: String Operators Operation Append to Path Operator (^) Concatenate Operator (+) Find String Operator (%) String Constant Operator (@) Description Adds additional paths to a path or a file name. Appends one string to the end of another string. Locates a substring in another string. Access a string constant that is used for one of the projects string entries.

Note: Do not use parentheses to enclose expressions on either side of a string operator. For example, avoid statements like the following:
szPath = szTestPath ^ (AUTOFILE + ".bat");

Instead, create expressions without parentheses for use with string operators, as shown below:
szFile = AUTOFILE + ".bat"; szPath = szTestPath ^ szFile;

String Constant Operator (@)

String entries enable you to access text strings for a given language from within your InstallScript code. That is, to keep the InstallScript code for your installation completely separate from any languagespecific strings that you may want to display during the installation, you can refer to each string by using its string identifier. When you use string identifiers in your InstallScript, you must precede them with the at sign (@). The String Editor view shows the collection of language-independent identifiers and corresponding language-specific values for your project. To learn more, see Localizing the End-User Interface.
446 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 11: Operators Structure Pointer Operator (->)

When you build a project that includes an InstallScript file (.rul) and the InstallScript code contains one or more references to string entries that use the @ operator, InstallShield validates the string entries at build time. If a string identifier in the projects InstallScript file is not defined in String Editor view, InstallShield displays build warning -7174.

Note: The @ operator is case-insensitive when it comes to string identifiers. Therefore, when you use a string identifier in your script, you do not necessarily need to match the case of the string identifier that is specified in the String Editor view. However, mixing case may prevent InstallShield from matching the string entries in the script to the corresponding string entries in the String Editor view at build time. Therefore, it is recommended that you use uppercase for all instances of string identifiers.

Tip: As an alternative to the @ operator, you can use the LoadStringFromStringTable function if you want to provide your own missing string error handling.

Structure Pointer Operator (->)

Use the structure pointer operator to reference individual elements in a structure by means of a pointer variable. The structure pointer operator must appear between the pointer variable name and the element name, with no intervening space. In the example below, a literal value is assigned to each element in a structure.
typedef DIMENSIONS begin SHORT sLength; SHORT sWidth; end; DIMENSIONS Table; NUMBER nvNumValue; DIMENSIONS POINTER pointerObject; begin pointerObject = &Table; pointerObject->sLength = 500; pointerObject->sWidth = 750;

Caution: You can use only one structure pointer in an expression. If structure A contains a member (Bptr) that is a pointer to structure B, which contains a member (Cptr) that is a pointer to structure C, you cannot reference a member of C from A. The expression A.Btptr->Cptr->Cmember is invalid in InstallScript.

Find String Operator (%)

Use the boolean Find String operator ( % ) to determine if one string is a substring of another string. The following example tests szStringVarA to determine if it contains the string sample. If it does, then MessageBox is called to display a message.
szStringVarA = "This is a sample string."; if (szStringVarA % "sample") then MessageBox("Variable contains 'string'.",INFORMATION);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

447

Chapter 11: Operators Find String Operator (%)

endif;

The character comparison is not case-sensitive. In the following example, the message box will be displayed:
typedef DIMENSIONS begin SHORT sLength; SHORT sWidth; end; DIMENSIONS Table; NUMBER nvNumValue; DIMENSIONS POINTER

pointerObject;

begin pointerObject = &Table; pointerObject->sLength = 500; pointerObject->sWidth = 750;

Note: The InstallScript function StrFind also determines if a substring is contained within another string. If the substring is found, StrFind returns its position within the string.

448

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

12
Objects and Object Handlers
This section describes the objects and object handlers that InstallScript supports.

Objects
InstallScript supports the following objects.
Table 12-1: InstallScript Objects Object Err Object Objects Object Reboot Object Description Use for exception handling. Obtain access to your project's InstallShield objects by either index or name. Pass command-line arguments to the installation after a reboot. This information is written to the appropriate registry key at the end of the installation, so that the installation runs after reboot. Make text substitutions.

TextSub Object

Err Object
The Err object is used for exception handling. It has the following properties and methods:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

449

Chapter 12: Objects and Object Handlers Objects

Properties
Table 12-2: Err Object Properties Property Number Source Description HelpFile Description A number that identifies the error. A string that identifies the source of the error. A string that describes the error. A string that specifies the fully qualified file name of a help file containing additional information about the error. A number that specifies the identifier of a help topic containing additional information about the error. This property holds the return value of the Windows API function GetLastError.

HelpContext

LastDllError

Methods
Table 12-3: Err Object Methods Method Clear Raise Description Clears the values of the Err object's properties. If executed after the try keyword, script processing passes to the next exception handler (that is, code inside a catch/endcatch block); otherwise processing passes to the setup engine's built-in exception handler. Also resets the values of Err object properties as follows:

Err.Raise( );Does not reset any Err object property values. Err.Raise( nNumber );Resets the value of Err.Number to nNumber. Err.Raise( nNumber, szSource );Resets the value of Err.Number to

nNumber and Err.Source to szSource.

Err.Raise( nNumber, szSource, szDesc );Resets the value of

Err.Number to nNumber, Err.Source to szSource, and Err.Description to szDesc.

Err.Raise( nNumber, szSource, szDesc, szHelpFile );Resets the

value of Err.Number to nNumber, Err.Source to szSource, Err.Description to szDesc, and Err.HelpFile to szHelpFile.
Err.Raise( nNumber, szSource, szDesc, szHelpFile, nHelpContext );Resets the value of Err.Number to nNumber, Err.Source to szSource,

Err.Description to szDesc, Err.HelpFile to szHelpFile, and Err.HelpContext to nHelpContext.

Objects Object

450

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 12: Objects and Object Handlers Objects

Project: This information applies to InstallScript projects.

The Objects object is used for getting access to your projects InstallShield objects by either index or name; for example:
set obj1 = Objects(1); set obj2 = Objects("New MFC 6.2 Runtime 1");

Properties
Table 12-4: Objects Object Properties Property Count Description The number of InstallShield objects included in your project.

Reboot Object
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The Reboot object is used for passing command-line arguments to the Setup.exe file after a restart; this information is written to the appropriate registry key at the end of the installation, so that the installation runs after the system is restarted. For example, the following statement runs the installation in debug mode after a restart:
Reboot.CommandLine = "-d";

Note that the specified argument or arguments are added to the existing command line; they do not replace the existing command line. Note also that currently you cannot change the existing command line or remove text from it.

Passing Parameters to the InstallScript Variable CMDLINE in an InstallScript MSI Installation

As with any Setup.exe command line, in an InstallScript MSI installation, if you are trying to pass information to the InstallScript variable CMDLINE variable when the Setup.exe file is launched after the restart, you must include the information after specifying the -z option. For example, the following adds TEST1 TEST2 to the reboot string and thus the CMDLINE variable when the Setup.exe file is launched after the restart.
Reboot.CommandLine = -z"TEST1 TEST2"

Note that since multiple z parameters are not supported, you must specify all information that is intended for the CMDLINE variable in a single Reboot.CommandLine call for your InstallScript MSI installation.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

451

Chapter 12: Objects and Object Handlers Object Handlers

TextSub Object
Project: This information applies to InstallScript projects.

The TextSub object is used for making text substitutions. It has the following property and method:

Properties
Table 12-5: TextSub Object Properties Property Value( szIdentifier ) Description The value of the string associated with the identifier szIdentifier.

Methods
Table 12-6: TextSub Object Methods Method Substitute( szString ) Description Replaces all angle-bracketed identifiers in szString with their associated strings.

Example
The following code:
TextSub.Value( "SUBBED" ) = "substituted text"; szString = "123<SUBBED>456<UNSUBBED>789"; TextSub.Substitute( szString );

gives szString the value "123substituted text456<UNSUBBED>789".

Object Handlers
InstallScript supports the following object handlers.
Table 12-7: InstallScript Object Handlers Object Handler InitProperties Description Executed when the object is inserted in a project. It initializes the values of the object script's variables that are used to read or write the values of object properties. Executed when the object project is opened and when an installation that includes the object is launched. It calls the appropriate ReadxxxxProperty functions to retrieve the property values stored in the property bag object. Executed when the object project is saved or built. It calls the appropriate WritexxxxProperty functions to save the property values to the property bag object.

ReadProperties

WriteProperties

452

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Chapter 12: Objects and Object Handlers Exception Handling

InitProperties
Project: This information applies to InstallScript projects.

The InitProperties handler is executed when the object is inserted in a project. It initializes the values of the object script's variables that are used to read or write the values of object properties. If you add a property to the object project by using the Add New Property dialog box, an appropriate statement, based on your entry in the dialog box's Default Value edit box, is automatically placed in this handler.

ReadProperties
Project: This information applies to InstallScript projects.

The ReadProperties handler is executed when the object project is opened and when a setup that includes the object is launched. It calls the appropriate ReadxxxxProperty functions to retrieve the property values stored in the property bag object. (Property values are saved to the property bag object by the WritexxxxProperty functions, which are called by the WriteProperties handler.) If you add a property to the object project by using the Add New Property dialog box, an appropriate ReadxxxxProperty function call is automatically placed in this handler.

WriteProperties
Project: This information applies to InstallScript projects.

The WriteProperties handler is executed when the object project is saved or built. It calls the appropriate WritexxxxProperty functions to save the property values to the property bag object. (Property values are retrieved from the property bag object by the ReadxxxxProperty functions, which are called by the ReadProperties handler.) If you add a property to the object project by using the Add New Property dialog box, an appropriate WritexxxxProperty function call is automatically placed in this handler.

Exception Handling
Exception handling lets you separate error handling from the rest of your script code. InstallScript supports exception handling with the Err object and the keywords try, catch, and endcatch. If an exception is raised during execution of code that follows the try keyword, script processing passes to the next exception handler (that is, code inside a catch/endcatch block). After an exception handler has executed, processing passes to the line after its endcatch keyword. If no exception is raised by code that follows the try keyword, the code in the exception handler is skipped and processing resumes with the line after the endcatch keyword.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 453

Chapter 12: Objects and Object Handlers Exception Handling

An exception can be raised by a call to the Err object's Raise method, which takes from zero to five arguments. You can retrieve the values of those arguments in the exception handler by checking the value of the corresponding Err object properties.

Note: Raised errors must be negative numbers; otherwise, the installation engine converts the error into the appropriate COM error. Therefore, any error code thrown should be a negative number.

The following code sample demonstrates exception handling:

askfile: AskText( "Path to file?", "", svPathName ); try if (!Is( FILE_EXISTS, svPathName )) then /* If file does not exist, raise an exception. (ERR_NOT_EXIST must have been given a value in a #define statement. The error number must be a negative number.) */ Err.Raise( ERR_NOT_EXIST ); endif; if GetFileInfo ( svPathName, FILE_SIZE, nvFileSize, svResult )<0 then /* If file information could not be obtained, raise an exception. (ERR_NO_INFO must have been given a value in a #define statement. The error number must be a negative number.) */ Err.Raise ( ERR_NO_INFO ); endif; SprintfBox ( INFORMATION, "File Size", "Size of %s is %ld.", svPathName, nvFileSize ); catch /* Exception handler. */ nTemp = Err.Number; /* Handle the exception based on its cause. */ switch (nTemp) case ERR_NOT_EXIST: if AskYesNo( svPathName + " does not exist. Enter another path?", YES )=YES then bTryAgain = TRUE; endif; case ERR_NO_INFO: MessageBox ( "Could not get size of " + svPathName, INFORMATION ); bTryAgain = FALSE; endswitch; endcatch; if bTryAgain then bTryAgain = FALSE; goto askfile; endif;

Try/catch/endcatch blocks can be nested as in the following example:

try /* Normal processing, part 1. */ try /* Normal processing, part 2. */
454 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Chapter 12: Objects and Object Handlers Exception Handling

catch /* Exception handling for part 2. */ endcatch; /* Normal processing, part 3. */ catch /* Exception handling for parts 1 and 3. */ endcatch;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

455

Chapter 12: Objects and Object Handlers Exception Handling

456

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

A
Built-In Functions (A-D)
For a list of functions by category, see Built-In Functions by Category.

AddFolderIcon
The AddFolderIcon function lets you perform tasks such as the following:

Create a shortcut or folder on the Start menu, the Programs menu, or the desktop. Use the szProgramFolder parameter to specify the appropriate location for the shortcut or folder. Create a cascading submenu on the Startup menu, and include a shortcut in the submenu.

Note: The shortcut target must be present on the target system before AddFolderIcon can be called. AddFolderIcon does not support the creation of Internet shortcuts.

Syntax
AddFolderIcon ( szProgramFolder, szItemName, szCommandLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

457

Appendix A: Built-In Functions (A-D) AddFolderIcon

Parameters
Table A-1: AddFolderIcon Parameters Parameter szProgramFolder Description Specify the name of the folder that should contain the shortcut, or specify the name of the program folder that you want to create. If the folder does not exist, the installation creates it. For this parameter, you can specify a subfolder in a multi-level cascading menu. If the subfolder does not exist, AddFolderIcon creates the subfolder and, if necessary, its parent folders. To add the shortcut to a specific folder, specify the fully qualified pathfor example:
C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs

To add a shortcut to the Programs menu on the Start menu, you can pass a null string ("") in this parameter. You can pass one of the following InstallScript system variables in this parameter:

FOLDER_DESKTOPAdds the shortcut to the desktop. FOLDER_STARTUPAdds the shortcut to the Startup menu. FOLDER_STARTMENUAdds the shortcut to the Start menu. FOLDER_PROGRAMSAdds the shortcut to the Start\Programs menu.

You can also specify a path relative to a folder that is identified by an InstallScript system variablefor example:
FOLDER_PROGRAMS ^ ACCESSORIES\\GAMES

szItemName

Specify the name of the shortcut. Calling AddFolderIcon to add a shortcut to a program folder also creates a link file in the links directory that is specified by szCommandLine. Note that Explorer shell does not allow the following characters in item names: /, \, :, ?, <, >, or |. Specify one of the following:

szCommandLine

The fully qualified name of the executable file that is associated with the shortcut, including any command-line parameters. This is added to the Target value on the shortcuts Properties dialog box. To add a shortcut to the Start Programs menu, enter the fully qualified path of the links directory, which is where your application stores its icon link files. The fully qualified path if szItemName is a subfolder.

Caution: If the command line includes a long file name, it must be enclosed in quotes. Command-line parameters, however, should not be surrounded with quotation marks. For that reason, it is advisable to build the szCommandLine string from two separate strings.

458

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AddFolderIcon

Table A-1: AddFolderIcon Parameters (cont.) Parameter szWorkingDir Description Specify the working directory for the shortcut target. If szItemName is a subfolder, this parameter is not applicable. AddFolderIcon writes this directory in the Start In box on the Shortcut tab of the shortcuts Properties dialog box. If you pass a null string ("") in this parameter, the function leaves this Start In box blank, and the path in the Target box is used.

Caution: Do not call LongPathToQuote to enclose this path in quotation marks. InstallShield automatically encloses these paths in quotation marks. szIconPath Specify the fully qualified path to the file that contains the icon that you want to be displayed for the shortcut. If szItemName is a subfolder, this parameter is not applicable.

Caution: Do not call LongPathToQuote to enclose this path in quotation marks. InstallShield automatically encloses these paths in quotation marks. nIcon Specify the icon index in the executable file that is specified by szIconPath. An icon index of 0 refers to the first icon in the file, an icon index of 1 refers to the second icon, and so on. If you are not using an icon, specify 0 in this parameter. If szItemName is a subfolder, this parameter is not applicable. szShortCutKey Specify the shortcut key (in the form of a string) that you want to be assigned to your shortcut. You can set szShortCutKey for the shortcut so that end users can press the appropriate hot keys to launch the shortcut. For example, if you want end users to be able to launch the product by pressing the CTRL key, the ALT key, and then the 1 key on the numeric keyboard, pass Ctrl + Alt + 1 in this parameter. If szItemName is a subfolder, this parameter is not applicable. nFlag Pass one or more of the following predefined constants in this parameter. To pass two or more predefined constants in this parameter, combine those constants with the bitwise OR operator ( | ).

REPLACEIndicates that the current icon or shortcut in the folder is to be replaced. RUN_MAXIMIZEDIndicates that the program should be maximized when launched. RUN_MINIMIZEDIndicates that the program should be minimized when launched. NULLIndicates no options.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

459

Appendix A: Built-In Functions (A-D) AddFolderIcon

Return Values
Table A-2: AddFolderIcon Return Values Return Value 0 Description Indicates that the function successfully added or replaced the shortcut in the specified folder and associated the executable file with it. Indicates that the function was unable to add or replace the shortcut and associate the executable file with it. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

<0

AddFolderIcon Examples
Choose one of the following examples:

Place a shortcut to an executable file on the Start menu and the Start Programs menu. (AddFolderIcon Example 1) Create a cascading submenu on the Startup menu and add a shortcut to the menu. (AddFolderIcon Example 2) Place a subfolder on the desktop and a shortcut pointing to an executable file in the new folder. (AddFolderIcon Example 3)

AddFolderIcon Example 1

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the AddFolderIcon function. * * This example places a shortcut to an executable file on the * Start menu and the Start Programs menu. * * Note: Before running this script, set the preprocessor * constants so that they reference the fully qualified * names of the Windows Notepad executable and a valid * text file on the target system. * \*-----------------------------------------------------------*/ #define PROGRAM "C:\\Windows\\Notepad.exe" #define PARAM "C:\\Windows\\Readme.txt" // Include Ifx.h for built-in InstallScript function prototypes.

460

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AddFolderIcon

#include "Ifx.h" export prototype ExFn_AddFolderIcon(HWND); function ExFn_AddFolderIcon(hMSI) STRING szProgramFolder, szItemName, szCommandLine, szWorkingDir; STRING szShortCutKey, szProgram, szParam, szIconPath; NUMBER nIcon; begin // Set up parameters for call to AddFolderIcon. szProgramFolder = FOLDER_STARTMENU; szItemName = "Notepad Example 1"; szProgram = PROGRAM; szParam = PARAM; LongPathToQuote (szProgram, TRUE); LongPathToShortPath (szParam); szCommandLine szWorkingDir szIconPath nIcon szShortCutKey = = = = = szProgram + " " + szParam; ""; ""; 0; "";

// Add a shortcut to the Start menu. if (AddFolderIcon (szProgramFolder, szItemName, szCommandLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, REPLACE) < 0) then MessageBox ("AddFolderIcon failed.", SEVERE); else SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.", szItemName); endif; szProgramFolder = ""; szItemName = "Notepad Example 2"; // Add a shortcut to the Programs menu. if (AddFolderIcon (szProgramFolder, szItemName, szCommandLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, REPLACE) < 0) then MessageBox ("AddFolderIcon failed.", SEVERE); else SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.", szItemName); endif; end;

AddFolderIcon Example 2

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script *
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 461

Appendix A: Built-In Functions (A-D) AddFolderIcon

* Demonstrates the AddFolderIcon function. * * This example creates a cascading submenu on the Startup menu * and adds a shortcut for an executable file to it. * * Note: Before running this script, set the preprocessor * constants so that they reference the fully qualified * names of the Windows Notepad executable file and a * valid text file on the target system. * \*-----------------------------------------------------------*/ #define PROGRAM "C:\\Windows\\Notepad.exe" #define PARAM "C:\\Windows\\Readme.txt" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_AddFolderIcon(HWND); function ExFn_AddFolderIcon(hMSI) STRING szProgramFolder, szItemName, szCommandLine, szWorkingDir; STRING szIconPath, szShortCutKey, szProgram, szParam; NUMBER nIcon, nFlag, nResult; begin // Set the fully qualified name of the Startup submenu. szProgramFolder = FOLDER_STARTUP ^ "SubMenu Example"; // Construct the shortcuts command-line property. szProgram = PROGRAM; szParam = PARAM; LongPathToQuote (szProgram, TRUE); LongPathToShortPath (szParam); szCommandLine = szProgram + " " + szParam; // Set up the shortcuts other properties to pass to AddFolderIcon. szItemName = "Notepad Example1"; szWorkingDir = ""; szIconPath = ""; nIcon = 0; szShortCutKey = ""; nFlag = REPLACE|RUN_MAXIMIZED; // Add the shortcut to the submenu; create the submenu if necessary. nResult = AddFolderIcon (szProgramFolder, szItemName, szCommandLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag); // Report the results. if (nResult < 0) then MessageBox ("AddFolderIcon failed.", SEVERE); else SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.", szItemName); endif; end;

462

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AddFolderIcon

AddFolderIcon Example 3

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the AddFolderIcon function. * * This example places a subfolder on the desktop and an icon * pointing to an executable in the new folder. The folder is * a shortcut that points to an actual directory. From this * folder the user can execute a shortcut that runs the program. * * Note: Before running this script, set the preprocessor * constants so that they reference the fully qualified * names of the Windows Notepad executable and a valid * text file on the target system. * \*-----------------------------------------------------------*/ #define FOLDER #define PROGRAM #define PARAM "C:\\Windows\\" "C:\\Windows\\Notepad.exe" "C:\\Windows\\Readme.txt"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_AddFolderIcon(HWND); function ExFn_AddFolderIcon(hMSI) STRING szProgramFolder, szItemName, szCommandLine, szWorkingDir; STRING szIconPath, szShortCutKey; STRING szProgram, szParam, szFolderDir; NUMBER nIcon, nFlag, nResult; begin // szProgramFolder is the Desktop on the local system. szProgramFolder = FOLDER_DESKTOP; szItemName = "Example folder"; // Create the folder which the folder icon will point to. szFolderDir = FOLDER ^ szItemName; CreateDir(szFolderDir); // The command line for the folder icon must be the folder path, and // it must be enclosed in quotation marks if the path is longer than // eight characters. szCommandLine = szFolderDir; LongPathToQuote(szCommandLine, TRUE); szWorkingDir szIconPath nIcon szShortCutKey = = = = ""; ""; 0; "";

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

463

Appendix A: Built-In Functions (A-D) AddProfString

nFlag

= REPLACE|RUN_MINIMIZED;

// Create the folder icon, and show the folder it points to. nResult = AddFolderIcon (szProgramFolder, szItemName, szCommandLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag); if (nResult < 0) then MessageBox("AddFolderIcon failed.", SEVERE); else SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.", szItemName); endif; // Display the folder just created. ShowProgramFolder (szFolderDir, SW_SHOW); // Add the Example icon to the newly created folder. szProgramFolder = szFolderDir; szItemName = "Notepad Example"; // Make sure the white space is not seen as a delimiter. szProgram = PROGRAM; LongPathToQuote (szProgram, TRUE); szParam = PARAM; LongPathToShortPath (szParam); szCommandLine = szProgram + " " + szParam; szWorkingDir = ""; szIconPath = ""; nResult = AddFolderIcon (szProgramFolder, szItemName, szCommandLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag); if (nResult < 0) then MessageBox ("AddFolderIcon failed.", SEVERE); else SprintfBox (INFORMATION, "AddFolderIcon", "%s created successfully.", szItemName); endif; end;

AddProfString
The AddProfString function unconditionally adds a profile string to an .ini file. Use AddProfString only to add non-unique keys, such as those found in the [386Enh] section of the System.ini file (device = ...). AddProfString adds the line KEY=VALUE to the end of the specified .ini file section. It does not replace or update an existing key. To update an existing non-unique key, call ReplaceProfString. To add a unique key or to update an existing unique key's value in an .ini file, call WriteProfString.

Syntax
AddProfString ( szFileName, szSectionName, szKeyName, szValue );

464

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AddProfString

Parameters
Table A-3: AddProfString Parameters Parameter szFileName Description Specifies the name of the .ini file to which the profile string is to be added. If szFileName is unqualified (that is, if a drive designation and path are not included), InstallShield searches for the file in the Windows folder. If the file does not exist, it is created in the specified folder; if a path is not included in file name, the file is created in the Windows folder. If the file name is qualified with a path that does not exist, AddProfString fails. Specifies the name of a section in the .ini file section. The profile string is inserted at the end of that section. If the section does not exist, InstallShield creates it. The section name should not be enclosed within delimiting brackets ( [ ] ). Note that the profile string is inserted even if the key specified by szKeyName already exists in that section. Specifies the name of the key to insert. The value of this parameter will appear to the left of the equal sign in the profile string (szKeyName = szValue). Specifies the value to assign to the key. The value of this parameter will appear to the right of the equal sign in the profile string (szKeyName = szValue).

szSectionName

szKeyName

szValue

Return Values
Table A-4: AddProfString Return Values Return Value 0 Description AddProfString successfully added the specified profile string to the .ini file. AddProfString was unable to add the profile string.

<0

Additional Information
AddProfString does not use the Windows API to change the .ini files. The Windows API cannot handle the types of changes possible with AddProfString. Changes made to .ini files can be logged for uninstallation. However, there are some important restrictions to be aware of. For more information, see Uninstalling Initialization (.ini) File Entries.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

465

Appendix A: Built-In Functions (A-D) AddProfString

AddProfString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions AddProfString and GetProfString. * * This script adds a profile string to a file; then it * retrieves and displays the string that was added. * * Note: The first time you run this script, it will create a * file named ISExampl.ini in the root of drive C. You * can delete that file when you have finished analyzing * this script. * \*-----------------------------------------------------------*/ #define EXAMPLE_INI "C:\\ISExampl.ini" // The new section, #define NEW_SECTION #define NEW_KEY #define NEW_VALUE key, and value to add to the file. "New Section" "New Key" "Test"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_AddProfString(HWND); function ExFn_AddProfString(hMSI) STRING svResult; begin // Add the profile string to the file. if (AddProfString (EXAMPLE_INI, NEW_SECTION, NEW_KEY, NEW_VALUE) != 0) then // Display an error message if the string could not be added. MessageBox ("AddProfString failed.", SEVERE); else // Retrieve the value of a key from the file. if (GetProfString (EXAMPLE_INI, NEW_SECTION, NEW_KEY, svResult) != 0) then // Display an error message if the string could not be retrieved. MessageBox ("GetProfString failed.", SEVERE); else // Display the key and its current value. MessageBox (NEW_KEY + "=" + svResult, INFORMATION); endif; endif; end;

466

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AdminAskPath

AdminAskPath
Project: This information applies to InstallScript MSI projects.

The AdminAskPath function displays a dialog that prompts the end user to enter the path to a destination location for an administrative installation (when the end user runs an InstallScript MSI project Setup.exe with the /a argument).

Syntax
AdminAskPath ( szMsg, szDefaultPath, svResultPath );

Parameters
Table A-5: AdminAskPath Parameters Parameter szMsg Description Specifies the message to display in this dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the default path to display in the edit field. The end user can modify this string. The default implementation of OnAdminInstallUIBefore passes INSTALLDIR in this parameter. Returns the resulting path, regardless of whether the user accepts the default path, modifies it, or selects an alternate path from the Choose Folder dialog. The default implementation of OnAdminInstallUIBefore passes INSTALLDIR in this parameter.

szDefaultPath

svResultPath

Return Values
Table A-6: AdminAskPath Return Values Return Value NEXT (1) BACK (12) Description Indicates that the user clicked the Next button. Indicates that the user clicked the Back button.

Additional Information
AdminAskPath uses the AskPath dialog, and it uses the same dialog resources as AskPath. Therefore, any changes you make to the layout of AskPath in the Dialog Editor are reflected in AdminAskPath.

To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

467

Appendix A: Built-In Functions (A-D) AskDestPath

AdminAskPath Example
Project: This information applies to InstallScript MSI projects.
//--------------------------------------------------------------------------// // InstallShield Example Script // // Demonstrates the AdminAskPath function. // // In the OnAdminInstallUIBefore event of an InstallScript MSI project, // prompt the user for the target directory into which files should be // uncompressed and copied. // //--------------------------------------------------------------------------function OnAdminInstallUIBefore( ) int nResult; begin Dlg_SdWelcome: SdWelcome("", ""); Dlg_AdminAskPath: // prompt the user for the target path, storing it in INSTALLDIR nResult = AdminAskPath("", INSTALLDIR, INSTALLDIR); if (nResult = BACK) goto Dlg_SdWelcome; // prepare the status dialog SetStatusExStaticText(SdLoadString(IDS_IFX_STATUSEX_STATICTEXT_FIRSTUI)); Enable(STATUSEX); end;

AskDestPath
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The AskDestPath function displays a dialog that enables the end user to specify a destination folder for the files to be installed by your installation. The dialog also includes a Browse button that enables the end user to select an existing folder on the system. To open the Choose Folder dialog from the Choose Destination Location dialog, the end user must click the Browse button. The Choose Folder dialog displays a list of all available folders. The end user can select an existing folder or enter a new folder name. If the end user enters the name of a folder that does not exist, a message box opens to enable the end user to create the folder.

468

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AskDestPath

Installations that run in silent mode should create the new folder if it does not exist before calling AskDestPath. This ensures that the confirmation dialog is not displayed. Without this step, two response files are required to handle the two possible conditions. The folder selected by the end user must be writable; non-writable folders are not accepted. If you want the end user to be able to select folders that are not writable, call the AskPath function instead.

Syntax
AskDestPath ( szTitle, szMsg, svDir, nReserved );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

469

Appendix A: Built-In Functions (A-D) AskDestPath

Parameters
Table A-7: AskDestPath Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title Choose Destination Location, pass a null string ("") in this parameter. Specifies the message to display in the dialog. To pass multiple lines of static text in this parameter, insert newline escape sequences ( \n ) where needed to break the line. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the default path to display when the dialog is opened; returns the path to the folder selected by the end user.

szMsg

svDir

Note: If the default folder specified by svDir does not already exist on the end user's system, it is not created unless the end user clicks the Browse button and follows the steps to create it from the Choose Folder dialog. Therefore, whenever you specify a default folder that you intend to use before calling FeatureMoveData (which creates the folder if necessary), you must call ExistsDir when AskDestPath returns in order to determine whether that folder exists. If it does not exist, call CreateDir to create it on the end user's system. Note that FeatureTransferData is called automatically in an installation running an event-based script. nReserved The value of this parameter must be 0 (zero).

Return Values
Table A-8: AskDestPath Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

AskDestPath Example
Project: This information applies to the following project types:

470

InstallScript
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AskOptions

InstallScript MSI

/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the AskDestPath function. * * This script calls AskDestPath to get the path to the location * where the installation will install files. That path is then * displayed in a message box. * \*-----------------------------------------------------------*/ #define TITLE_TEXT "AskDestPath Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_AskDestPath(HWND); function ExFn_AskDestPath(hMSI) STRING szTitle, szMsg, svDir; NUMBER nReturn; begin // Set a default path for the installation. svDir = INSTALLDIR; // Get a destination directory. Pass a null string in the // second parameter to display the default message. nReturn = AskDestPath (TITLE_TEXT, "", svDir, 0); if (nReturn < 0) then // Report the error. MessageBox ("AskDestPath failed.", SEVERE); elseif (nReturn = NEXT) then // Display the selected destination directory name. MessageBox ("You selected " + svDir + ".", INFORMATION); endif; end;

AskOptions
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The AskOptions function formats and displays a dialog that prompts the end user to select one or more options. The dialog displays up to nine selection controlseither check boxes or option buttons depending on the value of nValue. The default title for this dialog is Select Features. To change the contents of the title bar, call SetDialogTitle before calling AskOptions.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 471

Appendix A: Built-In Functions (A-D) AskOptions

Note: You cannot use the PlaceWindow function in conjunction with the AskOptions function. By default, the dialog appears in the center of the desktop, unless the background window mode is enabled. If the installation is in window mode, the dialog appears in the center of the background window.

Syntax
AskOptions ( nValue, szMsg, szText1, bvCheck1, szText2, bvCheck2[, szTextn, bvCheckn] [,..., ...] );

472

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AskOptions

Parameters
Table A-9: AskOptions Parameters Parameter nValue Description Specifies the type of controls to display. Pass one of the following predefined constants in this parameter:

szMsg

EXCLUSIVESpecifies option buttons, which enable the end user to select only one option. NONEXCLUSIVESpecifies check boxes, which enable the end user to select more than one option.

Specifies the message to display in the dialog. You can use this message to describe the options and/or ask the user to choose one or more options. If the message is too long for one line, use newline escape sequences ( \n ) to insert line breaks.

Note: Your operating system dictates the maximum message string length.By default, the display of szMsg text is limited to two lines by the AskOptions dialog resource in _Isres.dll. To display more than two lines of szMsg text, you can create a custom dialog from the AskOptions dialog. szText1 Specifies a text label to display next to the first check box or option button. The maximum number of characters that can be displayed depends on the font you use; be sure to check that the string specified fits in the static text field of the dialog. If the string does not fit, either shorten it or call SdAskOptions instead. To create an accelerator key, insert an ampersand (&) before the character you want to designate for that purpose. The character is displayed with an underline to indicate its function. For example, to make Alt + C the accelerator key for Custom, pass "&Custom"; to make Alt + S the accelerator key for Custom, pass "Cu&stom." bvCheck1 Specifies the initial status of the first check box or option button when the dialog is opened; returns the status of the first check box or option button when the dialog is closed. The following constants are passed and returned in this parameter:

szText2

TRUEThe first check box or option button is selected. FALSEThe first check box or option button is not selected.

Specifies a text label to display next to the second check box or option button. The maximum number of characters that can be displayed depends on the font you use; be sure to check that the string specified fits in the static text field of the dialog. If the string does not fit, either shorten it or call SdAskOptions instead. Create an accelerator in the same manner as you did for szText1.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

473

Appendix A: Built-In Functions (A-D) AskOptions

Table A-9: AskOptions Parameters (cont.) Parameter bvCheck2 Description Specifies the initial status of the second check box or option button when the dialog is opened; returns the status of the second check box or option button when the dialog is closed. The following constants are passed and returned in this parameter:

TRUEThe first check box or option button is selected. FALSEThe first check box or option button is not selected.

Up to seven additional options can be defined. Each additional option is indicated by a pair of parametersa string parameter that defines a label and a number variable that indicates the state of the option when AskOptions returns. To set the initial state of an option, assign TRUE or FALSE to the number variable before calling AskOptions.

Note: If nValue is EXCLUSIVE and the initial state of more than one option is set to TRUE, AskOptions preselects the first option in the parameter list that is set to TRUE.

Return Values
Table A-10: AskOptions Return Values Return Value NEXT (1) Description Indicates that the end user clicked the Next button. The states of the controls are returned in the individual bvCheck variables. Indicates that the end user clicked the Back button. The states of the controls are returned in the individual bvCheck variables.

BACK (12)

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

AskOptions Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the AskOptions function. *

474

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AskOptions

* The AskOptions dialog is displayed twice. First, it is * displayed with check boxes; then it is displayed with option * buttons. The example shows the maximum number of options * allowed--nine. * \*----------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_AskOptions(HWND); function ExFn_AskOptions(hMSI) STRING szMsg, szText1, szText2, szText3, szText4, szText5; STRING szText6, szText7, szText8, szText9; NUMBER nReturn, nValue, nvCheck1, nvCheck2, nvCheck3, nvCheck4; NUMBER nvCheck5, nvCheck6, nvCheck7, nvCheck8, nvCheck9; begin szMsg = "Select from the options below."; szText1 szText2 szText3 szText4 szText5 szText6 szText7 szText8 szText9 = = = = = = = = = = = = = = = = = = "Option "Option "Option "Option "Option "Option "Option "Option "Option TRUE; FALSE; FALSE; FALSE; FALSE; FALSE; FALSE; FALSE; FALSE; 1"; 2"; 3"; 4"; 5"; 6"; 7"; 8"; 9";

nvCheck1 nvCheck2 nvCheck3 nvCheck4 nvCheck5 nvCheck6 nvCheck7 nvCheck8 nvCheck9

// Display the check box (NONEXCLUSIVE) dialog. nValue = NONEXCLUSIVE; AskOptions (nValue, szText1, szText2, szText3, szText4, szText5, szText6, szText7, szText8, szText9, szMsg, nvCheck1, nvCheck2, nvCheck3, nvCheck4, nvCheck5, nvCheck6, nvCheck7, nvCheck8, nvCheck9);

// Display the option button (EXCLUSIVE) dialog. nValue = EXCLUSIVE; AskOptions (nValue, szMsg, szText1, nvCheck1, szText2, nvCheck2, szText3, nvCheck3, szText4, nvCheck4,
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 475

Appendix A: Built-In Functions (A-D) AskPath

szText5, szText6, szText7, szText8, szText9, end;

nvCheck5, nvCheck6, nvCheck7, nvCheck8, nvCheck9);

AskPath
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The AskPath function displays a dialog that prompts the end user to enter the path to a destination location. The dialog contains a single-line edit field in which you can display a default path. The end user has three options:

Accept the default path. Edit the default path. Display the Choose Folder dialog to select a folder.

To open the Choose Folder dialog, the end user must click the Browse button. The Choose Folder dialog displays a list of all available folders. The end user can select an existing folder or enter a new folder name. If the end user enters the name of a folder that does not exist, the folder is created.

Caution: AskPath does not verify the existence of the path entered by the end user. After calling AskPath, call CreateDir to create the path.

You cannot use the PlaceWindow function in conjunction with the AskPath function. By default, the dialog opens in the center of the desktop, unless the background window mode is enabled. If the installation is in window mode, the dialog opens in the center of the background window. The default title for the dialog is Choose Destination Location. To change the title, call SetDialogTitle before calling AskPath. The AskPath function accepts the name of a folder that exists but is not writable. To limit the end user's selection to writable folders, call the AskDestPath function instead.

Syntax
AskPath ( szMsg, szDefPath, svResultPath );

476

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AskPath

Parameters
Table A-11: AskPath Parameters Parameter szMsg Description Specifies the message to display in this dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the default path to display in the edit field. The end user can modify this string. Returns the resulting path, regardless of whether the user accepts the default path, modifies it, or selects an alternate path from the Choose Folder dialog. AskPath adds a backslash to the end of the path before placing it into svResultPath. If necessary, that backslash can be removed by calling StrRemoveLastSlash after AskPath returns. If the user clicks the Back button, the value of svResultPath will be unpredictable. Therefore, if you are using the same variable for both szDefPath and svResultPath, be sure to reinitialize that variable when the return value from AskPath is BACK.

szDefPath svResultPath

Note: The edit field displayed in the dialog scrolls to accommodate long strings. Because the number of characters that can be entered into the edit field is not limited, you should declare the variable passed in svResultPath without an explicit size. If the string variable is not large enough to store the text entered by the user, the string is truncated and an error message is displayed. Because this function appends a backslash and a NULL terminator to the end of the string, the size of the string must be at least two characters longer than the path entered by the user.

Return Values
Table A-12: AskPath Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button; svResultPath is set to a null string ("").

Additional Information
AdminAskPath uses the AskPath dialog, and it uses the same dialog resources as AskPath. Therefore, any changes you make to the layout of AskPath in the Dialog Editor are reflected in AdminAskPath.

To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

AskPath Example
Project: This information applies to the following project types:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

477

Appendix A: Built-In Functions (A-D) AskPath

InstallScript InstallScript MSI

/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the AskPath function. * * This script obtains the path to a folder on the * end user's computer. If the path does not exist, it creates * a folder at that location if indicated by the * end user. Finally, it displays the selected path. * \*-----------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_AskPath(HWND); function ExFn_AskPath(hMSI) STRING szMsg, svResultPath[101]; BOOL bTargetDirOk; begin // Disable the Back button in installation dialogs. Disable (BACKBUTTON); // Create the message to display in the AskPath dialog. szMsg = "Specify a folder for the application."; // Initialize valid path indicator. bTargetDirOk = FALSE; repeat // Get a path from the user. The default path is // the current value of the system variable INSTALLDIR. if (AskPath (szMsg, INSTALLDIR, svResultPath) = NEXT) then // Does the path entered by the user exist on the // target system? if (ExistsDir (svResultPath) = 0) then // If it exists, set indicator to exit the loop. bTargetDirOk = TRUE; else // If the path doesn't exists, ask if it should be created. if (AskYesNo ("Folder does not exist. Create it?",YES) = YES) then // Attempt to create the folder (directory). if (CreateDir (svResultPath) = 0) then // If the folder was created, set indicator to exit the loop. bTargetDirOk = TRUE; else // Inform the end user that the folder was not created. MessageBox ("Unable to create " + svResultPath, WARNING); endif; endif; endif; endif; until bTargetDirOk; // Display the name of the target folder.

478

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AskText

MessageBox ("The target folder is " + svResultPath, INFORMATION); // You'd also enable the Back button for subsequent dialogs. Enable (BACKBUTTON); end;

AskText
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The AskText function displays a dialog that contains one static text field and one edit box. Specify default text for the static text field in the parameter szQuestion. Specify default text for the edit box in the parameter szDefault.

You cannot use the PlaceWindow function in conjunction with the AskText function. By default, the dialog appears in the center of the desktop, unless the background window mode is enabled. If the installation is in window mode, the dialog opens in the center of the background window. The default title of this dialog is Enter Information. To change the contents of the title bar, call SetDialogTitle before calling AskText.

Syntax
AskText ( szQuestion, szDefault, svResult );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

479

Appendix A: Built-In Functions (A-D) AskText

Parameters
Table A-13: AskText Parameters Parameter szQuestion Description Specifies the question or statement to display. If the length of the string in this parameter exceeds the width of the static text field, one or more line breaks will be inserted into the string so that it displays on multiple lines in the dialog. If you prefer, you can format the string manually by inserting one or more newline escape sequences ( \n ) into it. This parameter does not have a default value. Specifies the default text for the edit box. The edit box scrolls, if necessary, to accommodate a long string. Returns the text entered by the end user when the Next button is clicked to close the dialog. If the user clicks the Back button, the value of svResult will be unpredictable. Therefore, if you are using the same variable for both szDefault and svResult, be sure to reinitialize that variable when the return value from AskText is BACK.

szDefault

svResult

Note: The string variable that you pass in svResult must be large enough to accommodate the text entered into the edit box. For that reason, you should use the autosize method to declare the variable.

Return Values
Table A-14: AskText Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
The dialog that is displayed by the AskText function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

AskText Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*-----------------------------------------------------------*\ * * InstallShield Example Script

480

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) AskYesNo

* * Demonstrates the AskText function. * * This script gets a company name from the end user. * \*-----------------------------------------------------------*/ #define MSG_TEXT "Please enter your company name." #define DEFAULT_COMPANY "My Software Company" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_AskText(HWND); function ExFn_AskText(hMSI) STRING svCompany, szTitle; NUMBER nResult; begin // Get the company name. nResult = AskText (MSG_TEXT, DEFAULT_COMPANY, svCompany); if nResult = NEXT then // Display the company name that was entered by the user. MessageBox ("Company: " + svCompany, INFORMATION); endif; end;

AskYesNo
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

The AskYesNo function presents a message box that displays a question the end user can answer by clicking a Yes or No button. The AskYesNo message contains four items:

Question mark icon Question text Yes button No button

Note: The default title is Question. To change the contents of the title bar, call SetDialogTitle before calling AskYesNo. The AskYesNo message box is created by a direct call to the corresponding Windows API function, which displays a system modal dialog. Once a modal dialog is displayed, it retains focus until it is closed by the end user.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

481

Appendix A: Built-In Functions (A-D) AskYesNo

Because this dialog is displayed by Windows, the text in the buttons cannot be changed by the installation. That text "Yes" and "No" in the English versionis displayed by Windows in the language appropriate to the version of Windows on which the installation is being run; no manual localization of this text is required. If you need to display a more flexible dialog, call a Windows API function directly or use a custom dialog.

Syntax
AskYesNo ( szQuestion, nDefault );

Parameters
Table A-15: AskYesNo Parameters Parameter szQuestion Description Specifies the question to display in the message box. If the message is too large to fit on one line, embed newline escape characters ( \n ) in the message to insert line breaks. Specifies the button that is selected by default. Pass one of the following predefined constants in this parameter:

nDefault

YESThe Yes button is highlighted when the dialog opens. NOThe No button is highlighted when the dialog opens.

Return Values
Table A-16: AskYesNo Return Values Return Value YES (1) NO (0) Description Indicates that the user clicked the Yes button. Indicates that the user clicked the No button.

Additional Information
The dialog that is displayed by the AskYesNo function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

AskYesNo Example
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

482

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchAdd

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the AskYesNo function. * * This script asks the user whether or not to display the * ReadMe file. If yes, the script launches the Windows * Notepad to open a ReadMe file. * * Note: Before running this script, set the preprocessor * constants so that they reference the fully qualified * names of the Windows Notepad executable and a valid * text file on the target system. * \*-----------------------------------------------------------*/ #define PROGRAM "C:\\Windows\\Notepad.exe" #define PARAM "C:\\Windows\\Readme.txt" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_AskYesNo(HWND); function ExFn_AskYesNo(hMSI) begin // Display the AskYesNo dialog. The default is set to Yes. if (AskYesNo("Installation complete. Would you like to read the Readme " + "file now?", YES) = YES) then LaunchApp(PROGRAM, PARAM); endif; end;

BatchAdd
The BatchAdd function inserts a SET command or other DOS command into a batch file that has been loaded into memory with BatchFileLoad. The parameter nOptions allows you to add the new command as the first or last statement in the file, replace an existing statement with the new command, or specify that the new command be added before or after an existing statement. Before calling BatchAdd, you must call BatchFileLoad to load the file to be modified into memory. After you modify the file, call BatchFileSave to save it to disk. Do not mix the Ez batch file functions with the advanced batch file functions. After calling BatchFileLoad, you cannot use Ez batch file functions until you have called BatchFileSave to save the file.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

483

Appendix A: Built-In Functions (A-D) BatchAdd

Syntax
BatchAdd ( szKey, szValue, szRefKey, nOptions );

484

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchAdd

Parameters
Table A-17: BatchAdd Parameters Parameter szKey Description Specifies the keyword to add to the batch file. PATH, TEMP, and MYENV are examples of valid keys for this parameter. Specifies the value of the key to be added to the batch file. This string must be no longer than 512 bytes; passing a string longer than 512 bytes will cause an installation error. To add a longer string, use the FileGrep and FileInsertLine functions.

szValue

Caution: Batch files do not support long paths completely. If you are using this function to add a line that contains a long path, call LongPathToShortPath to convert the long path to its short path equivalent before adding it to the string to be placed in the batch file. For information on long paths and long file names, refer to Long File Name Format. szRefKey Specifies the reference key relative to which you are adding szKey in the batch file. Specifies where in the file to insert the line. Pass one of the following predefined constants in this parameter:

nOptions

BEFOREThe statement is added before the first line that contains szRefKey. If szRefKey is a null string (""), the statement is added as the first line of the file. AFTERThe statement is added after the last line that contains szRefKey. If szRefKey is a null string (""), the statement is added as the last line of the file. REPLACEThe statement replaces an existing line in the file. If multiple lines with same key exist, only the last line is replaced. If szKey does not exist in the file, a new line will be added after szRefKey. If szRefKey is a null string (""), the new line is added as the last line of the file.

When the statement to be added is not a SET command, pass a null string ("") in szKey, pass the complete command in szValue, and use the OR operator to combine the constant COMMAND with one of the other option constants, as shown below:
BatchAdd("", "PAUSE", "", COMMAND | AFTER);

Note: BatchAdd automatically adds the DOS keyword SET to the beginning of the statement to be inserted unless you use the OR operator to combine the constant COMMAND with the value you pass in nOptions. If you do not explicitly specify REPLACE in nOptions, the specified statement is added even if a duplicate line exists in the batch file.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

485

Appendix A: Built-In Functions (A-D) BatchAdd

Return Values
Table A-18: BatchAdd Return Values Return Value 0 Description BatchAdd successfully added a SET statement or other command to the batch file. BatchAdd was unable to add the SET statement or other command to the batch file.

<0

Additional Information
An InstallScript reference key is either an environment variable, a DOS command, or a program file name. Environment variables are keywords such as PATH, COMSPEC, LIB, or other predefined or userdefined identifiers. The value of an environment variable is established by using the DOS SET command. Statements that appear in a batch file must be either DOS commands, program names (with or without command-line parameters), or comments. Refer to your operating system manual for a detailed definition of commands and environment variables.

BatchAdd Example
The following example applies to:

InstallScript/InstallScript MSI Installations

/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the BatchAdd function. * * This example script adds three statements to a batch file. * First, it adds a PATH statement. Next, it adds a command to * set the environment variable EXENV. Then it adds a command * to launch SHARE.EXE, placing it before the existing command * to start Windows. Finally, it backs up the original file * and saves the edited file under its original name. * * If any of the calls to BatchAdd fails, the setup exits * without saving changes to the batch file. * * Note: Before running this script, create a batch file * named ISExampl.bat in the root of drive C. For * best effect, that file should include the following * lines: * * PATH=C:\Windows * Win * \*-----------------------------------------------------------*/ #define EXAMPLE_BAT "C:\\ISEXAMPL.BAT" #define EXAMPLE_BAK "ISEXAMPL.BAK"

486

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchAdd

STRING szPath; // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" function OnBegin() begin // Load the batch file to be edited. if (BatchFileLoad (EXAMPLE_BAT) < 0) then MessageBox ("Unable to load " + EXAMPLE_BAT+".", SEVERE); abort; endif; // Add a SET PATH command that appends the value of an existing // search path to C:\EXAPP\BIN. szPath = "C:\\EXAPP\\BIN;%PATH%"; if (BatchAdd ("PATH", szPath, "PATH", AFTER) < 0) then MessageBox ("First call to BatchAdd failed", WARNING); abort; endif; // Add the line SET EXENV = C:\OTHERAPP\BIN. If the // environment variable EXENV already exists in the batch // file, the last SET EXENV statement is replaced. szPath = "C:\\OTHERAPP\\BIN"; if (BatchAdd ("EXENV", szPath, "EXENV", REPLACE) < 0) then MessageBox ("Second call to BatchAdd failed", WARNING); abort; endif; // Add the command SHARE.EXE before the command WIN. if (BatchAdd ("", "SHARE.EXE", "WIN", BEFORE | COMMAND) < 0) then MessageBox ("Third call to BatchAdd failed", WARNING); abort; endif; // Save the updated file; back up the original file. if (BatchFileSave(EXAMPLE_BAK) < 0) then MessageBox ("Unable to save " + EXAMPLE_BAK + ".", SEVERE); else MessageBox ("Batch file saved. Backup created.",INFORMATION); endif; end;

The following example applies to:

Basic MSI Installations

Tip: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the BatchAdd function.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

487

Appendix A: Built-In Functions (A-D) BatchAdd

* * This example script adds three statements to a batch file. * First, it adds a PATH statement. Next, it adds a command to * set the environment variable EXENV. Then it adds a command * to launch SHARE.EXE, placing it before the existing command * to start Windows. Finally, it backs up the original file * and saves the edited file under its original name. * * If any of the calls to BatchAdd fails, the setup exits * without saving changes to the batch file. * * Note: Before running this script, create a batch file * named ISExampl.bat in the root of drive C. For * best effect, that file should include the following * lines: * * PATH=C:\Windows * Win * \*-----------------------------------------------------------*/ #define EXAMPLE_BAT "C:\\ISEXAMPL.BAT" #define EXAMPLE_BAK "ISEXAMPL.BAK" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_BatchAdd(HWND); function ExFn_BatchAdd(hMSI) STRING szPath; begin // Load the batch file to be edited. if (BatchFileLoad (EXAMPLE_BAT) < 0) then MessageBox ("Unable to load " + EXAMPLE_BAT+".", SEVERE); abort; endif; // Add a SET PATH command that appends the value of an existing // search path to C:\EXAPP\BIN. szPath = "C:\\EXAPP\\BIN;%PATH%"; if (BatchAdd ("PATH", szPath, "PATH", AFTER) < 0) then MessageBox ("First call to BatchAdd failed", WARNING); abort; endif; // Add the line SET EXENV = C:\OTHERAPP\BIN. If the // environment variable EXENV already exists in the batch // file, the last SET EXENV statement is replaced. szPath = "C:\\OTHERAPP\\BIN"; if (BatchAdd ("EXENV", szPath, "EXENV", REPLACE) < 0) then MessageBox ("Second call to BatchAdd failed", WARNING); abort; endif; // Add the command SHARE.EXE before the command WIN. if (BatchAdd ("", "SHARE.EXE", "WIN", BEFORE | COMMAND) < 0) then MessageBox ("Third call to BatchAdd failed", WARNING); abort;
488 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchDeleteEx

endif; // Save the updated file; back up the original file. if (BatchFileSave(EXAMPLE_BAK) < 0) then MessageBox ("Unable to save " + EXAMPLE_BAK + ".", SEVERE); else MessageBox ("Batch file saved. Backup created.",INFORMATION); endif; end;

BatchDeleteEx
The BatchDeleteEx function deletes lines in a batch file that contain the value specified in szKey.

Note: Before calling BatchDeleteEx, you must call BatchFileLoad to load the file to be modified into memory. After you modify the file, call BatchFileSave to save it to disk. Do not mix the Ez batch file functions with the advanced batch file functions. After calling BatchFileLoad, you cannot use Ez batch file functions until you have called BatchFileSave to save the file.

Syntax
BatchDeleteEx ( szKey, nOptions );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

489

Appendix A: Built-In Functions (A-D) BatchDeleteEx

Parameters
Table A-19: BatchDeleteEx Parameters Parameter szKey Description Specifies the reference keyword that identifies the line or lines to be deleted. Indicates whether szKey specifies an environment variable in a SET statement or a command. Pass one of the following predefined constants in this parameter:

nOptions

0Specifies that szKey is an environment variable in a SET statement. An environment variable is either a predefined identifier (such as PATH, COMSPEC, and LIB), or a userdefined identifier. For example, the following statement would be deleted if the value of szKey was "LIBPATH" and nOptions was set to 0: COMMANDSpecifies that szKey is either a DOS command or a program file name.

SET LIBPATH=C:\Lang\Lib

Return Values
Table A-20: BatchDeleteEx Return Values Return Value 0 Description BatchDeleteEx successfully deleted lines containing the specified value. BatchFileLoad was unable to delete lines containing the specified value.

<0

BatchDeleteEx Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the BatchDeleteEx function. * * This example script deletes lines from a batch file. First, * it calls BatchFileLoad to load the file. Next, it deletes

490

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchFileLoad

* all lines with a PATH command. Then it deletes all lines * that reference MyApp.exe (for example, C:\MyApps\MyApp.exe). * Finally, it backs up the original file and saves the * edited file under its original name. * * Note: Before running this script, create a batch file * named ISExampl.bat in the root of drive C. For * best effect, that file should include the * following lines: * * SET PATH=C:\Windows * C:\MyApps\MyApp.exe * \*-----------------------------------------------------------*/ #define EXAMPLE_BAT "C:\\ISExampl.bat" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_BatchDeleteEx(HWND); function ExFn_BatchDeleteEx(hMSI) STRING szBackupFile; begin // Load or create the batch file to be edited. if (BatchFileLoad (EXAMPLE_BAT) < 0) then MessageBox ("Unable to load " + EXAMPLE_BAT + ".", SEVERE); abort; endif; // Delete all SET PATH= commands. BatchDeleteEx ("PATH", 0); // Delete all lines with references to MyApp.exe. BatchDeleteEx ("MyApp.exe", COMMAND); // Save the edited batch file. if (BatchFileSave("Example.bak") < 0) then MessageBox ("Unable to save " + EXAMPLE_BAT + ".", SEVERE); else MessageBox ("Batch file saved.",INFORMATION); endif; end;

BatchFileLoad
The BatchFileLoad function loads a copy of the specified batch file into memory so that other advanced batch file functions can be called to operate on the file. Specify the name of the batch file you want to edit in szBatchFile or pass a null string ("") in szBatchFile to edit the default batch file, which is set initially by InstallShield to the bootup Autoexec.bat file used by the system. Note that you can call BatchFileLoad to create a new batch file. To do so, pass in szBatchFile the name of a file that does not exist. Then call other batch functions to edit the new file. Finally, call BatchFileSave to save the new file to disk.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

491

Appendix A: Built-In Functions (A-D) BatchFileLoad

Note: Before using any of the advanced batch file functions, you must call BatchFileLoad to load the file to be modified into memory. After you modify the file, call BatchFileSave to save it to disk. To obtain the fully qualified file name of the batch file that will be used by default in the installation script, call BatchGetFileName. To specify a different batch file to be used by default in the installation script, call BatchSetFileName. Do not mix the Ez batch file functions with the advanced batch file functions. After calling BatchFileLoad, you cannot use Ez batch file functions until you have called BatchFileSave to save the file.

Syntax
BatchFileLoad ( szBatchFile );

Parameters
Table A-21: BatchFileLoad Parameters Parameter szBatchFile Description Specifies the fully qualified name of the batch file to load into memory. To load the current default batch file, pass a null string (""). If you specify a file in this parameter, that file becomes the default batch file. After calling this function, you can use all of the advanced batch file functions to manipulate this file. To create a new batch file with BatchFileLoad, pass in szBatchFile the name of a file that does not exist. Then call other batch functions to edit the new file.

Return Values
Table A-22: BatchFileLoad Return Values Return Value 0 Description BatchFileLoad successfully initialized the batch file buffer. If szConfigFile specified an existing batch file, the file was loaded into the buffer; otherwise, an empty buffer was created. BatchFileLoad was unable to initialize the batch file buffer.

<0

BatchFileLoad Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
492 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchFileLoad

/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the BatchFileLoad and BatchFileSave functions. * * This example script shows how to open a batch file for * editing, how to create a backup of the original file, and * how to save and close the edited file. * * To demonstrate how the file backup feature of BatchFileSave * prevents the overwriting of existing files, this script loads * and saves two different batch files. The first batch file is * backed up with a specific file name. The second is backed up * with a wildcard extension so that BatchFileSave will * generate a unique file extension consisting of three digits. * * Note: Before running this script, create two batch files * (ISExamp1.bat and ISExamp2.bat) in the root of drive C. * For best effect, you should delete or move any other * files named ISExamp1.* or ISExamp2.*. * \*-----------------------------------------------------------*/ // Names of batch files and backup files used in this example. #define EXAMPLE1 "ISExamp1" #define EXAMPLE2 "ISExamp2" // Full names of batch files. #define EXAMPLE1_BAT "C:\\" + EXAMPLE1 + ".bat" #define EXAMPLE2_BAT "C:\\" + EXAMPLE2 + ".bat" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_BatchFileLoad(HWND); function ExFn_BatchFileLoad(hMSI) begin // Load EXAMPLE1_BAT. if (BatchFileLoad (EXAMPLE1_BAT) < 0) then MessageBox ("Unable to load " + EXAMPLE1_BAT + ".", SEVERE); abort; endif; // // // // if Use other batch file functions here to edit the first file. Back up the original file with the extension "bak"; save the edited file under its original name. If ISExamp1.bak already exists, BatchFileSave will generate a numbered extension. (BatchFileSave (EXAMPLE1 + ".bak") < 0) then MessageBox ("Unable to save " + EXAMPLE1_BAT + ".", SEVERE); abort; else MessageBox (EXAMPLE1_BAT + " saved.",INFORMATION); endif; // Load EXAMPLE2_BAT. if (BatchFileLoad (EXAMPLE2_BAT) < 0) then MessageBox ("Unable to load " + EXAMPLE2_BAT + ".", SEVERE); abort; endif;
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 493

Appendix A: Built-In Functions (A-D) BatchFileSave

// // // if

Use other batch file functions here to edit the second file. Back up the original batch file with a numbered extension and save the edited file under its original name. (BatchFileSave (EXAMPLE2 + ".*") < 0) then MessageBox ("Unable to save " + EXAMPLE2_BAT + ".", SEVERE); abort; else MessageBox (EXAMPLE2_BAT + " saved.",INFORMATION); endif; end;

BatchFileSave
The BatchFileSave function saves to disk a batch file that has been loaded into memory with the function BatchFileLoad. The file is saved under its original name. If a file name is specified in szBackupFile, the original file is renamed with that file name before the edited file is written to disk. If szBackupFile contains a null string (""), the original file is replaced with the modified file. If you do not call BatchFileSave when you are finished modifying a batch file with advanced batch file functions, all modifications will be lost.

Note: Do not mix the Ez batch file functions with the advanced batch file functions. After calling BatchFileLoad, you cannot use Ez batch file functions until you have called BatchFileSave to save the file.

Syntax
BatchFileSave ( szBackupFile );

494

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchFileSave

Parameters
Table A-23: BatchFileSave Parameters Parameter szBackupFile Description Specifies whether a backup copy of the original file as it existed before editing should be saved.

If no backup file should be created, specify a null string in this parameter. If the original file should be backed up with a specific name, pass that file name in this parameter. The file name must be unqualified (that is, do not specify a drive and/or path). Note that if a file with the specified name already exists, BatchFileSave will generate a unique file extension, as described in the next bullet item. If the original file should be backed up with an installation-generated file extension, specify the wildcard character "" as the file extension (for example, "Batch."). The installation will then assign a numeric value, starting at 001, as the extension. If a file already exists with that extension, the extension's value will be increased by one until a unique file name is created.

Once the backup has been created, InstallShield stores the backup file name in the system variable INFOFILENAME.

Note: If the batch file specified by the last call to BatchFileLoad did not exist, then the backup file is identical to the batch file created by the call to BatchFileSave. If szBackupFile specifies the name of the original batch file, then a backup file is not created.

Return Values
Table A-24: BatchFileSave Return Values Return Value 0 Description BatchFileSave successfully saved the batch file in memory to disk.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

495

Appendix A: Built-In Functions (A-D) BatchFileSave

Table A-24: BatchFileSave Return Values (cont.) Return Value <0 Description BatchFileSave was unable to save the batch file to disk.

BatchFileSave Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the BatchFileLoad and BatchFileSave functions. * * This example script shows how to open a batch file for * editing, how to create a backup of the original file, and * how to save and close the edited file. * * To demonstrate how the file backup feature of BatchFileSave * prevents the overwriting of existing files, this script loads * and saves two different batch files. The first batch file is * backed up with a specific file name. The second is backed up * with a wildcard extension so that BatchFileSave will * generate a unique file extension consisting of three digits. * * Note: Before running this script, create two batch files * (ISExamp1.bat and ISExamp2.bat) in the root of drive C. * For best effect, you should delete or move any other * files named ISExamp1.* or ISExamp2.*. * \*-----------------------------------------------------------*/ // Names of batch files and backup files used in this example. #define EXAMPLE1 "ISExamp1" #define EXAMPLE2 "ISExamp2" // Full names of batch files. #define EXAMPLE1_BAT "C:\\" + EXAMPLE1 + ".bat" #define EXAMPLE2_BAT "C:\\" + EXAMPLE2 + ".bat" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_BatchFileSave(HWND); function ExFn_BatchFileSave(hMSI) begin // Load EXAMPLE1_BAT. if (BatchFileLoad (EXAMPLE1_BAT) < 0) then MessageBox ("Unable to load " + EXAMPLE1_BAT + ".", SEVERE); abort;

496

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchFind

endif; // // // // if Use other batch file functions here to edit the first file. Back up the original file with the extension "bak"; save the edited file under its original name. If ISExamp1.bak already exists, BatchFileSave will generate a numbered extension. (BatchFileSave (EXAMPLE1 + ".bak") < 0) then MessageBox ("Unable to save " + EXAMPLE1_BAT + ".", SEVERE); abort; else MessageBox (EXAMPLE1_BAT + " saved.",INFORMATION); endif; // Load EXAMPLE2_BAT. if (BatchFileLoad (EXAMPLE2_BAT) < 0) then MessageBox ("Unable to load " + EXAMPLE2_BAT + ".", SEVERE); abort; endif; // // // if Use other batch file functions here to edit the second file. Back up the original batch file with a numbered extension and save the edited file under its original name. (BatchFileSave (EXAMPLE2 + ".*") < 0) then MessageBox ("Unable to save " + EXAMPLE2_BAT + ".", SEVERE); abort; else MessageBox (EXAMPLE2_BAT + " saved.",INFORMATION); endif; end;

BatchFind
The BatchFind function searches a batch file for one or more occurrences of the reference key specified in szRefKey. If you specify the constant RESTART in nOptions, the first occurrence of the reference key is returned. To find the next occurrence of szRefKey, call this function repeatedly with nOptions set to CONTINUE.

Note: Before calling BatchFind, you must call BatchFileLoad to load the file to be modified into memory. After you modify the file, call BatchFileSave to save it to disk. Do not mix the Ez batch file functions with the advanced batch file functions. After calling BatchFileLoad, you cannot use Ez batch file functions until you have called BatchFileSave to save the file.

Syntax
BatchFind ( szRefKey, svResult, nOptions );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

497

Appendix A: Built-In Functions (A-D) BatchFind

Parameters
Table A-25: BatchFind Parameters Parameter szRefKey Description Specifies the reference key to search for. The reference key can be an environment variable, a DOS command, or a program name. If the reference key is a file name and you do not specify a file extension, the function returns all reference keys with the base file name. For example, if you specify Win.com, the search looks for this reference key only. If you specify Win, the reference keys Win.exe, Win.dll, Win.sys, and so on will be returned if they exist in the batch file. Specifies the value of the reference key that was found in the batch file. Specifies where to start the search; pass one of the following predefined constants in this parameter:

svResult

nOptions

CONTINUEStarts the search from the current position in the batch file. RESTARTStarts the search from the beginning of the batch file.

When the reference key you are searching for is a DOS command or program name (not an environment variable), use the OR operator to combine the constant COMMAND with CONTINUE or RESTART, as shown below:
BatchFind ("SCAN.EXE", svResult, COMMAND | RESTART);

Return Values
Table A-26: BatchFind Return Values Return Value 0 Description BatchFind successfully found the value of szRefKey and returned it in svResult. BatchFind was unable to find the value of szRefKey and return it in svResult.

<0

BatchFind Example

498

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchFind

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the BatchFind function. * * This example script searches a batch file and reports whether * or not the file includes a command that references SHARE.EXE. * It then finds and displays all PATH and SET PATH statements. * * Note: Before running this script, create a batch file * named ISExampl.bat and store it in the root of * drive C. The batch file should include a command * to launch Share.exe, and it should contain at least * one PATH or SET PATH= statement. * \*-----------------------------------------------------------*/ #define TARGET_BATCH "C:\\ISExampl.bat" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_BatchFind(HWND); function ExFn_BatchFind(hMSI) STRING svResult; NUMBER nResult; begin // Load the target batch file. if (BatchFileLoad (TARGET_BATCH ) < 0) then MessageBox ("Unable to load " + TARGET_BATCH abort; endif;

+ ".", SEVERE);

// Check for a SHARE.EXE command. nResult = BatchFind ("SHARE.EXE", svResult, COMMAND); if (nResult < 0) then MessageBox ("SHARE.EXE command not found.", WARNING); else MessageBox ("SHARE.EXE command found.", INFORMATION); endif; // Find the first PATH or SET PATH= statement. Pass RESTART in // the third parameter to begin searching at the top of the file. nResult = BatchFind ("PATH", svResult, RESTART); if (nResult < 0) then MessageBox ("PATH command not found.", WARNING); else // Loop while PATH commands are found. while (nResult = 0) MessageBox (svResult, INFORMATION);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 499

Appendix A: Built-In Functions (A-D) BatchGetFileName

// Find the next PATH command. Pass CONTINUE in the // third parameter to continue the search with the // statement that follows the last match. nResult = BatchFind ("PATH", svResult, CONTINUE); endwhile; MessageBox ("No more PATH commands.", WARNING); endif; end;

BatchGetFileName
The BatchGetFileName function retrieves the fully qualified name of the default batch file, which is set initially by InstallShield to the bootup Autoexec.bat file used by the system. To specify a different batch file to be used by default in the script, call BatchSetFileName.

Note: Do not mix the Ez batch file functions with the advanced batch file functions. After calling BatchFileLoad, you cannot use Ez batch file functions until you have called BatchFileSave to save the file.

Syntax
BatchGetFileName ( svFileName );

500

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchGetFileName

Parameters
Table A-27: BatchGetFileName Parameters Parameter svFileName Description Returns the fully qualified name of the default batch file in svFileName.

Return Values
Table A-28: BatchGetFileName Return Values Return Value 0 Description BatchGetFileName successfully retrieved the fully qualified name of the default batch file. BatchGetFileName was unable to retrieve the fully qualified name of the default batch file.

<0

BatchGetFileName Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the BatchGetFileName and BatchSetFileName * functions. * * This example script retrieves the fully qualified name of the * default batch file, which initially is the Autoexec.bat file * on the boot drive. It then makes C:\ISExampl.bat the default * batch file. Finally, it retrieves the name of the default * batch file again to show that it has been changed. * \*-----------------------------------------------------------*/ #define DEFAULT_BATCH_FILE "C:\\ISExampl.bat" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_BatchGetFileName(HWND); function ExFn_BatchGetFileName(hMSI) STRING svFilename; begin // Get the name of the default batch file.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

501

Appendix A: Built-In Functions (A-D) BatchMoveEx

if (BatchGetFileName (svFilename) < 0) then // Report the error; then abort. MessageBox ("First call to BatchGetFileName failed.", SEVERE); abort; else // Display the name of the default batch file. MessageBox ("The default batch file is " + svFilename + ".", INFORMATION); endif; // Make C:\ISExampl.bat the default batch file. if (BatchSetFileName(DEFAULT_BATCH_FILE) < 0) then // Report the error. MessageBox ("Unable to set new default batch file.", SEVERE); else // Verify that the default batch file has been changed. if (BatchGetFileName(svFilename) < 0) then // Handle an error. MessageBox ("Second call to BatchGetFileName failed.", SEVERE); else // Display the name of the default batch file. MessageBox ("Now the default batch file is " + svFilename + ".", INFORMATION); endif; endif; end;

BatchMoveEx
The BatchMoveEx function moves the line specified by szMove from one location to another in a batch file. The parameter nOptions specifies whether to position the line at the beginning or end of the batch file, or before or after the line specified by szRefKey.

Note: Before calling BatchMoveEx, you must call BatchFileLoad to load the file to be modified into memory. After you modify the file, call BatchFileSave to save it to disk. Do not mix the Ez batch file functions with the advanced batch file functions. After calling BatchFileLoad, you cannot use Ez batch file functions until you have called BatchFileSave to save the file.

Syntax
BatchMoveEx ( szMove, szRefKey, nOptions, nMoveOption );

502

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchMoveEx

Parameters
Table A-29: BatchMoveEx Parameters Parameter szMove Description Specifies the reference key that identifies the line to be moved. Specifies the key that identifies the reference line used to position the line being moved. If szRefKey is a null string (), the line specified by szMove is moved to the beginning or end of the file, depending on the value of nOptions. Specifies where to move the line. Pass one of the following predefined constants in this parameter:

szRefKey

nOptions

BEFOREThe line specified by szMove is moved before the line containing the reference key in szRefKey. If szRefKey is a null string (), the line specified by szMove is moved to the beginning of the file. AFTERThe line specified by szMove is moved after the line containing the reference key in szRefKey. If szRefKey is a null string (), the line specified by szMove is moved to the end of the file. When the reference key you are searching for is a DOS command or program name (not an environment variable), use the OR operator to combine the constant COMMAND with BEFORE or AFTER, as shown below:

BatchMoveEx (PATH, SCAN.EXE, BEFORE | COMMAND, 0);

nMoveOption

Specifies whether szMove is a command or an environment variable. Pass one of the following predefined constants in this parameter:

0Specifies that szMove is an environment variable. COMMANDSpecifies that szMove is a command.

Return Values
Table A-30: BatchMoveEx Return Values Return Value 0 Description BatchMoveEx successfully moved the specified line in the batch file.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

503

Appendix A: Built-In Functions (A-D) BatchMoveEx

Table A-30: BatchMoveEx Return Values (cont.) Return Value <0 Description BatchMoveEx was unable to move the line in the batch file.

BatchMoveEx Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the BatchMoveEx function. * * This example script moves lines within a batch file. First, * it calls BatchFileLoad to load the file. Next, it moves * the first PATH command to the end of the file. Then it * moves the first statement that references Share.exe ahead * of the statement that launches Windows. * * Note: Before running this script, create a batch file * named ISExampl.bat in the root of drive C. For * best effect, the first line in that file should * be a PATH command; the next statement should * launch Windows; the last statement should execute * Share.exe. * \*-----------------------------------------------------------*/ #define TARGET_BATCH "C:\\ISExampl.bat" #define BACKUP_BATCH "ISExampl.bak" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_BatchMoveEx(HWND); function ExFn_BatchMoveEx(hMSI) begin // Load the batch file to be edited. if BatchFileLoad (TARGET_BATCH) < 0 then MessageBox ("Unable to load " + TARGET_BATCH+".", SEVERE); abort; endif; // Move the PATH statement to the end of the file. if (BatchMoveEx ("PATH", "", AFTER, 0) < 0) then MessageBox ("Unable to move PATH statement.", SEVERE); else MessageBox ("PATH statement moved to end of file.", INFORMATION); endif;

504

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) BatchSetFileName

// Move the SHARE.EXE command before the WIN statement. if (BatchMoveEx ("SHARE.EXE", "WIN", BEFORE|COMMAND, COMMAND) < 0) then MessageBox ("Unable to move SHARE.EXE statement.", SEVERE); else MessageBox ("SHARE.EXE statement moved before WIN statement.", INFORMATION); endif; // Save the updated file; back up the original file. if BatchFileSave (BACKUP_BATCH) < 0 then MessageBox ("Unable to save " + BACKUP_BATCH+".", SEVERE); else MessageBox ("Batch file saved. Backup created.", INFORMATION); endif; end;

BatchSetFileName
The BatchSetFileName function specifies the name of the batch file to be used by Ez batch file functions and by BatchFileLoad when it is called with a null string ("") as its parameter. In InstallScript, this file is referred to as the default batch file. During installation initialization, the default batch file is set to the bootup Autoexec.bat file used by the system. BatchSetFileName simply assigns the name of the default batch file. It does not verify that the specified file exists, nor does it load the file into memory. Because of this, the function will succeed even if the file name is invalid or the specified file does not exist. An invalid file name causes subsequent Ez batch file and advanced batch file functions to fail.

Note: Do not mix the Ez batch file functions with the advanced batch file functions. After calling BatchFileLoad, you cannot use Ez batch file functions until you have called BatchFileSave to save the file.

Syntax
BatchSetFileName ( szBatchFile );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

505

Appendix A: Built-In Functions (A-D) BatchSetFileName

Parameters
Table A-31: BatchSetFileName Parameters Parameter szBatchFile Description Specifies the fully qualified name of the batch file to be used by default in the installation script.

Return Values
Table A-32: BatchSetFileName Return Values Return Value 0 Description BatchSetFileName successfully set the specified file as the default batch file. BatchSetFileName was unable to set the file as the default batch file.

<0

BatchSetFileName Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the BatchGetFileName and BatchSetFileName * functions. * * This example script retrieves the fully qualified name of the * default batch file, which initially is the Autoexec.bat file * on the boot drive. It then makes C:\ISExampl.bat the default * batch file. Finally, it retrieves the name of the default * batch file again to show that it has been changed. * \*-----------------------------------------------------------*/ #define DEFAULT_BATCH_FILE "C:\\ISExampl.bat" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_BatchSetFileName(HWND); function ExFn_BatchSetFileName(hMSI) STRING svFilename; begin // Get the name of the default batch file.

506

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CalculateAndAddFileCost

if (BatchGetFileName (svFilename) < 0) then // Report the error; then abort. MessageBox ("First call to BatchGetFileName failed.", SEVERE); abort; else // Display the name of the default batch file. MessageBox ("The default batch file is " + svFilename + ".", INFORMATION); endif; // Make C:\ISExampl.bat the default batch file. if (BatchSetFileName(DEFAULT_BATCH_FILE) < 0) then // Report the error. MessageBox ("Unable to set new default batch file.", SEVERE); else // Verify that the default batch file has been changed. if (BatchGetFileName(svFilename) < 0) then // Handle an error. MessageBox ("Second call to BatchGetFileName failed.", SEVERE); else // Display the name of the default batch file. MessageBox ("Now the default batch file is " + svFilename + ".", INFORMATION); endif; endif; end;

CalculateAndAddFileCost
The CalculateAndAddFileCost function determines the cost of the specified file and adds it to the current value of nvCostHigh and/or nvCostLow. This allows you to calculate and add up the cost of multiple files by calling the function multiple times in a loop. Set nvCostHigh and nvCostLow to zero before calling the function to determine the cost of a single file. This function is typically used when you need to determine the cost of file of a known size so this cost can then be passed to FeatureAddCost.

Note: Note that this function does not actually set any information to be used directly by the installation. You must call FeatureAddCost (as appropriate) after calling this function to add the additional cost to an existing feature.

Syntax
CalculateAndAddFileCost ( nFileSizeHigh, nFileSizeLow, szTargetDir, nClusterSize, nvCostHigh, nvCostLow );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

507

Appendix A: Built-In Functions (A-D) CallDLLFx

Parameters
Table A-33: CalculateAndAddFileCost Parameters Parameter nFileSizeHigh Description The upper 31 bits of the file size (in bytes). Typically retrieved using GetFileInfo. The lower 31 bits of the file size (in bytes). Typically retrieved using GetFileInfo. If nClusterSize is 0, the target folder for the file. This path is used to determine the cluster size of the target drive. If nClusterSize is non-zero, this parameter is ignored. Specifies the cluster size of the target drive. If this parameter is 0, the function determines this information from szTargetDir. The upper 31 bits of the installation cost (in bytes) of this file is added to the current value of this variable. The lower 31 bits of the installation cost (in bytes) of this file is added to the current value of this variable.

nFileSizeLow

szTargetDir

nClusterSize

nvCostHigh

nvCostLow

Return Values
Table A-34: CalculateAndAddFileCost Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

CallDLLFx
Tip: The CallDLLFx function is supported only for compatibility with scripts created in previous versions of InstallShield. Consider using the more flexible method described in Calling a .dll File Function instead of using the CallDLLFx function.

The CallDLLFx function calls a function within a specified .dll file.

Syntax
CallDLLFx ( szDLL, szFunction, lvValue, svValue );

508

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CallDLLFx

The function called must use the following fixed definition, where hwnd is the main window handle for the main InstallShield window:
LONG APIENTRY YourFunction (HWND hwnd, LPLONG lpIValue, LPSTR lpszValue);

Parameters
Table A-35: CallDLLFx Parameters Parameter szDLL Description Specifies the fully qualified file name of the .dll file that contains the function to execute. Specifies the name of the function in the .dll file specified in szDLL. Specifies a long integer variable to pass by reference to the .dll function. Specifies a string variable to pass to the .dll function.

szFunction

lvValue

svValue

Return Values
The CallDLLFx function returns a long integer from the function in the .dll file.

CallDLLFx Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CallDLLFx function. * * Note: This script requires that the constant DLL_FILE be set * to the fully qualified name of a .dll file that contains * a function called Test whose format matches the * prototype declaration below. That function should * modify the values passed in the third and fourth * parameters and then return those values in the same * parameters. * \*-----------------------------------------------------------*/ #define ID_NEXT 1 // Return value if user clicks 'Next' button #define ID_CANCEL 2 // Return value if user clicks 'Cancel' button #define ID_BACK 4 // Return value if user clicks 'Back' button

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

509

Appendix A: Built-In Functions (A-D) ChangeDirectory

export prototype ExFn_CallDLLFx(HWND); function ExFn_CallDLLFx(hMSI) INT nValue, nResult; STRING szString, szResult, szDLL, szValue, szReturn; begin // Set the setup window title. SetTitle ("CallDLLFx Example", 18, WHITE); // Set the location of the .dll. szDLL = SUPPORTDIR ^ "MYDLL.DLL"; // Set up parameters for call to .dll function. nValue = 3000; szString = "Test String"; // Show inputs to users. SprintfBox (INFORMATION, nValue, szString);

"", "Before - nValue: %i , szString: %s",

// Call .dll function; pass by value. nResult = CallDLLFx(szDLL, "Test", nValue, szString); // Show values returned by .dll function. SprintfBox(INFORMATION, "", "Returned - nValue: %i , szString: %s", nValue, szString); end;

ChangeDirectory
The ChangeDirectory function sets the current directory.

Note: After you call ChangeDirectory to make a specified directory the current directory, that directory cannot be deleted. Before you can delete that directory, you must call ChangeDirectory again to set a different current directory.

Syntax
ChangeDirectory ( szPath );

510

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ChangeDirectory

Parameters
Table A-36: ChangeDirectory Parameters Parameter szPath Description Specifies the name of the directory to set as the current directory. That name can be either a fully qualified directory name or a UNC path; it must not include a trailing backslash. If necessary, call StrRemoveLastSlash before calling ChangeDirectory.

Note: When you are specifying a file in your script, always specify the full path (using the appropriate InstallShield system variable, for example, SRCDIR) rather than depend on the current folder having the appropriate value. The script internally executes code that can change the current folder, so its value may not be what you expect.

Return Values
Table A-37: ChangeDirectory Return Values Return Value 0 Description ChangeDirectory successfully set the specified directory as the current directory. ChangeDirectory was unable to set the specified directory as the current directory.

<0

ChangeDirectory Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ChangeDirectory function. * * This example script makes the Windows folder the current * directory and then launches NotePad to display the file * Readme.txt. * \*-----------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 511

Appendix A: Built-In Functions (A-D) CharReplace

#include "Ifx.h" export prototype ExFn_ChangeDirectory(HWND); function ExFn_ChangeDirectory(hMSI) begin // Make the Windows folder the default directory. Note that // the InstallShield system variable WINDIR points // to the Windows folder.

ChangeDirectory (WINDIR); // Launch Notepad to view the Windows Readme.txt file. LaunchApp ("Notepad.exe", "Readme.txt" ); end;

CharReplace
The CharReplace function replaces all instances of the character cFind with cReplace in the string svString, except characters whose string index is less than nStart. The string index of the first character in a string is 0.

Syntax
CharReplace ( svString, cFind, cReplace, nStart );

512

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CharReplace

Parameters
Table A-38: CharReplace Parameters Parameter svString cFind Description Specifies the string whose characters will be replaced, and returns the modified string. Specifies the character to be replaced. Use the STRTOCHAR function to specify a char literal as cFind; for example:
CharReplace( svString, STRTOCHAR('a'), STRTOCHAR('e'), nStart );

cReplace

Specifies the character to replace cFind. Use the STRTOCHAR function to specify a char literal as cReplace; for example:
CharReplace( svString, STRTOCHAR('a'), STRTOCHAR('e'), nStart );

nStart

Specifies the string index at which to begin searching for cFind. Note that the string index of the first character in svString is 0 (zero). If you want to replace all instances of cFind in svString, specify 0 for nStart.

Return Values
Table A-39: CharReplace Return Values Return Value X < ISERR_SUCCESS Description The total number of replacements of cFind by cReplace. The function failed to replace the characters.

Additional Information
cFind or cReplace can be null characters ('\0'). To handle null-delimited strings, specify cFind or cReplace as StrToChar('\0'); note that the constant NULL is 0, not '\0', and cannot be used to specify the null character. When cFind or cReplace is '\0', CharReplace automatically sets the last two characters of the string buffer to '\0' before returning; therefore, the size of the string (which should be set explicitly) should be at least the number of characters to be stored plus two.

CharReplace Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
//--------------------------------------------------------------------------// // InstallScript Example Script // // Demonstrates the CharReplace function. // // This sample shows a sample path string before and after replacing

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

513

Appendix A: Built-In Functions (A-D) CloseFile

// every backslash character with a forward slash. // //--------------------------------------------------------------------------function OnBegin( ) STRING path_to_convert; begin // example path to convert path_to_convert = FOLDER_COMMON_APPDATA; MessageBox("Path before conversion: " + path_to_convert, INFORMATION); // replace backslashes with forward slashes CharReplace(path_to_convert, STRTOCHAR('\\'), STRTOCHAR('/'), 0); MessageBox("Path after conversion: " + path_to_convert, INFORMATION); end;

CloseFile
The CloseFile function closes a file that has been opened with a call to OpenFile. You cannot read from or write to a file after you close it.

Syntax
CloseFile ( nvFileHandle );

514

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CloseFile

Parameters
Table A-40: CloseFile Parameters Parameter nvFileHandle Description Specifies the handle of the file to be closed.

Return Values
Table A-41: CloseFile Return Values Return Value 0 Description Indicates that the function successfully closed the file. Indicates that the function was unable to close the file.

<0

CloseFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the OpenFile and CloseFile functions. * * OpenFile is called to open a file, which is then read into * a list. The file is then closed and the list is displayed. * * Note: Before running this script, set the preprocessor * constants so that they reference an existing file * in an existing directory. * \*-----------------------------------------------------------*/ #define EXAMPLE_FILE "Readme.txt" #define EXAMPLE_DIR "C:\\Windows" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CloseFile(HWND); function ExFn_CloseFile(hMSI) STRING svLine; NUMBER nvFileHandle; LIST listID; begin

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

515

Appendix A: Built-In Functions (A-D) CmdGetHwndDlg

// Set the file mode to normal. OpenFileMode (FILE_MODE_NORMAL); // Open the text file. if (OpenFile (nvFileHandle, EXAMPLE_DIR, EXAMPLE_FILE) < 0) then MessageBox ("OpenFile failed.", SEVERE); abort; endif; // Create an empty string list. listID = ListCreate (STRINGLIST); // Read lines from the text file into the string list. while GetLine (nvFileHandle, svLine) = 0 ListAddString (listID, svLine, AFTER); endwhile; // Close the file. if (CloseFile (nvFileHandle) < 0) then MessageBox ("CloseFile failed.", SEVERE); endif; // Display the text that was read from the file. SdShowInfoList ("","",listID); end;

CmdGetHwndDlg
The CmdGetHwndDlg function retrieves the window handle of the dialog identified by szDialogName. The dialog already must have been defined with EzDefineDialog or DefineDialog and initialized by calling WaitOnDialog.
CmdGetHwndDlg is typically called in the DLG_INIT routine for a custom dialog. The handle of the dialog

is assigned to a HWND variable to be used by other functions that need it.

Note: When a dialog is initialized with the WaitOnDialog function, a window handle is assigned to it; that handle is associated with the dialog only until it is closed by a call to EndDialog. If you call WaitOnDialog to open a dialog that has been opened and closed previously in your script, you must call CmdGetHwndDlg again to get the new handle. The old handle is no longer valid.

Syntax
CmdGetHwndDlg ( szDialogName );

516

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CmdGetHwndDlg

Parameters
Table A-42: CmdGetHwdDlg Parameters Parameter szDialogName Description Specifies the name of a dialog that has been defined with EzDefineDialog or DefineDialog.

Return Values
Table A-43: CmdGetHwdDlg Return Values Return Value >0 <0 Description The window handle of the dialog that was specified by szDialogName. CmdGetHwndDlg was unable to retrieve the handle. Verify that szDialogName refers to a dialog that has been properly defined and initialized.

CmdGetHwndDlg Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CmdGetHwndDlg function. * * This example displays a custom dialog. On initialization * of the dialog, the script calls CmdGetHwndDlg to retrieve * the dialog's window handle so that it can perform the * following operations: * * -- Change the text of the window's title bar. * -- Disable and enable buttons in the dialog. * -- Send messages to maximize and restore the dialog window. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the * built-in function SdBitmap. Because this dialog is stored in * the file _isres.dll, which is already compressed in the * installation, it can be used in a script as a custom dialog. * Note that the script changes the static text of the dialog's * Back and Next buttons to fit the requirements of the example. * \*-----------------------------------------------------------*/ // Dialog controls #define RES_DIALOG_ID #define RES_PBUT_RESTORE

12027 1

// ID of the custom dialog // ID of dialog's Next button

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

517

Appendix A: Built-In Functions (A-D) CmdGetHwndDlg

#define RES_PBUT_CANCEL #define RES_PBUT_MAXIMIZE

9 12

// ID of dialog's Cancel button // ID of dialog's Back button

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CmdGetHwndDlg(HWND); function ExFn_CmdGetHwndDlg(hMSI) STRING szDialogName; NUMBER nResult, nCmdValue, hwndDlg; BOOL bDone; begin // Specify a name to identify the custom dialog in // this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _ISUSER.DLL or _ISRES.DLL. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize the indicator used to control the loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable // states for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg(szDialogName); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the static text of the buttons. CtrlSetText (szDialogName, RES_PBUT_MAXIMIZE, "&Maximize"); CtrlSetText (szDialogName, RES_PBUT_RESTORE, "&Restore"); // Disable the Restore button using a call from Winsub. _WinSubEnableControl (hwndDlg, RES_PBUT_RESTORE, 0); case RES_PBUT_RESTORE: // Restore the window to its normal size.
518 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CoCreateObject

SendMessage (hwndDlg, WM_SYSCOMMAND, SC_RESTORE, 0); // Disable the Restore button using a call from Winsub. _WinSubEnableControl (hwndDlg, RES_PBUT_RESTORE, 0); // Enable the Maximize button using a call from Winsub. _WinSubEnableControl (hwndDlg, RES_PBUT_MAXIMIZE, 1); case RES_PBUT_MAXIMIZE: // Maximize the dialog's window. SendMessage (hwndDlg, WM_SYSCOMMAND, SC_MAXIMIZE, 0); // Disable the Maximize button using a call from Winsub. _WinSubEnableControl (hwndDlg, RES_PBUT_MAXIMIZE, 0); // Enable the Restore button using a call from Winsub. _WinSubEnableControl (hwndDlg, RES_PBUT_RESTORE, 1); case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory. ReleaseDialog (szDialogName); end;

CoCreateObject
Project: This information applies to InstallScript projects.

The CoCreateObject function initializes the COM object named by szProgID and returns a reference that can be assigned to a variable of type OBJECT by using the set keyword.

Syntax
CoCreateObject ( szProgID );

Parameters
Table A-44: CoCreateObject Parameters Parameter szProgID Description Specifies the program ID of the COM object to be initialized.

Return Values
The reference can be assigned to a variable of type OBJECT by using the set keyword.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 519

Appendix A: Built-In Functions (A-D) CoCreateObjectDotNet

Additional Information
To check whether the object was initialized successfully, call the IsObject function. Any object variable can be released by setting the object variable to the value of NOTHING or reassigning the object with the CoCreateObject, CoCreateObjectDotNet, CoGetObject, or DotNetCoCreateObject functions. However, this does not automatically unload the library referenced by the object. You must call the Windows API, CoFreeLibrary, manually to free the library. Otherwise, the library remains loaded until the installation finishes. For more information, see Extending Your Installation with COM Objects.

CoCreateObjectDotNet
Project: The following project types support the CoCreateObjectDotNet function:

InstallScript InstallScript MSI Basic MSI with InstallScript custom actions

The CoCreateObjectDotNet function has been deprecated. Calling this function is the same as calling the DotNetCoCreateObject function with a null string ("") for the szAppDomain parameter. For more information, see DotNetCoCreateObject.

CoGetObject
Project: This information applies to InstallScript projects.

The CoGetObject function returns a reference to the specified COM object (as Visual Basics GetObject function does); that reference can be assigned to a variable of type OBJECT by using the set keyword.

Syntax
CoGetObject ( szFilename, szProgID );

520

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CoGetObject

Parameters
Table A-45: CoGetObject Parameters Parameter szFilename Description Specifies the fully qualified name of the COM object. This parameter can be a null string ("") if szProgID is non-null. Specifies the program ID of the COM object. This parameter can be a null string ("") if szFilename is non-null.

szProgID

Return Values
A reference that can be assigned to a variable of type OBJECT by using the set keyword. Any object variable can be released by setting the object variable to the value of NOTHING or reassigning the object with the CoCreateObject, CoCreateObjectDotNet, CoGetObject, or DotNetCoCreateObject functions. However, this does not automatically unload the library referenced by the object. You must call the Windows API, CoFreeLibrary, manually to free the library. Otherwise, the library remains loaded until the installation finishes. For more information, see Extending Your Installation with COM Objects.

Additional Information
To check whether the object was initialized successfully, call the IsObject function.

CoGetObject Example
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CoGetObject function. * * This example shows how to create a virtual * directory on IIS server. * \*-----------------------------------------------------------*/ #include "ifx.h" #define VIRTUALDIR "My Virtual Dir" #define VIRTUALDIRPATH "c:\inetpub\wwwroot\MyDir" function OnBegin() OBJECT objIIS_Root, objVirtDir; begin set objIIS_Root = CoGetObject("IIS://localhost/W3SVC/1/Root", ""); if (IsObject(objIIS_Root)) then try set objVirtDir = objIIS_Root.Create("IISWebVirtualDir", VIRTUALDIR);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 521

Appendix A: Built-In Functions (A-D) ConfigAdd

if (IsObject(objVirtDir)) then objVirtDir.Path = VIRTUALDIRPATH; objVirtDir.AccessRead = TRUE; objVirtDir.AccessScript = TRUE; objVirtDir.SetInfo(); objVirtDir.AppCreate(TRUE); objVirtDir.SetInfo(); endif; catch MessageBox("Unable to create Virual Directory.", INFORMATION); endcatch; endif; end;

ConfigAdd
The ConfigAdd function adds a statement to the system configuration file that has been loaded into memory with ConfigFileLoad. You can specify the position of the statement relative to a reference key, or you can add the statement as the first or last line of the file. You can also replace an existing line in the file.

Note: Before calling ConfigAdd, you must first call ConfigFileLoad to load the system configuration file into memory. After you edit the file, call ConfigFileSave to save the file. Do not mix the Ez configuration file functions with the advanced configuration file functions. After calling ConfigFileLoad, you cannot use the Ez configuration file functions until you call ConfigFileSave to save your changes.

Syntax
ConfigAdd ( szKey, szValue, szRefKey, nOptions );

522

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigAdd

Parameters
Table A-46: ConfigAdd Parameters Parameter szKey Description Specifies the keyword in the statement that is being added to the system configuration file. Specifies the value of the keyword that is being added to the system configuration file. Specifies the reference key relative to which you are adding szKey in the system configuration file. If you pass a null string ("") in this parameter, the line is added as the first or last line in the file, depending on which predefined constant is passed in nOptions. Specifies whether the line is to be added before or after the line containing the reference key, or whether the line replaces an existing line. Pass one of the following predefined constants in this parameter:

szValue

szRefKey

nOptions

BEFOREThe statement is added before the line containing szRefKey. If szRefKey is a null string (""), the statement is added as the first line of the file. AFTERThe statement is added after the line containing szRefKey. If szRefKey is a null string (""), the statement is added as the last line of the file. REPLACEThe statement replaces an existing line in the file. If multiple lines with same key exist, only the last line is replaced. If a line to be replaced does not exist in the file, the new line is added as the last line of the file.

Return Values
Table A-47: ConfigAdd Return Values Return Value 0 Description ConfigAdd successfully added the statement to the specified system configuration file. ConfigAdd was unable to add the statement to the specified system configuration file.

<0

Additional Information
When the ConfigAdd function replaces a line in a system configuration file, it compares the reference keys in the two lines. A reference key is a substring that identifies the line. For example, in the following statement, the reference key is Kybrd.drv.
DEVICE=C:\Windows\System\Kybrd.drv /1024 /C:345

In the next statement, the reference key is PATH:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

523

Appendix A: Built-In Functions (A-D) ConfigAdd

SET PATH=C:\Windows;C:\Windows\System

ConfigAdd Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigAdd function. * * This example script adds two statements to a configuration * file. First, it calls ConfigFileLoad to load the file for * editing. Next, it adds a DEVICE statement. Then it adds a * DEVICEHIGH statement. Finally, it backs up the original file * and saves the edited file. * * Note: Before running this script, create a configuration * file named ISExampl.sys in the root of drive C. * That file should include the following lines: * * DEVICE=C:\Exapp\Exapp.sys * DEVICE=C:\Otherapp.exe * \*-----------------------------------------------------------*/ #define EXAMPLE_SYS "C:\\ISExampl.sys" #define EXAMSYS_BAK "ISExampl.bak" // Variables to pass as parameters to ConfigAdd. // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigAdd(HWND); function ExFn_ConfigAdd(hMSI) STRING szKey, szValue, szRefKey; begin // Load the target config file into memory. if ConfigFileLoad (EXAMPLE_SYS) < 0 then MessageBox ("Unable to load " + EXAMPLE_SYS + ".", SEVERE); abort; endif; // Set up parameters for the first call to ConfigAdd. szKey = "DEVICE"; szValue = "C:\\Exapp\\Exapp2.sys"; szRefKey = "Exapp.sys"; // Add the line DEVICE=C:\Exapp\Exapp2.SYS before the first // statement that references Exapp.sys. if (ConfigAdd (szKey, szValue, szRefKey, BEFORE) < 0) then MessageBox ("First call to ConfigAdd failed.", WARNING);

524

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigDelete

abort; endif; // Set up parameters for the second call to ConfigAdd. szKey = "DEVICEHIGH"; szValue = "C:\\Otherapp\\Otherapp.exe"; szRefKey = "Otherapp.exe"; // Replace the last existing line that references OtherApp.exe // with the statement DEVICEHIGH=C:\Otherapp\Otherapp.exe. if (ConfigAdd (szKey, szValue, szRefKey, REPLACE) < 0) then MessageBox ("Second call to ConfigAdd failed.", WARNING); abort; endif; // Backup the original file and if ConfigFileSave (EXAMSYS_BAK) MessageBox ("Unable to save else MessageBox (EXAMPLE_SYS + " endif; end; save the edited file. < 0 then " + EXAMPLE_SYS + ".", SEVERE); was updated and saved.",INFORMATION);

ConfigDelete
The ConfigDelete function removes lines from the system configuration file that has been loaded into memory by a call to ConfigFileLoad. The parameter szKey specifies a reference key that identifies the lines to be deleted. After using advanced configuration functions to edit a system configuration file, you must call ConfigFileSave to save your changes.

Note: Do not mix the Ez batch file functions with the advanced batch file functions. After calling BatchFileLoad, you cannot use Ez batch file functions until you have called BatchFileSave to save the file.

Syntax
ConfigDelete ( szKey );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

525

Appendix A: Built-In Functions (A-D) ConfigDelete

Parameters
Table A-48: ConfigDelete Parameters Parameter szKey Description Specifies the reference key that identifies the line or lines to delete. Common reference keys include Himem.sys, FILES, and STACKS.

Return Values
Table A-49: ConfigDelete Return Values Return Value 0 Description ConfigDelete successfully deleted the lines containing the reference key from the system configuration file. ConfigDelete was unable to delete the specified lines.

<0

ConfigDelete Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigDelete function. * * This example script deletes statements from a configuration * file. First, it calls ConfigFileLoad to load the file for * editing. Next, it deletes lines that contain a FILES * statement. Finally, it backs up the original file and * saves the edited file. * * Note: Before running this script, create a configuration * file named ISExampl.sys in the root of drive C. * That file should include at least one FILES statement. * \*-----------------------------------------------------------*/ #define TARGET_CONFIG #define BACKUP_CONFIG "C:\\ISExampl.sys" "ISExampl.bak"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigDelete(HWND);
526 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigFileLoad

function ExFn_ConfigDelete(hMSI) STRING szMsg; begin // Load the target config file to be edited. if (ConfigFileLoad (TARGET_CONFIG) < 0) then MessageBox ("Unable to load " + TARGET_CONFIG + ".", SEVERE); abort; endif; // Remove all lines in the file that contain the key "FILES". if (ConfigDelete ("FILES") < 0) then MessageBox ("ConfigDelete failed.", SEVERE); else // Back up the original file and save the edited file. if ConfigFileSave (BACKUP_CONFIG) < 0 then MessageBox ("Unable to save " + TARGET_CONFIG + ".", SEVERE); else MessageBox (TARGET_CONFIG + " was updated and saved.",INFORMATION); endif; endif; end;

ConfigFileLoad
The ConfigFileLoad function loads a copy of the specified system configuration file into memory so that other advanced configuration file functions can be called to operate on the file. Specify the name of the system configuration file you want to edit in szConfigFile or pass a null string ("") in szConfigFile to edit the default system configuration file, which is set initially by the installation to the bootup Config.sys file that is used by the system.

Note: Before using any of the advanced configuration file functions, you must first call ConfigFileLoad to load the system configuration file into memory. After you modify the file, call ConfigFileSave to save it to disk. To obtain the fully qualified name of the default system configuration file, call ConfigGetFileName. To make another file the default system configuration file, call ConfigSetFileName. Note that you cannot call ConfigFileLoad to create a new configuration file. To create a new configuration file, use CreateFile and CloseFile; this creates an empty file. Then use ConfigFileLoad and other functions to load and modify the file as needed. Do not mix the Ez configuration file functions with the advanced configuration file functions. After calling the ConfigFileLoad function, you cannot use the Ez configuration file functions until you use the ConfigFileSave function to save your changes.

Syntax
ConfigFileLoad ( szConfigFile );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

527

Appendix A: Built-In Functions (A-D) ConfigFileLoad

Parameters
Table A-50: ConfigFileLoad Parameters Parameter szConfigFile Description Specifies the fully qualified name of the system configuration file to load into memory. To load the default system configuration file, pass a null string ("") in this parameter.

Return Values
Table A-51: ConfigFileLoad Return Values Return Value 0 Description ConfigFileLoad successfully initialized the configuration file buffer. If szConfigFile specified an existing configuration file, the file was loaded into the buffer; otherwise, an empty buffer was created. ConfigFileLoad was unable to initialize the configuration file buffer.

<0

ConfigFileLoad Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigFileLoad and ConfigFileSave functions. * * This example script shows how to open a configuration file * for editing, how to create a backup of the original file, * and how to save and close the edited file. * * To demonstrate how the file backup feature of ConfigFileSave * prevents the overwriting of existing files, this script loads * and saves two different configuration files. The first file * is backed up with a specific file name. The second is backed * up with a wildcard extension so that ConfigFileSave will * generate a unique file extension consisting of three digits. * * Note: Before running this script, create two files * (ISExamp1.sys and ISExamp2.sys) in the root of * drive C. For best effect, you should delete or * move any other files named ISExamp1.* or ISExamp2.*. * \*-----------------------------------------------------------*/ // Names of Config files and backup files used in this example. #define EXAMPLE1 "ISEXAMP1"
528 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigFileSave

#define EXAMPLE2 "ISEXAMP2" // Full names of Config files. #define EXAMPLE1_SYS "C:\\" + EXAMPLE1 + ".sys" #define EXAMPLE2_SYS "C:\\" + EXAMPLE2 + ".sys" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigFileLoad(HWND); function ExFn_ConfigFileLoad(hMSI) begin // Load EXAMPLE1_SYS. if (ConfigFileLoad (EXAMPLE1_SYS) < 0) then MessageBox ("Unable to load " + EXAMPLE1_SYS + ".", SEVERE); abort; endif; // Use other Config functions here to edit the first file. // // // if Back up the original file with the extension 'bak'; save the edited file under its original name. If ISExamp1.bak already exists, ConfigFileSave will generate a numbered extension. (ConfigFileSave (EXAMPLE1 + ".bak") < 0) then MessageBox ("Unable to save " + EXAMPLE1_SYS + ".", SEVERE); abort; else MessageBox (EXAMPLE1_SYS + " saved.",INFORMATION); endif; // Load EXAMPLE2_SYS. if (ConfigFileLoad (EXAMPLE2_SYS) < 0) then MessageBox ("Unable to load " + EXAMPLE2_SYS + ".", SEVERE); abort; endif; // Use other Config file functions here to edit the second file. // Back up the original Config file with a numbered extension // and save the edited file under its original name. if (ConfigFileSave (EXAMPLE2 + ".*") < 0) then MessageBox ("Unable to save " + EXAMPLE2_SYS + ".", SEVERE); abort; else MessageBox (EXAMPLE2_SYS + " saved.",INFORMATION); endif; end;

ConfigFileSave
The ConfigFileSave function saves to disk a system configuration file that has been loaded into memory with the function ConfigFileLoad. The file is saved under its original name. If a file name is specified in szBackupFile, the original file is renamed with that file name before the edited file is written to disk. If

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

529

Appendix A: Built-In Functions (A-D) ConfigFileSave

szBackupFile contains a null string (""), the original file is replaced with the modified file. If you do not call ConfigFileSave when you are finished modifying a system configuration file with advanced configuration file functions, all modifications will be lost.

Note: Do not mix the Ez configuration file functions with the advanced configuration file functions. After calling the ConfigFileLoad function, you cannot use the Ez configuration file functions until you use the ConfigFileSave function to save your changes.

Syntax
ConfigFileSave ( szBackupFile );

530

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigFileSave

Parameters
Table A-52: ConfigFileSave Parameters Parameter szBackupFile Description Specifies whether or not a backup copy of the original file as it existed before editing should be saved, according to the following criteria:

If no backup file should be created, specify a null string in this parameter. If the original file should be backed up with a specific name, pass that file name in this parameter. The file name must be unqualified (that is, do not specify a drive and/or path). Note that if a file with the specified name already exists, ConfigFileSave generates a unique file extension, as described in the next bullet item. If the original file should be backed up with an installationgenerated file extension, specify the wildcard character (*) as the file extension (for example, "Config.*"). The installation then assigns a numeric value, starting at 001, as the extension. If a file already exists with that extension, the extension's value is increased by one until a unique file name is created.

Once the backup has been created, InstallShield stores the backup file name in the system variable INFOFILENAME.

Return Values
Table A-53: ConfigFileSave Return Values Return Value 0 <0 Description ConfigFileSave successfully wrote the file from memory to disk. ConfigFileSave was unable to write the file to disk.

ConfigFileSave Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigFileLoad and ConfigFileSave functions. * * This example script shows how to open a configuration file * for editing, how to create a backup of the original file, * and how to save and close the edited file. * * To demonstrate how the file backup feature of ConfigFileSave

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

531

Appendix A: Built-In Functions (A-D) ConfigFileSave

* prevents the overwriting of existing files, this script loads * and saves two different configuration files. The first file * is backed up with a specific file name. The second is backed * up with a wildcard extension so that ConfigFileSave will * generate a unique file extension consisting of three digits. * * Note: Before running this script, create two files * (ISExamp1.sys and ISExamp2.sys) in the root of * drive C. For best effect, you should delete or * move any other files named ISExamp1.* or ISExamp2.*. * \*-----------------------------------------------------------*/ // Names of Config files and backup files used in this example. #define EXAMPLE1 "ISEXAMP1" #define EXAMPLE2 "ISEXAMP2" // Full names of Config files. #define EXAMPLE1_SYS "C:\\" + EXAMPLE1 + ".sys" #define EXAMPLE2_SYS "C:\\" + EXAMPLE2 + ".sys" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigFileSave(HWND); function ExFn_ConfigFileSave(hMSI) begin // Load EXAMPLE1_SYS. if (ConfigFileLoad (EXAMPLE1_SYS) < 0) then MessageBox ("Unable to load " + EXAMPLE1_SYS + ".", SEVERE); abort; endif; // Use other Config functions here to edit the first file. // // // if Back up the original file with the extension 'bak'; save the edited file under its original name. If ISExamp1.bak already exists, ConfigFileSave will generate a numbered extension. (ConfigFileSave (EXAMPLE1 + ".bak") < 0) then MessageBox ("Unable to save " + EXAMPLE1_SYS + ".", SEVERE); abort; else MessageBox (EXAMPLE1_SYS + " saved.",INFORMATION); endif; // Load EXAMPLE2_SYS. if (ConfigFileLoad (EXAMPLE2_SYS) < 0) then MessageBox ("Unable to load " + EXAMPLE2_SYS + ".", SEVERE); abort; endif; // Use other Config file functions here to edit the second file. // Back up the original Config file with a numbered extension // and save the edited file under its original name. if (ConfigFileSave (EXAMPLE2 + ".*") < 0) then MessageBox ("Unable to save " + EXAMPLE2_SYS + ".", SEVERE); abort; else MessageBox (EXAMPLE2_SYS + " saved.",INFORMATION);
532 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigFind

endif; end;

ConfigFind
The ConfigFind function searches a system configuration file that has been loaded into memory with the function ConfigFileLoad. The parameter szRefKey is a reference key that specifies the search target in that file. If the reference key is found, its value is returned in svResult. To find all occurrences of szRefKey, call this function repeatedly with nOptions set to CONTINUE. To restart the search from the top of the file, specify the constant RESTART in nOptions. After you edit the file, call ConfigFileSave to save it.

Note: Do not mix the Ez configuration file functions with the advanced configuration file functions. After calling the ConfigFileLoad function, you cannot use the Ez configuration file functions until you use the ConfigFileSave function to save your changes.

Syntax
ConfigFind (szRefKey, svResult, nOptions);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

533

Appendix A: Built-In Functions (A-D) ConfigFind

Parameters
Table A-54: ConfigFind Parameters Parameter szRefKey Description Specifies the reference key to search for. If the reference key is a file name without a file extension, all file extensions are included in the search. For example, if you specify Win.com, the search looks only for that reference key. If you specify WIN, the files Win.exe, Win.dll, Win.sys, etc., are all returned. Returns the value of the reference key that was found in the system configuration file. Indicates whether to start the search from the beginning of the file or to continue from where the previous search was terminated. Pass one of the following predefined constants in this parameter:

svResult

nOptions

RESTARTStarts the search from the beginning of the file. CONTINUEStarts the search from the current position in the system configuration file. COMMANDIndicates that the reference key in szRefKey is a command, not an environment variable. The constant COMMAND can be joined with the constant RESTART or the constant CONTINUE by using the bitwise OR operator (|), as in the following example:

ConfigFind("Vga.drv", svResult, CONTINUE | COMMAND);

Note: A system configuration file can contain both environment variables and commands. To distinguish between environment variables and commands with the same name, use the constant COMMAND to specify that you are looking for executable commands.

Return Values
Table A-55: ConfigFind Return Values Return Value 0 Description ConfigFind successfully found the specified reference key and returned it in svResult.

534

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigFind

Table A-55: ConfigFind Return Values (cont.) Return Value <0 Description ConfigFind was unable to find the specified reference key.

ConfigFind Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigFind function. * * This example script searches a batch file and reports whether * or not the file includes a BUFFERS command. It then finds * and diplays all commands that reference Abc44.sys. * * Note: Before running this script, create a configuration * file called ISExampl.sys and store it in the root * of drive C. The configuration file should include * the following lines: * * DEVICE=C:\Abc44.sys /e:300 * DEVICE=C:\Abc44.sys /s:off * BUFFERS=50 * \*-----------------------------------------------------------*/ #define EXAMPLE_SYS "C:\\ISExampl.sys" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigFind(HWND); function ExFn_ConfigFind(hMSI) STRING svResult; NUMBER nResult; begin // Load EXAMPLE_SYS. if (ConfigFileLoad (EXAMPLE_SYS) < 0) then MessageBox ("Unable to load " + EXAMPLE_SYS + ".", SEVERE); abort; endif; // Check for a BUFFERS command. RESTART is passed in the // third parameter to begin searching at the top of the file. nResult = ConfigFind("BUFFERS", svResult, RESTART); if (nResult < 0) then

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

535

Appendix A: Built-In Functions (A-D) ConfigGetFileName

MessageBox ("BUFFERS command not found.", WARNING); else MessageBox (svResult, INFORMATION); endif; // Find the first command that references Abc44.sys. nResult = ConfigFind ("Abc44.sys", svResult, COMMAND | RESTART); if nResult < 0 then MessageBox ("The file Abc44.sys is not referenced.", WARNING); else // Loop while matching statements are found. while nResult = 0 // Display the matching statement. MessageBox (svResult, INFORMATION); // Find the next statement that references Abc44.sys. nResult = ConfigFind ("Abc44.sys", svResult, CONTINUE); endwhile; MessageBox ("No more matches on Abc44.sys.", WARNING); endif; end;

ConfigGetFileName
The ConfigGetFileName function retrieves the fully qualified name of the default system configuration file, which is set initially by InstallShield to the Config.sys file that was executed when the target system was started. To specify a different batch file to be used by default in the script, call ConfigSetFileName.

Note: Do not mix the Ez configuration file functions with the advanced configuration file functions. After calling the ConfigFileLoad function, you cannot use the Ez configuration file functions until you use the ConfigFileSave function to save your changes.

Syntax
ConfigGetFileName (svFileName);

536

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigGetFileName

Parameters
Table A-56: ConfigGetFileName Parameters Parameter svFileName Description Returns the fully qualified name of the default system configuration file.

Note: In rare circumstances, InstallShield might not be able to determine the fully qualified name of the default configuration file. In that case, svFileName is a null string ("").

Return Values
Table A-57: ConfigGetFileName Return Values Return Value 0 Description ConfigGetFileName successfully retrieved the fully qualified name of the default system configuration file. ConfigGetFileName was unable to retrieve the fully qualified name of the default system configuration file.

<0

ConfigGetFileName Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigGetFileName and ConfigSetFileName * functions. * * This example script retrieves the fully qualified name of the * default configuration file, which initially is the Config.sys * file on the boot drive. It then makes C:\ISExampl.sys the * default configuration file. Finally, it retrieves the name of * the default configuration file again to show that it has been * changed. * \*-----------------------------------------------------------*/ #define DEFAULT_CONFIG_FILE "C:\\ISExampl.sys"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

537

Appendix A: Built-In Functions (A-D) ConfigGetInt

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigGetFileName(HWND); function ExFn_ConfigGetFileName(hMSI) STRING svFilename; begin // Get and display the name of the default configuration file. if (ConfigGetFileName (svFilename) < 0) then // Report the error; then terminate. MessageBox ("First call to ConfigGetFileName failed.", SEVERE); abort; else // Display the name of the default configuration file. MessageBox ("The default configuration file is " + svFilename + ".", INFORMATION); endif; // Make C:\ISExampl.sys the default configuration file. if (ConfigSetFileName (DEFAULT_CONFIG_FILE) < 0) then // Report the error. MessageBox ("Unable to set new default configuration file.", SEVERE); else // Verify that the default configuration file has been changed. if (ConfigGetFileName (svFilename) = 0) then // Display the name of the default configuration file. MessageBox ("Now the default configuration file is " + svFilename + ".", INFORMATION); else // Report the error. MessageBox ("Second call to ConfigGetFileName failed.", SEVERE); endif; endif; end;

ConfigGetInt
The ConfigGetInt function retrieves the integer value of a reference key from a system configuration file that has been loaded into memory with the function ConfigFileLoad. ConfigGetInt retrieves values from commands that have only one value to the right of the equal sign (=).

Note: ConfigGetInt does not work on a command that has more than one value. For example, ConfigGetInt recognizes the statement FILES=20 and returns the number 20, but it does not recognize the statement STACKS=9,128. Before calling ConfigGetInt, you must first call ConfigFileLoad to load the system configuration file into memory. After you edit the file, call ConfigFileSave to save the file. Do not mix the Ez configuration file functions with the advanced configuration file functions. After calling the ConfigFileLoad function, you cannot use the Ez configuration file functions until you use the ConfigFileSave function to save your changes.

538

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigGetInt

Syntax
ConfigGetInt ( szKey, nvValue );

Parameters
Table A-58: ConfigGetInt Parameters Parameter szKey Description Specifies the reference key of the statement from which to retrieve the integer value. Returns the integer value of the reference key.

nvValue

Return Values
Table A-59: ConfigGetInt Return Values Return Value 0 Description ConfigGetInt successfully retrieved the integer value. ConfigGetInt was unable to retrieve the integer value.

<0

ConfigGetInt Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigGetInt and ConfigSetInt functions. * * This example script gets the current value of the FILES * command from a configuration file. If a FILES command is not * found, the command FILES=40 is added to the file. If a FILES * command is found, its value is tested. If the value is less * than 40, the command is replaced with the command FILES=40. * * Note: Before running this script, create a configuration file * called ISExampl.sys in the root directory of drive C. * That file should include the following line: * * FILES=20; * \*-----------------------------------------------------------*/

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

539

Appendix A: Built-In Functions (A-D) ConfigGetInt

#define EXAMPLE_SYS "C:\\ISExampl.sys" #define EXAMPLE_BAK "ISExampl.bak" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigGetInt(HWND); function ExFn_ConfigGetInt(hMSI) NUMBER nvValue; BOOL bFileChanged; begin // Load the configuration file. if (ConfigFileLoad (EXAMPLE_SYS) < 0) then MessageBox ("Unable to load " + EXAMPLE_SYS + ".", SEVERE); abort; endif; // Initialize indicator to show if file was updated. bFileChanged = FALSE; // Find the command "FILES" in the configuration file. if (ConfigGetInt ("FILES", nvValue) < 0) then // No FILES command found. Add FILES command. if ConfigAdd ("FILES", "40", "", AFTER) = 0 then MessageBox ("FILES=40 added to " + EXAMPLE_SYS + ".", INFORMATION); bFileChanged = TRUE; else MessageBox ("FILES command not found. Unable to update " + EXAMPLE_SYS + ".", SEVERE); endif; else // FILES command found. if (nvValue >= 40) then // FILES command setting is ok. SprintfBox (INFORMATION, "ConfigGetInt Example", "FILES=%d; no change required.", nvValue); else // FILES command needs to be changed. if (ConfigSetInt ("FILES", 40) < 0) then MessageBox ("Unable to update "+EXAMPLE_SYS + ".", SEVERE); else MessageBox ("The FILES setting was changed to 40.", INFORMATION); bFileChanged = TRUE; endif; endif; endif; // If the file was edited, save it. if bFileChanged then // // // if
540

Back up the original file with the extension 'bak'; save the edited file under its original name. If ISExamp1.bak already exists, ConfigFileSave will generate a numbered extension. (ConfigFileSave (EXAMPLE_BAK) < 0) then
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigMove

MessageBox ("Unable to save " + EXAMPLE_SYS + ".", SEVERE); else MessageBox (EXAMPLE_SYS + " saved.",INFORMATION); endif; endif; end;

ConfigMove
The ConfigMove function moves a line in a system configuration file that has been loaded into memory with the function ConfigFileLoad. The line can be moved to the first or last position in the file or before or after a specific line in the file.

Note: Before calling the ConfigMove function, you must first call ConfigFileLoad to load the Config.sys file into memory. After you edit the file, call ConfigFileSave to save the file. Do not mix the Ez configuration file functions with the advanced configuration file functions. After calling the ConfigFileLoad function, you cannot use the Ez configuration file functions until you use the ConfigFileSave function to save your changes.

Syntax
ConfigMove ( szMove, szRefKey, nOptions );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

541

Appendix A: Built-In Functions (A-D) ConfigMove

Parameters
Table A-60: ConfigMove Parameters Parameter szMove szRefKey Description Specifies the line to move. Specifies the key that identifies the reference line used to position the line to be moved. The position of the line to be moved is determined by the value of nOptions. Specifies whether you are moving the line in szMove before or after the line that contains the reference key in szRefKey. Pass one of the following predefined constants in this parameter:

nOptions

BEFOREThe line specified by szMove is placed before the line containing szRefKey. If szMove is a null string (""), the line is placed before the first line in the system configuration file. AFTERThe line specified by szMove is placed after the line containing szRefKey. If szMove is a null string (""), the line is placed after the last line in the system configuration file.

Return Values
Table A-61: ConfigMove Return Values Return Value 0 Description ConfigMove successfully moved the specified line in the system configuration file. ConfigMove was unable to move the line.

<0

ConfigMove Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigMove function. *

542

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigMove

* This example script moves lines in a configuration file. * First, it calls ConfigFileLoad to load the file. Next, it * moves the FILES statement to the end of the file. Then, * it moves the BUFFERS statement to the end of the file. * Next, it moves the statement referencing Himem.sys before * the DOS statement. Finally, it backs up the original file * and saves the edited file. * * Note: Before running this script, create a configuration * file called ISExampl.sys in the root of drive C. * That file should include the following lines: * * FILES=50 * DOS=HIGH,UMB * DEVICE=C:\WINDOWS\SETVER.EXE * BUFFERS=50 * Device=C:\Windows\Himem.sys * \*-----------------------------------------------------------*/ #define TARGET_CONFIG "C:\\ISExampl.sys" #define BACKUP_CONFIG "ISExampl.bak" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigMove(HWND); function ExFn_ConfigMove(hMSI) begin // Load the configuration file to be edited. if ConfigFileLoad (TARGET_CONFIG) < 0 then MessageBox ("Unable to load " + TARGET_CONFIG + ".", SEVERE); abort; endif; // Move the FILES statement to the end of the file. if (ConfigMove ("FILES", "", AFTER) < 0) then MessageBox ("Unable to move FILES statement.", SEVERE); else MessageBox ("FILES statement moved to the end of the file.", INFORMATION); endif; // Move the BUFFERS statement to the end of the file. if (ConfigMove ("BUFFERS", "", AFTER) < 0) then MessageBox ("Unable to move BUFFERS statement.", SEVERE); else MessageBox ("BUFFERS statement moved to the end of the file.", INFORMATION); endif; // Move the Himem.sys statement before the DOS statement. if (ConfigMove ("Himem.sys", "DOS", BEFORE) < 0) then MessageBox ("Unable to move Himem.sys statement.", SEVERE); else MessageBox ("Himem.sys statement moved before DOS statement.", INFORMATION); endif; // Save the updated file; back up the original file.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 543

Appendix A: Built-In Functions (A-D) ConfigSetFileName

if ConfigFileSave (BACKUP_CONFIG) < 0 then MessageBox ("Unable to save " + BACKUP_CONFIG+".", SEVERE); else MessageBox ("Config file saved. Backup created.",INFORMATION); endif; end;

ConfigSetFileName
The ConfigSetFileName function specifies the fully qualified name of the file you want to use as the default system configuration file. During installation initialization, the installation identifies the Config.sys file that was executed when the target system was started and makes it the default system configuration file. If this is the only system configuration file your installation will edit, it is unnecessary to call this function. Ez configuration files will use that file and the advanced configuration function ConfigFileLoad will open that file when its parameter is a null string (""). However, if you want to use Ez configuration file functions to modify a configuration file other than the bootup Config.sys file, you must call ConfigSetFileName to change the default system configuration file. For example, suppose you wanted to create a Config.sys file on the target system that would not be used at bootup time. You can set a file name in the application directory. Ez configuration file functions would operate on that file. If you call ConfigFileLoad with a null parameter, that file is loaded into memory, where it can be edited with advanced file functions.

The ConfigSetFileName function does not load a system configuration file into memory. You must use ConfigFileLoad to load a file into memory. ConfigSetFileName does not validate the file name you specify. If you specify an invalid file name, all future configuration file functions fail.

Note: Do not mix the Ez configuration file functions with the advanced configuration file functions. After calling the ConfigFileLoad function, you cannot use the Ez configuration file functions until you use the ConfigFileSave function to save your changes.

Syntax
ConfigSetFileName ( szConfigFile );

544

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigSetFileName

Parameters
Table A-62: ConfigSetFileName Parameters Parameter szConfigFile Description Specifies the fully qualified name of the file to set as the default system configuration file.

Return Values
Table A-63: ConfigSetFileName Return Values Return Value 0 Description ConfigSetFileName successfully retrieved the specified system configuration file. ConfigSetFileName was unable to retrieve the specified file.

<0

ConfigSetFileName Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigGetFileName and ConfigSetFileName * functions. * * This example script retrieves the fully qualified name of the * default configuration file, which initially is the Config.sys * file on the boot drive. It then makes C:\ISExampl.sys the * default configuration file. Finally, it retrieves the name of * the default configuration file again to show that it has been * changed. * \*-----------------------------------------------------------*/ #define DEFAULT_CONFIG_FILE "C:\\ISExampl.sys" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigSetFileName(HWND); function ExFn_ConfigSetFileName(hMSI) STRING svFilename; begin

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

545

Appendix A: Built-In Functions (A-D) ConfigSetInt

// Get and display the name of the default configuration file. if (ConfigGetFileName (svFilename) < 0) then // Report the error; then terminate. MessageBox ("First call to ConfigGetFileName failed.", SEVERE); abort; else // Display the name of the default configuration file. MessageBox ("The default configuration file is " + svFilename + ".", INFORMATION); endif; // Make C:\ISExampl.sys the default configuration file. if (ConfigSetFileName (DEFAULT_CONFIG_FILE) < 0) then // Report the error. MessageBox ("Unable to set new default configuration file.", SEVERE); else // Verify that the default configuration file has been changed. if (ConfigGetFileName (svFilename) = 0) then // Display the name of the default configuration file. MessageBox ("Now the default configuration file is " + svFilename + ".", INFORMATION); else // Report the error. MessageBox ("Second call to ConfigGetFileName failed.", SEVERE); endif; endif; end;

ConfigSetInt
The ConfigSetInt function changes a specified integer value in a system configuration file that has been loaded into memory with the function ConfigFileLoad. ConfigSetInt sets values in commands that have only one value to the right of the equal sign (=).

Note: This function does not work on a command that has more than one value. For example, ConfigSetInt recognizes the statement FILES=20 and can change 20 to another value, but it does not recognize the statement STACKS=9,128. Before calling ConfigSetInt, you must first call ConfigFileLoad to load the system configuration file into memory. After you edit the file, call ConfigFileSave to save the file. Do not mix the Ez configuration file functions with the advanced configuration file functions. After calling the ConfigFileLoad function, you cannot use the Ez configuration file functions until you use the ConfigFileSave function to save your changes.

Syntax
ConfigSetInt ( szKey, nValue );

546

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConfigSetInt

Parameters
Table A-64: ConfigSetInt Parameters Parameter szKey Description Specifies the reference keyword of the command whose integer value is to be set. Specifies the integer value you want to set for the command in szKey.

nValue

Return Values
Table A-65: ConfigSetInt Return Values Return Value 0 Description ConfigSetInt successfully set the specified integer in the system configuration file. ConfigSetInt was unable to set the specified integer.

<0

ConfigSetInt Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ConfigGetInt and ConfigSetInt functions. * * This example script gets the current value of the FILES * command from a configuration file. If a FILES command is not * found, the command FILES=40 is added to the file. If a FILES * command is found, its value is tested. If the value is less * than 40, the command is replaced with the command FILES=40. * * Note: Before running this script, create a configuration file * called ISExampl.sys in the root directory of drive C. * That file should include the following line: * * FILES=20; * \*-----------------------------------------------------------*/

#define EXAMPLE_SYS "C:\\ISExampl.sys" #define EXAMPLE_BAK "ISExampl.bak"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

547

Appendix A: Built-In Functions (A-D) ConfigSetInt

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ConfigSetInt(HWND); function ExFn_ConfigSetInt(hMSI) NUMBER nvValue; BOOL bFileChanged; begin // Load the configuration file. if (ConfigFileLoad (EXAMPLE_SYS) < 0) then MessageBox ("Unable to load " + EXAMPLE_SYS + ".", SEVERE); abort; endif; // Initialize indicator to show if file was updated. bFileChanged = FALSE; // Find the command "FILES" in the configuration file. if (ConfigGetInt ("FILES", nvValue) < 0) then // No FILES command found. Add FILES command. if ConfigAdd ("FILES", "40", "", AFTER) = 0 then MessageBox ("FILES=40 added to " + EXAMPLE_SYS + ".", INFORMATION); bFileChanged = TRUE; else MessageBox ("FILES command not found. Unable to update " + EXAMPLE_SYS + ".", SEVERE); endif; else // FILES command found. if (nvValue >= 40) then // FILES command setting is ok. SprintfBox (INFORMATION, "ConfigGetInt Example", "FILES=%d; no change required.", nvValue); else // FILES command needs to be changed. if (ConfigSetInt ("FILES", 40) < 0) then MessageBox ("Unable to update "+EXAMPLE_SYS + ".", SEVERE); else MessageBox ("The FILES setting was changed to 40.", INFORMATION); bFileChanged = TRUE; endif; endif; endif; // If the file was edited, save it. if bFileChanged then // // // if Back up the original file with the extension 'bak'; save the edited file under its original name. If ISExamp1.bak already exists, ConfigFileSave will generate a numbered extension. (ConfigFileSave (EXAMPLE_BAK) < 0) then MessageBox ("Unable to save " + EXAMPLE_SYS + ".", SEVERE); else MessageBox (EXAMPLE_SYS + " saved.",INFORMATION);
548 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConvertSizeToUnits

endif; endif; end;

ConvertSizeToUnits
The ConvertSizeToUnits function converts the size specified through nSizeSrcHigh and nSizeSrcLow in nUnitsSrc into nvSizeTargetHigh and nvSizeTargetLow in nUnitsTarget. You can also use this function to determine the best units to use for a particular size value that is not known until the setup is run.

Syntax
ConvertSizeToUnits ( nSizeSrcHigh, nSizeSrcLow, nUnitsSrc, nvSizeTargetHigh, nvSizeTargetLow, nvUnitsTarget );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

549

Appendix A: Built-In Functions (A-D) ConvertSizeToUnits

Parameters
Table A-66: CovertSizeToUnits Parameters Parameter nSizeSrcHigh Description Specifies the upper 31 bits of the size to be converted. Specifies the lower 31 bits of the size to be converted. The units of nSizeSrcHigh and nSizeSrcLow. Specify one of the following values:

nSizeSrcLow

nUnitsSrc

nvSizeTargetHigh nvSizeTargetLow nUnitsTarget

BYTESThe value is in bytes. KBYTESThe value is in kilobytes. MBYTESThe value is in megabytes. GBYTESThe value is in gigabytes. TBYTESThe value is in terabytes.

Returns the upper 31 bits of converted size. Returns the lower 31 bits of converted size. Specifies (and returns if -1 is specified) the units of nvSizeTargetHigh and nvSizeTargetLow. Specify one of the following values. (You can also specify 1 or any negative value. In this case, the function sets nUnitsTarget to the smallest units that ensures that nvSizeTargethigh is 0):

BYTESThe value is in bytes. KBYTESThe value is in kilobytes. MBYTESThe value is in megabytes. GBYTESThe value is in gigabytes. TBYTESThe value is in terabytes.

Return Values
Table A-67: ConvertSizeToUnits Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS ISERR_INVALID_ARG Description Indicates that the function was successful. Indicates that the function was not successful. Indicates that either nSizeSrcHigh or nSizeSrcLow is negative.

550

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) ConvertWinHighLowSizeToISHighLowSize

ConvertWinHighLowSizeToISHighLowSize
The ConvertWinHighLowSizeToISHighLowSize function converts the unsigned 64-bit Windows size specified through nSizeWinHigh and nSizeWinLow to the corresponding 62-bit InstallShield high and low size value.

Syntax
ConvertWinHighLowSizeToISHighLowSize ( nSizeWinHigh, nSizeWinLow, nvSizeISHigh, nvSizeISLow);

Parameters
Table A-68: ConvertWinHighLowSizeToISHighLowSize Parameters Parameter nSizeWinHigh Description Specifies the upper 31 bits of the Windows 64-bit size value. Specifies the lower 31 bits of the Windows 64-bit size value. Returns the upper 31 bits of the InstallShield 62-bit size value. Returns the lower 31 bits of the InstallShield 62-bit size value.

nSizeWinLow

nSizeISHigh

nSizeISLow

Return Values
Table A-69: ConvertWinHighLowSizeToISHighLowSize Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

CopyBytes
The CopyBytes function copies a specified number of bytes from one string to another string. You can specify the offset indices into the source and destination strings. CopyBytes is useful for working with binary files.

Syntax
CopyBytes ( svDest, nIndexDest, svSrc, nIndexSrc, nCount );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

551

Appendix A: Built-In Functions (A-D) CopyBytes

Parameters
Table A-70: CopyBytes Parameters Parameter svDest nIndexDest Description Specifies the destination string. Specifies the offset index (starting point) in the destination string at which location the bytes are to be inserted. The first byte in the string is at position 0. Specifies the source string. Do not pass an autosized string whose size is greater than 256 characters. Instead, declare the string with an explicit size. For more information about string sizing, see String Size and Autosize. Specifies the offset index (starting point) in the source string at which location bytes begin to be copied. The first byte in the string is at position 0. Specifies the total number of bytes you want to copy from svSrc to svDest. This value must be no larger than the size of svSrc - 1. For example, if svSrc was declared with a size of 512 (giving it a maximum string length of 511), then the value passed in nCount must be 511 or less.

svSrc

nIndexSrc

nCount

Return Values
Table A-71: CopyBytes Return Values Return Value 0 Description CopyBytes successfully copied a specified number of bytes from one string to another. CopyBytes was unable to copy the bytes.

<0

CopyBytes Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CopyBytes function.

552

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CopyCHARArrayToISStringArray

* * This example script retrieves the current date from the * target system. Then, it copies the year from the date and * displays the year to the end user. * \*-----------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CopyBytes(HWND); function ExFn_CopyBytes(hMSI) STRING svDate, svYear; NUMBER nvResult, nIndexDate, nIndexYear, nCount; begin // Get the date from the target system. GetSystemInfo (DATE, nvResult, svDate); // Set up parameters to pass to CopyBytes. The year is // in the last four bytes of svDate. nIndexYear = 0; nCount = 4; nIndexDate = StrLength(svDate) - nCount; // Copy the four bytes representing the year into svYear. if (CopyBytes (svYear, nIndexYear, svDate, nIndexDate, nCount) < 0) then // Report an error. MessageBox ("CopyBytes failed.", SEVERE); else // Display the year. MessageBox ("The year is " + svYear, INFORMATION); endif; end;

CopyCHARArrayToISStringArray
Description
The CopyCHARArrayToISStringArray function copies the strings from an existing array of ANSI character strings (pointed to by pCHARArray) to the existing string array specified by vArray.

Syntax
CopyCHARArrayToISStringArray ( vArray, pCHARArray );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

553

Appendix A: Built-In Functions (A-D) CopyFile

Parameters
Table A-72: CopyCHARArrayToISStringArray Parameters Parameter vArray Description Specifies the string array to which you want to copy strings. Specifies a pointer to an array of pointers to ANSI character strings. Typically, this pointer is returned by a previous call to GetCHARArrayFromISStringArray.

pCHARArray

Return Values
Table A-73: CopyCHARArrayToISStringArray Return Values Return Value ISERR_SUCCESS Description This function always returns ISERR_SUCCESS.

Additional Information
If pCHARArray was returned by a previous call to GetCHARArrayFromISStringArray, be careful when modifying strings contained in the array. Since the length of the strings contained in string arrays are managed internally by the setup, if you change the length of a string the entire string will not be copied back to the original array when you call CopyCHARArrayToISStringArray.

CopyFile
The CopyFile function creates a copy of the file specified by szSrcFile. The new file is given the name specified by szTargetFile. You must specify the name of the file that you want to copy onto the target location in the szTargetFile parameter of this function in order for the function to work. If you are copying files to WINSYSDIR64, you must first disable file system redirection using WOW64FSREDIRECTION. Otherwise, files being copied to WINSYSDIR64 are incorrectly redirected to the 32-bit Windows system folder. Since some Windows functionality which could be used by the installation requires that redirection be enabled to work, Windows documentation recommends that you disable redirection only for as long as necessary. It is recommended that you then enable file system redirection as soon as you have completed installing the necessary files to WINSYSDIR64.

Tip: It is strongly recommended that you disable the Cancel button using the Disable function before calling the CopyFile function if the status dialog is displayed during the copy. If you do not disable the Cancel button and the end user cancels during the copy file operation, the OnCancelling event handler is not called. Instead, the copy file operation returns a failure error code, which your script must handle by calling the appropriate event and then relaunching the copy file operation. You can enable the Cancel button using the Enable function.

554

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CopyFile

For file transfer, XCopyFile is an alternative to CopyFile. XCopyFile can perform version checking, mark locked .dll and .exe files for update after system restart, and increment registry reference counters for shared .dll and .exe files. You can also use XCopyFile to include subdirectories. If you use unqualified file names and set values for SRCDIR and TARGETDIR when using CopyFile, save the current values using VarSave before calling CopyFile and then restore them using VarRestore. If the target directory does not exist, CopyFile creates it. You cannot rename groups of files by using wildcards with CopyFile. You can, however, rename a single file using CopyFile.

Syntax
CopyFile ( szSrcFile, szTargetFile );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

555

Appendix A: Built-In Functions (A-D) CopyFile

Parameters
Table A-74: CopyFile Parameters Parameter szSrcFile Description Specifies the name of the file to copy. If the file name is qualifiedif it includes a pathCopyFile copies the file from the specified location. If szSrcFile contains an unqualified file namewithout path informationCopyFile copies from the directory identified by the system variable SRCDIR. To copy groups of files, use wild card characters in this parameter. You can specify a valid Uniform Resource Locator (URL) in this parameter. If you pass a CGI or ASP request (for example, "http://www.mydomain.net/ login.asp?name=Me&pwd=wow"), the response is sent to the file specified in the szTargetFile parameter. When passing a URL, do not include wildcard characters. To check the validity of a URL, call Is(VALID_PATH, szURL). szTargetFile Specifies the name to give to the copy of the file identified by szSrcFile. If the file name is qualifiedif it includes a pathCopyFile copies the file to the location specified by the path. If szSrcFile contains an unqualified file namewithout path informationthe copy is created in the directory specified by the system variable INSTALLDIR. If the target directory does not exist, it is created. You cannot specify a URL in this parameter. If you do, the function fails and returns ISERR_INVALID_ARG.

Note: When a wildcard character is included in the file name that is specified by szSrcFile, the file name part of szTargetFile is not ignored; instead, the szTargetFile value is treated as the target path to which each source file is copied to with its existing name. For example, the following code copies files to a folder named File.txt on the D drive:
CopyFile ("C:\\*.*", "D:\\File.txt");

If szTargetFile specifies an unqualified file name, the files are copied to the directory that is specified by TARGETDIR (in InstallScript installations) or INSTALLDIR (in Basic MSI and InstallScript MSI installations). For that reason, CopyFile cannot be used to copy and rename a group of files. The source and target directories must be different when szSrcFile contains one or more wildcard characters.

Return Values
Table A-75: CopyFile Return Values Return Value 0 Description Indicates that the function successfully copied the files from source to target directory. Indicates that an invalid argument was passed to the function.

ISERR_INVALID_ARG

556

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CopyFile

Table A-75: CopyFile Return Values (cont.) Return Value All other negative values Description Indicates that the function was unable to copy the requested file. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
After you modify .ini files with WriteProfString or WriteProfInt, you must flush the cache buffer under before using CopyFile. All .ini files are cached. This behavior can cause a delay in writing changes to the specified files. This delay can interfere with subsequent file operations. To avoid this problem, call WriteProfString with null parameters to force Windows to write the data to the .ini file immediately, as shown below:
WriteProfString ("C:\\Test.ini", "Windows", "KeyboardDelay", "100"); // null string ("") for all four parameters WriteProfString ("", "", "", ""); // CopyFile should now have access to updated file. CopyFile ("C:\\Test.ini", "C:\\Temp\\Test.ini");

CopyFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CopyFile function. * * This script copies files in the directory specified by * SOURCE_DIR to the directory specified by TARGET_DIR. * * Note: Before running this script, you must set the * preprocessor constants to existing paths on * the target system. * \*-----------------------------------------------------------*/ #define #define SOURCE_DIR "C:\\Source" TARGET_DIR "C:\\Target"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CopyFile(HWND); function ExFn_CopyFile(hMSI) NUMBER nResult;
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 557

Appendix A: Built-In Functions (A-D) CreateDir

begin // Copy all files in the source directory, including files // in subdirectories, to the target directory. nResult = CopyFile(SOURCE_DIR ^ "*.*", TARGET_DIR ^ "*.*"); // Report the results of the copy operation. switch (nResult) case 0: MessageBox ("Files successfully copied.", INFORMATION); case COPY_ERR_CREATEDIR: MessageBox ("A target directory could not be created.", SEVERE); case COPY_ERR_MEMORY: MessageBox ("Insufficient memory.", SEVERE); case COPY_ERR_NODISKSPACE: MessageBox ("Insufficint disk space.", SEVERE); case COPY_ERR_OPENINPUT: MessageBox ("Unable to open the input files in "+ SOURCE_DIR +".", SEVERE); case COPY_ERR_OPENOUTPUT: MessageBox ("Unable to copy the source files.", SEVERE); case COPY_ERR_TARGETREADONLY: MessageBox ("A target file already exists and cannot be overwritten.", SEVERE); default: MessageBox ("An unspecified error occurred.", SEVERE); endswitch; end;

CreateDir
The CreateDir function creates one or more subdirectories on the target drive. You can use a path that contains subdirectories on more than one level, such as C:\Programs\Winapps\Myapp. If any subdirectory in the path does not exist, CreateDir creates it. For example, if neither C:\Programs\Winapps nor C:\Programs\Winapps\Myapp exists, CreateDir creates both subdirectories.

Caution: CreateDir fails under the following conditions:

The path is illegal. The drive or any subdirectory in the path is write-protected. The drive name is invalid. You do not have network privileges to create subdirectories.

Syntax
CreateDir ( szDirPath );

558

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CreateDir

Parameters
Table A-76: CreateDir Parameters Parameter szDirPath Description Specifies the fully qualified path of the subdirectory to create. Separate each level in the path with a backslash by using the backslash escape character (\\).

Return Values
Table A-77: CreateDir Return Values Return Value 0 Description Indicates either that the function successfully created the specified directory on the target drive or that the specified directory already exists. Indicates that the directory does not already exist and that the function was unable to create it. You can obtain the error message text associated with a large negative return valuefor example, 2147024891 (0x80070005)by calling FormatMessage.

<0

CreateDir Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*-----------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CreateDir function. * * The user is asked to input a valid directory. If the * specified directory does not exist, CreateDir is called to * create it. Then CreateDir is called again to create a * multilevel directory structure beneath the specified * directory. * \*-----------------------------------------------------------*/ #define DEFAULT_DIR "C:\\ISExampl" #define SUBDIRS "N_Dir\\A_Dir" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

559

Appendix A: Built-In Functions (A-D) CreateFile

export prototype ExFn_CreateDir(HWND); function ExFn_CreateDir(hMSI) STRING svPath; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Prompt user for a directory to be created. AskPath ("Please enter a valid path.", DEFAULT_DIR, svPath); // Check to see if that directory already exists. if (ExistsDir (svPath) != EXISTS) then // The directory does not exist; create it. if (CreateDir (svPath) < 0) then // Report the error; then abort. MessageBox ("Unable to create directory", SEVERE); abort; else // Report success SprintfBox (INFORMATION, "CreateDir", "%s created.", svPath); endif; endif; // Create an entire multilevel directory structure // beneath the selected directory. if (CreateDir (svPath ^ SUBDIRS) < 0) then MessageBox ("Failed to create subdirectories beneath" + svPath +".", WARNING); else SprintfBox (INFORMATION, "CreateDir", "%s created beneath %s.", SUBDIRS, svPath); endif; end;

CreateFile
The CreateFile function creates a new file. If a file with the same name exists, CreateFile overwrites it. Before you create a file with CreateFile, you must set the file mode with OpenFileMode. CreateFile leaves the newly created file open in read/write (binary file) or append (text file) mode so you can read from or write to the file using other functions such as GetLine, ReadBytes, WriteLine, and WriteBytes. To write to an existing file, you must first open the file in FILE_MODE_APPEND mode using the OpenFileMode and OpenFile functions.

Note: In addition to read/write or append mode, all newly created files automatically open in OF_SHARE_DENY_NONE mode. This means that the files are opened without denying other programs read or write access to the files. This mode has its roots in the Windows API OpenFile.

When you finish reading from and writing to a file, you must close the file using the CloseFile function.

560

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CreateFile

Syntax
CreateFile ( nvFileHandle, szPath, szFileName );

Parameters
Table A-78: CreateFile Parameters Parameter nvFileHandle szPath Description Returns the handle of the new file. Specifies the fully qualified path of the subdirectory in which to create the new file.

Note: CreateFile fails if the folder specified in szPath does not exist. You can test for the existence of a folder by calling ExistsDir and create a folder by calling CreateDir. szFileName Specifies the name of the file to create.

Return Values
Table A-79: Return Values Return Value 0 Description Indicates that the function successfully created the new file. Indicates that the function was unable to create the specified file.

<0

Additional Information
The actions of the CreateFile function are not logged for uninstallation when logging is enabled. If you want a file that is created by CreateFile to be logged for uninstallation, transfer a starter file with the file name you want to the target system using XCopyFile while logging is enabled. You enable and disable logging with the Enable and Disable functions. XCopyFile actions are logged when logging is enabled, so the starter file is logged for uninstallation. After transferring the logged starter file, you can write to or overwrite the logged starter file using CreateFile and other file-related functions. The file name must remain unchanged; otherwise, it is not found during uninstallation.

CreateFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 561

Appendix A: Built-In Functions (A-D) CreateFile

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CreateFile and WriteLine functions. * * CreateFile is called to create a file to store a string. The * string is written into the file by the WriteLine function. * * Note: Before running this script, set the preprocessor * constant EXAMPLE_DIR so that it references an existing * directory on the target system. Note that if the file * specified by EXAMPLE_FILE already exists, it will be * overwritten. * \*--------------------------------------------------------------*/ #define EXAMPLE_DIR "C:\\" #define EXAMPLE_FILE "ISExampl.txt" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CreateFile(HWND); function ExFn_CreateFile(hMSI) STRING szTitle, szMsg; NUMBER nvFileHandle; begin // Set the file mode to append. OpenFileMode (FILE_MODE_APPEND); // Create a new file and leave it open. if (CreateFile (nvFileHandle, EXAMPLE_DIR, EXAMPLE_FILE) < 0) then // Report the error. MessageBox ("CreateFile failed.", SEVERE); abort; else // Set the message to write to the file. szMsg = "This line was appended by an example InstallShield script."; // Append the message to the file. if (WriteLine(nvFileHandle, szMsg) < 0) then // Report the error. MessageBox ("WriteLine failed.", SEVERE); else // Report success. szTitle = "CreateFile & WriteLine"; szMsg = "Successfully created and wrote to %s."; SprintfBox (INFORMATION, szTitle, szMsg, EXAMPLE_FILE); endif; endif; // Close the file. CloseFile (nvFileHandle); end;

562

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CreateInstallationInfo

CreateInstallationInfo
In an event-based script, the CreateInstallationInfo function is called automatically after the First UI Before event. It uses the system variables IFX_KEYPATH_PRODUCT_INFO and IFX_PRODUCT_KEY to create an application information key and a per application paths key for the program you are installing. The application information key is created immediately as a result of calling CreateInstallationInfo. The per application paths key is not created until a subsequent call to RegDBSetItem sets a [Path] or [DefaultPath] value under that key. CreateInstallationInfo provides the product name for display in the Welcome dialog as well as the company name, product name, and version number that MaintenanceStart uses to initialize the uninstallation log file. MaintenanceStart will fail if CreateInstallationInfo is not called before it in the script. Call CreateInstallationInfo only once in a setup. If you are launching multiple installations using DoInstall, each installation can of course have its own call to CreateInstallationInfo. CreateInstallationInfo is a special registry-related function, designed to work with certain predefined registry keys. For more information, see Special Registry-Related Functions.

Note: The InstallScript engine currently does not support writing or reading Add or Remove Programs information for a product in the 64-bit part of the registry. Therefore, using the REGDB_OPTION_WOW64_64KEY option with the REGDB_OPTIONS system variable is not supported for this registry function. Enabling the REGDB_OPTION_WOW64_64KEY option has no effect on where registry entries are created by this function.

Syntax
CreateInstallationInfo ( );

Parameters
None

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

563

Appendix A: Built-In Functions (A-D) CreateObject

Return Values
Table A-80: CreateInstallationInfo Return Values Return Value 0 <0 Description Indicates that the function was successful. Indicates that the function failed to create one or more of the registry keys You can obtain the error message text associated with a large negative return valuefor example, 2147024891 (0x80070005)by calling FormatMessage.

Additional Information
You must call CreateInstallationInfo before calling RegDBSetItem or RegDBGetItem. See the descriptions of those functions for further information. The per application paths key is not actually created until RegDBSetItem is called to set a value under that key. CreateInstallationInfo no longer fails when IFX_COMPANY_NAME, IFX_PRODUCT_NAME, or IFX_PRODUCT_VERSION are empty. CreateInstallationInfo fails if a remote registry is connected, IFX_KEYPATH_PRODUCT_INFO is empty, or the application information registry key cannot be created.

CreateObject
Project: In InstallScript projects, the CreateObject function has been replaced by the CoCreateObject.

The CreateObject function initializes the registered COM object named by szProgID and returns a reference that can be assigned to a variable of type OBJECT by using the set keyword. To check whether the object was initialized successfully, you can use the keywords trycatchendcatch for more control over exception handling for COM objects.

Note: The COM object must be registered on the target system in order for CreateObject to work.

Syntax
CreateObject ( szProgID );

564

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CreateProgramFolder

Parameters
Table A-81: CreateObject Parameters Parameter szProgID Description Specifies the ProgID of the COM object to be initialized.

Return Values
A reference that can be assigned to a variable of type OBJECT by using the set keyword.

CreateProgramFolder
The CreateProgramFolder function creates a new folder on the target system. The folder is created in the Start Programs menu.

Syntax
CreateProgramFolder ( szFolderName );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

565

Appendix A: Built-In Functions (A-D) CreateProgramFolder

Parameters
Table A-82: CreateProgramFolder Parameters Parameter szFolderName Description Specifies the name of the folder to add to the target system.

Return Values
Table A-83: CreateProgramFolder Return Values Return Value 0 Description Indicates that the function successfully added the folder to the target system or that the folder already existed. Indicates that the function was unable to add the specified program folder.

<0

CreateProgramFolder Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CreateProgramFolder function. * * This script creates a program folder named ExampleFolder on * the target system. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CreateProgramFolder(HWND); function ExFn_CreateProgramFolder(hMSI) STRING szFolderName, szTitle, szMsg; begin // Set up parameters for call to CreateProgramFolder. szFolderName = "ExampleFolder"; szTitle = "CreateProgramFolder"; szMsg = "%s created successfully."; // Create the program folder.
566 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CreateRegistrySet

if (CreateProgramFolder (szFolderName) < 0) then MessageBox ("Unable to create program folder", SEVERE); else SprintfBox (INFORMATION, szTitle, szMsg, szFolderName); endif; end;

CreateRegistrySet
The CreateRegistrySet function creates the registry entries specified by one or all registry sets in the current media that are not associated with a particular component. (The name of the current media is stored in the system variable MEDIA.) It is not necessary to call CreateRegistrySet for registry sets that are associated with one or more components since this function has no effect on the these registry sets. Registry entries stored in registry sets that are associated with components are created when the component itself is installed (for example, via a FeatureTransferData call).

Note: When you enable the REGDB_OPTION_WOW64_64KEY option, this affects where registry entries from registry sets are created. For example, if this option is enabled when you call the CreateRegistrySet function, the registry set is created in the 64-bit part of the registry. Note that this includes the default registry set which is created during file transfer immediately after the OnMoving event returns, and registry sets associated with components which are automatically created when the component is installed. Therefore, to avoid the data from these registry sets being created in the 64-bit portion of the registry unintentionally, it is recommended that you set this option only during the calling of the appropriate registry APIs in your script, then disable the option before continuing with the script.

Syntax
CreateRegistrySet (szRegistrySet);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

567

Appendix A: Built-In Functions (A-D) CreateRegistrySet

Parameters
Table A-84: CreateRegistrySet Parameters Parameter szRegistrySet Description Specifies the name of a registry set that is not associated with a particular component in the current media. To create all registry sets that are defined in the current media and are not associated with a particular component, pass a null string ("") in this parameter.

Return Values
Table A-85: CreateRegistrySet Return Values Return Value 0 <0 Description Indicates that the function was successful. Indicates that an unspecified error has occurred.

Additional Information
The value of the system variable MEDIA is set to 'DATA' during setup initialization. If you change the value of this variable to refer to a script-created feature set, you must change the value back to 'DATA' before calling CreateRegistrySet. If a registry set is associated only with components that are not included in the built media (because either they are not included in any features, they are included only in features whose Include in Build property is set to No, or they are included only in features that you have excluded from the built media using the Release Wizards Features panel), the registry set's entries are not automatically created during file transfer and can be installed by a call to CreateRegistrySet.

CreateRegistrySet Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CreateShellObjects and CreateRegistrySet * functions. * * Note: To run this example, you must create a project that * specifies registry entries and shell objects in the * Resources pane of the IDE. * \*--------------------------------------------------------------*/

export prototype ExFn_CreateRegistrySet(HWND); function ExFn_CreateRegistrySet(hMSI) NUMBER ndisk; STRING szPassword;

568

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CreateShellObjects

STRING svDir; begin // Set the default target for copying files. svDir = "C:\\temp"; // Get a target location from the user. AskDestPath ("", "", svDir, 0); // Assign the specified target location to // the corresponding system variable. INSTALLDIR = svDir; // Enable the progress indicator. SetStatusWindow (0, ""); Enable (STATUS); StatusUpdate (ON, 100); // Transfer files. if (ComponentMoveData (MEDIA,ndisk,0) < 0 ) then MessageBox ("Error in moving data", SEVERE); abort; endif; // Create the Registry sets that were defined in the Resources pane. if (CreateRegistrySet ("") < 0) then MessageBox ("Unable to create registry set.", SEVERE); abort; endif; // Create the Shell objects that were defined in the Resources pane. if (CreateShellObjects ("") < 0) then MessageBox ("Unable to create shell objects.", SEVERE); abort; endif; end;

CreateShellObjects
The CreateShellObjects function creates shortcuts that are included in the current media, but are not associated with a particular component. The function also creates the folders that contain the created shortcuts if they do not already exist on the target system. (The name of the current media is stored in the system variable MEDIA.) It is not necessary to call CreateShellObjects for shortcuts that are associated with one or more components because this function has no effect on these shortcuts. Shortcuts that are associated with components are created when the component itself is installed (for example, via a FeatureTransferData call). When the shortcuts are created, the folders containing the shortcuts will also be created, if necessary.

Caution: This function will have no effect if called from an InstallShield object's script. The creation of shell objects is not supported in an InstallShield Object project.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

569

Appendix A: Built-In Functions (A-D) CreateShellObjects

Note: CreateShellObjects will not create an empty folder on the target system: If a folder in the Shortcuts view is empty, this function will not create it. This restriction also applies to the shortcuts and corresponding folders that are automatically created when you call FeatureTransferData. To create an empty folder, call the CreateProgramFolder function in your script.

Syntax
CreateShellObjects (szReserved);

Parameters
Table A-86: CreateShellObjects Parameters Parameter szReserved Description Pass a null string () in this parameter. No other value is allowed.

Return Values
Table A-87: CreateShellObjects Return Values Return Value 0 <0 Description Indicates that the function was successful. Indicates that an unspecified error has occurred.

Additional Information
The value of the system variable MEDIA is set to 'DATA' during setup initialization. If you change the value of this variable to refer to a script-created component set, you must change the value back to 'DATA' before calling CreateShellObjects. This function should be called only after FeatureTransferData has been called.

CreateShellObjects Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CreateShellObjects and CreateRegistrySet * functions. * * Note: To run this example, you must create a project that * specifies registry entries and shell objects in the * Resources pane of the IDE. * \*--------------------------------------------------------------*/

570

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlClear

export prototype ExFn_CreateShellObjects(HWND); function ExFn_CreateShellObjects(hMSI) NUMBER ndisk; STRING szPassword; STRING svDir; begin //Set the default target for copying files. svDir = "C:\\temp"; // Get a target location from the user. AskDestPath ("","",svDir,0); // Assign the specified target location to // the corresponding system variable. INSTALLDIR = svDir; // Enable the progress indicator. SetStatusWindow (0, ""); Enable (STATUS); StatusUpdate (ON, 100); // Transfer files. if (ComponentMoveData (MEDIA,ndisk,0) < 0 ) then MessageBox ("Error in moving data",SEVERE); abort; endif; //Create the Registry sets that were defined in the Resources pane. if (CreateRegistrySet ("") < 0) then MessageBox ("Unable to create registry set.",SEVERE); abort; endif; //Create the Shell objects that were defined in the Resources pane. if (CreateShellObjects ("") < 0) then MessageBox ("Unable to create shell objects.",SEVERE); abort; endif; end;

CtrlClear
The CtrlClear function clears the contents of various controls; it deletes the contents of a single- or multiline edit field, static text field, single- or multi-selection list box, or the edit field of a combo box in a custom dialog.

Syntax
CtrlClear ( szDialogName, nControlID );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

571

Appendix A: Built-In Functions (A-D) CtrlClear

Parameters
Table A-88: CtrlClear Parameters Parameter szDialogName Description Specifies the name of the dialog that contains the control to be deleted. Specifies the control ID of the dialog identified by szDialogName.

nControlID

Return Values
Table A-89: CtrlClear Return Values Return Value 0 Description CtrlClear successfully deleted the contents of the specified control. CtrlClear was unable to delete the contents of the dialog.

<0

CtrlClear Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlClear, CtrlGetText, and CtrlSetText * functions. * * This example script displays a custom dialog that contains * edit boxes for a user name, company name, and serial number. * It also contains three buttons: Clear All, Done, and Cancel. * On initialization of the dialog, the script calls * CtrlSetText to place default text into each edit control. * * Button Operations * * Clear All Calls CtrlClear to clear all edit boxes. * * Done Calls CtrlGetText to retrieve edit box values. * If all fields contain data, the dialog * closes and the values from the edit boxes are * displayed in a message box. * * Cancel Closes the dialog. Edit box values are * not retrieved or displayed.
572 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlClear

* * The "custom" dialog used in this script is actually the * Sd dialog that is displayed by the built-in function * SdRegisterUserEx. Because this dialog is stored * in the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Initial values to #define USER_NAME #define COMPANY_NAME #define SERIAL_NUM display in the edit boxes. "Your Name" "Your Company" "123"

// Dialog and control IDs. #define RES_DIALOG_ID 12002 #define RES_EDIT_NAME 301 #define RES_EDIT_COMPANY 302 #define RES_EDIT_SERIAL 303 #define RES_PBUT_DONE 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_CLEAR 12

// // // // // // //

ID ID ID ID ID ID ID

of of of of of of of

the custom dialog the User Name edit box the Company Name edit box the Serial Number edit box dialog's Next button dialog's Cancel button dialog's Back button

STRING szDialogName, svName, svCompany, svSerial; NUMBER nResult, nCmdValue; BOOL bDone; #include "ifx.h" function OnBegin() begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize the indicator used to control the loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case IDCANCEL: // The user clicked the window's Close button.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 573

Appendix A: Built-In Functions (A-D) CtrlClear

Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the static text of the buttons. CtrlSetText (szDialogName, RES_PBUT_CLEAR, "Clear &All"); CtrlSetText (szDialogName, RES_PBUT_DONE, "&Done"); // Initialize the edit controls. CtrlSetText (szDialogName, RES_EDIT_NAME, USER_NAME); CtrlSetText (szDialogName, RES_EDIT_COMPANY, COMPANY_NAME); CtrlSetText (szDialogName, RES_EDIT_SERIAL, SERIAL_NUM); case RES_PBUT_CLEAR: // Clear all edit controls. CtrlClear (szDialogName, RES_EDIT_NAME); CtrlClear (szDialogName, RES_EDIT_COMPANY); CtrlClear (szDialogName, RES_EDIT_SERIAL); case RES_PBUT_DONE: // Retrieve the text from edit boxes. CtrlGetText (szDialogName, RES_EDIT_NAME, svName); CtrlGetText (szDialogName, RES_EDIT_COMPANY, svCompany); CtrlGetText (szDialogName, RES_EDIT_SERIAL, svSerial); // Verify that all three boxes have data. if (StrLength (svName) = 0) || (StrLength (svCompany) = 0) || (StrLength (svSerial) = 0) then MessageBox ("All fields must be completed.", WARNING); else bDone = TRUE; endif; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory. ReleaseDialog (szDialogName); // If the dialog was closed with the Done button, // display the text from the edit controls. if (nCmdValue = RES_PBUT_DONE) then SprintfBox (INFORMATION, "User Info", "Name: %s\n\nCompany: %s\n\nSerial: %s",
574 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlDir

svName, svCompany,svSerial); endif; end;

CtrlDir
The CtrlDir function fills a list box or a combo box control with a file listing that matches the specified path or file name in szDir. You can include names of files, subdirectories, and disk drives in the listing. The CtrlDir function works only with custom dialogs.

Syntax
CtrlDir ( szDialogName, nControlID, szDir, nItems );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

575

Appendix A: Built-In Functions (A-D) CtrlDir

Parameters
Table A-90: CtrlDir Parameters Parameter szDialogName nControlID Description Specifies the name of a dialog. Specifies the resource ID of the list box or combo box control. Specifies the fully qualified path or file name, which may include wildcard characters. Specifies the type of listing to display in the control. Pass one or more of the following predefined constants in this parameter. To include more than one type of element, combined these constants with the bitwise OR operator (|):

szDir

nItems

DLG_DIR_FILECreates a list of files matching the file specification szDir. DLG_DIR_DIRECTORYCreates a list of subdirectories that exist in the path specification szDir. DLG_DIR_DRIVECreates a list of drives.

Return Values
Table A-91: CtrlDir Return Values Return Value 0 Description CtrlDir successfully filled the specified control in a dialog. CtrlDir was unable to fill the specified control.

<0

CtrlDir Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlDir function. * * This example script displays a file listing in a custom * dialog. The directory listing is created by a call to

576

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlDir

* CtrlDir, which builds the list and places it into the * custom dialog's list box control. The user can then select * an item from the list with the keyboard or mouse. If the * dialog is closed with the Next button, the selected item * is displayed in a message box. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdSetupTypeEx. Because this dialog is stored * in the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID #define RES_PBUT_NEXT #define RES_PBUT_CANCEL #define RES_PBUT_BACK #define RES_DIALOG_LISTBOX #define RES_STA_MSG_ABOVE #define RES_STA_MSG_BELOW

12033 1 9 12 401 710 711

// // // // // // //

ID ID ID ID ID ID ID

of of of of of of of

the custom dialog Next button Cancel button Back button list box static message above list static message below list

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlDir(HWND); function ExFn_CtrlDir(hMSI) STRING szDialogName, svSelection; NUMBER nResult, nCmdValue; BOOL bDone; HWND hwndDlg; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

// Report an error; then terminate. if (nResult < 0) then MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize the indicator used to control the loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue)
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 577

Appendix A: Built-In Functions (A-D) CtrlGetCurSel

case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the messages that appear above and below the list box. CtrlSetText (szDialogName, RES_STA_MSG_ABOVE, "Files found in the root directory of the Windows drive:"); CtrlSetText (szDialogName, RES_STA_MSG_BELOW, "Select a file; then click the Next button"); list of all files in the root directory of the which Windows resides and put it into the dialog's control. (szDialogName, RES_DIALOG_LISTBOX, WINDISK^"*.*", DLG_DIR_FILE) < 0) then MessageBox ("CtrlDir failed.", SEVERE); bDone = TRUE; endif; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_NEXT: // Get the current selection so it can be displayed. CtrlGetCurSel (szDialogName, RES_DIALOG_LISTBOX, svSelection); bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory; ReleaseDialog (szDialogName); // If the Next button was used to close the dialog, // display the item that was selected from the list box. if (nCmdValue = RES_PBUT_NEXT) then MessageBox ( "You selected " + svSelection, INFORMATION); endif; end; // // // if Create a drive on list box (CtrlDir

CtrlGetCurSel
The CtrlGetCurSel function retrieves the currently selected item from a single-selection list box or combo box control in a custom dialog. Call CtrlGetMultCurSel to retrieve items from multi-selection list boxes.
578 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetCurSel

Syntax
CtrlGetCurSel ( szDialogName, nControlID, svText );

Parameters
Table A-92: CtrlGetCurSel Parameters Parameter szDialogName Description Specifies the name of a custom dialog that contains the item to be retrieved. Specifies the resource ID of the single-selection list box or combo box control. Returns the item currently selected with the control specified by nControlID.

nControlID

svText

Return Values
Table A-93: CtrlGetCurSel Return Values l Return Value 0 Description CtrlGetCurSel successfully retrieved the currently selected item from the dialog. CtrlGetCurSel was unable to retrieve the selected item.

<0

CtrlGetCurSel Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlGetCurSel and CtrlSetCurSel functions. * * This example script displays a custom dialog that has an * edit box and a list box. After the dialog is initialized, * the script places the names of folders that reside in the * root of the Windows disk into the dialog's list box. It * then calls CtrlSetCurSel to make "Windows" the selected folder. * * Each time the user selects a folder name from the list box, * the script calls CtrlGetCurSel to get the selected item so * that it can be placed into the edit box. When the dialog * is closed with the Done button, the currently selected item * is displayed in a message box.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 579

Appendix A: Built-In Functions (A-D) CtrlGetCurSel

* * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdSelectFolder. Because this dialog is stored * in the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // The folder that will be preselected in the list box. #define PRESELECTED_FOLDER "windows" // Dialog and control IDs. #define RES_DIALOG_ID #define RES_PBUT_NEXT #define RES_PBUT_CANCEL #define RES_PBUT_BACK #define RES_DIALOG_EDITBOX #define RES_DIALOG_LISTBOX #define RES_STA_DESC

12008 1 9 12 301 401 710

// // // // // // //

ID ID ID ID ID ID ID

of of of of of of of

the custom dialog Next button Cancel button Back button the edit box the list box the text at top of dialog

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlGetCurSel(HWND); function ExFn_CtrlGetCurSel(hMSI) STRING szDialogName, svSelection, szDesc; NUMBER nResult, nCmdValue; BOOL bDone; HWND hwndDlg; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from_isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE);
580 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetCurSel

abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the window title. SetWindowText (hwndDlg, "Select Folder"); // Set the message that appears at the top of the dialog. szDesc = "Specify an existing folder from the root of drive " + WINSYSDISK + "\nThen press Next to continue."; CtrlSetText (szDialogName, RES_STA_DESC, szDesc); // Fill the dialog's list box with the names of all folders // that reside in the root of the Windows drive. CtrlDir (szDialogName, RES_DIALOG_LISTBOX, WINSYSDISK + "\\*.*", DLG_DIR_DIRECTORY); // Select the preselected folder. CtrlSetCurSel (szDialogName, RES_DIALOG_LISTBOX, PRESELECTED_FOLDER); // Put the name of the preselected folder into the edit box. CtrlSetText (szDialogName, RES_DIALOG_EDITBOX, PRESELECTED_FOLDER); case RES_DIALOG_LISTBOX: // Get the current listbox selection. CtrlGetCurSel (szDialogName, RES_DIALOG_LISTBOX, svSelection); // Strip off the brackets. StrSub (svSelection, svSelection, 1, StrLength(svSelection) - 2); // Put the current selection in the edit box. CtrlSetText (szDialogName, RES_DIALOG_EDITBOX, svSelection); case RES_PBUT_BACK: bDone = TRUE; case RES_PBUT_NEXT: // Get the selection from the edit box. CtrlGetText (szDialogName, RES_DIALOG_EDITBOX, svSelection); // Verify that the edit box contains the name of a // folder that exists in the root of the Windows disk. if Is (PATH_EXISTS, WINSYSDISK + "\\"+ svSelection) then bDone = TRUE; else MessageBox ("Folder does not exist.", WARNING); endif ; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); endswitch; until bDone; // Close the custom dialog. EndDialog (szDialogName); // Remove the custom dialog from memory. ReleaseDialog (szDialogName);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 581

Appendix A: Built-In Functions (A-D) CtrlGetDlgItem

// If the edit box was closed with the Done button, // display the selected item. if (nCmdValue = RES_PBUT_NEXT) then MessageBox ("You selected " + svSelection + ".", INFORMATION); endif; end;

CtrlGetDlgItem
The CtrlGetDlgItem function retrieves the window handle of a control in a custom dialog. CtrlGetDlgItem is similar to the Windows API GetDlgItem, except that with CtrlGetDlgItem, you can specify the InstallScript dialog name instead of the dialogs window handle.

Syntax
CtrlGetDlgItem (byval string szDialogName, byval HWND hDialog, byval number nCtrlId);

Parameters
Table A-94: CtrlGetDlgItem Parameters Parameter szDialogName Description Specify the name of the dialog that contains the control whose handle is being retrieved. The dialog must already exist when the function is called. If hDialog is not a null string (""), you can specify a null string for szDialogName. hDialog Specify the window handle of the dialog that contains the control whose handle is being retrieved. The dialog must already exist when the function is called. If you specify a string (""), CtrlGetDlgItem determines the dialogs handle by calling CmdGetHwndDlg using szDialogName. nCtrlId Specify the ID of the control whose window handle you want to retrieve.

Return Values
CtrlGetDlgItem returns the window handle of the control or NULL if the control does not exist or an error occurred. GetExtendedErrInfo may return additional error information.

Additional Information
If you are making multiple calls to CtrlGetDlgItem to look up multiple controls, it is recommended that you call CmdGetHwndDlg to get the handle of the dialog and pass it to each function call. If you are looking up the window handle of a single control, it is recommended that you specify the dialog name and specify hDialog as a null string ("").

582

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetMLEText

CtrlGetMLEText
The CtrlGetMLEText function retrieves the contents of a multi-line edit field control in a custom dialog. InstallShield places each line of the multi-line edit field into a string list identified by listID. Call CtrlGetText to retrieve the contents of a single-line edit field control.

Syntax
CtrlGetMLEText ( szDialogName, nControlID, listID );

Parameters
Table A-95: CtrlGetMLEText Parameters Parameter szDialogName Description Specifies the name of a custom dialog that contains the multi-line edit control whose contents are to be retrieved. Specifies the resource ID of the multi-line edit control. Returns a string list of the lines in the edit field identified by nControlID. The string list identified by listID must already have been initialized by a call to ListCreate.

nControlID listID

Return Values
Table A-96: CtrlGetMLEText Return Values Return Value 0 <0 Description CtrlGetMLEText successfully retrieved the contents of a multi-line edit field. CtrlGetMLEText was unable to retrieve the contents of the control.

CtrlGetMLEText Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlSetMLEText and CtrlGetMLEText functions. * * This example script displays a custom dialog that contains * a multi-line edit box. The script creates a list of all * program folders on the target system and then calls * CtrlSetMLEText to place that list into the dialog's multi* line edit box. The dialog also contains a Save button that * enables the end user to save the folder names to a text file.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 583

Appendix A: Built-In Functions (A-D) CtrlGetMLEText

* When that option is selected, the script calls CtrlGetMLEText * to get the folder names from the multi-line edit box. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdShowInfoList. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * * Notes: The multi-line edit box is defined as read-only * in the resource; its contents cannot be edited. * * The script changes the static text of the dialog * box's Next button and disables the Back button in order * to make the dialog fit the needs of the example. * * The function GetGroupNameList may return an error * if the target system is running under a shell other * than the Explorer shell. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID #define RES_PBUT_BACK #define RES_PBUT_DONE #define RES_PBUT_SAVE #define RES_DIALOG_EDITBOX #define RES_TEXT

12007 12 9 1 301 711

// // // // // //

ID ID ID ID ID ID

of of of of of of

the custom dialog Next button Cancel button Back button edit box text above edit box

// Description to display above the multi-line edit box. #define DESC_TEXT "Click Save to store the list of program folder names in a disk file." // The program names will be saved in the root of the current // drive if the end user clicks the Save button. #define FOLDER_LIST_FILE "\\ISExampl.txt" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlGetMLEText(HWND); function ExFn_CtrlGetMLEText(hMSI) STRING szDialogName; NUMBER nCmdValue, nResult; BOOL bSave, bDone; LIST listFolders; HWND hwndDlg; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate.

584 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetMLEText

MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. bDone = TRUE; case DLG_ERR: MessageBox ("Dialog failed", SEVERE); bDone = TRUE; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the window title. SetWindowText (hwndDlg, "View Program Folders"); // Disable the Back button using a call from Winsub. _WinSubEnableControl (hwndDlg, RES_PBUT_BACK, 0); //Set the dialog's static text. CtrlSetText (szDialogName, RES_TEXT, DESC_TEXT); CtrlSetText (szDialogName, RES_PBUT_SAVE, "&Save"); CtrlSetText (szDialogName, RES_PBUT_DONE, "&Done"); // Create a string list to store the program folder names. listFolders = ListCreate (STRINGLIST); if (listFolders = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); bDone = TRUE; else // Get the folder names into a list. nResult = GetGroupNameList (listFolders); if (nResult = 0) then // Put the folder names into the // dialog's multi-line edit box. nResult = CtrlSetMLEText (szDialogName, RES_DIALOG_EDITBOX, listFolders); elseif (nResult != 0) then // Handle error from GetGroupNameList or CtrlSetMLEText. MessageBox ("Unable to create folder name list.", SEVERE); bDone = TRUE; endif; // Destroy the listID string list.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 585

Appendix A: Built-In Functions (A-D) CtrlGetMultCurSel

ListDestroy (listFolders); endif; case RES_PBUT_SAVE : // Initialize indicator to save program file names. bSave = FALSE; if (AskYesNo("Save list as " + FOLDER_LIST_FILE + "?", YES)) then // Check for existing file. if (Is (FILE_EXISTS, FOLDER_LIST_FILE) = 1) then // Query end user to overwrite existing file. if (AskYesNo ("Overwrite existing " + FOLDER_LIST_FILE + "?", YES)) then bSave = TRUE; endif; else bSave = TRUE; endif; endif; if bSave = TRUE then // Create a string list to store list from dialog. listFolders = ListCreate (STRINGLIST); if (listFolders = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); else // Get the folder names from the // dialog's multi-line edit box. nResult = CtrlGetMLEText (szDialogName, RES_DIALOG_EDITBOX, listFolders); // Save the list to a text file. ListWriteToFile (listFolders, FOLDER_LIST_FILE); // Destroy the listID string list. ListDestroy (listFolders); endif; endif; case RES_PBUT_DONE: bDone = TRUE; endswitch; until bDone; // Close the custom dialog. EndDialog (szDialogName); // Remove the custom dialog from memory. ReleaseDialog (szDialogName); end;

CtrlGetMultCurSel
The CtrlGetMultCurSel function retrieves the currently selected lines from a multi-selection list box control, that is, a list box control with the LBS_MULTIPLESEL style. (This function does not support extended selection list box controls, that is, list box controls with the LBS_EXTENDEDSEL style.) Each

586

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetMultCurSel

selected line of the multi-selection list box is placed into a string list identified by listID. To retrieve selected text from a single-selection list box control, call CtrlGetCurSel. CtrlGetMultCurSel is for use only with custom dialogs.

Syntax
CtrlGetMultCurSel ( szDialogName, nControlID, listID );

Parameters
Table A-97: CtrlGetMultCurSel Parameters Parameter szDialogName Description Specifies the name of a custom dialog that contains the list box control whose contents are to be retrieved. Specifies the resource ID of the multi-line edit control. Returns the lines of the list box identified by nControlID. The string list identified by listID must already have been initialized by a call to ListCreate.

nControlID

listID

Return Values
Table A-98: CtrlGetMultCurSel Return Values Return Value 0 Description CtrlGetMultCurSel successfully retrieved the currently selected items. CtrlGetMultCurSel was unable to retrieve the items.

<0

CtrlGetMultCurSel Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlSetMultCurSel and CtrlGetMultCurSel * functions. * * This script retrieves the names of all program folders * on the target system and places them in a list. When the * dialog is initialized, the CtrlSetList function sets this * list to be displayed in the list box. The CtrlSetMultCurSel
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 587

Appendix A: Built-In Functions (A-D) CtrlGetMultCurSel

* function is then called to highlight the user-selected * folder. * * This list is then destroyed. A new list is created when the * Next button is clicked. CtrlGetMultCurSel then retrieves the * elements in the list box and assigns them to this new string * list. This list is then displayed in an Sd dialog. * * Note: In order for this script to run properly, you must set * the RES_DIALOG_ID and RES_DIALOG_LISTBOX constants to a * dialog and list box created in _isuser.dll. * * The GetGroupNameList function used in this example may * return an error if the target system is running under a * shell other than Explorer. * \*--------------------------------------------------------------*/ // Dialog control IDs. #define RES_DIALOG_ID #define RES_PBUT_NEXT #define RES_PBUT_CANCEL #define RES_PBUT_BACK #define RES_DIALOG_LISTBOX

1 9 12

// // // // //

ID ID ID ID ID

of of of of of

dialog itself Next button Cancel button Back button list box

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlGetMultCurSel(HWND); function ExFn_CtrlGetMultCurSel(hMSI) STRING szDialogName, szDLL, szTitle, szMsg; STRING szText, szDefFolder, svResultFolder; NUMBER nCmdValue, nResult, nControlID, nSelectFlag; BOOL bDone; LIST listID, listFolders; begin Disable(BACKBUTTON); szDialogName = "CtrlSetMultCurSel"; szDLL = ""; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, szDLL, "", RES_DIALOG_ID);

if (nResult < 0) then MessageBox ("Error in defining dialog", SEVERE); bDone = TRUE; else bDone = FALSE; endif; // Create the listID string list. listID = ListCreate (STRINGLIST); if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); else
588 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetMultCurSel

MessageBox ("listID created.", INFORMATION); endif; // Retrieve the program folder names into a list. GetGroupNameList (listID); // Retrieve a folder name from the user. szTitle = "CtrlGetMultCurSel & CtrlSetMultCurSel"; SelectFolder (szTitle, szDefFolder, svResultFolder); // Loop until done. while (bDone = FALSE) // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.",SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // The following sets the list box to the list of program folders. nControlID = RES_DIALOG_LISTBOX; CtrlSetList (szDialogName, nControlID, listID); szText = svResultFolder; nSelectFlag = TRUE; //Set the user-selected folder to be highlighted. if (CtrlSetMultCurSel (szDialogName, nControlID, szText, nSelectFlag) < 0) then MessageBox ("CtrlSetMultCurSel failed.", SEVERE); endif; // Destroy the listID string list. ListDestroy (listID); MessageBox ("listID destroyed.", INFORMATION); case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case RES_PBUT_NEXT: // Create the listFolders string list. listFolders = ListCreate (STRINGLIST); if (listFolders = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); else MessageBox ("listFolders created.", INFORMATION); endif; // Retrieve the highlighted elements in the list box, and // put them into the listFolders string list. if (CtrlGetMultCurSel (szDialogName, nControlID, listFolders) < 0) then
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 589

Appendix A: Built-In Functions (A-D) CtrlGetState

MessageBox ("CtrlGetMultCurSel failed.", SEVERE); else MessageBox ("CtrlGetMultCurSel successful.", INFORMATION); endif; bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; case RES_PBUT_CANCEL: // The user clicked the window's Cancel button. Do (EXIT); endswitch; endwhile; szMsg = "The following are the elements highlighted in the list box:";

// Display the list of elements highlighted. SdShowInfoList (szTitle, szMsg, listFolders); // Remove listFolders string list from memory. ListDestroy (listFolders); MessageBox ("listFolders destroyed.", INFORMATION); // Close the dialog. EndDialog (szDialogName); // Remove the dialog from memory. ReleaseDialog (szDialogName); end;

CtrlGetState
The CtrlGetState function gets the current state of a check box or option button control from a custom dialog.

Syntax
CtrlGetState ( szDialogName, nControlID );

590

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetState

Parameters
Table A-99: CtrlGetState Parameters Parameter szDialogName Description Specifies the name of the dialog that contains the control. Specifies the resource ID of the check box or option button control whose state is to be retrieved.

nControlID

Return Values
Table A-100: CtrlGetState Return Values Return Value BUTTON_CHECKED (-1001) BUTTON_UNCHECKED (-1002) DLG_ERR (-1) Description The check box or option button is selected. The check box or option button is not selected. CtrlGetState was unable to determine the state of the control.

CtrlGetState Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlGetState and CtrlSetState functions. * * This example script displays a custom dialog that contains * four check boxes. The script calls CtrlSetState to set the * first two check boxes to checked. The last two are unchecked * by default. When the end user clicks the Next button, the * script calls CtrlGetState to retrieve the state of each * each check box. The script then displays a message box that * reports which check boxes were checked. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdAskOptions. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 591

Appendix A: Built-In Functions (A-D) CtrlGetState

// Dialog and control IDs. #define RES_DIALOG_ID 12020 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12 #define ID_OP1_CHECK 501 #define ID_OP2_CHECK 502 #define ID_OP3_CHECK 503 #define ID_OP4_CHECK 504 #define ID_STA_DESC 711

// // // // // // // // //

ID ID ID ID ID ID ID ID ID

of of of of of of of of of

the custom dialog Next button Cancel button Back button Option 1 check box Option 2 check box Option 3 check box Option 4 check box static text description

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlGetState(HWND); function ExFn_CtrlGetState(hMSI) STRING szDialogName, szMsg; NUMBER nResult, nCmdValue, hwndDlg; BOOL bDone; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "ExDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize the indicator used to control the loop. bDone = FALSE; repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, "");
592 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetState

// Set the window title. SetWindowText (hwndDlg, "Select Options"); // Set static text description displayed above check boxes. CtrlSetText (szDialogName, ID_STA_DESC, "Select and/or clear options. Then click Next."); // Options are cleared by default, so select Options 1 and 2. if (CtrlSetState (szDialogName, ID_OP1_CHECK, BUTTON_CHECKED) < 0) then MessageBox ("First call to CtrlSetState failed.", SEVERE); bDone = TRUE; elseif (CtrlSetState(szDialogName, ID_OP2_CHECK, BUTTON_CHECKED) < 0) then MessageBox ("Second call to CtrlSetState failed.", SEVERE); bDone = TRUE; endif; case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Build message if end user clicked the Next button. if (nCmdValue = RES_PBUT_NEXT) then // Start building the message to display to the end user. szMsg = "You selected the following items:\n\n"; // If first option is selected, add line to message. if (CtrlGetState (szDialogName, ID_OP1_CHECK) = BUTTON_CHECKED) then szMsg = szMsg + "Option 1\n"; endif; // If second option is selected, add line to message. if (CtrlGetState (szDialogName, ID_OP2_CHECK) = BUTTON_CHECKED) then szMsg = szMsg + "Option 2\n"; endif; // If third option is selected, add line to message. if (CtrlGetState (szDialogName, ID_OP3_CHECK) = BUTTON_CHECKED) then szMsg = szMsg + "Option 3\n"; endif; // If fourth option is selected, add line to message. if (CtrlGetState (szDialogName, ID_OP4_CHECK) = BUTTON_CHECKED) then szMsg = szMsg + "Option 4\n"; endif; endif; // Close the custom dialog. EndDialog (szDialogName); // Remove the custom dialog from memory. ReleaseDialog (szDialogName); // Display message if dialog was closed with Next button. if (nCmdValue = RES_PBUT_NEXT) then
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 593

Appendix A: Built-In Functions (A-D) CtrlGetSubCommand

MessageBox (szMsg, INFORMATION); endif; end;

CtrlGetSubCommand
The CtrlGetSubCommand function retrieves the action performed on a control in a custom dialog. For example, CtrlGetSubCommand can tell you if the user single-clicked or double-clicked a list box or combo box control. It can also tell you when the contents of an edit field have changed. Advanced developers can call CmdGetHwndDlg to handle additional information.

Syntax
CtrlGetSubCommand (szDialogName);

Parameters
Table A-101: CtrlGetSubCommand Parameters Parameter szDialogName Description Specifies the name of a custom dialog.

Return Values
Table A-102: CtrlGetSubCommand Return Values Return Value EDITBOX_CHANGE (-1007) LISTBOX_ENTER (-1008) LISTBOX_SELECT (-1009) Description The contents of the edit box have changed. The user double-clicked a list box item. The user single-clicked a list box item.

CtrlGetSubCommand Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlGetSubCommand function. * * This example script displays a list of program groups in * the list box of a custom dialog. It then responds to events

594

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetSubCommand

* from the edit box and list box as follows: * * Single-click in list box: Selected item is put into edit box. * * Double-click in list box: Double-clicked item is stored for * later display and dialog is closed. * * Change in edit box value: The default system sound is played. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdSelectFolder. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID #define RES_PBUT_NEXT #define RES_PBUT_CANCEL #define RES_PBUT_BACK #define RES_DIALOG_EDITBOX #define RES_DIALOG_LISTBOX

12008 1 9 12 301 401

// // // // // //

ID ID ID ID ID ID

of of of of of of

custom dialog Next button Cancel button Back button edit box list box

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlGetSubCommand(HWND); function ExFn_CtrlGetSubCommand(hMSI) STRING szDialogName, svSelection; NUMBER nResult, nCmdValue, nSubCommand; BOOL bDone, bSelected; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize indicators used to control the while loop // and indicate whether an item was selected. bDone = FALSE; bSelected = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 595

Appendix A: Built-In Functions (A-D) CtrlGetSubCommand

// Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Place a list of folders into the dialog's list box. if (CtrlPGroups (szDialogName, RES_DIALOG_LISTBOX) < 0) then MessageBox ("CtrlPGroups failed.", SEVERE); endif; case RES_DIALOG_LISTBOX: // Get the event. nSubCommand = CtrlGetSubCommand (szDialogName); if (nSubCommand = LISTBOX_SELECT) then // Single-click: Put the selected item in the edit box. CtrlGetCurSel (szDialogName, RES_DIALOG_LISTBOX, svSelection ); CtrlSetText (szDialogName, RES_DIALOG_EDITBOX, svSelection ); elseif (nSubCommand = LISTBOX_ENTER) then // Double-click: Get the selected item and set // indicator to exit. CtrlGetCurSel (szDialogName, RES_DIALOG_LISTBOX, svSelection ); bSelected = TRUE; bDone = TRUE; endif; case RES_DIALOG_EDITBOX: // Get the event. nSubCommand = CtrlGetSubCommand (szDialogName); // Play default system sound if the edit box contents have changed. if (nSubCommand = EDITBOX_CHANGE) then MessageBeep (0); endif; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_NEXT: // Get the current selection from the edit box. CtrlGetText (szDialogName, RES_DIALOG_EDITBOX, svSelection ); bSelected = TRUE; bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory.
596 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetText

ReleaseDialog (szDialogName); if bSelected then // Display the name of the selected folder. MessageBox ("You selected " + svSelection +".",INFORMATION); endif; end;

CtrlGetText
The CtrlGetText function retrieves the text from an edit field, static text field, or button control of a custom dialog. To retrieve the text from multi-line edit field controls, call CtrlGetMLEText.

Syntax
CtrlGetText ( szDialogName, nControlID, svText );

Parameters
Table A-103: CtrlGetText Parameters Parameter szDialogName Description Specifies the name of a dialog that contains the field or control whose text is to be retrieved. Specifies the resource ID of the edit field, static text field, or button control. Returns the text from the control or field identified by nControlID.

nControlID

svText

Return Values
Table A-104: CtrlGetText Return Values Return Value 0 Description CtrlGetText successfully retrieved the contents of the control. CtrlGetText was unable to retrieve the contents.

<0

CtrlGetText Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 597

Appendix A: Built-In Functions (A-D) CtrlGetText

* * InstallShield Example Script * * Demonstrates the CtrlSetText, CtrlGetText, and CtrlSelectText * functions. * * This example script displays a custom dialog with two * edit boxes to obtain a user name and company name. The * script calls CtrlSetText to place initial values into the * edit boxes and CtrlSelectText to select the contents of the * first edit box. When the user clicks the Next button, the * script calls CtrlGetText to retrieve the contents of the edit * boxes so that they can be displayed in a message box after * the custom dialog is closed. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdRegisterUser. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12001 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12 #define RES_EDITNAME 301 #define RES_EDITCOMPANY 302

// // // // // //

ID ID ID ID ID ID

of of of of of of

custom dialog Next button Cancel button Back button edit box edit box

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlGetText(HWND); function ExFn_CtrlGetText(hMSI) STRING szDialogName, svName, svCompany; NUMBER nResult, nCmdValue; BOOL bDone; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize indicator used to control the loop. bDone = FALSE; // Loop until done.
598 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetText

repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Put initial values into the edit boxes. CtrlSetText (szDialogName, RES_EDITNAME, "Your name"); CtrlSetText (szDialogName, RES_EDITCOMPANY, "Your company"); // Select the Name edit box. CtrlSelectText (szDialogName, RES_EDITNAME); case RES_PBUT_NEXT: // Get the contents of the edit boxes. CtrlGetText (szDialogName, RES_EDITNAME, svName); CtrlGetText (szDialogName, RES_EDITCOMPANY, svCompany); // Verify that both edit boxes have data. if (StrLength(svName) = 0) || (StrLength(svCompany) = 0) then MessageBox ("Both fields must be completed.", INFORMATION); else bDone = TRUE; endif; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Remove the dialog from memory. ReleaseDialog (szDialogName); // If dialog is closed with Next button, display name and company. if nCmdValue = RES_PBUT_NEXT then MessageBox (svName + "\n" + svCompany, INFORMATION); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

599

Appendix A: Built-In Functions (A-D) CtrlGetUrlForLinkClicked

CtrlGetUrlForLinkClicked
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The CtrlGetUrlForLinkClicked function retrieves the URL for a link that an end user clicked.

Tip: To learn how to add links to dialogs in InstallScript and InstallScript MSI projects, see Using an HTML Control on a Dialog.

Syntax
CtrlGetUrlForLinkClicked (byval string szDialogName, byval number nControlID, byref string svText);

Parameters
Table A-105: CtrlGetUrlForLinkClicked Parameters Parameter szDialogName nControlID Description Specify the name of the dialog that contains the HTML control. Specify the control ID of the HTML control. This ID is the same as the ID of the static control that was converted into an HTML control. Specify the string variable to return the link URL text.

svText

Return Values
Table A-106: CtrlGetUrlForLinkClicked Return Values Return Value 0 ISERR_GEN_FAILURE Description CtrlGetUrlForLinkClicked was able to determine the link that the end user clicked. CtrlGetUrlForLinkClicked was unable to determine the link that an end user clicked. This function returns this value if the specified control ID is not for an HTML control.

CtrlGetUrlForLinkClicked Example
Project: This information applies to the following project types:

600

InstallScript

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlGetUrlForLinkClicked

InstallScript MSI

//--------------------------------------------------------------------------// // InstallShield Example Script // // Demonstrates how to use an HTML control with the // CtrlGetUrlForLinkClicked and CtrlSetText functions // // To use this sample script: // 1. Add a custom dialog to your project. // 2. Add a static text control to the dialog. // //---------------------------------------------------------------------------

#define MY_HYPERLINK1 1401 function MyCustomDialog(szTitle, szMsg) STRING szDlg, szTemp, szUrl; NUMBER nId, nMessage, nTemp, nSdDialog; HWND hwndDlg; BOOL bDone; begin // TO DO: add code to define the custom dialog while (!bDone) nId = WaitOnDialog( szDlg ); switch(nId) case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Put the corresponding Info in the List Field if( szMsg != "" ) then SdSetStatic(szDlg, SD_STA_MSG, szMsg); endif; SdSetDlgTitle(szDlg, hwndDlg, szTitle); CtrlSetText(szDlg, MY_HYPERLINK1, "[html]<style type=\"text/css\">html,body {padding:0; margin:0;} * {font-size: 8pt; font-family: \"MS Sans Serif\";}</style> <a href=\"http://www.MyWebSite.com\"> Visit my Web site</a>"); case MY_HYPERLINK1: CtrlGetUrlForLinkClicked(szDlg, MY_HYPERLINK1, szUrl); MessageBox("Hyperlink clicked: " + szUrl, 0); // TO DO: Add additional case statements as needed. default: // check standard handling
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 601

Appendix A: Built-In Functions (A-D) CtrlPGroups

if (SdIsStdButton( nId ) && SdDoStdButton( nId )) then bDone = TRUE; endif; endswitch; endwhile; end;

CtrlPGroups
The CtrlPGroups function places a list of existing program folders in a list box or combo box control. This function is for use only with custom dialogs.

Syntax
CtrlPGroups ( szDialogName, nControlID );

Parameters
Table A-107: CtrlPGroups Parameters Parameter szDialogName Description Specifies the name of a custom dialog that contains the control to use. Specifies the resource ID of a list box or combo box control.

nControlID

Return Values
Table A-108: CtrlPGroups Return Values Return Value 0 Description CtrlPGroups successfully placed the specified list of program folders in the control. CtrlPGroups was unable to place the specified list of program folders in the control.

<0

CtrlPGroups Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script *
602 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlPGroups

* Demonstrates the CtrlPGroups function. * * This example script displays a custom dialog that has an * edit box and a list box. After the dialog is initialized, * the script calls CtrlPGroups to create a list of program * folder names and place that list into the dialog's list box. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdSelectFolder. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12008 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12 #define RES_DIALOG_EDITBOX 301 #define RES_DIALOG_LISTBOX 401

// // // // // //

ID ID ID ID ID ID

of of of of of of

custom dialog Next button Cancel button Back button edit box list box

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlPGroups(HWND); function ExFn_CtrlPGroups(hMSI) STRING szDialogName, svSelection; NUMBER nResult, nCmdValue, nControlID; BOOL bDone; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE:
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 603

Appendix A: Built-In Functions (A-D) CtrlPGroups

// The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Place a list of folders into the dialog's list box. if (CtrlPGroups (szDialogName, RES_DIALOG_LISTBOX) < 0) then MessageBox ("CtrlPGroups failed.", SEVERE); bDone = TRUE; endif; case RES_DIALOG_LISTBOX: // Get the current list box selection. CtrlGetCurSel (szDialogName, RES_DIALOG_LISTBOX, svSelection); // Put the current selection in the edit box. CtrlSetText (szDialogName, RES_DIALOG_EDITBOX, svSelection); case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_NEXT: // Get the current value of the edit box. CtrlGetText (szDialogName, RES_DIALOG_EDITBOX, svSelection); // Verify that the edit box contains the name of an // existing program folder. if CtrlSetCurSel (szDialogName, RES_DIALOG_LISTBOX, svSelection) = 0 then bDone = TRUE; else MessageBox ("Program folder does not exist.", WARNING); endif; case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory. ReleaseDialog (szDialogName); // If the edit box was closed with the Done button, // display the selected item. if (nCmdValue = RES_PBUT_NEXT) then MessageBox ( "You selected " + svSelection + ".", INFORMATION); endif; end;

604

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSelectText

CtrlSelectText
The CtrlSelectText function selects all the text in an edit field or the edit field of a combo box. If the control is a multi-line edit field, this function selects all the text on all lines. This function is for use only with custom dialogs.

Syntax
CtrlSelectText ( szDialogName, nControlID );

Parameters
Table A-109: CtrlSelectText Parameters Parameter szDialogName Description Specifies the name of a valid dialog that contains the edit field to be selected. Specifies the resource ID of the edit field or combo box control to be selected.

nControlID

Return Values
Table A-110: CtrlSelectText Return Values Return Value 0 Description CtrlSelectText successfully selected all the text in the field. CtrlSelectText was unable to select the text.

<0

CtrlSelectText Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlSetText, CtrlGetText, and CtrlSelectText * functions. * * This example script displays a custom dialog with two * edit boxes to obtain a user name and company name. The * script calls CtrlSetText to place initial values into the * edit boxes and CtrlSelectText to select the contents of the * first edit box. When the user clicks the Next button, the * script calls CtrlGetText to retrieve the contents of the edit
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 605

Appendix A: Built-In Functions (A-D) CtrlSelectText

* boxes so that they can be displayed in a message box after * the custom dialog is closed. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdRegisterUser. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12001 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12 #define RES_EDITNAME 301 #define RES_EDITCOMPANY 302

// // // // // //

ID ID ID ID ID ID

of of of of of of

custom dialog Next button Cancel button Back button edit box edit box

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlSelectText(HWND); function ExFn_CtrlSelectText(hMSI) STRING szDialogName, svName, svCompany; NUMBER nResult, nCmdValue; BOOL bDone; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize indicator used to control the loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE);
606 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetCurSel

abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Put initial values into the edit boxes. CtrlSetText (szDialogName, RES_EDITNAME, "Your name"); CtrlSetText (szDialogName, RES_EDITCOMPANY, "Your company"); // Select the Name edit box. CtrlSelectText (szDialogName, RES_EDITNAME); case RES_PBUT_NEXT: // Get the contents of the edit boxes. CtrlGetText (szDialogName, RES_EDITNAME, svName); CtrlGetText (szDialogName, RES_EDITCOMPANY, svCompany); // Verify that both edit boxes have data. if (StrLength(svName) = 0) || (StrLength(svCompany) = 0) then MessageBox ("Both fields must be completed.", INFORMATION); else bDone = TRUE; endif; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Remove the dialog from memory. ReleaseDialog (szDialogName); // If dialog is closed with Next button, display name and company. if nCmdValue = RES_PBUT_NEXT then MessageBox (svName + "\n" + svCompany, INFORMATION); endif; end;

CtrlSetCurSel
The CtrlSetCurSel function searches the specified list or combo box control for a string. If the string is found, CtrlSetCurSel selects (highlights) the item. Call CtrlSetMultCurSel for multi-selection list box and combo box controls. The CtrlSetCurSel function is for use only with custom dialogs.

Syntax
CtrlSetCurSel ( szDialogName, nControlID, szText );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

607

Appendix A: Built-In Functions (A-D) CtrlSetCurSel

Parameters
Table A-111: CtrlSetCurSel Parameters Parameter szDialogName Description Specifies the name of a valid custom dialog that contains the control to be searched. Specifies the resource ID of the control that contains the search string. Specifies the search string. If the string is found, it is selected (highlighted).

nControlID

szText

Return Values
Table A-112: CtrlSetCurSel Return Values Return Value 0 Description CtrlSetCurSel successfully found and selected the specified string. CtrlSetCurSel was unable to find and select the specified string.

<0

CtrlSetCurSel Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlGetCurSel and CtrlSetCurSel functions. * * This example script displays a custom dialog that has an * edit box and a list box. After the dialog is initialized, * the script places the names of folders that reside in the * root of the Windows disk into the dialog's list box. It * then calls CtrlSetCurSel to make "Windows" the selected folder. * * Each time the user selects a folder name from the list box, * the script calls CtrlGetCurSel to get the selected item so * that it can be placed into the edit box. When the dialog * is closed with the Done button, the currently selected item * is displayed in a message box. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdSelectFolder. Because this dialog is stored
608 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetCurSel

* in the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // The folder that will be preselected in the list box. #define PRESELECTED_FOLDER "windows" // Dialog and control IDs. #define RES_DIALOG_ID #define RES_PBUT_NEXT #define RES_PBUT_CANCEL #define RES_PBUT_BACK #define RES_DIALOG_EDITBOX #define RES_DIALOG_LISTBOX #define RES_STA_DESC

12008 1 9 12 301 401 710

// // // // // // //

ID ID ID ID ID ID ID

of of of of of of of

the custom dialog Next button Cancel button Back button the edit box the list box the text at top of dialog

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlSetCurSel(HWND); function ExFn_CtrlSetCurSel(hMSI) STRING szDialogName, svSelection, szDesc; NUMBER nResult, nCmdValue; BOOL bDone; HWND hwndDlg; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from_isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 609

Appendix A: Built-In Functions (A-D) CtrlSetCurSel

// IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the window title. SetWindowText (hwndDlg, "Select Folder"); // Set the message that appears at the top of the dialog. szDesc = "Specify an existing folder from the root of drive " + WINSYSDISK + "\nThen press Next to continue."; CtrlSetText (szDialogName, RES_STA_DESC, szDesc); // Fill the dialog's list box with the names of all folders // that reside in the root of the Windows drive. CtrlDir (szDialogName, RES_DIALOG_LISTBOX, WINSYSDISK + "\\*.*", DLG_DIR_DIRECTORY); // Select the preselected folder. CtrlSetCurSel (szDialogName, RES_DIALOG_LISTBOX, PRESELECTED_FOLDER); // Put the name of the preselected folder into the edit box. CtrlSetText (szDialogName, RES_DIALOG_EDITBOX, PRESELECTED_FOLDER); case RES_DIALOG_LISTBOX: // Get the current list box selection. CtrlGetCurSel (szDialogName, RES_DIALOG_LISTBOX, svSelection); // Strip off the brackets. StrSub (svSelection, svSelection, 1, StrLength(svSelection) - 2); // Put the current selection in the edit box. CtrlSetText (szDialogName, RES_DIALOG_EDITBOX, svSelection); case RES_PBUT_BACK: bDone = TRUE; case RES_PBUT_NEXT: // Get the selection from the Edit box. CtrlGetText (szDialogName, RES_DIALOG_EDITBOX, svSelection); // Verify that the edit box contains the name of a // folder that exists in the root of the Windows disk. if Is (PATH_EXISTS, WINSYSDISK + "\\"+ svSelection) then bDone = TRUE; else MessageBox ("Folder does not exist.", WARNING); endif ; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); endswitch; until bDone; // Close the custom dialog. EndDialog (szDialogName); // Remove the custom dialog from memory. ReleaseDialog (szDialogName); // If the edit box was closed with the Done button, // display the selected item. if (nCmdValue = RES_PBUT_NEXT) then
610 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetFont

MessageBox ("You selected " + svSelection + ".", INFORMATION); endif; end;

CtrlSetFont
The CtrlSetFont function specifies a font for a control in a custom dialog. Call this function from within the DLG_INIT routine of the dialog message processing loop.

Syntax
CtrlSetFont ( szDialogName, hFont, nControlID );

Parameters
Table A-113: CtrlSetFont Parameters Parameter szDialogName hFont Description Specifies the name of a valid dialog. Specifies the handle of a font that has been created by a call to GetFont Specifies the resource ID of the control whose font is to be set. To set the font for all the controls in the dialog, pass the predefined constant ALLCONTROLS in this parameter.

nControlID

Return Values
Table A-114: CtrlSetFont Return Values Return Value 0 Description CtrlSetFont successfully set the requested font in a dialog. CtrlSetFont was unable to set the font in the requested dialog.

<0

CtrlSetFont Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 611

Appendix A: Built-In Functions (A-D) CtrlSetFont

* * Demonstrates the GetFont and CtrlSetFont functions. * * This example script calls GetFont to retrieve the handles * of four fonts. These handles are then passed to CtrlSetFont * to set the font of the static text fields in a custom dialog * box. * * The "custom" dialog used in this script is actually the * InstallShield dialog that is displayed by the built-in * function SetupType. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 10203 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_TEXT_1 202 #define RES_TEXT_2 #define RES_TEXT_3 #define RES_TEXT_4 210 220 230

// // // //

ID ID ID ID

of of of of

the custom dialog Next button Cancel button first static text box

// ID of second static text box // ID of third static text box // ID of fourth static text box

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlSetFont(HWND); function ExFn_CtrlSetFont(hMSI) STRING szDialogName; NUMBER nResult, nCmdValue; HWND hFont1, hFont2, hFont3, hFont4; BOOL bDone; begin // Get the handle of the fonts to use for the static text // that is displayed by the custom dialog. hFont1 = GetFont("Arial", 14, STYLE_BOLD); hFont2 = GetFont("Times New Roman", 11, STYLE_ITALIC); hFont3 = GetFont("Arial", 10, STYLE_BOLD); hFont4 = GetFont("Courier New", 9, STYLE_NORMAL); if (hFont1 = 0 || hFont2 = 0 || hFont3 = 0 || hFont4 = 0) then // Report an error; then terminate. MessageBox ("Unable to get all fonts. ", SEVERE); abort; endif; // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // // // // Define to get string by its the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter.

nResult = EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

612

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetFont

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog.", SEVERE); abort; endif; // Initialize indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the font and text for static text box 1. if (CtrlSetFont (szDialogName, hFont1, RES_TEXT_1) = 0) then CtrlSetText (szDialogName, RES_TEXT_1, "This text is set in 14-point Arial bold."); else CtrlSetText (szDialogName, RES_TEXT_1, "Unable to set font for first static text box."); endif; // Set font and text for static text box 2. if (CtrlSetFont (szDialogName, hFont2, RES_TEXT_2) = 0) then CtrlSetText (szDialogName, RES_TEXT_2, "This text is set in 11-point Times New Roman italic."); else CtrlSetText (szDialogName, RES_TEXT_2, "Unable to set font for second static text box."); endif; // Set font and text for static text box 3. if (CtrlSetFont (szDialogName, hFont3, RES_TEXT_3) = 0) then CtrlSetText (szDialogName, RES_TEXT_3, "This text is set in 10-point Arial bold."); else CtrlSetText (szDialogName, RES_TEXT_3, "Unable to set font for third static text box."); endif; // Set font and text for static text box 4. if (CtrlSetFont (szDialogName, hFont4, RES_TEXT_4) = 0) then CtrlSetText (szDialogName, RES_TEXT_4, "This text is set in 9-point Courier New.");
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 613

Appendix A: Built-In Functions (A-D) CtrlSetList

else CtrlSetText (szDialogName, RES_TEXT_4, "Unable to set font for fourth static text box."); endif; case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); endswitch; until bDone; // Close the dialog EndDialog (szDialogName); // Free the dialog from memory ReleaseDialog (szDialogName); end;

CtrlSetList
The CtrlSetList function places the contents of a string list into the specified single- or multi-selection list box or combo box control. Any pre-existing contents are replaced with the items contained in listID. InstallShield places each element of the string list into each element of the list box or combo box control.

Syntax
CtrlSetList (szDialogName, nControlID, listID);

614

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetList

Parameters
Table A-115: CtrlSetList Parameters Parameter szDialogName Description Specifies the name of a dialog that contains the list box or combo box. Specifies the resource ID of the list box or combo box. Specifies the name of a string list that contains the elements to be copied into the list box or combo box control.

nControlID

listID

Return Values
Table A-116: CtrlSetList Return Values Return Value 0 Description CtrlSetList successfully placed the contents of the string list into the control. CtrlSetList was unable to place the contents of the string list into the control.

<0

CtrlSetList Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlSetList function. * * This example script displays a custom dialog that * contains a list box. After the dialog is initialized, * the script calls CtrlSetList to place a list of * InstallShield background color constants into the custom dialogs * list box. * * The user can view the background that corresponds to a * color constant either by double-clicking the constant or by * selecting it and clicking the Set button. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdSetupTypeEx. Because this dialog is stored in * the file _isres.dll, which is already compressed in
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 615

Appendix A: Built-In Functions (A-D) CtrlSetList

* the installation, it can be used in a script as a custom * dialog. Note that the script changes the dialog's * static text and disables the Back button to make the dialog * meet the requirements of the example. * \*--------------------------------------------------------------*/ // Dialog controls. #define RES_DIALOG_ID #define RES_PBUTTON_SET #define RES_PBUTTON_DONE #define RES_PBUTTON_BACK #define RES_DIALOG_LISTBOX #define RES_TEXT_ABOVE #define RES_TEXT_BELOW

12033 1 9 12 401 710 711

// // // // // // //

ID ID ID ID ID ID ID

of of of of of of of

the custom dialog Next button Cancel button Back button edit box. text above edit box text below edit box

// Description to display above and below the multi-line edit box. #define DESC_TEXT_ABOVE "View the background colors that can be produced with InstallShield's predefined constants." #define DESC_TEXT_BELOW "To change the background color, select a color; then click the Set button. Or double-click the color name." // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" // Script-defined function to create color list. prototype CreateColorList (); // Script-defined functions to change background color. prototype SetBackgroundColor (STRING); export prototype ExFn_CtrlSetList(HWND); function ExFn_CtrlSetList(hMSI) STRING szDialogName, svCurSel; NUMBER nCmdValue, nResult; BOOL bDone; LIST listBackgroundColors; HWND hwndDlg; begin Enable ( BACKGROUND ); // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Call script-defined function to create color list. listBackgroundColors = CreateColorList (); if (listBackgroundColors = LIST_NULL) then
616 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetList

MessageBox ("Unable to create list of background colors", SEVERE); abort; endif; // Initialize indicator used to control the loop. bDone = FALSE; repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. bDone = TRUE; case DLG_ERR: MessageBox ("Dialog failed", SEVERE); bDone = TRUE; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the window title. SetWindowText (hwndDlg, "View Program Folders"); //Set the dialog's static text. CtrlSetText (szDialogName, RES_TEXT_ABOVE, DESC_TEXT_ABOVE); CtrlSetText (szDialogName, RES_TEXT_BELOW, DESC_TEXT_BELOW); CtrlSetText (szDialogName, RES_PBUTTON_SET, "&Set"); CtrlSetText (szDialogName, RES_PBUTTON_DONE, "&Done"); // Disable the Back button using a call from Winsub. _WinSubEnableControl (hwndDlg, RES_PBUTTON_BACK, 0); // Place the list of colors into the dialog's list box. nResult = CtrlSetList (szDialogName, RES_DIALOG_LISTBOX, listBackgroundColors); if (nResult != 0) then // Handle error from CtrlSetList. MessageBox ("Unable to create folder name list.", SEVERE); bDone = TRUE; endif; // Destroy the color list. ListDestroy (listBackgroundColors); case RES_DIALOG_LISTBOX: // If the end user double-clicked a color, display it. if (CtrlGetSubCommand (szDialogName) = LISTBOX_ENTER) then CtrlGetCurSel (szDialogName, RES_DIALOG_LISTBOX, svCurSel); SetBackgroundColor (svCurSel); endif; case RES_PBUTTON_DONE: bDone = TRUE; case RES_PBUTTON_SET : // Display the selected color. CtrlGetCurSel (szDialogName, RES_DIALOG_LISTBOX, svCurSel);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 617

Appendix A: Built-In Functions (A-D) CtrlSetList

SetBackgroundColor (svCurSel); endswitch; until bDone; end; /*--------------------------------------------------------------*\ * * Script-defined functions begin here. * \*--------------------------------------------------------------*/ // CreateColorList returns a list of background color constants. function CreateColorList () LIST listBkColors; begin // Create a list to hold the colors constants; listBkColors = ListCreate (STRINGLIST); // Build the list of color constants. if (listBkColors != LIST_NULL) then ListAddString (listBkColors, "BK_BLUE", AFTER); ListAddString (listBkColors, "BK_GREEN", AFTER); ListAddString (listBkColors, "BK_MAGENTA", AFTER); ListAddString (listBkColors, "BK_ORANGE", AFTER); ListAddString (listBkColors, "BK_RED", AFTER); ListAddString (listBkColors, "BK_YELLOW", AFTER); ListAddString (listBkColors, "BK_SOLIDBLACK", AFTER); ListAddString (listBkColors, "BK_SOLIDBLUE", AFTER); ListAddString (listBkColors, "BK_SOLIDGREEN", AFTER); ListAddString (listBkColors, "BK_SOLIDMAGENTA", AFTER); ListAddString (listBkColors, "BK_SOLIDORANGE", AFTER); ListAddString (listBkColors, "BK_SOLIDPINK", AFTER); ListAddString (listBkColors, "BK_SOLIDRED", AFTER); ListAddString (listBkColors, "BK_SOLIDWHITE", AFTER); ListAddString (listBkColors, "BK_SOLIDYELLOW", AFTER); endif; // Return the pointer to the list. return listBkColors; end; // SetBackgroundColor sets the background to the color // specified by szColor. function SetBackgroundColor (szColor) NUMBER nColor; begin // Determine which color the end user selected. if szColor = "BK_BLUE" then nColor = BK_BLUE; elseif szColor = "BK_GREEN" then nColor = BK_GREEN; elseif szColor = "BK_MAGENTA" then nColor = BK_MAGENTA; elseif szColor = "BK_ORANGE" then nColor = BK_ORANGE; elseif szColor = "BK_RED" then nColor = BK_RED; elseif szColor = "BK_YELLOW" then nColor = BK_YELLOW; elseif szColor = "BK_SOLIDBLACK" then
618 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetMLEText

nColor = BK_SOLIDBLACK; elseif szColor = "BK_SOLIDBLUE" then nColor = BK_SOLIDBLUE; elseif szColor = "BK_SOLIDGREEN" then nColor = BK_SOLIDGREEN; elseif szColor = "BK_SOLIDMAGENTA" then nColor = BK_SOLIDMAGENTA; elseif szColor = "BK_SOLIDORANGE" then nColor = BK_SOLIDORANGE; elseif szColor = "BK_SOLIDPINK" then nColor = BK_SOLIDPINK; elseif szColor = "BK_SOLIDRED" then nColor = BK_SOLIDRED; elseif szColor = "BK_SOLIDWHITE" then nColor = BK_SOLIDWHITE; elseif szColor = "BK_SOLIDYELLOW" then nColor = BK_SOLIDYELLOW; endif; // Set the background to the selected color. SetColor (BACKGROUND, nColor); end;

CtrlSetMLEText
The CtrlSetMLEText function sets the text of a multi-line edit box control. InstallShield separately places each string in listID into the multi-line edit box control. This function is for use only with custom dialogs.

Syntax
CtrlSetMLEText ( szDialogName, nControlID, listID );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

619

Appendix A: Built-In Functions (A-D) CtrlSetMLEText

Parameters
Table A-117: CtrlSetMLEText Parameters Parameter szDialogName nControlID Description Specifies the name of a dialog. Specifies the resource ID of the multi-line edit box control in the dialog. Specifies the name of a valid string list that contains the elements to be copied into the multi-line edit control.

listID

Return Values
Table A-118: CtrlSetMLEText Return Values Return Value 0 <0 Description CtrlSetMLEText set the text into the control. CtrlSetMLEText was unable to set the text in the control.

CtrlSetMLEText Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlSetMLEText and CtrlGetMLEText functions. * * This example script displays a custom dialog that contains * a multi-line edit box. The script creates a list of all * program folders on the target system and then calls * CtrlSetMLEText to place that list into the dialog's multi* line edit box. The dialog also has a Save button that * enables the end user to save the folder names to a text file. * When that option is selected, the script calls CtrlGetMLEText * to get the folder names from the multi-line edit box. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdShowInfoList. Because this dialog is stored * in the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. *
620 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetMLEText

* Notes: The multi-line edit box is defined as read-only * in the resource; its contents cannot be edited. * * The script changes the static text of the dialog * box's Next button and disables the Back button to * make the dialog fit the needs of the example. * * The function GetGroupNameList may return an error * if the target system is running under a shell other * than the Explorer shell. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID #define RES_PBUT_BACK #define RES_PBUT_DONE #define RES_PBUT_SAVE #define RES_DIALOG_EDITBOX #define RES_TEXT

12007 12 9 1 301 711

// // // // // //

ID ID ID ID ID ID

of of of of of of

the custom dialog Next button Cancel button Back button edit box text above edit box

// Description to display above the multi-line edit box. #define DESC_TEXT "Click Save to store the list of program folder names in a disk file." // The program names will be saved in the root of the current // drive if the end user clicks the Save button. #define FOLDER_LIST_FILE "\\ISExampl.txt" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlSetMLEText(HWND); function ExFn_CtrlSetMLEText(hMSI) STRING szDialogName; NUMBER nCmdValue, nResult; BOOL bSave, bDone; LIST listFolders; HWND hwndDlg; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

621

Appendix A: Built-In Functions (A-D) CtrlSetMLEText

// Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. bDone = TRUE; case DLG_ERR: MessageBox ("Dialog failed", SEVERE); bDone = TRUE; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the window title. SetWindowText (hwndDlg, "View Program Folders"); // Disable the Back button using a call from Winsub. _WinSubEnableControl (hwndDlg, RES_PBUT_BACK, 0); //Set the dialog's static text. CtrlSetText (szDialogName, RES_TEXT, DESC_TEXT); CtrlSetText (szDialogName, RES_PBUT_SAVE, "&Save"); CtrlSetText (szDialogName, RES_PBUT_DONE, "&Done"); // Create a string list to store the program folder names. listFolders = ListCreate (STRINGLIST); if (listFolders = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); bDone = TRUE; else // Get the folder names into a list. nResult = GetGroupNameList (listFolders); if (nResult = 0) then // Put the folder names into the // dialog's multi-line edit box. nResult = CtrlSetMLEText (szDialogName, RES_DIALOG_EDITBOX, listFolders); elseif (nResult != 0) then // Handle error from GetGroupNameList or CtrlSetMLEText. MessageBox ("Unable to create folder name list.", SEVERE); bDone = TRUE; endif; // Destroy the listID string list. ListDestroy (listFolders); endif; case RES_PBUT_SAVE : // Initialize indicator to save program file names. bSave = FALSE; if (AskYesNo("Save list as " + FOLDER_LIST_FILE + "?", YES)) then // Check for existing file. if (Is (FILE_EXISTS, FOLDER_LIST_FILE) = 1) then // Query end user to overwrite existing file.
622 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetMultCurSel

if (AskYesNo ("Overwrite existing " + FOLDER_LIST_FILE + "?", YES)) then bSave = TRUE; endif; else bSave = TRUE; endif; endif; if bSave = TRUE then // Create a string list to store list from dialog. listFolders = ListCreate (STRINGLIST); if (listFolders = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); else // Get the folder names from the // dialog's multi-line edit box. nResult = CtrlGetMLEText (szDialogName, RES_DIALOG_EDITBOX, listFolders); // Save the list to a text file. ListWriteToFile (listFolders, FOLDER_LIST_FILE); // Destroy the listID string list. ListDestroy (listFolders); endif; endif; case RES_PBUT_DONE: bDone = TRUE; endswitch; until bDone; // Close the custom dialog. EndDialog (szDialogName); // Remove the custom dialog from memory. ReleaseDialog (szDialogName); end;

CtrlSetMultCurSel
The CtrlSetMultCurSel function searches the specified multi-selection list or combo box control. If nSelectFlag is set to TRUE, CtrlSetMultCurSel selects (highlights) the item when it is found. This function is for use only with custom dialogs.

Syntax
CtrlSetMultCurSel (szDialogName, nControlID, szText, nSelectFlag);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

623

Appendix A: Built-In Functions (A-D) CtrlSetMultCurSel

Parameters
Table A-119: CtrlSetMultCurSel Parameters Parameter szDialogName nControlID Description Specifies the name of a custom dialog. Specifies the resource ID of the multi-selection list box control in the dialog. Specifies the search string. Indicates whether or not to select an item when CtrlSetMultCurSel finds it. Pass one of the following predefined constants in this parameter:

szText nSelectFlag

TRUEIndicates that the item is to be selected. FALSEIndicates that the item is not to be selected.

Return Values
Table A-120: CtrlSetMultCurSel Return Values Return Value 0 Description CtrlSetMultCurSel successfully found the text in the control and either selected it or did not select it, as indicated in nSelectFlag. CtrlSetMultCurSel was unable to find the text in the control.

<0

CtrlSetMultCurSel Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlSetMultCurSel and CtrlGetMultCurSel * functions. * * This script retrieves the names of all program folders * on the target system and places them in a list. When the * dialog is initialized, the CtrlSetList function sets this * list to be displayed in the list box. The CtrlSetMultCurSel * function is then called to select the user-selected
624 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetMultCurSel

* folder. * * This list is then destroyed. A new list is created when the * Next button is clicked. CtrlGetMultCurSel then retrieves the * elements in the list box and assigns them to this new string * list. This list is then displayed in an Sd dialog. * * Note: In order for this script to run properly, you must set * the RES_DIALOG_ID and RES_DIALOG_LISTBOX constants to a * dialog and list box created in _isuser.dll. * * The GetGroupNameList function used in this example may * return an error if the target system is running under a * shell other than the Explorer shell. * \*--------------------------------------------------------------*/ // Dialog controls. #define RES_DIALOG_ID #define RES_PBUT_NEXT #define RES_PBUT_CANCEL #define RES_PBUT_BACK #define RES_DIALOG_LISTBOX

1 9 12

// // // // //

ID ID ID ID ID

of of of of of

dialog Next button Cancel button Back button list box

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlSetMultCurSel(HWND); function ExFn_CtrlSetMultCurSel(hMSI) STRING szDialogName, szDLL, szTitle, szMsg; STRING szText, szDefFolder, svResultFolder; NUMBER nCmdValue, nResult, nControlID, nSelectFlag; BOOL bDone; LIST listID, listFolders; begin Disable(BACKBUTTON); szDialogName = "CtrlSetMultCurSel"; szDLL = ""; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, szDLL, "", RES_DIALOG_ID);

if (nResult < 0) then MessageBox ("Error in defining dialog", SEVERE); bDone = TRUE; else bDone = FALSE; endif; // Create the listID string list. listID = ListCreate (STRINGLIST); if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); else MessageBox ("listID created.", INFORMATION);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 625

Appendix A: Built-In Functions (A-D) CtrlSetMultCurSel

endif; // Retrieve the program folder names into a list. GetGroupNameList (listID); // Retrieve a folder name from the user. szTitle = "CtrlGetMultCurSel & CtrlSetMultCurSel"; SelectFolder (szTitle, szDefFolder, svResultFolder); // Loop until done. while (bDone = FALSE) // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.",SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // The following sets the list box to the list of program folders. nControlID = RES_DIALOG_LISTBOX; CtrlSetList (szDialogName, nControlID, listID); szText = svResultFolder; nSelectFlag = TRUE; //Set the user-selected folder to be highlighted. if (CtrlSetMultCurSel (szDialogName, nControlID, szText, nSelectFlag) < 0) then MessageBox ("CtrlSetMultCurSel failed.", SEVERE); endif; // Destroy the listID string list. ListDestroy (listID); MessageBox ("listID destroyed.", INFORMATION); case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case RES_PBUT_NEXT: // Create the listFolders string list. listFolders = ListCreate (STRINGLIST); if (listFolders = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); else MessageBox ("listFolders created.", INFORMATION); endif; // Retrieve the highlighted elements in the list box and // put them into the listFolders string list. if (CtrlGetMultCurSel (szDialogName, nControlID, listFolders) < 0) then MessageBox ("CtrlGetMultCurSel failed.", SEVERE);
626 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetState

else MessageBox ("CtrlGetMultCurSel successful.", INFORMATION); endif; bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; case RES_PBUT_CANCEL: // The user clicked the window's Cancel button. Do (EXIT); endswitch; endwhile; szMsg = "The following are the elements highlighted in the list box:";

// Display the list of elements highlighted. SdShowInfoList (szTitle, szMsg, listFolders); // Remove listFolders string list from memory. ListDestroy (listFolders); MessageBox ("listFolders destroyed.", INFORMATION); // Close the dialog. EndDialog (szDialogName); // Remove dialog from memory. ReleaseDialog (szDialogName); end;

CtrlSetState
The CtrlSetState function sets the current state of a check box or option button control in a custom dialog. You can set certain characteristics of option buttons and check boxes when you create them using a resource or dialog editor. If you experience difficulties with the behavior of a button control, check the characteristics of the control in the editor.

Syntax
CtrlSetState ( szDialogName, nControlID, nState );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

627

Appendix A: Built-In Functions (A-D) CtrlSetState

Parameters
Table A-121: CtrlSetState Parameters Parameter szDialogName Description Specifies the name of a dialog that contains the check box or option button control. Specifies the resource ID of the check box or option button control. Specifies the new state of the button control. Pass one of the following predefined constants in this parameter:

nControlID

nState

BUTTON_CHECKEDSets the button's state to CHECKED. BUTTON_UNCHECKEDSets the button's state to UNCHECKED.

Return Values
Table A-122: CtrlSetState Return Values Return Value 0 Description CtrlSetState successfully set the state of the check box or option button control. CtrlSetState was unable to set the state of the control.

<0

CtrlSetState Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlGetState and CtrlSetState functions. * * This example script displays a custom dialog that contains * four check boxes. The script calls CtrlSetState to set the * first two check boxes to checked. The last two are unchecked * by default. When the end user clicks the Next button, the * script calls CtrlGetState to retrieve the state of each * each check box. The script then displays a message box that * reports which check boxes were selected. *

628

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetState

* The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdAskOptions. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12020 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12 #define ID_OP1_CHECK 501 #define ID_OP2_CHECK 502 #define ID_OP3_CHECK 503 #define ID_OP4_CHECK 504 #define ID_STA_DESC 711

// // // // // // // // //

ID ID ID ID ID ID ID ID ID

of of of of of of of of of

the custom dialog Next button Cancel button Back button Option 1 check box Option 2 check box Option 3 check box Option 4 check box static text description

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlSetState(HWND); function ExFn_CtrlSetState(hMSI) STRING szDialogName, szMsg; NUMBER nResult, nCmdValue, hwndDlg; BOOL bDone; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "ExDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize the indicator used to control the loop. bDone = FALSE; repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 629

Appendix A: Built-In Functions (A-D) CtrlSetState

abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the window title. SetWindowText (hwndDlg, "Select Options"); // Set static text description displayed above check boxes. CtrlSetText (szDialogName, ID_STA_DESC, "Select and/or clear options. Then click Next."); // Options are cleared by default, so select Options 1 and 2. if (CtrlSetState (szDialogName, ID_OP1_CHECK, BUTTON_CHECKED) < 0) then MessageBox ("First call to CtrlSetState failed.", SEVERE); bDone = TRUE; elseif (CtrlSetState(szDialogName, ID_OP2_CHECK, BUTTON_CHECKED) < 0) then MessageBox ("Second call to CtrlSetState failed.", SEVERE); bDone = TRUE; endif; case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Build message if end user clicked Next button. if (nCmdValue = RES_PBUT_NEXT) then // Start building the message to display to the end user. szMsg = "You selected the following items:\n\n"; // If first option is selected, add line to message. if (CtrlGetState (szDialogName, ID_OP1_CHECK) = BUTTON_CHECKED) then szMsg = szMsg + "Option 1\n"; endif; // If second option is selected, add line to message. if (CtrlGetState (szDialogName, ID_OP2_CHECK) = BUTTON_CHECKED) then szMsg = szMsg + "Option 2\n"; endif; // If third option is selected, add line to message. if (CtrlGetState (szDialogName, ID_OP3_CHECK) = BUTTON_CHECKED) then szMsg = szMsg + "Option 3\n"; endif; // If fourth option is selected, add line to message. if (CtrlGetState (szDialogName, ID_OP4_CHECK) = BUTTON_CHECKED) then szMsg = szMsg + "Option 4\n"; endif; endif;

630

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetText

// Close the custom dialog. EndDialog (szDialogName); // Remove the custom dialog from memory. ReleaseDialog (szDialogName); // Display message if dialog was closed with Next button. if (nCmdValue = RES_PBUT_NEXT) then MessageBox (szMsg, INFORMATION); endif; end;

CtrlSetText
The CtrlSetText function sets the text of a single-line edit field, static text field, or button control in a custom dialog. To set the text in multi-line edit fields, call CtrlSetMLEText.

Syntax
CtrlSetText ( szDialogName, nControlID, szText );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

631

Appendix A: Built-In Functions (A-D) CtrlSetText

Parameters
Table A-123: CtrlSetText Parameters Parameter szDialogName nControlID Description Specify the name of the dialog that you want to modify. Specify the resource ID of the single-line edit field, static text field, or button control in which text is to be set. Specify the text to place in the control.

szText

Tip: If you want the control to be an HTML control, you can specify [html] at the beginning of the szText value. To learn more, see Using an HTML Control on a Dialog.

Return Values
Table A-124: CtrlSetText Return Values Return Value 0 ISERR_GEN_FAILURE Description CtrlSetText successfully set the text in the control. CtrlSetText was unable to set the text in the control.

CtrlSetText Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CtrlSetText, CtrlGetText, and CtrlSelectText * functions. * * This example script displays a custom dialog with two * edit boxes to obtain a user name and company name. The * script calls CtrlSetText to place initial values into the * edit boxes and CtrlSelectText to select the contents of the * first edit box. When the user clicks the Next button, the * script calls CtrlGetText to retrieve the contents of the edit * boxes so that they can be displayed in a message box after * the custom dialog is closed. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdRegisterUser. Because this dialog is stored in * the file _isres.dll, which is already compressed in
632 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) CtrlSetText

* the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12001 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12 #define RES_EDITNAME 301 #define RES_EDITCOMPANY 302

// // // // // //

ID ID ID ID ID ID

of of of of of of

custom dialog Next button Cancel button Back button edit box edit box

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_CtrlSetText(HWND); function ExFn_CtrlSetText(hMSI) STRING szDialogName, svName, svCompany; NUMBER nResult, nCmdValue; BOOL bDone; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize indicator used to control the loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName");
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 633

Appendix A: Built-In Functions (A-D) DefineDialog

SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Put initial values into the edit boxes. CtrlSetText (szDialogName, RES_EDITNAME, "Your name"); CtrlSetText (szDialogName, RES_EDITCOMPANY, "Your company"); // Select the Name edit box. CtrlSelectText (szDialogName, RES_EDITNAME); case RES_PBUT_NEXT: // Get the contents of the edit boxes. CtrlGetText (szDialogName, RES_EDITNAME, svName); CtrlGetText (szDialogName, RES_EDITCOMPANY, svCompany); // Verify that both edit boxes have data. if (StrLength(svName) = 0) || (StrLength(svCompany) = 0) then MessageBox ("Both fields must be completed.", INFORMATION); else bDone = TRUE; endif; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Remove the dialog from memory. ReleaseDialog (szDialogName); // If dialog is closed with Next button, display name and company. if nCmdValue = RES_PBUT_NEXT then MessageBox (svName + "\n" + svCompany, INFORMATION); endif; end;

DefineDialog
The DefineDialog function defines a custom dialog. Call this function instead of EzDefineDialog when you need to specify a dialog attribute that cannot be specified with EzDefineDialog.

Note: DefineDialog does not display the custom dialog. To display a custom dialog, you must call WaitOnDialog.

Syntax
DefineDialog ( szDialogName, hInstance, szDLLName, nDialogID, szDialogID, nReserved, hwndOwner, lMsgLevel );

634

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DefineDialog

Parameters
Table A-125: DefineDialog Parameters Parameter szDialogName Description Specifies the name of the custom dialog that you want to define. This name identifies that dialog and is used in all subsequent calls to custom dialog functions. The dialogs name is case-sensitiveyou must use it exactly as you specify in this parameter. Specifies the instance handle of the .dll file in which the dialog resides. If you specify the fully qualified name of the .dll file in szDLLName, you can specify 0 in this parameter. To obtain the instance handle of a .dll file, call the Microsoft Windows API LoadLibrary. Specifies the name of the .dll file that contains the dialog resource. If this name is not qualified, that is, if you do not specify the drive and path with the file name, the InstallScript engine searches for the .dll file in the Windows folder. If it is not found there, the InstallScript engine searches the folders specified in the search path. When the dialog is located in _isuser.dll, you can specify a null string ("") in this parameter; the InstallScript engine automatically checks _isuser.dll if this parameter is specified as a null string ("").

hInstance

szDLLName

Note: When you use a .dll file other than _isres.dll or _isuser.dll, you must call UseDLL to load the .dll file before calling DefineDialog. To unload the .dll file from memory, call UnUseDLL after calling ReleaseDialog. nDialogID Specifies the dialogs resource ID if you use a number rather than a string to identify the resource. This parameter is used only when szDialogID is a null string (""). It is recommended that you use nDialogID rather than szDialogID to identify the dialog resource.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

635

Appendix A: Built-In Functions (A-D) DefineDialog

Table A-125: DefineDialog Parameters (cont.) Parameter szDialogID Description Specifies the dialogs resource ID if you use a string rather than a number to identify the resource. If this parameter is a null string (""), nDialogID is used to identify the dialog resources. It is recommended that you use nDialogID rather than szDialogID to identify the dialog resource.

Note: If you created the dialog in the Dialogs view, the dialog is created with a string ID; therefore, you must specify this name as the szDialogID parameter to define the dialog. If you override an existing dialog in the Dialogs view, the dialog has a numeric ID, and you must specify the ID in the nDialogID parameter. If you want to use numeric IDs in all caseswhich is what is recommendedyou must edit the dialog in the Dialogs view to change the ISResourceID property of the created dialog to the desired Dialog ID instead of 0. Note that if you do this, the dialog name is no longer used when the dialog is created; it is used only in the Dialogs view in InstallShield to identify the dialog. The dialog is built with the correct numeric ID. nReserved hwndOwner Pass zero in this parameter. No other value is allowed. Specifies the window handle of the owner window. Specify HWND_INSTALL in this parameter to make the InstallShield main installation window the owner of the dialog. This parameter specifies which windows messages will be send to the dialog. You must use the OR operator (|) to combine one of the following constants with the constant DLG_CENTERED.

lMsgLevel

DLG_MSG_STANDARDFilters out most Windows messages; only those directly related to the dialog's controls are passed to the dialog. DLG_MSG_ALLPasses most Windows messages.

636

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DefineDialog

Return Values
Table A-126: DefineDialog Return Values Return Value 0 DLG_ERR_ALREADY_EXISTS (-3) Description DefineDialog successfully defined the dialog. You are trying to define a dialog already defined by DefineDialog. You cannot define two dialogs with the same name. Indicates an unspecified error condition.

DLG_ERR (-1)

DefineDialog Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DefineDialog, EndDialog, and ReleaseDialog * functions. * * This script opens a simple custom dialog that displays * a bitmap. The dialog can be closed with any of three * buttons: Back, Next, or Cancel. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdBitmap. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * * In order to use this dialog as a custom dialog, the * script first defines it by calling DefineDialog. It then * displays the dialog by calling WaitOnDialog. When an event * ends dialog processing, EndDialog is called to close the * dialog. Then the dialog is released from memory by * a call to ReleaseDialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12027 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12

// // // //

ID ID ID ID

of of of of

dialog itself Next button Cancel button Back button

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_DefineDialog(HWND);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

637

Appendix A: Built-In Functions (A-D) DefineDialog

function ExFn_DefineDialog(hMSI) STRING szDialogName, szDLLName, szDialog; NUMBER nDialog, nResult, nCmdValue; BOOL bDone; HWND hInstance, hwndParent; begin // Define the name of a dialog to pass as first // parameter to DefineDialog. szDialogName = "ExampleDialog"; // DefineDialog's second parameter will be 0 because the // .dll file is in _isres.dll. hInstance = 0; // DefineDialog's third parameter will be null; installation will // search for the dialog in _isuser.dll and _isres.dll. szDLLName = ""; // DefineDialog's fifth parameter will be null because the // dialog is identified by its ID in the fourth parameter. szDialog = ""; // This value is reserved and must be 0. hwndParent = 0; // Define the dialog. The installation's main window will own the // dialog (indicated by HWND_INSTALL in parameter 7). nResult = DefineDialog (szDialogName, hInstance, szDLLName, RES_DIALOG_ID, szDialog, hwndParent, HWND_INSTALL, DLG_MSG_STANDARD|DLG_CENTERED); // Check for an error. if (nResult < 0) then MessageBox ("An error occurred while defining the dialog.", SEVERE); bDone = TRUE; abort; endif; // Initialize the indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog(szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202.
638 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DeinstallSetReference

hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; // check standard handling if (SdIsStdButton( nCmdValue ) && SdDoStdButton( nCmdValue )) then bDone = TRUE; endif; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory. ReleaseDialog (szDialogName); end;

DeinstallSetReference
The DeinstallSetReference function is obsolete. If you want to check whether a file is locked during uninstallation, write script code that calls the Is function with the FILE_LOCKED constant for the nIsFlag parameter and that responds as needed.

Syntax
DeinstallSetReference (szReferenceFile);

DeinstallStart
The DeinstallStart function is obsolete. Installations create the required registry keys to enable uninstallation.

Syntax
DeinstallStart (szObsolete, svObsolete, szObsolete, lReserved);

Delay
The Delay function delays the execution of a script by a specified number of seconds. Other tasks running simultaneously with InstallShield proceed normally while InstallShield is delayed.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

639

Appendix A: Built-In Functions (A-D) DeleteCHARArray

Syntax
Delay ( nSeconds );

Delay Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the Delay function. * * First, SdShowMsg is called to display a message box and Delay * is called to pause the script for three seconds. Then the * message box is removed and Delay is called again to pause for * two seconds. Finally, another message is displayed for three * seconds. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_Delay(HWND); function ExFn_Delay(hMSI) begin SdShowMsg ("This message will be displayed for three seconds.", TRUE); Delay (3); SdShowMsg ("", FALSE); Delay (2); SdShowMsg ("This is another message that will be displayed for a mere " + "three seconds.", TRUE); Delay (3); end;

DeleteCHARArray
Description
The DeleteCHARArray function deletes the array of pointers to which pCHARArray points.

640

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DeleteDir

Syntax
DeleteCHARArray ( pCHARArray );

Parameters
Table A-127: DeleteCHARArray Parameters Parameter pCHARArray Description Specifies a pointer to an array of pointers to ANSI character strings. Typically, this pointer is returned by a previous call to GetCHARArrayFromISStringArray.

Return Values
Table A-128: DeleteCHARArray Return Values Return Value ISERR_SUCCESS Description This function always returns ISERR_SUCCESS.

DeleteDir
The DeleteDir function deletes a subdirectory. Depending on the value you use in the parameter nFlag, you can delete a subdirectory only if it is empty, delete a subdirectory even if it contains files, or delete an entire root directory. Set nFlag with extreme caution.

Note: Note the following restrictions:

You cannot use DeleteDir to delete the current directory. You cannot delete files on a network system where you lack the appropriate rights. DeleteDir cannot delete read-only, hidden, or system files. If DeleteDir encounters a read-only file, the function can fail after having deleted only some of the files in the subdirectory.

Syntax
DeleteDir( szDir, nFlag );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

641

Appendix A: Built-In Functions (A-D) DeleteDir

Parameters
Table A-129: DeleteDir Parameters Parameter szDir Description Specifies the fully qualified name of the directory to delete. Specifies deletion options. Pass one of the following predefined constants in this parameter:

nFlag

ALLCONTENTSDeletes the directory in szDir, including all subdirectories and files beneath it. The directory you are deleting must be a subdirectory and cannot be a root directory of the drive. ONLYDIRDeletes the directory in szDir only if it is empty. Otherwise, the function fails. ROOTDeletes the directory in szDir even if it is the root directory. If szDir is a root directory, DeleteDir will delete everything on the disk.

Return Values
Table A-130: DeleteDir Return Values Return Value 0 Description Indicates that the function successfully deleted the subdirectory. Indicates that the function was unable to delete the subdirectory.

<0

DeleteDir Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DeleteDir function. * * First, CreateDir is called to create a directory. Then, * DeleteDir is called to delete it.

642

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DeleteFile

* \*--------------------------------------------------------------*/ #define EXAMPLE_DIR "C:\\Newdir" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_DeleteDir(HWND); function ExFn_DeleteDir(hMSI) begin // Create a directory. if (CreateDir (EXAMPLE_DIR) != 0) then // Report the error; then terminate. MessageBox ("Unable to create directory.", SEVERE); else // Report success. MessageBox (EXAMPLE_DIR + " was created.", INFORMATION); // Delete the directory. If the directory is not // empty, it is not deleted. if (DeleteDir (EXAMPLE_DIR, ONLYDIR) = 0) then // Report success. MessageBox (EXAMPLE_DIR + " was deleted.", INFORMATION); else MessageBox ("Unable to delete directory.", SEVERE); endif; endif; end;

DeleteFile
The DeleteFile function deletes one or more files.

Project: In a Basic MSI or InstallScript MSI project, this functionality might be better achieved by using the native Windows Installer RemoveFiles action. For more information, see the Windows Installer Help.

Note: Note the following:

You cannot use DeleteFile to delete files on a network system where you lack the appropriate rights. DeleteFile cannot delete read-only, hidden, or system files. You can use wild-card characters with FindFile to locate files and then delete them with DeleteFile.

Syntax
DeleteFile ( szFile );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

643

Appendix A: Built-In Functions (A-D) DeleteFile

Parameters
Table A-131: DeleteFile Parameters Parameter szFile Description Specifies the names of the files to delete. If szFile specifies a fully qualified file name, that is, if it includes a path, DeleteFile will delete the file from specified directory. If szFile contains an unqualified file name, that is, without path information, DeleteFile deletes the file from the directory that is specified by the system variable TARGETDIR (in InstallScript installations) or INSTALLDIR (in Basic MSI and InstallScript MSI installations). You can include wildcard characters in szFile to delete more than one file.

Return Values
Table A-132: DeleteFile Return Values Return Value 0 Description Indicates that the function successfully deleted the specified file or files. The specified path was not found. The specified file was not found or no files matched the specified wildcard. Indicates that the function was unable to delete one or more of the specified files. In the case of multiple files, only the error for the last file that could not be deleted is returned. The system variable ERRORFILENAME contains a semicolon delimited list of the files that could not be deleted. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005) by calling FormatMessage.

ISERR_PATH_NOT_FOUND (0x80070003) ISERR_FILE_NOT_FOUND (0x80070004)

All other negative values

DeleteFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DeleteFile function. * * First, DeleteFile is called to delete a specified file from a * directory. Then it is called again to delete all files with * the extention "sys" from the same directory.

644

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DeleteFolderIcon

* * Note: Before running this script, create a directory named * ISExampl in the root of drive C. Then create a file * named ISExampl.txt in that directory. Finally, create * two or more files with the extension "sys" in that * directory. These files will be deleted by the script. * \*--------------------------------------------------------------*/ #define #define #define #define DEL_DIR DEL_FILE DEL_SYS_FILES TITLE_TEXT "C:\\ISExampl" "ISExampl.txt" "*.sys" "DeleteFile example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_DeleteFile(HWND); function ExFn_DeleteFile(hMSI) STRING szMsg; begin // Delete the file specified by DEL_FILE from the target directory. if (DeleteFile (DEL_DIR ^ DEL_FILE) < 0) then MessageBox ("First call to DeleteFile failed.", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, "%s was delete from %s.", DEL_FILE, DEL_DIR); endif; // Delete the files specified by DEL_SYS_FILES // from the target directory. if (DeleteFile (DEL_SYS_FILES) < 0) then MessageBox ("Second call to DeleteFile failed.", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, "All files matching %s were delete from %s.", DEL_SYS_FILES, DEL_DIR); endif; end;

DeleteFolderIcon
The DeleteFolderIcon function removes a shortcut from a folder.

Note: DeleteFolderIcon cannot be used for Internet shortcuts.

Syntax
DeleteFolderIcon ( szProgramFolder, szItemName );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

645

Appendix A: Built-In Functions (A-D) DeleteFolderIcon

Parameters
Table A-133: DeleteFolderIcon Parameters Parameter szProgramFolder szItemName Description Specifies the name of the folder that contains the shortcut to remove. Specifies the name of the shortcut to delete.

Return Values
Table A-134: DeleteFolderIcon Parameters Return Value 0 Description Indicates that the function successfully deleted the specified shortcut. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage. <0 Indicates that the function was unable to delete the shortcut.

DeleteFolderIcon Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DeleteFolderIcon and DeleteProgramFolder * functions. * * This script deletes the 'Notepad Example' icon from the * 'Example folder' folder. DeleteProgramFolder is then * called again to delete this folder. * * Note: In order for this script to run properly, you must set * the preprocessor constants to a valid folder and icon * on the target system. To easily create this example * folder and icon, run the AddFolderIcon example #3. * \*--------------------------------------------------------------*/ #define FOLDER "C:\\Windows\\Example folder" #define ICON "Notepad Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_DeleteFolderIcon(HWND);

646

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DeleteProgramFolder

function ExFn_DeleteFolderIcon(hMSI) begin // Display the folder. ShowProgramFolder (FOLDER, SW_SHOW); Delay (3); // Delete the 'Notepad Example' icon. if (DeleteFolderIcon (FOLDER, ICON) < 0) then MessageBox ("DeleteFolderIcon failed.", SEVERE); endif; // Delete the 'Example folder' icon. if (DeleteProgramFolder (FOLDER) < 0) then MessageBox ("DeleteProgramFolder failed.", SEVERE); endif; end;

DeleteProgramFolder
The DeleteProgramFolder function deletes a program folder (that is, a subfolder of the Start menu's Programs folder) and its contents, including all shortcuts and all of the program folder's subfolders and their contents. DeleteProgramFolder cannot delete the Programs folder.

Tip: In a Windows Installer based or InstallScript MSI project, this functionality is possibly better achieved by using the native Windows Installer RemoveFolders action. Or, if you are simply uninstalling, the MSI engine natively handles the removal of all files and folders created during the setup. For more information on the RemoveFolders action, see the Windows Installer Help.

Syntax
DeleteProgramFolder ( szFolderName );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

647

Appendix A: Built-In Functions (A-D) DeleteProgramFolder

Parameters
Table A-135: DeleteProgramFolder Parameters Parameter szFolderName Description Specifies the name of the folder to remove.

Return Values
Table A-136: DeleteProgramFolder Return Values Return Value 0 Description Indicates that the function successfully removed the specified folder. Indicates that the function was unable to remove the folder. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

<0

DeleteProgramFolder Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DeleteFolderIcon and DeleteProgramFolder * functions. * * This script deletes the 'Notepad Example' icon from the * 'Example folder' folder. DeleteProgramFolder is then * called again to delete this folder. * * Note: In order for this script to run properly, you must set * the preprocessor constants to a valid folder and icon * on the target system. To easily create this example * folder and icon, run the AddFolderIcon example #3. * \*--------------------------------------------------------------*/ #define FOLDER "C:\\Windows\\Example folder" #define ICON "Notepad Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h"

648

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DeleteWCHARArray

export prototype ExFn_DeleteProgramFolder(HWND); function ExFn_DeleteProgramFolder(hMSI) begin // Display the folder. ShowProgramFolder (FOLDER, SW_SHOW); Delay (3); // Delete the 'Notepad Example' icon. if (DeleteFolderIcon (FOLDER, ICON) < 0) then MessageBox ("DeleteFolderIcon failed.", SEVERE); endif; // Delete the 'Example folder' icon. if (DeleteProgramFolder (FOLDER) < 0) then MessageBox ("DeleteProgramFolder failed.", SEVERE); endif; end;

DeleteWCHARArray
Description
The DeleteWCHARArray function deletes the array of pointers to which pCHARArray points.

Syntax
DeleteWCHARArray ( pCHARArray );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

649

Appendix A: Built-In Functions (A-D) DialogSetFont

Parameters
Table A-137: DeleteWCHARArray Parameters Parameter pCHARArray Description Specifies a pointer to an array of pointers to Unicode character strings. Typically, this pointer is returned by a previous call to GetWCHARArrayFromISStringArray.

Return Values
Table A-138: DeleteWCHARArray Return Values Return Value ISERR_SUCCESS Description This function always returns ISERR_SUCCESS.

DialogSetFont
The DialogSetFont function sets the font for InstallScript dialogs that are displayed at run time. This function affects built-in InstallScript dialogs and custom InstallScript dialogs (that is, dialogs that are defined through EzDefineDialog or DefineDialog). This function does not affect dialogs that are displayed by calling the Windows API function MessageBox, which are displayed in the font specified by the user for message boxes (specified using the Windows Control panel). This function does not affect the text in the title bar of any dialog; the font of dialog title bars is set by Windows.

Syntax
DialogSetFont (szFontName, nFontSize, nReserved);

Parameters
Table A-139: DialogSetFont Parameters Parameter szFontName Description Specifies the font to be usedfor example, Times New Roman. Specifies the font sizefor example, 10. Pass 0 (zero) in this parameter. No other value is allowed.

nFontSize nReserved

Return Values
DialogSetFont always returns 0 (zero). If the function cannot change the font, dialog text is displayed in the system font.

650

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DialogSetInfo

Additional Information
When changing the font of InstallShield dialogs, use a font that you know is available on any system that the setup is running on. Also, be sure to test the setup on a variety of screen resolutions to ensure that the font works correctly.

DialogSetInfo
Edition: This information applies to the following project types:

InstallScript InstallScript MSI (in event-driven InstallScriptnot in InstallScript custom actions)

The DialogSetInfo function changes the following display elements in run-time dialogs:

The image to be displayed The style of the check boxes used to obtain end-user selections The precision of the values that indicate available hard drive space

You must call DialogSetInfo each time that you want to change a particular aspect of a single dialog. Changes that are made by a call to DialogSetInfo remain in effect for the remainder of the installation or until they are changed again by a subsequent call to DialogSetInfo.

Note: If your script calls DialogSetInfo before calling any of the Sd dialog functions, the call to DialogSetInfo must be preceded by a call to SdInit. If it is not, the call to DialogSetInfo has no effect.

Syntax
DialogSetInfo ( nInfoType, szInfoString, nParameter );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

651

Appendix A: Built-In Functions (A-D) DialogSetInfo

Parameters
Table A-140: DialogSetInfo Parameters Parameter nInfoType Description Specifies the display feature to be modified. Pass one of the following predefined constants in this parameter:

DLG_INFO_USEDECIMALBy default, the values displayed to indicate feature sizes, available disk space, and required disk space are rounded to the nearest kilobyte or megabyte. Pass this constant when you want these values displayed to the nearest tenth of a kilobyte or megabyte. The following dialogs are affected by this parameter: FeatureDialog, SdFeatureDialog, SdFeatureDialog2, SdFeatureDialogAdv, and SdFeatureMult. DLG_INFO_KUNITSBy default, the values displayed to indicate feature sizes, available disk space, and required disk space are displayed as a measurement in megabytes. Pass this constant to display these measurements in kilobytes. The following dialogs are affected by this parameter: FeatureDialog, SdFeatureDialog, SdFeatureDialog2, SdFeatureDialogAdv, and SdFeatureMult. DLG_INFO_ALTIMAGESpecifies an alternate bitmap to be displayed in the dialog. If nParameter is set to DLG_INFO_ALTIMAGE_VERIFY_BMP or TRUE, szInfoString should specify the image to be displayed in the dialog. This parameter applies to all dialogs that display the standard installation image on the left side of the dialog. For more information, see the nParameter description. Display effects that have been set with SetDisplayEffect do not apply to alternate images, which are always displayed without any special effects.

DLG_INFO_CHECKSELECTIONSpecifies that the selection method will be determined by the constant passed to nParameter.

Note: You can use the DLG_INFO_ALTIMAGE parameter to enable a 16-color, 256-color, or true color (24-bit) bitmap. Note that color distortion may occur when a 256-color bitmap is displayed on a 16-color system or when a true color bitmap is displayed on a 256-color system. It is recommended that you specify an alternate image that is compatible with the color mode of the target system.

652

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DialogSetInfo

Table A-140: DialogSetInfo Parameters (cont.) Parameter szInfoString Description When DLG_INFO_ALTIMAGE is passed in nInfoType, this parameter specifies the file name of an alternate bitmap to display and, optionally, a set of bitmap attributes. If bitmap attributes are included, the string passed in this parameter should be formatted as follows:
"bitmap file name;transparent flag;3-D flag;<unused>;background color"

Bitmap file nameSpecifies the name of the bitmap file. If the file name is unqualified (that is, if it does not include a drive designation and path), the installation searches for the bitmap in SUPPORTDIR. Transparent flagIndicates whether to display the bitmap transparently. When this flag is 1 (true), all portions of the bitmap that are magenta (RGB Value: 255,0,255) will be displayed transparently. The default for this parameter is 0 (non-transparent). 3-D flagIndicates whether to add a 3-D border around the edges of the static field that contains the bitmap. The default for this parameter is 0 (no 3D border). <unused>This portion of the formatted string is ignored, but it must be included. That is, the formatted string must contain four semicolons, with two semicolons between the 3-D flag and the background color. Background colorIndicates the color to use for the background of the static text field. Note that this color will be visible only if the bitmap is smaller than the static text field in which it appears or if the transparent flag is set to 1 and the bitmap has transparent areas. The background color must be expressed as an RGB value, that is, as three numeric values separated by commas.

The following example will display the bitmap from the file MyBitmap.bmp, which is located in the SUPPORTDIR folder. The bitmap is placed on a black background and has a three-dimensional border. Any parts of the bitmap that are magenta are displayed in the background color of black.
SUPPORTDIR ^ "MyBitmap.bmp" + ";1;1;;0,0,0"

Note that the standard bitmap measures 57 x 53. An alternate bitmap should be about this size as well. If the bitmap is larger than this size, it will be centered vertically within the title area, and the right side of the bitmap will be aligned with the right side of the dialog. (In the Welcome, SdWelcome, and SdFinish dialogs, the right side of the bitmap will be aligned with the right side of the larger image within which the bitmap appears.) The left side of the bitmap will extend as far to the left of the dialog as necessary. Any part of the bitmap that extends below the title area of the dialog will be clipped. If the bitmap is smaller than 57 x 53 it will be will displayed correctly, but it will not be resized or extended. This parameter is ignored when the default bitmap is being restored or when nInfoType is not DLG_INFO_ALTIMAGE.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

653

Appendix A: Built-In Functions (A-D) DialogSetInfo

Table A-140: DialogSetInfo Parameters (cont.) Parameter nParameter Description Operates in conjunction with nInfoType to specify dialog features. When nInfoType is DLG_INFO_CHECKSELECTION, pass one of the following predefined constants to specify check box style:

CHECKBOXSpecifies Windows 3.1-style check boxes. CHECKBOX95Specifies Windows 95-style check boxes. CHECKLINESpecifies checkline-style check boxes. CHECKMARKSpecifies checkmark-style check boxes.

When nInfoType is DLG_INFO_ALTIMAGE, pass one of the following predefined constants to specify which bitmap to display:

DLG_INFO_ALTIMAGE_VERIFY_BMPSpecifies that the bitmap that is indicated by szInfoString should be used in subsequent dialogs. Before this bitmap is used, the installation checks for the existence of the bitmap. DLG_INFO_ALTIMAGE_REVERT_IMAGE (-1)Specifies that subsequent dialogs should display the default bitmap. The installation does not check for the existence of a bitmap. TRUESpecifies that the bitmap that is indicated by szInfoString should be used in subsequent dialogs. The installation does not check for the existence of the bitmap.

When nInfoType is either DLG_INFO_KUNITS or DLG_INFO_USEDECIMAL, pass one of the following predefined constants to specify how sizes should be displayed:

TRUESpecifies that sizes should be displayed as indicated by nInfoType. FALSESpecifies that sizes should be displayed in the default style.

Return Values
Table A-141: DialogSetInfo Return Values Return Value ISERR_SUCCESS (0) Description The function successfully set the specified style. If DLG_INFO_ALTIMAGE_VERIFY_BMP was passed in nParameter, this return value also indicates that the bitmap was found. An unspecified error occurred when the function attempted to set the dialog information. The bitmap that was indicated by szInfoString was not found.

< ISERR_SUCCESS (< 0) ISERR_FILE_NOT_FOUND (0x80070004)

Additional Information
To preview the effects of a call to DialogSetInfo in an InstallScript installation, run the Dialog Sampler (which is available from the Tools menus InstallScript submenu), change the attributes of the dialogs (by clicking the Attributes button), then examine the changes in dialogs such as SdFeatureMult.

654

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DialogSetInfo

DialogSetInfo Example
Edition: This information applies to the following project types:

InstallScript InstallScript MSI (in event-driven InstallScriptnot in InstallScript custom actions)

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DialogSetInfo function. * * This script calls AskText twice. On the first call the * AskText dialog displays the default bitmap. Then * DialogSetInfo is called to specify an alternate bitmap; * that bitmap is then displayed on the second call to AskText. * * Note: Before running this script, set the defined constant * FULL_BMP_PATH so that it references a bitmap file * included in the Support Files/Billboards view. * \*--------------------------------------------------------------*/ #define FULL_BMP_PATH SUPPORTDIR ^ "MyBitmap.bmp" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" function OnBegin() STRING szText, szMsg, szBmpPath; STRING svReturnText; NUMBER nReturn; begin start: // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Display the AskText dialog with its default bitmap. szText = "Default Bitmap."; szMsg = "The bitmap on the left is the default."; nReturn = AskText (szMsg, szText, svReturnText); // Enable the Back button. Enable (BACKBUTTON); szBmpPath = FULL_BMP_PATH; // Set the alternate bitmap for the AskText dialog. DialogSetInfo (DLG_INFO_ALTIMAGE, szBmpPath, TRUE); // Set the text for display in the AskText dialog. szText = "Alternate Bitmap."; szMsg = "The bitmap on the left is a custom bitmap. This alternate " + "bitmap was displayed using the DLG_INFO_ALTBITMAP option in " + "DialogSetInfo.";
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 655

Appendix A: Built-In Functions (A-D) DialogSetInfo

// Display the AskText dialog with the alternate // bitmap. nReturn = AskText (szMsg, szText, svReturnText); // Handle Back button. if (nReturn = BACK) then // Restore the default bitmap setting. DialogSetInfo (DLG_INFO_ALTIMAGE, "", DLG_INFO_ALTIMAGE_REVERT_IMAGE); goto start; endif; end;

Dialog Styles
Four different dialog styles are available:

CHECKBOX Dialog Style CHECKBOX95 Dialog Style CHECKMARK Dialog Style CHECKLINE Dialog Style

CHECKBOX Dialog Style

Figure A-1: CHECKBOX Dialog Style

656

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DialogSetInfo

CHECKBOX95 Dialog Style

Figure A-2: CHECKBOX95 Dialog Style

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

657

Appendix A: Built-In Functions (A-D) DialogSetInfo

CHECKMARK Dialog Style

Figure A-3: CHECKMARK Dialog Style

658

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DIFxDriverPackageGetPath

CHECKLINE Dialog Style

Figure A-4: CHECKLINE Dialog Style

DIFxDriverPackageGetPath
Project: This function applies to InstallScript projects only. This function is not required in InstallScript MSI projects since DIFx can be called by the Windows Installer in those projects.

The DIFxDriverPackageGetPath function retrieves the fully qualified path to a driver store .inf file.

Note: This function calls the DIFxAPI function DriverPackageGetPath. See the DIFxAPI documentation for additional details regarding this function and its parameters and return values.

Syntax
DIFxDriverPackageGetPath( byval string szDriverPackageInfPath, byref string svDestInfPath, byval number nISFlags );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

659

Appendix A: Built-In Functions (A-D) DIFxDriverPackageInstall

Parameters
Table A-142: DIFxDriverPackageGetPath Parameters Parameter szDriverPackageInfPath Description Specifies the fully qualified path to a driver package .inf file for which to retrieve the corresponding driver store .inf file. Specifies the fully qualified path of the driver store .inf file that corresponds to the driver package .inf file supplied by DriverPackageInfPath. Specifies InstallScript-specific flags. The following flags are available:

svDestInfPath

nISFlags

0Default behavior ISDIFX_OPTION_DONT_RESOLVE_TEXTSUBSBy default, the function resolves any text substitutions found in szDriverPackageInfPath. However, if this flag is specified, text substitutions are not resolved.

Return Values
Table A-143: DIFxDriverPackageGetPath Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description The function was successful. The function failed. If the return value from DriverPackageGetPath is a Win32 error (a positive return value), ISERR_WIN_BASE is added to the error to ensure that it is < ISERR_SUCCESS. You can use the following code to get the original Win32 error, if desired:
if( nResult & ISERR_WIN_BASE ) then nResult = nResult - ISERR_WIN_BASE; endif;

For a list of specific errors, see DIFx Errors.

Additional Information
For more information on DIFx and DIFxAPI, see the MSDN Library.

DIFxDriverPackageInstall
Project: This function applies to InstallScript projects only. This function is not required in InstallScript MSI projects since DIFx can be called by the Windows Installer in those projects.

660

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DIFxDriverPackageInstall

The DIFxDriverPackageInstall function installs a driver package in the driver store and then installs the driver in the system. If all of the files associated with the driver are in a single component or you can guarantee that all appropriate driver files will be installed when this components Installed event is called, then the recommended place for calling this function is in the component containing the DIFx driver's Installed event. Otherwise, call this function in the installations OnMoved event. If uninstall logging is enabled when this function is called, the driver installed by this function is logged for uninstallation and is automatically removed by the OnUninstallingDIFxDriverFile event when the application is removed.

Note: This function calls the DIFxAPI function DriverPackageInstall. See the DIFxAPI documentation for additional details regarding this function and its parameters and return values.

Syntax
DIFxDriverPackageInstall( byval string szDriverPackageInfPath, byval number nFlags, byval number nISFlags );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

661

Appendix A: Built-In Functions (A-D) DIFxDriverPackageInstall

Parameters
Table A-144: DIFxDriverPackageInstall Parameters Parameter szDriverPackageInfPath Description String that supplies the fully qualified path to the driver package .inf file of the driver package to install. One or more flags that control the installation operation. In most cases you can specify 0 because the installer will automatically add the appropriate flags. The following additional flags can be specified manually:

nFlags

Note: These flags are defined by and passed directly to the Flags parameter of the DIFxAPI function DriverPackageInstall. See the DIFxAPI documentation for additional information regarding these flags.

DRIVER_PACKAGE_REPAIRRe-installs the specified driver package in the driver store even if the driver package is already installed. This flag is specified automatically in repair mode. DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT(Applies only to PnP function drivers) Preinstalls and installs the driver only if the driver package is a better match to a device in the device tree. DRIVER_PACKAGE_FORCE(Applies only to PnP function drivers) By default, installs a new driver for device only if the new driver is a better match for the device than the driver currently installed for the device. If you specify this flag, the function preinstalls and installs the specified driver package even if the driver package currently installed for a device is a better match for the device than the specified driver package. DRIVER_PACKAGE_SILENTSuppresses the display of user dialogs. If a user interaction is required to continue the installation, for example, in response to a driver signing dialog, the installation operation fails without displaying a user message. The function returns an error code that indicates the cause of the failure. DRIVER_PACKAGE_LEGACY_MODEPreinstalls and installs unsigned driver packages and driver packages that cannot be completely preinstalled because there are files that cannot be found.

662

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DIFxDriverPackageInstall

Table A-144: DIFxDriverPackageInstall Parameters (cont.) Parameter nISFlags Description Specifies InstallScript-specific flags. The following flags are available:

0Default behavior ISDIFX_OPTION_DONT_ASSOCIATEBy default, associates the installed driver with the application being installed. If this flag is specified the driver is not associated with any application. ISDIFX_OPTION_NO_REPAIRBy default, the function automatically adds the DRIVER_PACKAGE_REPAIR flag when calling the DriverPackagePreinstall function if REINSTALLMODE is TRUE. If this flag is specified, DRIVER_PACKAGE_REPAIR is not added automatically. However, it is passed if it is specified in nFlags. ISDIFX_OPTION_LOG_IN_DRIVER_PACKAGE_PATHBy default, the function logs the installed driver for uninstallation in the installed driver cache. If this flag is specified, the driver is logged in the package path instead. ISDIFX_OPTION_DONT_RESOLVE_TEXTSUBSBy default, the function resolves any text substitutions found in szDriverPackageInfPath. However, if this flag is specified, text substitutions are not resolved.

Return Values
Table A-145: DIFxDriverPackageInstall Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description The function was successful. The function failed. If the return value from DriverPackageInstall is a Win32 error (a positive return value), ISERR_WIN_BASE is added to the error to ensure that it is < ISERR_SUCCESS. You can use the following code to get the original Win32 error, if desired:
if( nResult & ISERR_WIN_BASE ) then nResult = nResult - ISERR_WIN_BASE; endif;

For a list of specific errors, see DIFx Errors.

Additional Information
For more information on DIFx and DIFxAPI, see the MSDN Library. When a driver is installed by DIFxDriverPackageInstall or uninstalled by DIFxDriverPackageUninstall, the driver is associated with the application being installed by the installation by default. This association can be disabled by specifying ISDIFX_OPTION_DONT_ASSOCIATE. These functions use the following script variables to determine the application to associate:

ISDIFXAPPID IFX_PRODUCT_DISPLAY_NAME IFX_PRODUCT_NAME

ISP-1800-RG00 663

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DIFxDriverPackagePreinstall

IFX_COMPANY_NAME

DIFxDriverPackagePreinstall
Project: This function applies to InstallScript projects only. This function is not required in InstallScript MSI projects since DIFx can be called by the Windows Installer in those projects.

The DIFxDriverPackagePreinstall function preinstalls a driver package for a Plug and Play (PnP) function driver in the driver store and installs the .inf file for the driver package in the system .inf file directory. If all of the files associated with the driver are in a single component or you can guarantee that all appropriate driver files will be installed when this components Installed event is called, then the recommended place for calling this function is in the component containing the DIFx driver's Installed event. Otherwise, call this function in the installations OnMoved event. If uninstall logging is enabled when this function is called, the driver pre-installed by this function is logged for uninstallation and is automatically removed by the OnUninstallingDIFxDriverFile event when the application is removed.

Note: This function calls the DIFxAPI function DriverPackagePreinstall. See the DIFxAPI documentation for additional details regarding this function and its parameters and return values.

Syntax
DIFxDriverPackagePreinstall( byval string szDriverPackageInfPath, byval number nFlags, byval number nISFlags );

664

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DIFxDriverPackagePreinstall

Parameters
Table A-146: DIFxDriverPackagePreinstall Parameters Parameter szDriverPackageInfPath Description String that supplies the fully qualified path to the driver package .inf file of the driver package to pre-install. One or more flags that control the installation operation. In most cases, specify 0 to have the installer automatically add the appropriate flags. The following additional flags can be specified manually:

nFlags

Note: These flags are defined by and passed directly to the Flags parameter of the DIFxAPI function DriverPackagePreinstall. See the DIFxAPI documentation for additional information regarding these flags.

DRIVER_PACKAGE_REPAIRRe-installs the specified driver package in the driver store even if the driver package is already installed. This flag is specified automatically in repair mode. DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT(Applies only to PnP function drivers) Preinstalls and installs the driver only if the driver package is a better match to a device in the device tree. DRIVER_PACKAGE_FORCE(Applies only to PnP function drivers) By default, installs a new driver for device only if the new driver is a better match for the device than the driver currently installed for the device. If you specify this flag, the function preinstalls and installs the specified driver package even if the driver package currently installed for a device is a better match for the device than the specified driver package. DRIVER_PACKAGE_SILENTSuppresses the display of user dialogs. If a user interaction is required to continue the installation, for example, in response to a driver signing dialog, the installation operation fails without displaying a user message. The function returns an error code that indicates the cause of the failure. DRIVER_PACKAGE_LEGACY_MODEPreinstalls and installs unsigned driver packages and driver packages that cannot be completely preinstalled because there are files that cannot be found.

nISFlags

Specifies InstallScript-specific flags. The following flags are available:

0Default behavior ISDIFX_OPTION_NO_REPAIRBy default, the function automatically adds the DRIVER_PACKAGE_REPAIR flag when calling DriverPackagePreinstall if REINSTALLMODE is TRUE. If this flag is specified, DRIVER_PACKAGE_REPAIR is not added automatically. However, it is passed if it is specified in nFlags. ISDIFX_OPTION_LOG_IN_DRIVER_PACKAGE_PATHBy default, the function logs the installed driver for uninstallation in the installed driver cache. If this flag is specified, the driver is logged in the package page instead. ISDIFX_OPTION_DONT_RESOLVE_TEXTSUBSBy default, the function resolves any text substitutions found in szDriverPackageInfPath. If this flag is specified, text substitutions are not resolved.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

665

Appendix A: Built-In Functions (A-D) DIFxDriverPackageUninstall

Return Values
Table A-147: DIFxDriverPackagePreinstall Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description The function was successful. The function failed. If the return value from DriverPackagePreinstall is a Win32 error (a positive return value), ISERR_WIN_BASE is added to the error to ensure that it is < ISERR_SUCCESS. You can use the following code to get the original Win32 error, if desired:
if( nResult & ISERR_WIN_BASE ) then nResult = nResult - ISERR_WIN_BASE; endif;

For a list of specific errors, see DIFx Errors.

Additional Information
For more information on DIFx and DIFxAPI, see the MSDN Library.

DIFxDriverPackageUninstall
Project: This function applies to InstallScript projects only. This function is not required in InstallScript MSI projects since DIFx can be called by the Windows Installer in those projects.

The DIFxDriverPackageUninstall function uninstalls the specified driver package from the system and removes the driver package from the driver store. It is not necessary to call this function explicitly for drivers installed with DIFxDriverPackageInstall or DIFxDriverPackagePreinstall while uninstall logging is enabled as these drivers are automatically removed by the OnUninstallingDIFxDriverFile event.

Note: This function calls the DIFxAPI function DriverPackageUninstall. See the DIFxAPI documentation for additional details regarding this function and its parameters and return values.

Syntax
DIFxDriverPackageUninstall( byval string szDriverPackageInfPath, byval number nFlags, byval number nISFlags );

666

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DIFxDriverPackageUninstall

Parameters
Table A-148: DIFxDriverPackageUninstall Parameters Parameter szDriverPackageInfPath Description String that supplies the fully qualified path to the driver package .inf file of the driver package to pre-install. One or more flags that control the installation operation. In most cases, specify 0 to have the installer automatically add the appropriate flags. The following additional flags can be specified manually:

nFlags

Note: These flags are defined by and passed directly to the Flags parameter of the DIFxAPI function DriverPackageUninstall. See the DIFxAPI documentation for additional information regarding these flags.

DRIVER_PACKAGE_FORCE(Applies only to PnP function drivers) By default, installs a new driver for device only if the new driver is a better match for the device than the driver currently installed for the device. If you specify this flag, the function preinstalls and installs the specified driver package even if the driver package currently installed for a device is a better match for the device than the specified driver package. DRIVER_PACKAGE_SILENTSuppresses the display of user dialogs. If a user interaction is required to continue the installation, for example, in response to a driver signing dialog, the installation operation fails without displaying a user message. The function returns an error code that indicates the cause of the failure. DRIVER_PACKAGE_DELETE_FILESRemoves the binary files from a system that were copied to the system when the driver package was installed. The function removes a binary file from the system only if the binary file is identical to the corresponding binary file in the driver store.

Caution: Use this flag with caution. Only use this flag if you can verify that a binary file in the system is not required by any other driver package or application. nISFlags Specifies InstallScript-specific flags. The following flags are available:

0Default behavior ISDIFX_OPTION_DONT_ASSOCIATEBy default, the function associates the installed driver with the application being installed. If this flag is specified, the driver is not associated with any application. ISDIFX_OPTION_DONT_RESOLVE_TEXTSUBSBy default, the function resolves any text substitutions found in szDriverPackageInfPath. If this flag is specified, text substitutions are not resolved.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

667

Appendix A: Built-In Functions (A-D) Disable

Return Values
Table A-149: DIFxDriverPackageUninstall Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description The function was successful. The function failed. If the return value from DriverPackageUninstall is a Win32 error (a positive return value), ISERR_WIN_BASE is added to the error to ensure that it is < ISERR_SUCCESS. You can use the following code to get the original Win32 error, if desired:
if( nResult & ISERR_WIN_BASE ) then nResult = nResult - ISERR_WIN_BASE; endif;

For a list of specific errors, see DIFx Errors.

Additional Information
For more information on DIFx and DIFxAPI, see the MSDN Library. When a driver is installed by DIFxDriverPackageInstall or uninstalled by DIFxDriverPackageUninstall, the driver is associated with the application being installed by the installation by default. This association can be disabled by specifying ISDIFX_OPTION_DONT_ASSOCIATE. These functions use the following script variables to determine the application to associate:

ISDIFXAPPID IFX_PRODUCT_DISPLAY_NAME IFX_PRODUCT_NAME IFX_COMPANY_NAME

Disable
The Disable function deactivates the user interface object or setup feature specified by the parameter nConstant. If your script calls the Disable function to disable the Next or Back button, that button is disabled in all dialogs displayed after that function call. To re-enable the Next or Back button, you must call Enable with the corresponding constant.

Syntax
Disable ( nConstant );

668

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) Disable

Parameters
Table A-150: Disable Parameters Parameter nConstant Description Specifies the user interface object or operational feature to disable. Pass one of the following predefined constants in this parameter:

BACKBUTTONDisables (grays out) the Back button that is displayed in some built-in dialogs. The Back button is enabled by default. BACKGROUNDDisables and hides the installations main background window. Note that this parameter has no effect when the installation is in full-screen mode. BILLBOARDSuppresses the display of billboards during an installation. CANCELBUTTONDisables (grays out) the Cancel button that is displayed in some built-in dialogs. DIALOGCACHEDisables the dialog cache mechanism. For more information about dialog caching, see Enable.

Note: DIALOGCACHE has no effect on dialogs that do not have a Next or Back button.

HOURGLASSCauses the mouse cursor to change from the Busy cursor (an hourglass by default), to a normal cursor (a pointer by default).

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

669

Appendix A: Built-In Functions (A-D) Disable

Table A-150: Disable Parameters (cont.) Parameter nConstant (cont.) Description

LOGGINGDisables the logging of uninstallation information so that no information is recorded in the uninstallation log file. Note that logging is enabled automatically by default. If you need to disable logging, it is recommended that you do so by calling Disable with the LOGGING constant immediately before performing operations that should not be logged for uninstallation. Then you can re-enable logging by calling Enable with the LOGGING constant. For more information about logging, see InstallScript Functions that Are Logged for Uninstallation.

Tip: To prevent changes that are made by a component from being undone during uninstallation, select No for the Uninstall setting of a component in an InstallScript project, or select Yes for the Permanent setting of a component in an InstallScript MSI project.

NEXTBUTTONDisables (grays out) the Next button that is displayed in some built-in InstallScript dialogs. On most dialogs, the Next button is enabled by default.

Note: Calling Disable with the NEXTBUTTON constant has no effect on the SdCustomerInformation, SdCustomerInformationEx, SdRegisterUser, or SdRegisterUserEx dialogs since they enable and disable the Next button internally.

PCRESTOREDisables System Restore compatibility, which is enabled by default. REGISTRYFUNCTIONS_USETEXTSUBSDisables text substitutions in strings that are passed to registry functions; this is enabled by default. Use this option when working with registry function strings that contain opening angle brackets (<) and closing angle brackets (>) but that should not be interpreted as text substitutions. SELFREGISTERBATCHDisables the batch method for registering files copied with XCopyFile and the SELFREGISTER constant. The batch method is enabled by default. When the batch method is disabled, files are registered immediately when copied with XCopyFile and the SELFREGISTER constant. If the batch method is enabled, registration is postponed until data transfer takes place.

670

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) Disable

Table A-150: Disable Parameters (cont.) Parameter nConstant (cont.) Description

SERVICE_DIFX_32Disables DIFx support for 32-bit platforms. SERVICE_DIFX_AMD64Disables DIFx support for AMD 64-bit platforms. SERVICE_DIFX_IA64Disables DIFx support for Itanium 64-bit platforms. SERVICE_ISFONTREGDisables global font registration. For details, see

Installing Fonts Through InstallScript and InstallScript Object Projects.

Global font registration is enabled by default; once it is disabled, it cannot be reenabled from the script.

STATUSDisables and hides the progress indicator (status bar). STATUSBBRDDisables and hides the progress dialog that includes a billboard. STATUSDLGDisables and hides the dialog style progress indicator (status bar). STATUSEXDisables the display of the default Setup Status dialog. STATUSOLDDisables and hides the old style progress indicator (status bar). UPDATE_SERVICE_INSTALLThis constant is obsolete. USE_LOADED_SKINIntended for use with custom dialogs that will not work with dialog skins (for example, dialogs that are not the standard size); not recommended for use with built-in dialogs. Disables the use of the skin that you specified in the Specify Skin setting on the Build tab for the release in the Releases view. (If you selected the <Do not use any skin> option in that setting, this constant has no effect.) Disabling of the skin applies only to dialogs that are displayed after you call Disable(USE_LOADED_SKIN); in your InstallScript code. To disable skin use for a custom dialog, you must call Disable(USE_LOADED_SKIN); before calling WaitOnDialog. To re-enable skin use, call Enable(USE_LOADED_SKIN); in your script.

Project: The USE_LOADED_SKIN constant is applicable to InstallScript projects.

WOW64FSREDIRECTIONDisables 64-bit Windows file system redirection. You must do this when installing files to the WINSYSDIR64 destination. If you do not disable file system redirection when installing files to the 64-bit Windows system folder, the files are incorrectly redirected to the 32-bit Windows system folder. Calling this function with this parameter on 32-bit Windows has no effect.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

671

Appendix A: Built-In Functions (A-D) Disable

Return Values
Table A-151: Disable Return Values Return Value 0 Description Indicates that the function successfully disabled the user interface object or setup feature specified by the parameter nConstant. Indicates that the function was unable to disable the user interface object or setup feature specified by the parameter nConstant.

<0

Disable Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the Disable and Enable functions. * * This script displays two dialogs. In the first box, the * Back button is disabled. In the second box, the Next button * is disabled and the Back button enabled. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_Disable(HWND); function ExFn_Disable(hMSI) begin start: // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // The following displays a dialog with the Back button disabled. SetupType ("", "", "", TYPICAL, 0); // Enable the Back button, Enable (BACKBUTTON); // Next button is disabled. Disable (NEXTBUTTON); // The following displays a dialog with only the Back button enabled. if (SetupType ("", "", "", TYPICAL, 0) = BACK) then // If the Back button is pressed, the Next button is enabled. Enable (NEXTBUTTON); goto start; endif; end;

672

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) Do

Do
The Do function executes the currently defined EXIT and HELP handlers, giving you greater control over these handlers, which are normally executed only when the user presses the F1 key (HELP) or the Cancel button (EXIT). Using the Do function, you can execute EXIT or HELP handlers in response to custom dialog events or to any user input from built-in dialogs. You can also use the Do function during script development to test your EXIT and HELP handlers. The Do function can also register queued self-registering files. Files are queued for registration using the batch method for installing self-registering files. When you call Do(SELFREGISTRATIONPROCESS), the installation carries out self-registration of all queued files, even if one of them fails. (Note that when you call FeatureTransferData, Do(SELFREGISTRATIONPROCESS) is called automatically after the files are installed but before the FeatureTransferData call returns. If you use an event-based script, the FeatureTransferData function is called by the default code for the OnMoveData event handler function.)

Syntax
Do (nOperation);

Parameters
Table A-152: Do Parameters Parameter nOperation Description Specifies the type of operation to perform. Pass one of the following predefined constants in this parameter:

EXITInitiates the Exit operation. If no EXIT handler is defined, the default Exit dialog is displayed. HELPInitiates the Help operation. If no HELP handler is defined, the function takes no action. SELFREGISTRATIONPROCESSRegisters all self-registering files that have been queued for registration.

Return Values
Table A-153: Do Return Values Return Value 0 <0 Description The Do function successfully initiated the specified operation. The Do function was unable to initiate the specified operation.

Additional Information
The Do function allows the currently defined HELP and EXIT handlers to execute without the end user pressing F1. The Do function also provides more versatility than the goto statement, which can be used to call HELP and EXIT handler labels. The goto statement cannot be used in all circumstances, but the Do function can be called virtually anytime. For more information on default and custom HELP and EXIT handlers, see HandlerEx.
ISP-1800-RG00 673

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) Do

If Do fails for any reason, it returns -1. The names of the files that failed to self-register are stored in the InstallScript system variable ERRORFILENAME, and each is separated by a semicolon (;).

Do Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the Do function. * * This script calls Do to test the HELP and EXIT handler. * * Note: Before running this script, set the preprocessor * constant so that it references a valid * help file on the target system. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" #define HELPFILE WINDIR^"Help\\Windows.chm" export prototype ExFn_Do(HWND); function ExFn_Do(hMSI) begin // Install the exit handler. HandlerEx (EXIT, Exit_Handler); // Install the help handler. HandlerEx (HELP, Help_Handler); // Execute loop forever -- or until user aborts. while (TRUE) if (AskYesNo ("View the help?", NO) = YES) then // Execute the help handler. Do (HELP); endif; // Execute the exit handler. Do (EXIT); endwhile; // The exit handler. Exit_Handler: // Ask for confirmation to abort. if (AskYesNo ("Do you really want to exit?", NO) = YES) then abort; else // Continue if not sure.
674 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DoInstall

return; endif; // The help handler. Help_Handler: // Display the help. LaunchApplication (HELPFILE, "", "", SW_SHOW, INFINITE, LAAW_OPTION_WAIT); return; end;

DoInstall
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The DoInstall function launches another InstallShield installation that has a valid setup executable file (.exe). The second installation is executed immediately when this function is called. The third parameter, nOptions, specifies various options, including whether the installation should wait until the launched application terminates before continuing.

Note: DoInstall cannot be used directly to launch a .msi file. In addition, because DoInstall adds command-line parameters that are specific to InstallShield installations, DoInstall should not be used to launch a non-InstallShield installation. To launch a non-InstallShield installation, use the LaunchAppllication function.

Syntax
DoInstall ( byval string szSetupExe, byval string szCmdLine, byval number nOptions );

Parameters
Table A-154: DoInstall Parameters Parameter szSetupExe Description Specifies the fully qualified nameincluding a drive designation and complete pathof the setup executable file to be launched. Alternatively, you can specify the compiled script file of the installation to be launched. For InstallScript MSI installations, you can specify the installations .msi package. Note that in order to be able to use DoInstall, your installation must include a valid setup executable file named Setup.exe, or an alternative name, as described in Additional Information.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

675

Appendix A: Built-In Functions (A-D) DoInstall

Table A-154: DoInstall Parameters (cont.) Parameter szCmdLine Description Specifies the command line for the launched installation. You can specify any valid startup InstallShield command line for this parameter. Note that DoInstall automatically adds some command-line switches, depending on the nOptions specified.

Note: Unlike with previous versions of InstallShield, if you are passing command-line parameters to a child InstallScript MSI installation, you must pass these options through the /z parameter (as when launching the installation directly). nOptions Specifies options for launching the installation. You can specify any valid LaunchApplication option, including:

LAAW_OPTION_NOWAIT LAAW_OPTION_WAIT

You can also specify some additional options that apply only to DoInstall: DOINSTALL_OPTION_NOHIDEPROGRESSSpecifies that the entire initialization user interface, including the initial progress dialog and splash screen (if any), should be displayed for the child installation. If this option is not specified, DoInstall automatically hides the initialization user interface of the child installation by using the /hide_progress option.

DOINSTALL_OPTION_NOHIDESPLASHSpecifies that the splash screen (if any) should be displayed for the child installation that is being launched. DOINSTALL_OPTION_NOLANGSWITCHSpecifies that the /l switch will not be specified. By default, DoInstall adds the /l switch to szCmdLine so that the launched installation runs in the same language as the launching installation. Note that if the child installation does not support the language in which the parent installation is running (as determined by calling Is(LANGUAGE_SUPPORTED)), the /l switch is not added.

DOINSTALL_OPTION_NOSETBATCHINSTALLSpecifies that DoInstall should not use the LAAW_OPTION_SET_BATCH_INSTALL option to determine whether the child installation performed actions that require a reboot. Thus, BATCH_INSTALL for the parent installation will not be changed by DoInstall, regardless of the actions of the child installation. By default, DoInstall automatically uses the LAAW_OPTION_SET_BATCH_INSTALL option.

You can combine these constants by using the bitwise OR operator ( | ). Note that combining DOINSTALL_OPTION_NOSETBATCHINSTALL with LAAW_OPTION_SET_BATCH_INSTALL may lead to unexpected results.

676

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DoInstall

Return Values
Table A-155: DoInstall Return Values Return Value 0 Description If DoInstall was called with LAAW_OPTION_WAIT as the third argument, the installation launched by DoInstall terminated successfully. 0 is always returned when DoInstall is called with LAAW_OPTION_NOWAIT as the third argument. Control resumes in the calling installation with the statement that follows the DoInstall function. The InstallScript installation launched by DoInstall with LAAW_OPTION WAIT as the third argument exited with the abort keyword. This usually indicates that the user canceled the installation. The InstallScript MSI installation launched by DoInstall with LAAW_OPTION WAIT as the third argument exited with the abort keyword. This usually indicates that the user canceled the installation. An unspecified error has occurred. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

ISERR_SETUP_CANCELED (0x80042000)

-3

All other negative values

Additional Information
By default, DoInstall automatically attempts to launch the specified setup executable file. If a nonexecutable file name is specified in szSetupExe, the function attempts to launch Setup.exe in the specified folder. If the installations executable file has a name other than Setup, the launched installations Setup.ini file must have the new name of Setup.exe in the [Startup] sections LauncherName key.

Project: If you specify a value for the Setup File Name setting for a release in the Releases view of an InstallScript MSI project and then build the release, InstallShield automatically adds file name value to Setup.ini. If you rename the setup launcher executable file in an InstallScript project, you must add the name to the Setup.ini file manually.

When the installation is run from any removable media, such as a CD or a DVD, the Setup.exe file on Disk1 may not be available during the entire installation. (If Setup.exe becomes unavailable while it is running, the operating system sometimes displays a prompt to request that the end user insert the correct disk, and this may cause the installation to fail.) Therefore, to avoid this problem, the Setup.exe file is copied to a Temp folder, and the installation is relaunched from there. The original Setup.exe then terminates. However, when this happens, DoInstall behaves as if the installation has completed, and it does not wait. To avoid this issue, you may want to use the /clone_wait parameter when you are launching the child installation; when this occurs, the launched installation keeps the original launched process running, and the parent installation then waits. Note, however, that this may cause problems if the original CD containing Setup.exe is not available throughout the entire installation. This includes multiple-CD installations, where the first CD is not available during some parts of the installation. The only other way to avoid this problem is to add code that determines the ID of the child processes of the launched process and wait for the child process to complete.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

677

Appendix A: Built-In Functions (A-D) DoInstall

DoInstall Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DoInstall function. * * This example script runs the MessageBox example script * using the DoInstall function. * * Note: To make this example work correctly you must also do * the following: * * 1. Create a second setup project. This setup will be * launched by the DoInstall function. This project * should include an up-to-date built release. * * 2. Create a new folder named 'Second' in the disk1 * folder of this setup. * * 3. Copy the disk# folder(s) from the second setup * into the newly created 'Second' folder. * * The second setup should then be launched successfully. * \*--------------------------------------------------------------*/ #define SECOND_INSTALL_PATH SRCDIR ^ "Second\\Disk1" #define SECOND_INSTALL_FILENAME "Setup.exe" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_DoInstall(HWND); function ExFn_DoInstall(hMSI) NUMBER nReturn; STRING szTemp; begin MessageBox ("About to launch the second setup.", INFORMATION); // Launch the second setup. nReturn = DoInstall (SECOND_INSTALL_PATH ^ SECOND_INSTALL_FILENAME, "", LAAW_OPTION_WAIT); if ( nReturn = 0) then // Report successful second setup launch. MessageBox("The second setup was launched successfully.", INFORMATION); else // Report failure to launch second setup. SprintfBox(SEVERE, "", "DoInstall failed with a return code of %d.", nReturn); endif;

678

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DotNetCoCreateObject

end;

DotNetCoCreateObject
Project: The following project types support the DotNetCoCreateObject function:

InstallScript InstallScript MSI Basic MSI with InstallScript custom actions

The DotNetCoCreateObject function calls functions in .NET assemblies without the assembly being registered for COM interoperability. This function lets you specify the .NET application domain in which the .NET assemblies should be loaded and run. Each object created with this function is associated with a single class in a single .NET assembly. If you want to access multiple classes in the same assembly, you must create a separate object for each class.

Important: The assembly does not have to be registered as a COM component, but the assembly must be built to be compatible with COM interoperability. Assemblies built with Visual Studio .NET 2003 and earlier are automatically built with this compatibility. However, projects created with Visual Studio 2005 must manually specify [assembly: ComVisible(true)] in the appropriate file.

Syntax
DotNetCoCreateObject ( byval string szAssemblyPathFile, byval string szAssemblyAndClassName, byval string szAppDomain );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

679

Appendix A: Built-In Functions (A-D) DotNetCoCreateObject

Parameters
Table A-156: DotNetCoCreateObject Parameters Parameter szAssemblyPathFile Description Specifies the full path and file name of the .NET assembly that contains the appropriate class. Specifies the assembly and class name.

szAssemblyAndClassName

Note: This value is the same as the szProgId parameter if the assembly is registered for COM interoperability using the CoCreateObject function. szAppDomain Specifies the .NET application domain to load and run the assembly in. If the specified application domain does not exist in the installation process, it is created; otherwise, the existing application domain is used. This is true if you call DotNetCoCreateObject multiple times with the same szAppDomain. If you specify a null string ("") for this parameter or call CoCreateObjectDotNet instead of DotNetCoCreateObject, the assembly is loaded into the default application domain after the installation completes; thus, the .NET assembly file is locked until the installation has finished. For more information on .NET application domains, see the .NET Framework Developers Guide in the MSDN Library.

Return Values
The reference can be assigned to a variable of type OBJECT by using the set keyword.

Additional Information
The DotNetCoCreateObject function is similar to the CoCreateObjectDotNet function. The only difference is that with DotNetCoCreateObject, you can specify the .NET application domain that should be loaded; the assembly is then run in this domain. For CoCreateObjectDotNet, the .NET assembly is loaded into the default application domain after the installation completes; thus, the .NET assembly file is locked until the installation has finished.

Any object variable can be released by setting the object variable to the value of NOTHING or reassigning the object with the CoCreateObject, CoCreateObjectDotNet, CoGetObject, or DotNetCoCreateObject functions. However, this does not automatically unload the library referenced by the object. You must call the Windows API CoFreeLibrary manually to free the library. Otherwise, the library remains loaded until the installation finishes. For more information, see Extending Your Installation with COM Objects.

680

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix A: Built-In Functions (A-D) DotNetUnloadAppDomain

This function throws an exception if the object cannot be created. This can occur if the .NET Framework is not installed on the system, or for other reasons. To handle this exception, surround calls to this function with try...catch blocks. For more information, see Exception Handling.

DotNetUnloadAppDomain
Project: The following project types support the DotNetUnloadAppDomain function:

InstallScript InstallScript MSI Basic MSI with InstallScript custom actions

The DotNetUnloadAppDomain function unloads the specified .NET application domain and releases any assemblies that are currently loaded into the specified application domain.

Note: Once an application domain is unloaded, all .NET objects that were created with DotNetCoCreateObject become invalid. Therefore, you should set these objects to NOTHING using the set command before calling DotNetUnloadAppDomain.

Syntax
DotNetUnloadAppDomain ( byval string szAppDomain );

Parameters
Table A-157: DotNetUnloadAppDomain Parameters Parameter szAppDomain Description Specifies the .NET application domain to be unloaded. For more information on .NET application domains, see the .NET Framework Developers Guide in the MSDN Library.

Return Values
Table A-158: DotNetUnloadAppDomain Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCESS Description The domain was successfully unloaded. The domain was not unloaded.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

681

Appendix A: Built-In Functions (A-D) DotNetUnloadAppDomain

682

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

B
Built-In Functions (E-G)
For a list of functions by category, see Built-In Functions by Category.

Enable
The Enable function activates the user interface object or setup feature specified by the parameter nConstant. By default, an installation runs without a background. To enable window mode, you must call Enable with the BACKGROUND constant, and then again with DEFWINDOWMODE or FULLWINDOWMODE. These constants are not supported for use in Basic MSI installations.

Note: If your script calls the Disable function to disable the Next or Back button, that button is disabled in all dialogs displayed after that function call. To re-enable the Next or Back button, you must call Enable with the corresponding constant.

Syntax
Enable ( nConstant );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

683

Appendix B: Built-In Functions (E-G) Enable

Parameters
Table B-1: Enable Parameters Parameter nConstant Description Specifies the user interface object or operational feature you want to enable. Pass one of the following predefined constants in this parameter:

BACKBUTTONEnables the Back button that is displayed in some built-in dialogs. The Back button is enabled by default, but it can be disabled by calling the Disable function. BACKGROUNDDisplays the installations main background window when the installation is in window mode. When installation is in full-screen mode, which is the default mode, this constant has no effect. To enable window mode, you must call Enable with the constant DEFWINDOWMODE or FULLWINDOWMODE. CANCELBUTTONEnables the Cancel button that is displayed in some built-in dialogs and the status dialog. DEFWINDOWMODEConfigures the main background window to be a normal window with a title bar. If the background window is enabled, its appearance changes immediately. If the background window is not enabled, no change to the screen occurs until Enable is called with the constant BACKGROUND. DIALOGCACHEEnables the dialog cache mechanism, which eliminates the screen flash that appears between the display of dialogs. This screen flash is most noticeable in the title bar of installations running in window mode. Note that the dialog caching mechanism works only for dialogs that have BACK and NEXT buttons. Dialog caching is enabled by default.

Note: DIALOGCACHE has no effect on dialogs that do not have a Next or Back button.

FULLWINDOWMODEConfigures the main background window to be a maximized window with a title bar. If the background window is enabled, its appearance will change immediately. If the background window is not enabled, no change to the screen will occur until Enable is called with the constant BACKGROUND. HOURGLASSCauses the mouse cursor to change to the Busy cursor, an hourglass by default. INDVFILESTATUSEnables the display (on the second line of the progress indicator) of the fully qualified file name of each file as it is transferred when FeatureMoveData, CopyFile, or XCopyFile is called and the progress indicator is enabled.

684

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) Enable

Table B-1: Enable Parameters (cont.) Parameter nConstant (cont.) Description

LOGGINGEnables the logging of uninstallation information. When logging is enabled, results of operations that the InstallScript engine logs for uninstallation are recorded in the uninstallation log file and are reversed during uninstallation. Note that logging is enabled automatically by default. If you need to disable logging, it is recommended that you do so by calling Disable with the LOGGING constant immediately before performing operations that should not be logged for uninstallation. Then you can re-enable logging by calling Enable with the LOGGING constant. For more information about logging, see InstallScript Functions that Are Logged for Uninstallation.

NEXTBUTTONEnables the Next button that is displayed by some built-in dialogs. On most dialogs, the Next button is enabled by default.

Note: Calling Enable with the BACKBUTTON constant has no effect on the SdCustomerInformation, SdCustomerInformationEx, SdRegisterUser, or SdRegisterUserEx dialogs since they enable and disable the Next button internally.

PCRESTOREEnables System Restore compatibility, which is enabled by default. REGISTRYFUNCTIONS_USETEXTSUBSEnables text substitutions in strings that are passed to registry functions; this is enabled by default. SELFREGISTERBATCHSpecifies whether to use the batch method for registering files copied with XCopyFile and the SELFREGISTER constant. The batch method is enabled by default. When the batch method is disabled, files are registered immediately when copied with XCopyFile and the SELFREGISTER constant. If the batch method is enabled, registration is postponed until data transfer takes place.

SERVICE_DIFX_32Enables DIFx support for 32-bit platforms. SERVICE_DIFX_AMD64Enables DIFx support for AMD 64-bit platforms. SERVICE_DIFX_IA64Enables DIFx support for Itanium 64-bit platforms. STATUSEnables the display of the progress indicator (status bar). STATUSBBRDEnables the display of the progress dialog that includes a billboard. STATUSDLGEnables the display of the dialog style progress indicator (status bar). STATUSEXEnables the display of the standard Setup Status dialog. STATUSOLDEnables the display of the old style progress indicator (status bar), which does not have a Cancel button.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

685

Appendix B: Built-In Functions (E-G) Enable

Table B-1: Enable Parameters (cont.) Parameter nConstant (cont.) Description

UPDATE_SERVICE_INSTALLThis constant is obsolete. USE_LOADED_SKINIntended for use with custom dialogs that will not work with dialog skins (for example, dialogs that are not the standard size); not recommended for use with built-in dialogs. Enables the use of the skin that you specified in the Specify Skin setting on the Build tab for the release in the Releases view. (If you selected the <Do not use any skin> option in that setting, this constant has no effect.) If you specify a skin, it is displayed by default; Disable(USE_LOADED_SKIN); and Enable(USE_LOADED_SKIN); are called internally by functions that display dialogs that cannot be displayed with a skin. Enabling of the skin applies only to dialogs that are displayed after you call Enable(USE_LOADED_SKIN); in your script. To enable skin use (after disabling it) for a custom dialog, you must call Enable(USE_LOADED_SKIN); before calling WaitOnDialog.

Project: The USE_LOADED_SKIN constant is applicable to InstallScript projects.

WOW64FSREDIRECTIONEnables 64-bit Windows file system redirection. You must disable file system redirection when installing files to the WINSYSDIR64 destination. If you do not disable file system redirection when installing files to the 64-bit Windows system folder, the files are incorrectly redirected to the 32-bit Windows system folder. Once you have installed the necessary files to the 64-bit system folder, it is recommended that you immediately enable file system redirection. Calling this function with this parameter on 32bit Windows has no effect.

Return Values
Table B-2: Enable Return Values Return Value 0 Description Indicates that the function successfully enabled the user interface object or setup feature specified by the parameter nConstant. Indicates that the function was unable to enable the user interface object or setup feature specified by the parameter nConstant.

<0

Enable Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the Disable and Enable functions. * * This script displays two dialogs. In the first box, the * Back button is disabled. In the second box, the Next button * is disabled and the Back button enabled. * \*--------------------------------------------------------------*/

686

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EndCurrentDialog

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_Enable(HWND); function ExFn_Enable(hMSI) begin start: // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // The following displays a dialog with the Back button disabled. SetupType ("", "", "", TYPICAL, 0); // Enable the Back button, Enable (BACKBUTTON); // Next button is disabled. Disable (NEXTBUTTON); // The following displays a dialog with only the Back button enabled. if (SetupType ("", "", "", TYPICAL, 0) = BACK) then // If the Back button is pressed, the Next button is enabled. Enable (NEXTBUTTON); goto start; endif; end;

EndCurrentDialog
Project: This information applies to InstallScript projects.

The EndCurrentDialog function closes the currently displayed dialog by calling EndDialog. It removes the dialog and initiates the dialog closing process.

Syntax
EndCurrentDialog ( );

Parameters
None

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

687

Appendix B: Built-In Functions (E-G) EndDialog

Return Values
Table B-3: EndCurrentDialog Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description EndCurrentDialog successfully closed the dialog. No dialog is currently displayed.

EndDialog
The EndDialog function closes a custom dialog. It removes the dialog and initiates the dialog closing process. Use EndDialog when any of the following conditions exist:

The Next button or its equivalent has been processed. The Cancel button or its equivalent has been processed. The Close system menu option has been selected. This action sends the DLG_CLOSE message. Any other situation in which the user ends the dialog operation.

After calling EndDialog to end a custom dialog, call the ReleaseDialog function to free the memory associated with the custom dialog.

Note: You can call WaitOnDialog to redisplay a custom dialog that was closed by a call to EndDialog provided that you have not called ReleaseDialog to remove the dialog from memory. If you call WaitOnDialog to open a dialog that has been opened and closed previously in your script, you must call CmdGetHwndDlg again to get the new handle. The old handle is no longer valid.

Syntax
EndDialog ( szDialogName );

688

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EndDialog

Parameters
Table B-4: EndDialog Parameters Parameter szDialogName Description Specifies the name of the dialog to close.

Return Values
Table B-5: EndDialog Return Values Return Value 0 <0 Description EndDialog successfully closed the dialog. EndDialog was unable to close the dialog.

EndDialog Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DefineDialog, EndDialog, and ReleaseDialog * functions. * * This script opens a simple custom dialog that displays * a bitmap. The dialog can be closed with any of three * buttons: Back, Next, or Cancel. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdBitmap. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * * In order to use this dialog as a custom dialog, the * script first defines it by calling DefineDialog. It then * displays the dialog by calling WaitOnDialog. When an event * ends dialog processing, EndDialog is called to close the * dialog. Then the dialog is released from memory by * a call to ReleaseDialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12027 #define RES_PBUT_NEXT 1

// ID of dialog itself // ID of Next button

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

689

Appendix B: Built-In Functions (E-G) EndDialog

#define RES_PBUT_CANCEL #define RES_PBUT_BACK

9 12

// ID of Cancel button // ID of Back button

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EndDialog(HWND); function ExFn_EndDialog(hMSI) STRING szDialogName, szDLLName, szDialog; NUMBER nDialog, nResult, nCmdValue; BOOL bDone; HWND hInstance, hwndParent; begin // Define the name of a dialog to pass as first // parameter to DefineDialog. szDialogName = "ExampleDialog"; // DefineDialog's second parameter will be 0 because the // .dll file is in _isres.dll. hInstance = 0; // DefineDialog's third parameter will be null; installation // will search for the dialog in _isuser.dll and _isres.dll. szDLLName = ""; // DefineDialog's fifth parameter will be null because the // dialog is identified by its ID in the fourth parameter. szDialog = ""; // This value is reserved and must be 0. hwndParent = 0; // Define the dialog. The installation's main window will own the // dialog (indicated by HWND_INSTALL in parameter 7). nResult = DefineDialog (szDialogName, hInstance, szDLLName, RES_DIALOG_ID, szDialog, hwndParent, HWND_INSTALL, DLG_MSG_STANDARD|DLG_CENTERED); // Check for an error. if (nResult < 0) then MessageBox ("An error occurred while defining the dialog.", SEVERE); bDone = TRUE; abort; endif; // Initialize the indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog(szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR:
690 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EnterDisk

MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory. ReleaseDialog (szDialogName); end;

EnterDisk
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

The EnterDisk function displays a message box that prompts the end user to insert the next disk. The system variable SRCDIR contains the default path, which is displayed on the message box. The end user can modify the default path by typing a new path and clicking OK.
EnterDisk recognizes the correct disk by searching the disk for the tag file specified by szTagFile. If the disk does not contain the tag file, the function calls the EnterDiskError function to display an error

message box that prompts the end user to enter the correct disk. At build time, InstallShield does not automatically generate tag files in the disk image folders. To use tag files, add them to the disk image folders after the folders are built.

Note: You cannot use the PlaceWindow function in conjunction with the EnterDisk function. By default, the message box appears in the center of the desktop, unless the background window mode is enabled. If the installation is in window mode, the message box opens in the center of the background window. The default title is Setup Needs the Next Disk. To change the title, call SetDialogTitle before calling EnterDisk.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

691

Appendix B: Built-In Functions (E-G) EnterDisk

Syntax
EnterDisk (szMsg, szTagFile);

Parameters
Table B-6: EnterDisk Parameters Parameter szMsg szTagFile Description Specifies the message that prompts the end user to insert the proper disk. Specifies the name of the tag file. EnterDisk searches for this file on the inserted disk. If the file is not found, the function calls the EnterDiskError function to display a message that asks the user to insert the correct disk. If you pass a null string ("") in this parameter, the function does not search for any file; it assumes that the correct disk is being used.

Return Values
Table B-7: EnterDisk Return Values Return Value OK (1) <0 Description Indicates that the user clicked the OK button. Indicates that an unspecified error has occurred.

Additional Information
The dialog that is displayed by the EnterDisk function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

EnterDisk Example
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * This example demonstrates the EnterDisk function.

692

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EnterDiskError

* * EnterDisk is called to prompt the user to insert a disk or * to specify a path. EnterDisk then searches for the tag file * at that location. * \*--------------------------------------------------------------*/ #include "ifx.h" export prototype ExFn_EnterDisk(HWND); function ExFn_EnterDisk(hMSI) STRING szMsg, szTagFile; begin // Set up parameters for call to EnterDisk. szMsg = "Please insert disk 2"; szTagFile = "ISExampl.txt"; // Display the EnterDisk dialog. EnterDisk (szMsg, szTagFile); end;

EnterDiskError
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

The EnterDiskError function checks whether a specified path and file exists. The function displays an appropriate error if the file does not exist in the specified path; then it returns success or failure, depending on whether the specified file exists.

Tip: EnterDiskError can also check for the presence of a specific path, without a particular file.

Syntax
EnterDiskError (byval string szPath, byval string szFile);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

693

Appendix B: Built-In Functions (E-G) EnterLoginInfo

Parameters
Table B-8: EnterDiskError Parameters Parameter szPath szFile Description Specify the path to be checked. Specify the name of the file to be checked. If you want EnterDisk to check for just the path, but not a specific file, specify a null string ("").

Return Values
Table B-9: EnterDiskError Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description The specified path and file exist. The specified path and file do not exist.

Additional Information
Since the EnterDiskError function is typically called only internally by the EnterDisk function, it does not include any silent mode handling, other than the normal MessageBox silent mode handling. By default, the dialog displays the same error message and the default message box title for the installation, regardless of the error that occurs. You can change this behavior by calling the SetErrorTitle and SetErrorMsg functions with nErrorId set as follows:

ERR_BOX_DISKIDCustomize the title or message displayed when the specified disk does not exist. ERR_BOX_BADPATHCustomize the title or message displayed when the specified path does not

exist.
ERR_BOX_BADTAGFILECustomize the title or message displayed when the specified file does not exist. (If a null string ("") is specified for szFile, no error check occurs, and no message is displayed.)

EnterLoginInfo
Project: This information applies to the following project types.

InstallScript InstallScript MSI

The EnterLoginInfo function displays a dialog that enables the end user to specify a user name and password. Note that the dialog does not validate or use the specified information. In addition, the dialog does not perform any error checking for the specified information.

694

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EnterLoginInfo

The EnterLoginInfo dialog is typically used to let the end user specify a network user name and password. The SdLogonUserInformation dialog is similar to the EnterLoginInfo dialog, but the SdLogonUserInformation dialog provides additional options. If your installation needs to obtain information to log into a SQL Server, SQLServerLogin offers additional functionality.

Syntax
EnterLoginInfo (byval string szMsg, byref string svUser, byref string svPassword);

Parameters
Table B-10: EnterLoginInfo Parameters Parameter szMsg Description Specifies the static text to be displayed in the dialog. To display the default text, pass a null string ("") in this parameter. Specifies the default value that is initially displayed in the User Name box when the function is called, and specifies the string that the end user specified when the function returns. The dialog does not allow more than 255 characters to be entered in the User Name box. svPassword Specifies the default value that is initially displayed in the Password box when the function is called, and specifies the string that the end user specified when the function returns. The dialog does not allow more than 255 characters to be entered in the Password box.

svUser

Return Values
Table B-11: EnterLoginInfo Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description The function was successful. The function was not successful.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

695

Appendix B: Built-In Functions (E-G) EnterPassword

EnterPassword
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The EnterPassword function displays a dialog that queries the end user for a password; the characters that the end user types in the edit box are displayed as asterisks (*).

Note: To check the returned password, you can call FeatureValidate, as is done in the default code for the OnCheckMediaPassword event handler function.

Syntax
EnterPassword ( szMsg, szDefault, svResult );

Parameters
Table B-12: EnterPassword Parameters Parameter szMsg Description Specifies a message to display in the dialog. This text is considered a static control. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the text that is initially displayed in the edit box. Returns the text that the end user enters in the edit box.

szDefault svResult

Return Values
Table B-13: EnterPassword Return Values Return Value NEXT BACK < ISERR_SUCCESS Description Indicates that the user clicked the Next button. Indicates that the user clicked the Back button. Indicates that the dialog could not be displayed.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

696

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) ExistsDir

ExistsDir
The ExistsDir function checks for the existence of a specified directory on the target system or the Internet.

Syntax
ExistsDir ( szPath );

Parameters
Table B-14: ExistsDir Parameters Parameters szPath Description Specifies the fully qualified path of the directory to find on the target system, or the valid Uniform Resource Locator (URL) of the directory to find on the Internet. To check the validity of a URL, call Is(VALID_PATH, szURL).

Return Values
Table B-15: ExistsDir Return Values Return Value EXISTS (0) NOTEXISTS (-1) All other negative values Description Indicates that the specified directory exists. Indicates that the specified directory does not exist. Indicates that the function was unable to determine whether the specified directory exists. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

ExistsDir Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ExistsDir function. * * AskPath is called to get a directory name from the user. * Then, ExistsDir is called to determine whether the directory * exists. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ExistsDir Example"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

697

Appendix B: Built-In Functions (E-G) ExistsDisk

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ExistsDir(HWND); function ExFn_ExistsDir(hMSI) STRING svPath; begin // Get the path to be created. AskPath ("Please enter a path:", "", svPath); // Check for the existence of the directory. if (ExistsDir (svPath) = EXISTS) then SprintfBox (INFORMATION, TITLE_TEXT, "%s already exists.", svPath); else SprintfBox (INFORMATION, TITLE_TEXT, "%s does not exist", svPath); endif; end;

ExistsDisk
The ExistsDisk function checks for the existence of a specified disk drive on the target system.

Syntax
ExistsDisk ( szDisk );

698

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) ExistsDisk

Parameters
Table B-16: ExistsDisk Parameters Parameter szDisk Description Specifies the letter of the disk drive.

Return Values
Table B-17: ExistsDisk Return Values Return Value EXISTS (0) NOTEXISTS (-1) Description Indicates that the specified drive exists on the target system. Indicates that the specified drive does not exist on the target system.

ExistsDisk Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ExistsDisk function. * * AskText is called to get a disk drive name from the user. * Then, ExistsDir is called to determine whether the drive * exists. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ExistsDisk Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ExistsDisk(HWND); function ExFn_ExistsDisk(hMSI) STRING svDrive; begin if (AskText ("Enter the letter of a disk drive.", "C", svDrive) = NEXT) then // Check for the existence of the specified drive. if (ExistsDisk (svDrive) = EXISTS) then SprintfBox (INFORMATION, TITLE_TEXT, "Drive %s exists.", svDrive); else SprintfBox (INFORMATION, TITLE_TEXT, "Drive %s does not exist", svDrive);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

699

Appendix B: Built-In Functions (E-G) EzBatchAddPath

endif; endif; end;

EzBatchAddPath
The EzBatchAddPath function modifies the default batch file by adding a path either to the search path in a PATH command or to the value assigned to an environment variable. Unless it is changed by a call to BatchSetFileName, the default batch file is the Autoexec.bat file that was executed by the system during the boot sequence. To determine the fully qualified name of the default batch file, call BatchGetFileName. To change the name of the batch file to be used by EzBatchAddPath, call BatchSetFileName.

EzBatchAddPath does not make a backup copy of the file it modifies. EzBatchAddPath can fail if the default batch file is hidden or read-only.

Note: Do not mix Ez batch file functions and advanced batch file functions. After calling BatchFileLoad to load a batch file in memory, you cannot call any of the Ez batch file functions until you call BatchFileSave to save the file.

Syntax
EzBatchAddPath ( szKey, szPath, szRefDir, nPosition );

700

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzBatchAddPath

Parameters
Table B-18: EzBatchAddPath Parameters Parameter szKey Description Specifies the name of the environment variable to modify. For example, to modify the PATH statement, specify "PATH" here. If the specified environment variable is not found in the default file batch file, a complete SET statement is created for that environment variable and inserted into the file.

Caution: The EzBatchAddPath function does not support long file names. Call LongPathToShortPath to convert the long path to its short path equivalent before passing it to EzBatchAddPath. For an explanation of long file names, see Long File Names. szPath Specifies the path to add to the current value of the environment variable. A delimiting semicolon is inserted to separate it from other paths in the search path. Specifies the reference key (a path) relative to which you are adding the new path specified by szPath. If this is a null string (""), the directory is added to the beginning or end of the search path, depending on the value of nPosition. If the path specified by szRefDir is not found in the search path, the value of szKey is added to the end. Specifies where in the search path to add the new path. Pass one of the following predefined constants in this parameter:

szRefDir

nPosition

BEFOREThe new path is inserted before the path specified by szRefDir. If szRefDir contains a null string (""), the directory is added to the front of the search path. AFTERThe new path is inserted after the path specified by szRefDir. If szRefDir contains a null string (""), the directory is added to the end of the search path.

Return Values
Table B-19: EzBatchAddPath Return Values Return Value 0 <0 Description EzBatchAddPath successfully added the path to the batch file. EzBatchAddPath was unable to add the path to the batch file.

EzBatchAddPath Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

701

Appendix B: Built-In Functions (E-G) EzBatchAddPath

* InstallShield Example Script * * Demonstrates the EzBatchAddPath function. * * First, BatchSetFileName is called to change the default batch * file to EXAMPLE_BATCH. Then EzBatchAddPath is then called to * add C:\WINDOWS to the beginning of the PATH statement. A * second call to EzBatchAddPath adds C:\UTILS after the WINDOWS * keyword in the PATH statement. * * Note: Before running this script, create a batch file * named ISExampl.bat and store it in the root of * drive C. * \*--------------------------------------------------------------*/ #define EXAMPLE_BATCH "C:\\ISExampl.bat" #define TITLE "EzBatchAddPath example" #define MSG "Successful.\n\n%s added to %s statement." // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EzBatchAddPath(HWND); function ExFn_EzBatchAddPath(hMSI) STRING szKey, szPath, szRefDir; begin // Set the default batch file. BatchSetFileName (EXAMPLE_BATCH); // Set up parameters for next call to EzBatchAddPath. szKey = "PATH"; szPath = "C:\\WINDOWS"; szRefDir = ""; if (EzBatchAddPath (szKey, szPath, szRefDir, BEFORE) < 0) then // Report the error. MessageBox ("EzBatchAddPath failed.", SEVERE); else // Report success. SprintfBox (INFORMATION, TITLE, MSG, szPath, szKey); // Set up parameters for next call to EzBatchAddPath. szKey = "PATH"; szPath = "C:\\UTILS"; szRefDir = "WINDOWS"; if (EzBatchAddPath (szKey, szPath, szRefDir, AFTER) < 0) then // Report the error. MessageBox ("EzBatchAddPath failed.", SEVERE); else // Report success. SprintfBox (INFORMATION, TITLE, MSG, szPath, szKey); endif; endif; end;

702

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzBatchAddString

EzBatchAddString
The EzBatchAddString function adds a line of text to the default batch file; unless it is changed by a call to BatchSetFileName, the default batch file is the Autoexec.bat file that was executed by the system during the boot sequence. To determine the fully qualified name of the default batch file, call BatchGetFileName. To change the name of the batch file to be used by EzBatchAddPath, call BatchSetFileName.

The EzBatchAddString function can fail if the default batch file is hidden or read-only. EzBatchAddString does not make a backup copy of the file it modifies.

Note: Do not mix Ez batch file functions and advanced batch file functions. After calling BatchFileLoad to load a batch file in memory, you cannot call any of the Ez batch file functions until you call BatchFileSave to save the file.

Syntax
EzBatchAddString ( szLine, szRefKey, nOptions );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

703

Appendix B: Built-In Functions (E-G) EzBatchAddString

Parameters
Table B-20: EzBatchAddString Parameters Parameter szLine Description Specifies the line of text to add to the file. Unless you specify NOSET in nOptions, this function assumes that szLine is an environment variable; the text "SET" is inserted at the front of the string before szLine is written to the default batch file.

Caution: The EzBatchAddString function does not support long file names. If you are using this function to add a line that contains a long path, call LongPathToShortPath to convert the long path to its short path equivalent before adding it to the string to be placed in the batch file. For an explanation of long file names, see Long File Names. szRefKey Specifies the reference key relative to which you want to add szLine in the default batch file. EzBatchAddString searches the default batch file for the reference key and places the contents of szLine before or after that line, depending on the value of nOptions.

Note: EzBatchAddString looks for the appropriate reference keyword in the parameter szRefKey. For example, the keyword for an environment variable is the name of the environment variable itself. nOptions Specifies the option to use. Pass one of the following predefined constants in this parameter:

BEFOREszLine is added before the line containing szRefKey. If szRefKey is a null string (""), szLine is added as the first line of the file. AFTERszLine is added after the line containing szRefKey. If szRefKey is a null string (""), szLine is added as the last line of the file. REPLACEszLine replaces an existing line in the file. If multiple lines with same key exist, EzBatchAddString replaces only the last line that contains the key. NOSETSpecifies that the text "SET" should not be inserted at the front of the string in szLine. COMMANDIndicates that the reference key you are searching for is a DOS command or program name (not an environment variable).

The NOSET and COMMAND constants can be combined with each other or the BEFORE, AFTER, or REPLACE constants using the logical OR operator. For example, when the reference key you are searching for is a DOS command or program name (not an environment variable), use the OR operator to combine the constant COMMAND with the constant AFTER, as shown below:
EzBatchAddString (szLine, szRefKey, AFTER | COMMAND);

704

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzBatchAddString

Return Values
Table B-21: EzBatchAddString Return Values Return Value 0 <0 Description EzBatchAddString successfully added the text string to the specified batch file. EzBatchAddString was unable to add the text string.

EzBatchAddString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the EzBatchAddString function. * * This script performs four operations on a batch file: * * -- First, it adds a comment line at the top of the file. * * -- Next, it adds the line "SET TEMP=C:\EXAPP3", placing it * it after the PATH statement. * * -- Then, it adds the command "C:\EXAPP3\EXAPP.EXE", placing * it after the "SET TEMP=C:\EXAPP3" statement. * * -- Finally, it replaces the existing PATH statement with a * new PATH statement. * * Note: Before running this script, create a batch file * named ISExampl.bat and store it in the root of * drive C. For best effect, include a PATH statement * in that file. * \*--------------------------------------------------------------*/ #define BATCH_FILE "C:\\ISExampl.bat" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EzBatchAddString(HWND); function ExFn_EzBatchAddString(hMSI) STRING szLine, szRefKey; NUMBER nOptions; begin // Set the default batch file. BatchSetFileName (BATCH_FILE);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

705

Appendix B: Built-In Functions (E-G) EzBatchReplace

// Set up szLine szRefKey nOptions

parameters for next call to EzBatchAddString. = "rem This is the first line of the file."; = ""; = BEFORE|NOSET;

// Add a comment line to the top of the batch file. if (EzBatchAddString (szLine, szRefKey, nOptions) < 0) then MessageBox ("First call to EzBatchAddString failed.", SEVERE); else MessageBox ("First call to EzBatchAddString successful.", INFORMATION); endif; // Set up szLine szRefKey nOptions parameters for next call to EzBatchAddString. = "TEMP=C:\\EXAPP3"; = "PATH"; = AFTER;

// Add a line after the PATH statement. if (EzBatchAddString (szLine, szRefKey, nOptions) < 0) then MessageBox ("Second call to EzBatchAddString failed.", SEVERE); else MessageBox ("Second call to EzBatchAddString successful.", INFORMATION); endif; // Set up szLine szRefKey nOptions parameters for next call to EzBatchAddString. = "C:\\EXAPP3\\EXAPP.EXE"; = "TEMP"; = AFTER|NOSET;

// Add a command line after the SET TEMP statement. if (EzBatchAddString (szLine, szRefKey, nOptions) < 0) then MessageBox ("Third call to EzBatchAddString failed.", SEVERE); else MessageBox ("Third call to EzBatchAddString successful.", INFORMATION); endif; // Set up szLine szRefKey nOptions parameters for next call to EzBatchAddString. = "PATH=C:\\;C:\\Windows"; = "PATH"; = AFTER|NOSET|REPLACE|COMMAND;

// Replace the PATH statement. if (EzBatchAddString (szLine, szRefKey, nOptions) < 0) then MessageBox ("Fourth call to EzBatchAddString failed.", SEVERE); else MessageBox ("Fourth call to EzBatchAddString successful.", INFORMATION); endif; endprogram

EzBatchReplace
The EzBatchReplace function replaces an existing line of text in the default batch file; unless it is changed by a call to BatchSetFileName, the default batch file is the Autoexec.bat file that was executed by the system during the boot sequence. To determine the fully qualified name of the default batch file, call BatchGetFileName. To change the name of the batch file to be used by EzBatchAddPath, call BatchSetFileName.
706 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzBatchReplace

Some common keys in a batch file are PATH, COMSPEC, TEMP, Smartdrv.exe, Win.com, and Share.exe.

The EzBatchReplace function may fail if the default batch file is hidden or read-only. EzBatchReplace does not make a backup copy of the file it modifies.

Note: Do not mix Ez batch file functions and advanced batch file functions. After calling BatchFileLoad to load a batch file in memory, you cannot call any of the Ez batch file functions until you call BatchFileSave to save the file.

Syntax
EzBatchReplace ( szNewString );

Parameters
Table B-22: EzBatchReplace Parameters Parameter szNewString Description Specifies the new string to insert in place of an existing line in the file. EzBatchReplace parses szNewString and determines the key of the string. It then searches the default batch file for a line that contains the same key. The function replaces the last line found with the same key.

Caution: The EzBatchReplace function does not support long file names. If you are using this function to replace a line that contains a long path, call LongPathToShortPath to convert the long path to its short path equivalent before replacing it in the string in the batch file. For an explanation of long file names, see Long File Names.

Return Values
Table B-23: EzBatchReplace Return Values Return Value 0 <0 Description EzBatchReplace successfully replaced the line of text. EzBatchReplace was unable to replace the line of text.

EzBatchReplace Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 707

Appendix B: Built-In Functions (E-G) EzBatchReplace

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the EzBatchReplace function. * * EzBatchReplace is called to replace lines in a batch file. * * This script replaces three lines in the specified batch file. * First, it replaces the SET COMSPEC command. Then it replaces * the PATH statement. Finally, it replaces the command line * that references SMARTDRV.EXE. * * Note: Before running this script, create a batch file * named ISExampl.bat and store it in the root of * drive C. For best effect, that file should include * the following lines: * * SET COMSPEC=C:\COMMAND.COM * PATH C:\ * SMARTDRV.EXE * \*--------------------------------------------------------------*/ #define EXAMPLE_BAT "C:\\ISExampl.bat" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EzBatchReplace(HWND); function ExFn_EzBatchReplace(hMSI) begin // Set the default batch file. BatchSetFileName (EXAMPLE_BAT); // Replace the SET COMSPEC statement. if (EzBatchReplace ("SET COMSPEC=C:\\DOS\\COMMAND.COM") < 0) then MessageBox ("First call to EzBatchReplace failed.", SEVERE); else MessageBox ("First call to EzBatchReplace succeeded.", INFORMATION); endif;

// Replace the PATH command. if (EzBatchReplace ("PATH C:\\DOS;C:\\MYAPP") < 0) then MessageBox ("Second call to EzBatchReplace failed.", SEVERE); else MessageBox ("Second call to EzBatchReplace succeeded.", INFORMATION); endif; // Replace the SMARTDRIVE statement. if (EzBatchReplace ("SMARTDRV.EXE /P 1024 /C 512") < 0) then MessageBox ("Third call to EzBatchReplace failed.", SEVERE); else MessageBox ("Third call to EzBatchReplace succeeded.", INFORMATION); endif; end;

708

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzConfigAddDriver

EzConfigAddDriver
The EzConfigAddDriver function adds a device driver statement to the default system configuration file. You can specify the position of the driver statement relative to another driver statement. For example, an application may require loading a device driver before or after the Windows Himem.sys driver. Unless changed by a call to ConfigSetFileName, the default system configuration file is the Config.sys file that was executed by the system during the boot sequence. To make another file the default system configuration file, call ConfigSetFileName. To determine the fully qualified name of the default system configuration file, call ConfigGetFileName.

Note: Do not mix the Ez configuration file functions and the advanced configuration file functions. After calling ConfigFileLoad, you cannot call any of the Ez configuration file functions until you call ConfigFileSave to save the file.

Syntax
EzConfigAddDriver ( szDriver, szRefKey, nPosition );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

709

Appendix B: Built-In Functions (E-G) EzConfigAddDriver

Parameters
Table B-24: EzConfigAddDriver Parameters Parameter szDriver Description Specifies the fully qualified name of the driver to add to the file. If the driver already exists in one or more places in the system configuration file, this function replaces only the last occurrence of the line containing the driver. Specifies the name of the device driver relative to which you are adding szDriver. Indicates whether szDriver is to be added before or after the driver specified by szRefKey. Pass one of the following predefined constants in this parameter:

szRefKey nPosition

BEFOREThe statement is added before the line containing szRefKey. If szRefKey contains a null string (""), the driver is inserted as the first driver in the system configuration file. AFTERThe statement is added after the line containing szRefKey. If szRefKey contains a null string (""), the driver is inserted as the last driver in the system configuration file.

Return Values
Table B-25: EzConfigAddDriver Return Values Return Value 0 <0 Description EzConfigAddDriver successfully added the device driver statement to the file. EzConfigAddDriver was unable to add the driver statement.

EzConfigAddDriver Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the EzConfigAddDriver function. * * This example calls EzConfigAddDriver to add four statements * to a configuration file. * * -- The first call to EzConfigAddDriver adds a new line of * text after the last line. * * -- The second call adds a new line of text before the first * line. *

710

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzConfigAddDriver

* -- The third call adds the driver C:\DRDOS\HIDOS.SYS after * the key HIMEM.SYS * * -- The fourth call adds the driver EXAPP.SYS before the key * HIMEM.SYS. * * Note: Before running this script, create a configuration file * named ISExampl.sys in the root of drive C. For best * effect, include the following line in that file: * * DEVICE=C:\\Himem.sys * \*--------------------------------------------------------------*/ #define EXAMPLE_SYS "C:\\ISEXampl.sys" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EzConfigAddDriver(HWND); function ExFn_EzConfigAddDriver(hMSI) STRING szDriver, szRefKey; begin // Set the default configuration file. ConfigSetFileName (EXAMPLE_SYS); // Set up parameters for next call to EzConfigAddDriver. szDriver = "C:\\NEW\\MYAPP.DRV"; szRefKey = ""; // Add a driver to the end of the configuration file. if (EzConfigAddDriver (szDriver, szRefKey, AFTER) < 0) then MessageBox ("First call to EzConfigAddDriver failed.", SEVERE); else MessageBox ("First call to EzConfigAddDriver successful.", INFORMATION); endif; // Set up parameters for next call to EzConfigAddDriver. szDriver = "C:\\SYSTEM\\DMDRVR.BIN"; szRefKey = ""; // Add a driver to the top of the configuration file. if (EzConfigAddDriver (szDriver, szRefKey, BEFORE) < 0) then MessageBox ("Second call to EzConfigAddDriver failed.", SEVERE); else MessageBox ("Second call to EzConfigAddDriver successful.", INFORMATION); endif; // Set up parameters for next call to EzConfigAddDriver. szDriver = "C:\\DRDOS\\HIDOS.SYS"; szRefKey = "HIMEM.SYS"; // Add the "HIDOS.SYS" driver after the "HIMEM.SYS" key. if (EzConfigAddDriver (szDriver, szRefKey, AFTER) < 0) then MessageBox ("Third call to EzConfigAddDriver failed.", SEVERE); else MessageBox ("Third call to EzConfigAddDriver successful.", INFORMATION); endif; // Set up parameters for next call to EzConfigAddDriver.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 711

Appendix B: Built-In Functions (E-G) EzConfigAddString

szDriver szRefKey

= "EXAPP.SYS"; = "HIMEM.SYS";

// Add the "EXAPP.SYS" driver before the "HIMEM.SYS" key. if (EzConfigAddDriver (szDriver, szRefKey, BEFORE) < 0) then MessageBox ("Fourth call to EzConfigAddDriver failed.", SEVERE); else MessageBox ("Fourth call to EzConfigAddDriver successful.", INFORMATION); endif; end;

EzConfigAddString
The EzConfigAddString function adds a line of text to the default system configuration file. You can specify the position of the line you add in reference to another statement in the file. Unless changed by a call to ConfigSetFileName, the default system configuration file is the Config.sys file that was executed by the system during the boot sequence. To make another file the default system configuration file, call ConfigSetFileName. To determine the fully qualified name of the default system configuration file, call ConfigGetFileName.

Note: Do not mix the Ez configuration file functions and the advanced configuration file functions. After calling ConfigFileLoad, you cannot call any of the Ez configuration file functions until you call ConfigFileSave to save the file.

Syntax
EzConfigAddString ( szLine, szRefKey, nOptions );

712

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzConfigAddString

Parameters
Table B-26: EzConfigAddString Parameters Parameter szLine szRefKey Description Specifies the line of text to add to the system configuration file. Specifies the reference key relative to which you want to position szLine in the system configuration file. EzConfigAddString searches the system configuration file for the reference key and places the contents of the parameter szLine before or after the line containing the key, depending on which constants is passed in nOptions. Indicates whether the line specified by szLine is to be added before or after the line containing szRefKey. Pass one of the following predefined constants in this parameter:

nOptions

BEFOREThe line specified by szLine is added before the line containing szRefKey. If szRefKey contains a null string (""), szLine is inserted as the first line of the system configuration file. AFTERThe line specified by szLine is added after the line containing szRefKey. If szRefKey contains a null string (""), szLine is inserted as the last line of the system configuration file.

Return Values
Table B-27: EzConfigAddString Return Values Return Value 0 Description EzConfigAddString successfully added the string to the default system configuration file. EzConfigAddString was unable to add the text string.

<0

EzConfigAddString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the EzConfigAddString function. * * This example calls EzConfigAddString to add four lines to a * configuration file. * * -- The first call adds a new line of text at the end of * the file. *
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 713

Appendix B: Built-In Functions (E-G) EzConfigAddString

* -- The second call adds a new line of text at the top of * the file. * * -- The third call adds the line FASTOPEN=512 after the key * LASTDRIVE. * * -- The fourth call adds the line EXAPPHI=ON before the key * EXAPPHI.SYS. * * Note: Before running this script, create a configuration * file named ISExampl.sys and store it in the root of * drive C. For best effect, that file should include * the following lines: * * LASTRDRIVE=F * DEVICE=Exapphi.sys * \*--------------------------------------------------------------*/ #define EXAMPLE_SYS "C:\\ISExampl.sys" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EzConfigAddString(HWND); function ExFn_EzConfigAddString(hMSI) STRING szLine, szRefKey; begin // Set the default configuration file. ConfigSetFileName (EXAMPLE_SYS); // Set up parameters for next call to EzConfigAddString. szLine = "SHELL=C:\\COMMAND.COM /P /E:512"; szRefKey = ""; // Add a line to the end of the file. if (EzConfigAddString (szLine, szRefKey, AFTER) < 0) then MessageBox ("First call to EzConfigAddString failed.", SEVERE); else MessageBox ("First call to EzConfigAddString succeeded.", INFORMATION); endif; szLine = "DEVICE=C:\\System\\Dmdrvr.bin"; szRefKey = ""; // Add a line to the top of the file. if (EzConfigAddString (szLine, szRefKey, BEFORE) < 0) then MessageBox ("Second call to EzConfigAddString failed.", SEVERE); else MessageBox ("Second call to EzConfigAddString succeeded.", INFORMATION); endif; // Set up parameters for next call to EzConfigAddString. szLine = "FASTOPEN=512"; szRefKey = "LASTDRIVE"; // Add a line to the file after the key "LASTDRIVE". if (EzConfigAddString (szLine, szRefKey, AFTER) < 0) then MessageBox ("Third call to EzConfigAddString failed.", SEVERE); else
714 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzConfigGetValue

MessageBox ("Third endif;

call to EzConfigAddString succeeded.", INFORMATION);

// Set up parameters for next call to EzConfigAddString. szLine = "EXAPPHI=ON"; szRefKey = "EXAPPHI.SYS"; // Add a line to the file before the key "Exapphi.sys". if (EzConfigAddString (szLine, szRefKey, BEFORE) < 0) then MessageBox ("Fourth call to EzConfigAddString failed.", SEVERE); else MessageBox ("Fourth call to EzConfigAddString succeeded.", INFORMATION); endif; end;

EzConfigGetValue
The EzConfigGetValue function retrieves the numeric value of a parameter, such as FILES or BUFFERS, from the default system configuration file. Unless changed by a call to ConfigSetFileName, the default system configuration file is the Config.sys file that was executed by the system during the boot sequence. To make another file the default system configuration file, call ConfigSetFileName. To determine the fully qualified name of the default system configuration file, call ConfigGetFileName.

Note: Do not mix the Ez configuration file functions and the advanced configuration file functions. After calling ConfigFileLoad, you cannot call any of the Ez configuration file functions until you call ConfigFileSave to save the file.

Syntax
EzConfigGetValue ( szRefKey, nvValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

715

Appendix B: Built-In Functions (E-G) EzConfigGetValue

Parameters
Table B-28: EzConfigGetValue Parameters Parameter szRefKey nvValue Description Specifies the name of the parameter whose value is to be retrieved. Returns the numeric value of the key specified by szRefKey.

Return Values
Table B-29: EzConfigGetValue Return Values Return Value 0 <0 Description EzConfigGetValue successfully retrieved the value. EzConfigGetValue was unable to retrieve the value.

EzConfigGetValue Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the EzConfigGetValue function. * * EzConfigGetValue is called to retrieve a value from a key in * the default configuration file. Unless changed by a call to * ConfigSetFileName, the default configuration file is the * Config.sys file that resides in the root of the boot drive. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EzConfigGetValue(HWND); function ExFn_EzConfigGetValue(hMSI) NUMBER nvValue; begin // Retrieve the numeric value of the FILES key from the // default configuration file. if (EzConfigGetValue ("FILES", nvValue) < 0) then // Report the error. MessageBox ("EzConfigGetValue failed.", SEVERE); else

716

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzConfigSetValue

// Display the value of the FILES key. SprintfBox (INFORMATION, "EzConfigGetValue Example", "FILES = %d", nvValue); endif; end;

EzConfigSetValue
The EzConfigSetValue function sets the value of a command in the default system configuration file. Unless changed by a call to ConfigSetFileName, the default system configuration file is the Config.sys file that was executed by the system during the boot sequence. To make another file the default system configuration file, call ConfigSetFileName. To determine the fully qualified name of the default system configuration file, call ConfigGetFileName.

Note: Do not mix the Ez configuration file functions and the advanced configuration file functions. After calling ConfigFileLoad, you cannot call any of the Ez configuration file functions until you call ConfigFileSave to save the file.

Syntax
EzConfigSetValue (szRefKey, nValue);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

717

Appendix B: Built-In Functions (E-G) EzConfigSetValue

Parameters
Table B-30: EzConfigSetValue Parameters Parameter szRefKey Description Specifies the command whose value is to be changed or added in the default system configuration file. If the key does not exist in that file, it is added. Specifies the new value of the command specified by szRefKey.

nValue

Return Values
Table B-31: EzConfigSetValue Return Values Return Value 0 <0 Description EzConfigSetValue successfully set the value. EzConfigSetValue was unable to set the value.

EzConfigSetValue Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the EzConfigSetValue function. * * EzConfigSetValue is called to add or change the BUFFER and * FILES commands in the default configuration file. * * Note: The first time you run this script, it will create a * file named ISExampl.sys in the root of drive C. You * may delete that file when you have finished analyzing * this script. * \*--------------------------------------------------------------*/ #define EXAMPLE_SYS "C:\\ISExampl.sys" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EzConfigSetValue(HWND); function ExFn_EzConfigSetValue(hMSI) STRING szRefKey, szMsg; NUMBER nValue; begin

718

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzDefineDialog

// Set the default configuration file. ConfigSetFileName (EXAMPLE_SYS); // Add or change the BUFFERS command. if (EzConfigSetValue ("BUFFERS", 30) < 0) then MessageBox ("Unable to set Buffers in " + EXAMPLE_SYS + ".", SEVERE); else MessageBox ("Buffers set to 30 in " + EXAMPLE_SYS+".", INFORMATION); endif; // Add or change the FILES command. if (EzConfigSetValue ("FILES", 30) < 0) then MessageBox ("Unable to set Files in " + EXAMPLE_SYS + ".", SEVERE); else MessageBox ("Files set to 30 in " + EXAMPLE_SYS + ".", INFORMATION); endif; end;

EzDefineDialog
The EzDefineDialog function defines a custom dialog.

Note: This function does not display the custom dialog. To display a custom dialog, call WaitOnDialog.

Syntax
EzDefineDialog ( szDialogName, szDLLName, szDialogID, nDialogID );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

719

Appendix B: Built-In Functions (E-G) EzDefineDialog

Parameters
Table B-32: EzDefineDialog Parameters Parameter szDialogName Description Specifies the name to associate with the dialog identified by szDialogID or nDialogID. To process that dialog, use this name in subsequent calls to custom dialog functions. Note that the dialog's name is case-sensitive; you must use it exactly as you have specified it in this parameter. Specifies the name of the .dll file that contains the dialog resource. If this name is not qualified, that is, if you do not specify the drive and path with the file name, InstallShield searches for the .dll file in the Windows folder. If it is not found there, InstallShield searches the folders specified in the search path. When the dialog is located in _isuser.dll, you can specify a null string ("") in this parameter; InstallShield automatically checks _isuser.dll if this parameter is specified as a null string ("").

szDLLName

Note: When you use a .dll file other than _isres.dll or _isuser.dll, you must call UseDLL to load the .dll file before calling EzDefineDialog. To unload the .dll file from memory, call UnUseDLL after calling ReleaseDialog. szDialogID Specifies the dialog's resource ID if you use a string rather than a number to identify the resource. If this parameter is a null string (""), nDialogID is used to identify the dialog resources. It is recommended that you use nDialogID rather than szDialogID to identify the dialog resource.

Note: If you created the dialog in the Dialogs view, the dialog is created with a string ID; therefore, you must specify this name as the szDialogID parameter to define the dialog. If you override an existing dialog in the Dialogs view, the dialog has a numeric ID, and you must specify the ID in the nDialogID parameter. If you want to use numeric IDs in all caseswhich is what is recommendedyou must edit the dialog in the Dialogs view to change the ISResourceID property of the created dialog to the desired Dialog ID instead of 0. Note that if you do this, the dialog name is no longer used when the dialog is created; it is used only in the Dialogs view in InstallShield to identify the dialog. The dialog is built with the correct numeric ID. nDialogID Specifies the dialog's resource ID if you use a number rather than a string to identify the resource. This parameter is used only when szDialogID is a null string (""). It is recommended that you use nDialogID rather than szDialogID to identify the dialog resource.

720

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) EzDefineDialog

Return Values
Table B-33: EzDefineDialog Return Values Return Value 0 Description EzDefineDialog successfully defined the dialog.

DLG_ERR_ALREADY_EXISTS (-3) Indicates that you are trying to define a dialog that has already been defined in the installation script. You cannot define two dialogs with the same name. DLG_ERR (-1) Indicates an unspecified error condition.

EzDefineDialog Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the EzDefineDialog function. * * This script opens a simple custom dialog that displays * a bitmap. The dialog can be closed with any of three * buttons: Back, Next, or Cancel. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdBitmap. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * * In order to use this custom dialog, the script first defines * it by calling EzDefineDialog. It then displays the dialog * and gets dialog events by calling WaitOnDialog. When an * event ends dialog processing, EndDialog is called to close * the dialog. Then the dialog is released from memory by * a call to ReleaseDialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12027 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12

// // // //

ID ID ID ID

of of of of

dialog itself Next button Cancel button Back button

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EzDefineDialog(HWND);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

721

Appendix B: Built-In Functions (E-G) EzDefineDialog

function ExFn_EzDefineDialog(hMSI) STRING szDialogName, szDLLName, szDialog; NUMBER nDialog, nResult, nCmdValue; BOOL bDone; HWND hInstance, hwndParent; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize the indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog(szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; if (SdIsStdButton( nCmdValue ) && SdDoStdButton( nCmdValue )) then bDone = TRUE; endif; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName);
722 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureAddCost

// Free the dialog from memory. ReleaseDialog (szDialogName); end;

FeatureAddCost
Project: This information applies to InstallScript projects.

The FeatureAddCost function specifies that the feature includes additional installation operations that should be accounted for when updating the progress bar during the installation. Specifically, the FeatureAddCost function adds the value of nCost to the specified feature. This function can be called anytime before calling StatusUpdate, but it should typically be used before displaying a feature dialog so that the dialog shows the intended size for the feature to be installed.

Important: The FeatureAddCost function is supported only for file media. Use FeatureGetData or FeatureSetData to set the size of script-created features.

Note: The information specified in this function is not remembered in subsequent installations. This function should be called each time that the feature is being installed, including during repair or maintenance mode. Also, the setup engine has no way to determine whether the specified cost is for a single file or multiple files. Therefore, it does not attempt to adjust the specified size based on the cluster size of the target drive. Thus, you should use the GetAndAddFileCost, CalculateAndAddFileCost , or GetAndAddAllFilesCost functions to determine the cost of the file, taking into account cluster size, before calling this function.

Syntax
FeatureAddCost ( szMediaSource, szFeature, szTarget, nCostHigh, nCostLow );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

723

Appendix B: Built-In Functions (E-G) FeatureAddItem

Parameters
Table B-34: FeatureAddCost Parameters Parameter szMediaSource szFeature Description The media source, typically MEDIA. Specifies the feature to add this cost to. Note that a specific feature in the media must be specified as installation cost is calculated by feature. Cost cannot be specified for the entire media. Specifies the target directory for the cost specified by nCost. This value is used when determining which volume or drive this cost applies to and when displaying the size required for the feature in the feature dialog. Currently, only a single szTarget variable for custom cost is supported for each feature. If you call this function multiple times for the same feature, szTarget variable should be the same each time. Otherwise, the value specified during the last call is used for the target of all additional cost for the feature. Specifies the upper 31 bits of the additional cost to be added to the feature. Specifies the lower 31 bits of the additional cost to be added to the feature.

szTarget

nCostHigh nCostLow

Return Values
Table B-35: FeatureAddCost Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully added the cost. Indicates that the function was unable to add the cost.

FeatureAddItem
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureAddItem function adds a feature to a script-created feature set. If a script-created feature set with the name specified by szFeatureSet does not already exist, this function creates it. Call FeatureAddItem once for each feature you want to add to a given script-created feature set. You can create multiple script-created feature sets, each with a unique name (szFeatureSet parameter).

Caution: This function cannot be used with file media libraries.

724

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureAddItem

Syntax
FeatureAddItem ( szFeatureSet, szFeature, nDataSize, bSelected );

Parameters
Table B-36: FeatureAddItem Parameters Parameter szFeatureSet Description Specifies the name of the script-created feature set to which an item will be added. If the script-created feature set does not exist, FeatureAddItem creates it. Specifies the name of the feature to be added. Do not use a null string (""). To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls. Specifies the size in bytes of the data the feature represents. If the feature is a series of files, this parameter specifies the total uncompressed size of all the files. Specifies the default selection setting of the feature. Pass one of the following predefined constants in this parameter:

szFeature

nDataSize

bSelected

TRUEIndicates that the feature is selected by default. If TRUE is passed to select a subfeature whose parent feature is not selected, the subfeature is not selecteddespite passing TRUE in the bSelected parameter. FALSEIndicates that the feature is not selected by default.

Note: Default selection settings are cleared when the user selects a feature or subfeature displayed in a dialog. If the user clears a selected feature, all of its subfeatures are cleared. If the user clears all of a feature's subfeatures, the feature's selection setting is cleared.

Return Values
Table B-37: FeatureAddItem Return Values Return Value 0 Description FeatureAddItem successfully added the item to the feature or subfeature to the script-created feature set. FeatureAddItem was unable to add the item to the feature or subfeature to the script-created feature set. For additional information, call FeatureError.

<0

Additional Information
To display a single level of features to the end user for selection, use FeatureDialog, SdFeatureDialog, or SdFeatureDialogAdv. To display features and their subfeatures, use SdFeatureDialog2, SdFeatureMult, or SdFeatureTree.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

725

Appendix B: Built-In Functions (E-G) FeatureAddItem

You can use FeatureAddItem and script-created feature sets to allow users to select from options other than file media feature options:
1. 2. 3.

Call FeatureAddItem to create a script-created feature set containing the options you want. To display those options for selection, call SdAskOptions or SdAskOptionsList with the scriptcreated feature set name in the parameter szFeature. To determine which options were selected, call FeatureIsItemSelected.

FeatureAddItem Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureAddItem function. * * In this script, FeatureAddItem is called to create a * script-created feature set consisting of drives attached * to the target system. These features are displayed in an * SdAskOptionsList dialog so that the end user can select * from among the drives. * \*--------------------------------------------------------------*/ LIST listDrives, listFeatures; STRING szSaveMEDIAValue, svDrive; LONG nResult; BOOL bSelected; #include "ifx.h" function OnBegin() begin // Create the list to store drive names. listDrives = ListCreate(STRINGLIST); // Add all fixed drives to the list. GetValidDrivesList(listDrives, FIXED_DRIVE, -1); // Save the value of the system variable MEDIA so it can // be restored for later calls to transfer data. szSaveMEDIAValue = MEDIA; // Specify a name for the script-created feature set. MEDIA = "Drives"; // Put the drive names into the script-created feature set. nResult = ListGetFirstString(listDrives, svDrive); while (nResult != END_OF_LIST) FeatureAddItem(MEDIA, svDrive, 0, FALSE); nResult = ListGetNextString(listDrives, svDrive); endwhile; // Display the list of drives. Let user select one drive. SdAskOptionsList("Select a Drive" , "Select one of the drives attached to your system." ,

726

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureAddUninstallCost

"" , EXCLUSIVE); // Find the selected drive in the list. bSelected = FALSE; nResult = ListGetFirstString(listDrives, svDrive); bSelected = ComponentIsItemSelected (MEDIA , svDrive); while ((nResult != END_OF_LIST) && !bSelected); nResult = ListGetNextString(listDrives, svDrive); bSelected = ComponentIsItemSelected (MEDIA , svDrive); endwhile; // Release the list from memory. ListDestroy (listDrives); if bSelected then MessageBox("You selected drive " + svDrive + ".", INFORMATION); endif; // Restore MEDIA to its previous value for file transfer. MEDIA = szSaveMEDIAValue; end;

FeatureAddUninstallCost
Project: This information applies to InstallScript projects.

The FeatureAddUninstallCost function specifies that the feature includes additional uninstallation operations that must be accounted for when updating the progress bar during uninstallation. You do not have to call this function for operations that are included in the uninstallation log file. This includes operations that are handled by the XCopyFile function that may or may not have had to call the FeatureAddCost function to update the progress bar during the installation. This function is only needed for operations that were carried out by functionality other than the InstallScript engine. This function can be called anytime before calling StatusUpdate and can be called multiple times.

Syntax
FeatureAddUninstallCost ( szMediaSource, szFeature, nOps, nOpType);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

727

Appendix B: Built-In Functions (E-G) FeatureCompareSizeRequired

Parameters
Table B-38: FeatureAddUninstallCost Parameters Parameter szMediaSource szFeature Description The media source, typically MEDIA. Specifies the feature to add this cost to. Note that a specific feature in the media must be specified. Uninstallation cost is calculated by feature. Cost cannot be specified for the entire media. The number of operations to be added. Indicates the type of operation. Pass one of the following predefined constants in this parameter:

nOps nOpType

FEATURE_OPCOST_UNINSTALL_FILESpecifies the operation as uninstalling a file. You can also specify this constant using the value 4096. This enables you to experiment with different sizes to determine what size to use for your custom operation. FEATURE_OPCOST_UNINSTALL_REGORINISpecifies the operation as uninstalling a registry file. You can also specify this constant using the value 2048. This enables you to experiment with different sizes to determine what size to use for your custom operation. FEATURE_OPCOST_UNINSTALL_UNREGFILESpecifies the operation as unregistering a file. You can also specify this constant using the value 16384. This enables you to experiment with different sizes to determine what size to use for your custom operation.

Note: You can also pass a numeric value in this parameter to indicate an operation of a specific cost. You may need to experiment with different values to determine the appropriate value for a specified custom operation. Note that the total uninstall cost added is nOps multiplied by nOpType.

Return Values
Table B-39: FeatureAddUninstallCost Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully added the cost. Indicates that the function was unable to add the cost.

FeatureCompareSizeRequired
Project: This information applies to the following project types:
728 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureCompareSizeRequired

InstallScript InstallScript MSI

The FeatureCompareSizeRequired function determines whether the target folder contains enough free space for the selected features specified by szFeatureSource, which must be a file media. If the target folder does not have sufficient free space, the fully qualified folder name is returned in svTarget and the amount of required free space is returned in nvSize. If your setup specifies a destination folder for a feature in a file library at run time, it must do so by calling FeatureSetTarget before checking for free space with FeatureCompareSizeRequired.

Note: This function cannot be used with script-created feature sets.

Syntax
FeatureCompareSizeRequired ( szFeatureSource, svTarget, nvSize );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

729

Appendix B: Built-In Functions (E-G) FeatureCompareSizeRequired

Parameters
Table B-40: FeatureCompareSizeRequired Parameters Parameter szFeatureSource svTarget Description You must pass the system variable MEDIA in this parameter. No other value is valid. Returns a null string ("") if there is sufficient free space available on the target drive. Returns the target path if there is not sufficient free space on the target drive.

Note: The parameter svTarget is used only to return a folder name. You cannot use the parameter to specify a destination folder. FeatureCompareSizeRequired checks the drive that is indicated by the destination folder that you specified for each component in the Components view. If szFeatureSource is a file media with features to be installed in the General Application Destination, you must assign a destination path to TARGETDIR (in InstallScript installations) or INSTALLDIR (in InstallScript MSI installations) before calling FeatureCompareSizeRequired. You can obtain a destination path from an end user by calling AskDestPath or a feature dialog. nvSize Returns 0 if there is sufficient free space available on the target drive. Returns the size (in bytes) required if there is not sufficient free space on the target drive.

Return Values
Table B-41: FeatureCompareSizeRequired Return Values Return Value 0 <0 Description FeatureCompareSizeRequired was successful. FeatureCompareSizeRequired failed. Call FeatureError for additional information.

FeatureCompareSizeRequired Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureAddItem, FeatureSetData, * FeatureCompareSizeRequired, and SdFeatureMult functions. * * Notes: DESTDIR must reference a drive with very little space * available, such as a floppy drive. Remember to put a * diskette into the floppy drive before running this * script. * \*--------------------------------------------------------------*/ #define FEAT1 "CAD Prog. Files"

730

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureCompareSizeRequired

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

FEAT1SIZE FEAT1DESC FEAT2 FEAT2SIZE FEAT2DESC SUBFEAT1 SUBFEAT1SIZE SUBFEAT1DESC SUBFEAT2 SUBFEAT2SIZE SUBFEAT2DESC SUBFEAT3 SUBFEAT3SIZE SUBFEAT3DESC DESTDIR SDFEATTITLE SDFEATMSG FEATSIZEERRMSG

25000000 "CAD program EXEs and DLLs." "CAD Templates" 18000000 "CAD template files." "Industrial" 7000000 "CAD industrial engineering template files." "Civil" 5000000 "CAD civil engineering template files." "Mechanical" 6000000 "CAD mechanical engineering template files." "a:\\" "Displaying Script-created Features" "Make sure all features are selected." "Make sure target drive is accessible."

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FeatureCompareSizeRequired(HWND); function ExFn_FeatureCompareSizeRequired(hMSI) STRING svDir, svTarget; NUMBER nvSize, nData; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Make a script-created feature set that includes subfeatures // and give it the media name "Run-time CAD". MEDIA = "Run-time CAD"; FeatureAddItem (MEDIA, FEAT1, FEAT1SIZE, TRUE); FeatureSetData (MEDIA, FEAT1, FEATURE_FIELD_DESCRIPTION, nData, FEAT1DESC); FeatureAddItem (MEDIA, FEAT2, FEAT1SIZE, TRUE); FeatureSetData (MEDIA, FEAT2, FEATURE_FIELD_DESCRIPTION, nData, FEAT2DESC); FeatureAddItem (MEDIA, FEAT2 + "\\" + SUBFEAT1, SUBFEAT1SIZE, TRUE); FeatureSetData (MEDIA, FEAT2 + "\\" + SUBFEAT1, FEATURE_FIELD_DESCRIPTION, nData, SUBFEAT1DESC); FeatureAddItem (MEDIA, FEAT2 + "\\" + SUBFEAT2, SUBFEAT2SIZE, TRUE); FeatureSetData (MEDIA, FEAT2 + "\\" + SUBFEAT2, nData, SUBFEAT2DESC); FEATURE_FIELD_DESCRIPTION,

FeatureAddItem (MEDIA, FEAT2 + "\\" + SUBFEAT3, SUBFEAT3SIZE, TRUE); FeatureSetData (MEDIA, FEAT2 + "\\" + SUBFEAT3, FEATURE_FIELD_DESCRIPTION, nData, SUBFEAT3DESC); // Display the script-created features and subfeatures. SdFeatureMult (SDFEATTITLE, SDFEATMSG, svDir, ""); // Set INSTALLDIR to DESTDIR, which, if you define as a floppy drive
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 731

Appendix B: Built-In Functions (E-G) FeatureDialog

// (with a diskette in it), causes FeatureCompareSizeRequired // to display its 'not enough space' message. nvSize = 0; INSTALLDIR = DESTDIR; if (FeatureCompareSizeRequired(MEDIA, svTarget, nvSize) < 0) then MessageBox (FEATSIZEERRMSG, SEVERE); endif; end;

FeatureDialog
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureDialog function displays a dialog that enables the end user to select one or more items from a list of features in the installation. The end user can also select a destination location. When the end user clicks the Browse button, the Choose Folder dialog, which displays a list of existing folders, opens. The end user can select an existing folder from the list or enter a new folder name in the Path field. FeatureDialog returns the name of the specified folder in svDir. If the user specifies a folder that does not currently exist, the installation creates the folder.

Caution: If your installation does not use a setup type dialog, you must call FeatureSetupTypeSet to specify a setup type that has been defined in the Setup Types view in InstallShield before calling FeatureDialog.

Syntax
FeatureDialog ( szTitle, szMsg, svDir, szFeature );

732

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureDialog

Parameters
Table B-42: FeatureDialog Parameters Parameter szTitle Description Specifies the dialog title. To display the default title (Select Features), pass a null string ("") in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the default destination location variable. Returns the folder selected by the end user. The location returned in svDir does not affect file transfer unless you assign it to TARGETDIR (in InstallScript installations) or INSTALLDIR (in InstallScript MSI installations). If the default folder specified by svDir does not already exist on the end users system, it will not be created unless the end user clicks the Browse button and follows the steps to create it from the Choose Folder dialog. Therefore, whenever you specify a default folder, you must call ExistsDir when FeatureDialog returns in order to determine whether that folder exists. If it does not exist, call CreateDir to create it on the end users system. szFeature Specifies the feature whose subfeatures are displayed for selection. Pass a null string ("") in this parameter to display all top-level features. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls. FeatureDialog searches for the requested features in the script-created feature set specified by the system variable MEDIA.

szMsg

svDir

Note: If necessary, feature names are truncated to allow the display of the largest possible feature size. The space required to display the size depends on the maximum feature size (2 GB), the feature size options currently in use, and the font used to display feature information in the dialog. Feature size options are set with the DialogSetInfo function. When the space required to display the maximum possible size has been determined, all feature names are truncated automaticallyif necessaryto fit the remaining space. This ensures that feature names will not overlap feature sizes. Note that the name of a feature that requires less space to display its size (or that is not selected) may still be truncated under this method. To maximize performance and ensure that complete feature names are displayed, make feature names or display names smaller than the space available in the dialog.

Return Values
Table B-43: FeatureDialog Parameters Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

733

Appendix B: Built-In Functions (E-G) FeatureDialog

Table B-43: FeatureDialog Parameters (cont.) Return Value <0 Description Unable to display the FeatureDialog dialog. Call FeatureError for additional information.

Additional Information
The Choose Folder dialog indicates the amount of disk space that each feature occupies. A feature's size is displayed as 0 if it is not selected. Once it has been selected, its actual size is displayed.

FeatureDialog Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureDialog function. * * This example script displays a dialog that displays a list * of features in the setup that the user can install and the * amount of space that each feature occupies. * * Comments: To run this example script, create a project (or * insert into a project) with several features * and/or subfeatures with components containing * files. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" // Include iswi.h for Windows Installer API function prototypes and constants, // and to declare code for the OnBegin and OnEnd events. #include "iswi.h" // The keyword export identifies MyFunction() as an entry-point function. // The argument it accepts must be a handle to the Installer database. export prototype MyFunction(HWND); // To Do: // Declare global variables, define constants, and prototype userdefined and DLL functions here.

function MyFunction(hMSI) STRING szTitle, szMsg, svDir; begin

734

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureError

svDir = INSTALLDIR; szTitle = "Select Features"; szMsg = "Select the features you want to install on your computer."; // Display available features. FeatureDialog (szTitle, szMsg, svDir, ""); end;

FeatureError
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FeatureError does not return error information for unsupported functions. For example, ComponentInitialize, ComponentUpdate, and ComponentValidate are not supported as feature functions. FeatureError does not work for these functions.

The FeatureError function obtains additional error information when a feature function returns a value less than zero. The following code fragment shows a typical implementation of FeatureError:
nResult = FeatureGetData (MEDIA, svFeature, FEATURE_FIELD_SELECTED, nvResult, svResult); if(nResult < 0) then FeatureError(svFeatureSource, svFeature, svComponent, svFile, nvError); SprintfBox (INFORMATION, "FeatureGetData Error Information", "FeatureGetData had the following error:\n\n" + "Media Name: %s\nFeature: %s\nComponent: %s\n" + "File: %s\nError Number: %ld" svFeatureSource, svFeature, svComponent, svFile, nvError); endif;

The FeatureError function should be called only after another feature function returns a value less than zero. FeatureError might return invalid error codes if called when another feature function has not returned a value that is less than zero.

Note: FeatureError returns information for all parameters (media name, feature name, component name, file name, and error code) only for script-created feature sets. For features in the file media (MEDIA), FeatureError returns only the error code.

Syntax
FeatureError ( svFeatureSource, svFeature, svComponent, svFile, nvError );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

735

Appendix B: Built-In Functions (E-G) FeatureError

Parameters
Table B-44: FeatureError Parameters Parameter svFeatureSource Description Returns the media name of the script-created feature set if relevant to the error indicated by nvError. Returns the name of the feature if relevant to the error indicated by nvError. Returns the name of the component if relevant to the error indicated by nvError. Returns the name of the file if relevant to the error indicated by nvError. Returns a code that identifies the type of error that occurred in a previous call to a feature-related function. These error codes are described below.

svFeature svComponent svFile nvError

Error Codes
The following table describes the error codes returned by FeatureError.

Note: After correcting errors involving the media, you must rebuild the project. Table B-45: FeatureError Error Codes Code -101 Description Cannot add feature. Cause FeatureAddItem was unable to add a feature to the scriptcreated feature set. FeatureAddItem was called twice with the same media name and feature name. FeatureSelectItem was used to select or deselect a feature that is required by a currently selected feature. Deselect the dependent feature (that requires the other feature) before attempting to select or deselect the required feature. An attempt was made to access a feature that does not exist. This error occurs when a feature name is specified incorrectly in a feature function call. Feature names must be specified exactly as they appear in the Setup Design view or in the call to FeatureAddItem. Feature names are case-sensitive. The target disk or directory has insufficient free space, the disk space cannot be determined because TARGETDIR (in an InstallScript installation) or INSTALLDIR (in an InstallScript MSI installation) is invalid, or a script-defined folder of a feature has not been set. A script-created feature set name was passed to a feature function that operates only on file media.

-102

Specified feature already exists.

-103

Specified feature cannot be selected or deselected.

-105

Specified feature cannot be found in the media.

-108

Out of disk space.

-118

Attempted operation not allowed with script-created feature sets.

736

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureError

Table B-45: FeatureError Error Codes (cont.) Code -125 Description The list specified in the feature function is not valid. Attempted operation not allowed with file media library. Cause When calling FeatureListItems, verify that the list you are passing to the function is valid. A file media name was passed to a feature function (for example, FeatureAddItem), that operates only on script-created feature sets. The media has been declared, but it not associated with any features. Make sure that script-created features are associated with the media. Insufficient memory is available to the setup. Display a message to the end user to close all other applications or to cancel the setup, reboot the system, and restart the setup. An invalid option has been specified for a feature functionfor example, specifying only a component when both a component and file name are required. One of the values passed to a feature function is invalid. This error can be caused, for example, by passing an empty string in the second parameter of FeatureAddItem.

-126

-132

The specified media cannot be found.

-136

Unable to allocate memory.

-137

Specified option is not valid.

-147

Invalid value passed to a featurerelated function.

Return Values
Table B-46: FeatureError Return Values Return Value 0 <0 Description FeatureError was successful. FeatureError failed.

FeatureError Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureError function. * * This example script demonstrates a function that adds a feature * to a script-created feature set. * * Comments: To run this example script, create a project (or * insert into a project) with several features and/or * subfeatures with components containing files. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

737

Appendix B: Built-In Functions (E-G) FeatureError

#include "Ifx.h" // Include iswi.h for Windows Installer API function prototypes and constants, // and to declare code for the OnBegin and OnEnd events. #include "iswi.h" // The keyword export identifies MyFunction() as an entry-point function. // The argument it accepts must be a handle to the Installer database. export prototype MyFunction(HWND); prototype HandleMoveDataError(number); // To Do: // Declare global variables, define constants, and prototype userdefined and DLL functions here.

function MyFunction(hMSI) STRING NUMBER begin szTitle = "List MEDIA Features"; szMsg = "MEDIA contains the following top-level features:"; // Initialize the string list. listID = ListCreate (STRINGLIST); // Create a list of top-level features in the specified media. nResult = FeatureListItems (MEDIA, "", listID); // Call the error handler function. HandleMoveDataError (nResult); // Display a list of top-level features. SdShowInfoList (szTitle, szMsg, listID); end; function HandleMoveDataError(nResult) STRING szErrMsg, svFeature , svComponent , svFile; begin svFeature = ""; svComponent = ""; svFile = ""; // In cases where FeatureListItems returns a value not equal to zero, display an // error message. switch (nResult) case 0: return 0; default: FeatureError (MEDIA , svFeature , svComponent , svFile , nResult); szErrMsg = "An error occurred during the process: %d" + "\n\n" + "Feature: " + svFeature + "\n" + "Component: " + svComponent + "\n" + "File: " + svFile; SprintfBox (SEVERE, "", szErrMsg, nResult); return nResult; endswitch;
738 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

szTitle, szMsg; listID, nResult;

Appendix B: Built-In Functions (E-G) FeatureErrorInfo

end;

FeatureErrorInfo
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureErrorInfo function, which is called in the default code for the OnComponentError event handler, returns information about a file transfer error that does not generate any error event other than FeatureErrorfor example, FileLocked or SelfRegistrationError.

Note: This function returns information only about file transfer errors. For information about errors from script-created features, call FeatureError.

Syntax
FeatureErrorInfo ( );

Parameters
None

Return Values
A reference that can be assigned to a variable of type OBJECT by using the set keyword. Upon assignment, that variable (oErrorInfo in the following example) has the following properties:
Table B-47: FeatureErrorInfo Return Values Property oErrorInfo.Feature Description An object whose properties provide information about the feature that was being transferred when the error occurred. If the error is not associated with a particular feature, or the feature cannot be identified, this property is not set; test for this case by checking the value of IsObject (oErrorInfo.Feature). The display name of the feature that was being transferred when the error occurred. If you did not specify a display name for this feature, this string is null (""). The name of the feature that was being transferred when the error occurred. A string describing the file transfer error. This string may be null (""). The numeric code for the file transfer error.

oErrorInfo.Feature.DisplayName

oErrorInfo.Feature.Name oErrorInfo.Feature.Description oErrorInfo.LastError

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

739

Appendix B: Built-In Functions (E-G) FeatureErrorInfo

FeatureErrorInfo Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureError function. * * This example script demonstrates a function that adds a feature * to a script-created feature set. * * Comments: To run this example script, create a project (or * insert into a project) with several features and/or * subfeatures with components containing files. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" // Include iswi.h for Windows Installer API function prototypes and constants, // and to declare code for the OnBegin and OnEnd events. #include "iswi.h" // The keyword export identifies MyFunction() as an entry-point function. // The argument it accepts must be a handle to the Installer database. export prototype MyFunction(HWND); prototype HandleMoveDataError(number); // To Do: // Declare global variables, define constants, and prototype userdefined and DLL functions here.

function MyFunction(hMSI) STRING NUMBER begin szTitle = "List MEDIA Features"; szMsg = "MEDIA contains the following top-level features:"; // Initialize the string list. listID = ListCreate (STRINGLIST); // Create a list of top-level features in the specified media. nResult = FeatureListItems (MEDIA, "", listID); // Call the error handler function. HandleMoveDataError (nResult); // Display a list of top-level features. SdShowInfoList (szTitle, szMsg, listID); end; function HandleMoveDataError(nResult) STRING szErrMsg, svFeature , svComponent , svFile; begin
740 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

szTitle, szMsg; listID, nResult;

Appendix B: Built-In Functions (E-G) FeatureFileEnum

svFeature = ""; svComponent = ""; svFile = ""; // In cases where FeatureListItems returns a value not equal to zero, display an // error message. switch (nResult) case 0: return 0; default: FeatureError (MEDIA , svFeature , svComponent , svFile , nResult); szErrMsg = "An error occurred during the process: %d" + "\n\n" + "Feature: " + svFeature + "\n" + "Component: " + svComponent + "\n" + "File: " + svFile; SprintfBox (SEVERE, "", szErrMsg, nResult); return nResult; endswitch; end;

FeatureFileEnum
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureFileEnum function builds a list of the files in a component associated with the specified feature or a list of the components associated with a particular feature.

Note: This function cannot be used with script-created feature sets.

Syntax
FeatureFileEnum ( szFeatureSource, szFeature, szQuery, listFilesorComponents, nOption );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

741

Appendix B: Built-In Functions (E-G) FeatureFileEnum

Parameters
Table B-48: FeatureFileEnum Parameters Parameter szFeatureSource szFeature Description Pass MEDIA in this parameter. Specifies the name of the feature to be enumerated. Do not pass a null string ("") in this parameter. FeatureFileEnum requires a specific feature name. To query the components in a particular feature, specify a component specification (same format as a file specification). Delimit the component specification with double backslashes and enclose the expression in double quotation marks. The component specification can include wild-card characters: an asterisk (*) as a substitute for zero or more characters, or a question mark (?) as a substitute for a single character. The following example specifies all of the components in the feature specified in szFeature:
"*.*"

szQuery

To query the files in a particular component, specify a component name and a file specification. Delimit the component name and the file specification with double backslashes and enclose the expression in double quotation marks. You can also specify only a file specification. The file name part of the file specification may include wild-card characters. The following example specifies all of the files in the component Graphic_Examples:
"Graphic_Examples\\*.*"

Note: There are limitations when using this functionality in InstallScript MSI installations (both when querying components and files), because complex wild-card expressions are not supported. When querying files, you must specify one of the following as szQuery: listFilesOrComponents <Component Name>\*.* <Component Name>\<Complete File Name> <Component Name>\*.<Extension> <Component Name>\<File Name>.* *.* <Complete Component>

When querying components, you must specify one of the following as szQuery:

When querying components, returns a list of the components that match szQuery. When querying files, returns a list of the names of all files that match szQuery. The string list identified by listFilesOrComponents must already have been initialized by a call to ListCreate. Pass NO_SUBDIR in this parameter. Note that nOptions is ignored when querying the list of components.

nOption

742

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFileEnum

Return Values
Table B-49: FeatureFileEnum Return Values Return Value 0 <0 Description FeatureFileEnum was successful. FeatureFileEnum failed.

FeatureFileEnum Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureFileEnum function. * * Notes: To run this example script, create a project with the * following features (f), subfeatures (sf), and * components (c): * * (f) Program_Files * (c) Program_DLLS * (c) Program_EXEs * (f) Example_Files * (sf) Graphics * (c) Graphic_Examples * * Be sure to assign files to the components so there * is something to enumerate. * \*--------------------------------------------------------------*/ #define #define #define #define #define #define FEAT1 FEAT2 SUBFEAT1 EXECCOMP GRAPHCOMP SDSHOWTITLE "Program Files" "Example Files" "Graphics" "Program Executable Files" "Graphic Examples" "FeatureFileEnum Results" FEAT1 + " enumerated files:" FEAT2 + " enumerated files:"

#define SDSHOWMSG1 #define SDSHOWMSG2

prototype HandleFeatureError (NUMBER); NUMBER nResult; LIST listList1, listList2; program // Create two lists to store file names. listList1 = ListCreate (STRINGLIST); listList2 = ListCreate (STRINGLIST); // Build a list of the program files. nResult = FeatureFileEnum (MEDIA, FEAT1, EXECCOMP + "\\*.*", listList1, INCLUDE_SUBDIR);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

743

Appendix B: Built-In Functions (E-G) FeatureFileEnum

HandleFeatureError (nResult); // Build a list of the graphic files. nResult = FeatureFileEnum (MEDIA, FEAT2 + "\\" + SUBFEAT1, GRAPHCOMP+"\\*.*", listList2, INCLUDE_SUBDIR); HandleFeatureError (nResult); // Display the program files. SdShowInfoList (SDSHOWTITLE, SDSHOWMSG1, listList1); // Display the graphic files. SdShowInfoList (SDSHOWTITLE, SDSHOWMSG2, listList2); // Release the lists from memory. ListDestroy (listList1); ListDestroy (listList2); endprogram /*--------------------------------------------------------------------------*\ * * Function: HandleFeatureError * * Purpose: This function evaluates the value returned by a feature * function and if the value is less than zero, displays the error * number and aborts the setup. * \*--------------------------------------------------------------------------*/ function HandleFeatureError( nResult ) NUMBER STRING nvError; svFeatureSource, svFeature, svComponent, svFile;

begin if (nResult < 0) then FeatureError (svFeatureSource, svFeature, svComponent, svFile, nvError); SprintfBox (INFORMATION, "Data Transfer Error Information", "FeatureError returned the following data transfer error.\n" + "Setup will now abort.\n\n" + "Media Name: %s\nFeature: %s\nComponent: %s\n" + "File: %s\nError Number: %ld", svFeatureSource, svFeature, svComponent, svFile, nvError); abort; endif; end;

744

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFileInfo

FeatureFileInfo
Project: This information applies to the following project types:

InstallScript InstallScript MSI

Note that this function does not work with files in InstallScript Object projects.

The FeatureFileInfo retrieves information on a file in the file media that is referenced by szFeatureSource (MEDIA).

Note: This function cannot be used with script-created features.

Syntax
FeatureFileInfo ( szFeatureSource, szFeature, szFile, nInfo, nvResult, svResult );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

745

Appendix B: Built-In Functions (E-G) FeatureFileInfo

Parameters
Table B-50: FeatureFileInfo Parameters Parameter szFeatureSource szFeature szFile Description Pass MEDIA in this parameter. Specifies the feature containing the component in which the file is found. Specifies the component and the file name, with or without a path. Delimit tokens in the szFile expression with double backslashes and enclose the expression in double quotation marks.

If there are two tokens in szFile, the first is the component name and the second is the file name:

component\\file name

If there are more than two tokens in szFile, the first is the component name, the last is the file name, and the middle tokens form the path:

"component\\path\\file name"

For example:

"Shared_Files\\Is5.dll"Shared_Files is a component and Is5.dll is a file name. "Shared_Files\\dev\\myapp\\dlls\\Is5.dll"Shared_Files is a component, \\dev\\myapp\\dlls is a path, and Is5.dll is a file name.

Note: InstallShield lets you add entire file and folder structures to your components by dragging and dropping them in the Files view.

746

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFileInfo

Table B-50: FeatureFileInfo Parameters (cont.) Parameter nInfo Description Specifies the type of information to be retrieved. Pass a constant in this parameter. The available constants apply to either a specified component, or a specified file in a component. The available file-specific constants are:

FEATURE_INFO_ATTRIBUTEAttribute values for the specified file. For more information about the File table attributes that are returned, see the Windows Installer Help. Only InstallScript MSI projects support this constant; InstallScript projects do not support it. FEATURE_INFO_DATEDate value for the specified file in the format mm-ddyy. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. If this constant is used with FeatureFileInfo in an InstallScript MSI installation, the function returns failure. FEATURE_INFO_DATE_EXDate value for the specified file in the 2000compliant format mm-dd-yyyy. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. If this constant is used with FeatureFileInfo in an InstallScript MSI installation, the function returns failure. FEATURE_INFO_TIMETime value for the specified file in the format hh:mm, using 24-hour time. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. If this constant is used with FeatureFileInfo in an InstallScript MSI installation, the function returns failure. FEATURE_INFO_VERSIONLSThe minor version number or numbers in string form. FEATURE_INFO_VERSIONMSThe major version number or numbers in string form. FEATURE_INFO_VERSIONSTRThe entire version number in string form. FEATURE_INFO_MD5_SIGNATUREReturns the MD5 signature of the file specified by szFile. Note that this information is generated during the media build, so calling this function with this parameter does not cause the MD5 signature to be generated.

Note: Raw MD5 signature data for a particular file consists of 16 generated numeric values of 16 bit each (between 0x00 and 0xFF). These values are usually stored in a string of unsigned characters. However, the InstallScript language does not support unsigned characters, so instead of returning the raw MD5 file data, each of the 16 numeric values are converted to their string equivalent and placed in the resulting string. This results in a string of 32 characters, where each set of two characters represent a single numeric value. This is sometimes referred to as a MD5 hex string.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

747

Appendix B: Built-In Functions (E-G) FeatureFileInfo

Table B-50: FeatureFileInfo Parameters (cont.) Parameter nInfo (cont.) Description

FEATURE_INFO_ORIGSIZE_HIGHReturns the upper 31 bits of size of the original file. If the original size of the file is more than 2 GB, the size of the file is equal to the value returned for FEATURE_INFO_ORIGSIZE_HIGH multiplied by 2 GB added to the value returned for FEATURE_INFO_ORIGSIZE_LOW. Only InstallScript installations support this constant. FEATURE_INFO_ORIGSIZE_LOWReturns the lower 31 bits of size of the original file. If the original size of the file is more than 2 GB, the size of the file is equal to the value returned for FEATURE_INFO_ORIGSIZE_HIGH multiplied by 2 GB added to the value returned for FEATURE_INFO_ORIGSIZE_LOW. FEATURE_INFO_COMPSIZE_LOWReturns the lower 31 bits of size of the compressed file. If the compressed size of the file is more than 2 GB, the size of the file is equal to the value returned for FEATURE_INFO_COMPSIZE_HIGH multiplied by 2 GB added to the value returned for FEATURE_INFO_COMPSIZE_LOW. FEATURE_INFO_COMPSIZE_HIGHReturns the upper 31 bits of size of the compressed file. If the original size of the file is more than 2 GB, the size of the file is equal to the value returned for FEATURE_INFO_ORIGSIZE_HIGH multiplied by 2 GB added to the value returned for FEATURE_INFO_ORIGSIZE_LOW. Only InstallScript installations support this constant.

Note: You can use the ConvertSizeToUnits function to convert these values into a single value of KBYTES, MBYTES, GBYTES, or TBYTES.

748

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFileInfo

Table B-50: FeatureFileInfo Parameters (cont.) Parameter nInfo (cont.) Description The available component-specific constants are:

FEATURE_INFO_COMPONENT_FLAGSGeneral flags that are set for the specified component. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. FEATURE_INFO_DESTINATIONDestination setting for the component. Note that any text substitutions that are included in the destination are not resolved in the returned string. To determine the component's destination with any text substitutions resolved, call TextSubSubstitute on the returned string. FEATURE_INFO_DOTNET.NET flags that are selected for the specified component. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. FEATURE_INFO_FTPLOCATIONFTP Location setting for the specified component. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. FEATURE_INFO_HTTPLOCATIONHTTP Location setting for the specified component. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. FEATURE_INFO_LANGUAGELanguages setting for the specified component. Because this applies only to a component, szFile must be a single token expression identifying a component. FEATURE_INFO_MISCMiscellaneous setting for the specified component. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. FEATURE_INFO_OSOperating System setting for the specified component. Because this applies only to a component, szFile must be a single token expression that identifies a component. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. FEATURE_INFO_OVERWRITEOverwrite flags that are set for the specified component. Only InstallScript projects support this constant; InstallScript MSI projects do not support it. FEATURE_INFO_PLATFORM_SUITEPlatform Suites setting for the specified component. Because this applies only to a component, szFile must be a single token expression that identifies a component. Only InstallScript projects support this constant; InstallScript MSI projects do not support it.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

749

Appendix B: Built-In Functions (E-G) FeatureFileInfo

Table B-50: FeatureFileInfo Parameters (cont.) Parameter nvResult Description Specifies information that is dependent on the constant that is passed in nInfo. When nInfo is FEATURE_INFO_ORIGSIZE_HIGH, FEATURE_INFO_ORIGSIZE_LOW, or FEATURE_INFO_ATTRIBUTE, nvResult returns a number value. When nInfo is FEATURE_INFO_ATTRIBUTE, nvResult returns a numeric value that represents the file attributes from the Windows Installer File table. To determine the file attribute settings, use file attribute constants in bitwise OR operations with nvResult. For an example of how to test nvResult, see FeatureFileInfo Example. For more information about the File table attributes, see the Windows Installer Help. When nInfo is FEATURE_INFO_LANGUAGE or FEATURE_INFO_OS, the parameter position occupied by nvResult must specify a LIST variable to store the language or operating system IDs. You must call ListCreate with the constant NUMBERLIST to create the list before you call FeatureFileInfo to determine which languages or operating systems are specified by the component:
listID = ListCreate(NUMBERLIST); FeatureFileInfo(szFeatureSource, szFeature, szFile, FEATURE_INFO_LANGUAGE, listID, svResult);

When nInfo is FEATURE_INFO_LANGUAGE, FeatureFileInfo adds language IDs to the list; when nInfo is FEATURE_INFO_OS, FeatureFileInfo adds operating system IDs to the list. When ninfo is FEATURE_INFO_COMPONENT_FLAGS, nvResult returns one or more of the following values:

FEATURE_INFO_COMPONENT_FLAG_COMPRESSEDThe components Compressed setting is Yes. FEATURE_INFO_COMPONENT_FLAG_DATAASFILESThe components files are placed in a particular folder for a CD-ROM type of release. (This is determined by the CD-ROM Folder setting for the feature that contains the component.) Only InstallScript projects support this constant; InstallScript MSI projects do not support it. FEATURE_INFO_COMPONENT_FLAG_DONTUNINSTALLThe components Uninstall setting is No. FEATURE_INFO_COMPONENT_FLAG_ENCRYPTEDThe component is encrypted. (This is determined by whether the feature that includes the component has Yes selected for its Encryption setting.) FEATURE_INFO_COMPONENT_FLAG_POTENTIALLYLOCKEDThe components Potentially Locked setting is Yes. FEATURE_INFO_COMPONENT_FLAG_SELFREGISTERINGThe components Self-Register setting is Yes. FEATURE_INFO_COMPONENT_FLAG_SHAREDThe components Shared setting is Yes.

750

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFileInfo

Table B-50: FeatureFileInfo Parameters (cont.) Parameter nvResult (cont.) Description When ninfo is FEATURE_INFO_OVERWRITE, nvResult returns one or more of the following values:

FEATURE_VALUE_ALWAYSThe components Overwrite setting is Always. FEATURE_VALUE_DATE_NEWERThe components Overwrite setting is Newer Date. FEATURE_VALUE_DATE_OLDERThe components Overwrite setting is Older Date. FEATURE_VALUE_DATE_SAMEThe components Overwrite setting is Same or Newer Date. FEATURE_VALUE_NEVERThe components Overwrite setting is Never. FEATURE_VALUE_VERSION_NEWERThe components Overwrite setting is Newer Version. FEATURE_VALUE_VERSION_OLDERThe components Overwrite setting is Older Version. FEATURE_VALUE_VERSION_SAMEThe components Overwrite setting is Same or Newer Version.

Note that nvResult could contain both date and version values. When ninfo is FEATURE_INFO_DOTNET, nvResult may return the following value: FEATURE_VALUE_LOCAL_ASSEMBLYThe component is marked as a local assembly. svResult Returns the date, time, or version when nInfo specifies a corresponding information type.

Return Values
Table B-51: FeatureFileInfo Return Values Return Value 0 <0 Description FeatureFileInfo was successful. FeatureFileInfo failed.

FeatureFileInfo Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureFileInfo function. * * This script calls FeatureFileInfo repeatedly to retrieve * information about the file media. The information is stored * in a list and then displayed. *
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 751

Appendix B: Built-In Functions (E-G) FeatureFileInfo

* Note: To run this example script, create a project with the * following features (f), subfeatures (sf), and * components (c): * * (f) Example_Files * (sf) Graphics * (c) Graphic_Examples * * Be sure to assign at least one file to the Graphic_Examples * component so there is something to enumerate. * Also, remember to specify the file name in the #define * FILE line. * \*--------------------------------------------------------------*/ #define #define #define #define #define #define FEAT "Example Files" SUBFEAT "Graphics" COMP "Graphic Examples" FILE "comdlg32.dll" SDSHOWTITLE "ComponentFileInfo Results" SDSHOWMSG FILE + " information:"

prototype HandleFeatureError (NUMBER); NUMBER nReturn, nvResult; STRING svResult; LIST listID; program // Create a list to store file media information. listID = ListCreate (STRINGLIST); // Get the original size of the specified file. nReturn = FeatureFileInfo (MEDIA, FEAT + "\\" + SUBFEAT, COMP + "\\" + FILE, FEATURE_INFO_ORIGSIZE , nvResult, svResult); HandleFeatureError (nvResult); // Convert the original size to a string. Sprintf (svResult ,"%d", nvResult); // Add the string to the list. ListAddString (listID, "The Original size of the file is svResult, AFTER);

" +

// Get the attributes of the specified file. nReturn = FeatureFileInfo (MEDIA, FEAT + "\\" + SUBFEAT, COMP + "\\" + FILE, FEATURE_INFO_ATTRIBUTE , nvResult, svResult); HandleFeatureError (nReturn); // If no attributes are set, indicate normal attributes. if (nvResult = FILE_ATTR_NORMAL) then svResult = "normal"; // If attributes are set, concatenate them for display. else if (FILE_ATTR_ARCHIVED & nvResult) then
752 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFileInfo

svResult = "archived,"; endif; if (FILE_ATTR_HIDDEN & nvResult) then svResult = svResult + "hidden,"; endif; if (FILE_ATTR_READONLY & nvResult) then svResult = svResult + "read-only,"; endif; if (FILE_ATTR_SYSTEM & nvResult) then svResult = svResult + "system,"; endif; if (FILE_ATTR_DIRECTORY & nvResult) then svResult = svResult + "directory,"; endif; endif; // Add the string of attributes to the list. ListAddString (listID, "The attribute for the file is svResult, AFTER);

" +

// Get the major file version of the specified file. nReturn = FeatureFileInfo (MEDIA, FEAT + "\\" + SUBFEAT, COMP + "\\" + FILE, FEATURE_INFO_VERSIONMS , nvResult, svResult); HandleFeatureError (nReturn); // Add the major file version to the list. ListAddString (listID, "The upper 32-bit version value svResult, AFTER);

" +

// Get the minor file version of the specified file. nReturn = FeatureFileInfo (MEDIA, FEAT + "\\" + SUBFEAT, COMP + "\\" + FILE, FEATURE_INFO_VERSIONLS , nvResult, svResult); HandleFeatureError (nReturn); // Add the minor file version to the list. ListAddString (listID, "The lower 32-bit version value is svResult, AFTER); " +

// Get the complete file version of the specified file. nReturn = FeatureFileInfo (MEDIA, FEAT + "\\" + SUBFEAT, COMP + "\\" + FILE, FEATURE_INFO_VERSIONSTR , nvResult, svResult); HandleFeatureError (nReturn); // Add the complete file version to the list. ListAddString (listID, "The version for the file is svResult, AFTER); // Display the list. SdShowInfoList (SDSHOWTITLE, SDSHOWMSG, listID);

" +

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

753

Appendix B: Built-In Functions (E-G) FeatureFilterLanguage

// Release the list from memory. ListDestroy(listID); endprogram /*--------------------------------------------------------------------------*\ * * Function: HandleFeatureError * * Purpose: This function evaluates the value returned by a feature * function and if the value is less than zero, displays the error * number and aborts the setup. * \*--------------------------------------------------------------------------*/ function HandleFeatureError (nvResult) NUMBER STRING nvError; svFeatureSource, svFeature, svComponent, svFile;

begin if (nvResult < 0) then FeatureError(svFeatureSource, svFeature, svComponent, svFile, nvError); SprintfBox(INFORMATION, "Data Transfer Error Information", "FeatureError returned the following data transfer error.\n" + "Setup will now abort.\n\n" + "Media Name: %s\nFeature: %s\nComponent: %s\n" + "File: %s\nError Number: %ld", svFeatureSource, svFeature, svComponent, svFile, nvError); abort; endif; end;

FeatureFilterLanguage
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureFilterLanguage function filters (excludes) files from file transfer based on language. By default, all languages included in the media build are unfiltered (included). You must call FeatureFilterLanguage for each language you wish to filter or unfilter.

Note: This function cannot be used with script-created feature sets.

754

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFilterLanguage

Filtering Language-Specific Components

Task

To filter language-specific components during the installation:

1.
2.

Filter (exclude) all languages by calling FeatureFilterLanguage with ISLANG_ALL in the parameter nLangID and bFiltered set to TRUE. For each language that you want to install, call FeatureFilterLanguage with the appropriate language constant in nLangID and with the parameter bFiltered parameter set to FALSE. Each call unfilters (includes) components for the language specified in nLangID.

Note: You cannot specify multiple language constants in the nLangID parameter by using the OR operator ( | ). Specifying multiple language constants causes the function to perform incorrectly.

Supporting Different Languages

InstallShield allows you to designate components for any language or language subgroup that is supported by Windows. However, in order for the Release Wizard to build a language-specific component, you must have support for the language of that component. Your setup must also support the language of the component. If your setup includes language-specific components that are designated as specific to a language not supported by InstallShield or by your setup, the components are filtered (not included) by the Release Wizard.

Using FeatureFilterLanguage With GetSystemInfo

When using FeatureFilterLanguage in conjunction with the GetSystemInfo function, you must consider the following: The language constants that can be used to designate language-specific components are a small subset of the language constants that can be returned by GetSystemInfo. If your setup includes language filtering based on these return values, you must use a switch statement to convert constants returned by this function into one of the constants supported for language filtering.

Syntax
FeatureFilterLanguage ( szFeatureSource, nLangID, bFiltered );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

755

Appendix B: Built-In Functions (E-G) FeatureFilterLanguage

Parameters
Table B-52: FeatureFilterLanguage Parameters Parameter szFeatureSource nLangID Description Specifies the media name of the file media. Specifies the ID of the language to filter or unfilter. Only one language constant can be specified for each function call. To filter all languages, pass ISLANG_ALL in this parameter. See Language IDs to learn more. Indicates whether to filter (exclude) or unfilter (include) the language specified in nLangID. Pass one of the following predefined constants in this parameter:

bFiltered

TRUEFilter the language specified in nLangIDdo not include it in the file transfer. FALSEDo not filter the language specified in nLangIDinclude it in the file transfer.

Return Values
Table B-53: FeatureFilterLanguage Return Values Return Value 0 <0 Description FeatureFilterLanguage was successful. FeatureFilterLanguage failed.

FeatureFilterLanguage Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureFilterLanguage function. * * First, FeatureFilterLanguage is called to exclude all * languages. Next, GetSystemInfo is called to determine the * target computer's default language/locale. * * Then, FeatureFilterLanguage is called again to include the * language appropriate for the target computer. If language * support is not provided for the target computer, English is * used. Finally, the FeatureMoveData is called to create the * installation. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FeatureFilterLanguage(HWND);

756

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFilterOS

function ExFn_FeatureFilterLanguage(hMSI) STRING szResult; NUMBER nResult, nDisk; begin // Filter out all language-specific file groups. FeatureFilterLanguage (MEDIA, ISLANG_ALL, TRUE); // Retrieve the target machine's default language/locale setting. GetSystemInfo (LANGUAGE, nResult, szResult); // Turn off filtering for file groups specific to the target // machine's default language/locale setting. switch (nResult) case ISLANG_FRENCH_CANADIAN: FeatureFilterLanguage (MEDIA, ISLANG_FRENCH_CANADIAN, FALSE); case ISLANG_FRENCH_STANDARD, ISLANG_FRENCH_BELGIAN, ISLANG_FRENCH_SWISS, ISLANG_FRENCH_LUXEMBOURG: FeatureFilterLanguage (MEDIA, ISLANG_FRENCH_STANDARD, FALSE ); case ISLANG_GERMAN_STANDARD, ISLANG_GERMAN_SWISS, ISLANG_GERMAN_AUSTRIAN, ISLANG_GERMAN_LUXEMBOURG, ISLANG_GERMAN_LIECHTENSTEIN: FeatureFilterLanguage (MEDIA, ISLANG_GERMAN, FALSE); // Use English as a default. default: FeatureFilterLanguage (MEDIA, ISLANG_ENGLISH, FALSE); endswitch; // Transfer files for selected language. FeatureMoveData (MEDIA, nDisk, 0); end;

FeatureFilterOS
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureFilterOS function filters components that are flagged for specified operating systems and suites.

Note: This function cannot be used with script-created feature sets.

Any filtering that is done when the installation is first run must also be done during maintenance mode. Be sure to call this function in code that is executed during both initial and maintenance installations. Do not call this function from the following event handlers: OnAppSearch, OnCCPSearch, OnFirstUIBefore, OnFirstUIAfter, OnMaintUIBefore, or OnMaintUIAfter.

Project: Components are not filtered by default in an InstallScript MSI installation.

InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 757

Appendix B: Built-In Functions (E-G) FeatureFilterOS

In an InstallScript installation, FeatureFilterOS is called by the default OnFilterComponents event handler during both initial and maintenance installations. This event handler filters components by default that are specific to operating systems and suites other than those on the target system. An installation that is run in maintenance mode has no information about the filtering that was done during the initial installation.

Syntax
FeatureFilterOS ( szMediaLibrary, nSuites, nOS, bFiltered );

758

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFilterOS

Parameters
Table B-54: FeatureFilterOS Parameters Parameter szMediaLibrary nSuites Description Specifies the media name of the file media library. Specifies the operating system suite or suites that you want to filter. Choose from the following values. You can combine values using the bitwise OR operator ( | ).

Note: The suites listed here are those that can be specified in the Windows API's OSVERSIONINFOEX data structure.

ISOS_ST_ALLAll Windows suites ISOS_ST_XP_PROWindows XP Professional ISOS_ST_XP_HOMEWindows XP Home Edition ISOS_ST_SERVERWindows Server ISOS_ST_WORKSTATIONWindows Workstation ISOS_ST_BACKOFFICEMicrosoft BackOffice ISOS_ST_DATACENTERWindows Server Datacenter ISOS_ST_ENTERPRISEWindows Server Enterprise ISOS_ST_SERVER2003_R2Microsoft Windows Server 2003 R2 ISOS_ST_SMALLBUSINESSMicrosoft Small Business Server ISOS_ST_SMALLBUSINESS_RESTRICEDMicrosoft Small Business Server with the restrictive client license ISOS_ST_TERMINALMicrosoft Terminal Services ISOS_ST_PROC_ARCH_3232-bit Processors ISOS_ST_PROC_ARCH_IA64Intel Itanium 64-bit Processor ISOS_ST_PROC_ARCH_AMD64AMD Athalon 64-bit Processor 0 (zero)Specifies that FeatureFilterOS ignores components' Platform Suite properties

Project: InstallScript MSI projects do not have support for platform suites. Therefore, in an InstallScript MSI project, you must specify the number 0 for nSuites. Otherwise, the function fails and the information that is specified in nOS is ignored.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

759

Appendix B: Built-In Functions (E-G) FeatureFilterOS

Table B-54: FeatureFilterOS Parameters (cont.) Parameter nOS Description Specifies the operating system or operating systems that you wish to filter. Choose from the following values. You can combine values using the bitwise OR operator ( | ).

ISOSL_ALLAll Windows systems ISOSL_WIN2000Windows 2000 ISOSL_WINXPWindows XP Edition ISOSL_WINSERVER2003Windows Server 2003 ISOSL_WINVISTA_SERVER2008 (or ISOSL_WINVISTA)Windows Vista or Windows Server 2008 ISOSL_WIN7_SERVER2008R2Windows 7 or Windows Server 2008 R2

Note: Windows Vista and Windows Server 2008 have the same major and minor version numbers. Therefore, the installation considers Windows Server 2008 to be the same as Windows Vista; thus, components that are marked for Windows Vista are also installed on Windows Server 2008. bFiltered Specifies whether to filter (exclude) or unfilter (include) the operating systems specified in nOS. Pass one of the following predefined constants in this parameter:

TRUEFilter the specified operating systemdo not include them in the file transfer. FALSEDo not filter the specified operating systeminclude them in the file transfer.

Return Values
Table B-55: FeatureFilterOS Return Values Return Value 0 <0 Description FeatureFilterOS was successful. FeatureFilterOS failed. Call FeatureError for additional information.

Additional Information
While both ISOSL_ALL and ISOSL_SUPPORTED specify all Windows systems when passed as the third argument to FeatureFilterOS, they have different numeric values. ISOSL_ALL is zero (0) and ISOSL_SUPPORTED is the value obtained by combining every operating system constant using the bitwise OR operator, that is, ISOSL_WIN7_SERVER2008R2 | ISOSL_WINVISTA_SERVER2008 | ... . In some cases, you may find it useful to perform bitwise operations on ISOSL_SUPPORTED and other operating system constants.

FeatureFilterOS Example
/*--------------------------------------------------------------*\ *
760 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureFilterOS

* InstallShield Example Script * * Demonstrates the FeatureFilterOS function. * * To run this script, create a blank setup project. * Specify Windows 95, Windows 98, and Windows NT 4.0 * (Intel) for operating systems in the Components view. * Use release flags to specify which platforms to include * in the build. Specify Windows 95, Windows 98, and Windows * NT 4.0 (Intel). When you run the Release Wizard, enter the * release flags in the Filtering Settings panel. * \*--------------------------------------------------------------*/ // You can convert the following define statements into string // entries to localize your setup. #define COMPANY_NAME "MultiLangOS Inc." #define PRODUCT_NAME "MultiLangOS" #define PRODUCT_VERSION "1.0" #define PROGRAMFOLDER "MultiLangOS" #define PRODUCT_KEY "Mlangos.exe" #define DEINST_KEY "MultiLangOS" #define ASKDESTTITLE "Destination Location" #define ASKDESTMSG "Select a destination location." #define COMPERRTITLE "Data Transfer Error Information" #define COMPERRMSG1 "FeatureError returned the following error." #define COMPERRMSG2 "Setup will now abort." #define COMPERRMSG3 "Media Name:" #define COMPERRMSG4 "Feature:" #define COMPERRMSG5 "Component:" #define COMPERRMSG6 "File:" #define COMPERRMSG7 "Error Number:" prototype HandleFeatureError (NUMBER); // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FeatureFilterOS(HWND); function ExFn_FeatureFilterOS(hMSI) STRING svResult, svDir, svLogFile; NUMBER nvResult, nvDisk; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up uninstallation and get destination location. InstallationInfo(COMPANY_NAME, PRODUCT_NAME, PRODUCT_VERSION, PRODUCT_KEY); INSTALLDIR = PROGRAMFILES ^ PROGRAMFOLDER; AskDestPath (ASKDESTTITLE, ASKDESTMSG, INSTALLDIR , 0 ); DeinstallStart (INSTALLDIR, svLogFile, DEINST_KEY, 0); RegDBSetItem (REGDB_UNINSTALL_NAME, DEINST_KEY); // Get the operating system and call FeatureFilterOS // to filter the operating systems that are not present. GetSystemInfo (OS, nvResult, svResult);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 761

Appendix B: Built-In Functions (E-G) FeatureFilterOS

switch (nvResult) case IS_WINDOWSNT: GetSystemInfo (WINMAJOR, nvResult, svResult); if (nvResult = 4) then // It's NT 4.0, so filter Windows 95 and Windows 98. FeatureFilterOS (MEDIA, 0, ISOSL_WIN95, TRUE); FeatureFilterOS (MEDIA, 0, ISOSL_WIN98, TRUE); else MessageBox ("Target system OS not supported.", SEVERE); abort; endif; case IS_WINDOWS9X: // It's Windows 95 or 98, so filter Windows NT 4.0. FeatureFilterOS (MEDIA, 0, ISOSL_NT40, TRUE); // Determine if it's Windows 95 or Windows 98. GetSystemInfo (WINMINOR, nvResult, svResult); if (nvResult < 10) then // It's Windows 95, so filter Windows 98 too. FeatureFilterOS (MEDIA, 0, ISOSL_WIN98, TRUE); else // It's Windows 98, so filter Windows 95 too. FeatureFilterOS (MEDIA, 0, ISOSL_WIN95, TRUE); endif; default: MessageBox ("Target system OS not supported.", SEVERE); abort; endswitch; // Transfer files to target system. nvResult = FeatureMoveData (MEDIA, nvDisk, 0); if (nvResult < 0) then HandleFeatureError (nvResult); endif; end; /*--------------------------------------------------------------------------*\ * * Function: HandleFeatureError * * Purpose: This function evaluates the value returned by a feature * function and if the value is less than zero, displays the error * number and aborts the setup. * \*--------------------------------------------------------------------------*/ function HandleFeatureError( nResult ) NUMBER nvError; STRING svFeatureSource, svFeature, svComponent, svFile; begin FeatureError (svFeatureSource, svFeature, svComponent, svFile, nvError); SprintfBox(INFORMATION, FEATERRTITLE, FEATERRMSG1 + "\n" + FEATERRMSG2 + "\n\n" + FEATERRMSG3 + " %s\n" + FEATERRMSG4 + " %s\n" + FEATERRMSG5 + " %s\n" + FEATERRMSG6 + " %s\n" + FEATERRMSG7 + " %ld", svFeatureSource, svFeature, svComponent, svFile, nvError); abort; end;
762 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureGetCost

FeatureGetCost
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureGetCost function is obsolete. Use the FeatureGetCostEx function instead. The FeatureGetCost function determines the total space, in kilobytes (KB), required on the target drive for the feature that is specified by szFeature. When determining required drive space, this function takes into account whether the feature is currently selected, whether any components associated with the feature are currently filtered by operating system or language, and the cluster size on the target drive.

Syntax
FeatureGetCost ( szFeatureSource, szFeature, szTargetDir, nvRequiredSpace );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

763

Appendix B: Built-In Functions (E-G) FeatureGetCost

Parameters
Table B-56: FeatureGetCost Parameters Parameter szFeatureSource Description Specifies the media name of the file media whose features have been specified for installation and uninstallation. Typically, you would pass the system variable MEDIA in this parameter. Specifies the feature for which you want to determine the total space that is required on the target drive. Specifies the drive that is used, or the path whose drive is used, in determining required drive space. Typically, you would pass the system variable TARGETDIR in this parameter. Returns the required drive space, in KB.

szFeature

szTargetDir

nvRequiredSpace

Return Values
Table B-57: FeatureGetCost Return Values Return Value 0 <0 Description Indicates that the function successfully determined the required drive space. Indicates that the function could not determine the required drive space. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

FeatureGetCost Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureGetCost function. * * This example script displays a dialog that shows the user * the size of each top-level feature that they selected. * * Comments: To run this example script, create a project (or * insert into a project) with several features * and/or subfeatures with components containing * files. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() string svDir, svFeature, svFeatureInfo; LIST listFeatures, listFeatureInfo; number nListGetString, nvRequiredSpace;
764 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureGetCostEx

begin svDir = TARGETDIR; SdFeatureTree ("", "", svDir, "", 1); listFeatures = ListCreate ( STRINGLIST ); FeatureListItems ( MEDIA, "", listFeatures ); nListGetString = ListGetFirstString ( listFeatures, svFeature ); listFeatureInfo = ListCreate ( STRINGLIST ); while nListGetString=0 FeatureGetCost ( MEDIA, svFeature, svDir, nvRequiredSpace ); Sprintf ( svFeatureInfo, "Selected feature %s has a size of %ld KB.\n", svFeature, nvRequiredSpace ); ListAddString ( listFeatureInfo, svFeatureInfo, AFTER ); nListGetString = ListGetNextString ( listFeatures, svFeature ); endwhile; ListDestroy ( listFeatures ); SdShowInfoList ( "", "", listFeatureInfo ); ListDestroy ( listFeatureInfo ); end;

FeatureGetCostEx
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureGetCostEx function returns the cost of the specified feature (in bytes) using the nvCostHigh and nvCostLow parameters. If szFeature is "", the cost of the entire media is returned. This function replaces the FeatureGetCost and FeatureGetTotalCost functions.

Syntax
FeatureGetCostEx ( szMediaSource, szFeature, szTarget, nvCostHigh, nvCostLow );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

765

Appendix B: Built-In Functions (E-G) FeatureGetData

Parameters
Table B-58: FeatureGetCostEx Parameters Parameter szMediaSource szFeature Description The media source, typically MEDIA. Specifies the feature to get the cost of. If this value is "", the function returns the cost of the entire media. Specifies the target directory for the feature specified by szFeature. Returns the upper 31 bits of the cost of the feature. Each cost unit returned represents 2GB of cost. For example, a value of 4 for this variable represents a cost of 8GB. Returns the lower 31 bits of the cost of the feature. The maximum value for this variable is 1 or 2GB of cost. Any cost greater than this is returned in the nvCostHigh variable.

szTarget nvCostHigh

nvCostLow

Return Values
Table B-59: FeatureGetCostEx Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

FeatureGetData
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureGetData function retrieves information about a feature.

Syntax
FeatureGetData ( szFeatureSource, szFeature, nInfo, nvResult, svResult );

766

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureGetData

Parameters
Table B-60: FeatureGetData Parameters Parameter szFeatureSource Description Specifies the media name of the script-created feature set or (in InstallScript projects) file media library that contains the feature for which information is retrieved. Specifies the name of the feature from which information is retrieved. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls. Specifies the type of information to retrieve. Pass one of the following predefined constants in this parameter:

szFeature

nInfo

FEATURE_FIELD_CDROM_FOLDERFor a CD-ROM media type, the location of the features data on the CD-ROM. Only InstallScript projects support this constant; InstallScript MSI projects do not. This constant is available for file media libraries, not for script-created feature sets. FEATURE_FIELD_DESCRIPTIONThe description displayed when the feature is selected in a feature selection dialog. This is the text from the features Description property. FEATURE_FIELD_DISPLAYNAMEThe feature name displayed in the selection dialogs. This is the value in the features Display Name setting. FEATURE_FIELD_ENCRYPTSpecifies whether the feature is encrypted. Only InstallScript projects support this constant; InstallScript MSI projects do not. This constant is available for file media libraries, not for script-created feature sets. FEATURE_FIELD_FILENEEDDefines how critical the feature files are for the installation. Only InstallScript projects support this constant; InstallScript MSI projects do not. FEATURE_FIELD_FLAGSIndicates the flags that are set for the feature. Only InstallScript projects support this constant; InstallScript MSI projects do not. This constant is available for file media libraries, not for script-created feature sets. FEATURE_FIELD_FTPLOCATIONSpecifies an FTP location. This value is stored in the features FTP Location setting. FEATURE_FIELD_GUIDThe GUID that is associated with the feature. Only InstallScript projects support this constant; InstallScript MSI projects do not. This constant is available for file media libraries, not for script-created feature sets.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

767

Appendix B: Built-In Functions (E-G) FeatureGetData

Table B-60: FeatureGetData Parameters (cont.) Parameter nInfo (cont.) Description

FEATURE_FIELD_HANDLER_ONINSTALLEDThe name of the OnInstalled event for the feature. This constant is available for file media libraries, not for script-created feature sets. FEATURE_FIELD_HANDLER_ONINSTALLINGThe name of the OnInstalling event for the feature. This constant is available for file media libraries, not for script-created feature sets. FEATURE_FIELD_HANDLER_ONUNINSTALLEDThe name of the OnUninstalled event for the feature. This constant is available for file media libraries, not for scriptcreated feature sets. FEATURE_FIELD_HANDLER_ONUNINSTALLINGThe name of the OnUninstalling event for the feature. This constant is available for file media libraries, not for scriptcreated feature sets. FEATURE_FIELD_HTTPLOCATIONSpecifies an HTTP location. This value is stored in the features HTTP Location setting. FEATURE_FIELD_IMAGESpecifies the index of the icon to be displayed in nvResult. If no icon should be displayed for the feature, nvResult returns -1. FEATURE_FIELD_MISCMiscellaneous text. This field can be useful at run time because you can use it to flag or identify features using any information you want. FEATURE_FIELD_PASSWORDSpecifies whether a password is associated with the feature. This constant is available for file media libraries, not for script-created feature sets. Only InstallScript projects support this constant; InstallScript MSI projects do not. FEATURE_FIELD_SELECTEDIndicates whether the feature specified in szFeature is selected. FEATURE_FIELD_SIZETotal original file size for the feature specified in szFeature. This constant is available for file media libraries, not for script-created feature sets. FEATURE_FIELD_STATUSIn InstallScript installations, this text is displayed in the progress indicator during file transfer. This constant is available for file media libraries, not for script-created feature sets. In InstallScript MSI installations, the features display name is returned. FEATURE_FIELD_VISIBLEDetermines whether the feature that is specified in szFeature is visible in the selection dialog. This value is stored in the features Display setting.

768

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureGetData

Table B-60: FeatureGetData Parameters (cont.) Parameter nvResult Description Returns a numeric value when nInfo produces a numeric result. When nInfo is FEATURE_FIELD_FILENEED, nvResult returns one of the following values:

FEATURE_VALUE_CRITICALThis feature contains critical files. FEATURE_VALUE_HIGHLYRECOMMENDEDThis feature is highly recommended. FEATURE_VALUE_STANDARDThis feature may or may not be included.

When nInfo is FEATURE_FIELD_FLAGS, nvResult returns one of the following values: FEATURE_DATA_FLAG_PASSWORDThe feature is password protected. FEATURE_DATA_FLAG_PASSWORD_VALIDATEDThe features password has been validated. (The installation is using FeatureValidate or the feature is not password protected.) FEATURE_DATA_FLAG_DATA_AS_FILESThe features files are placed in a particular folder for a CD-ROM type of release. FEATURE_DATA_FLAG_SPLIT_AFTERThis flag is set only for build-generated features. FEATURE_DATA_FLAG_SPLIT_BEFOREThis flag is set only for build-generated features. FEATURE_DATA_FLAG_SPLIT_BEFORE_NOT_ALLOWEDThis flag is set only for build-generated features. FEATURE_DATA_FLAG_SPLIT_NOT_ALLOWEDThis flag is set only for buildgenerated features. FEATURE_DATA_FLAG_VISIBLEThe feature is visible. FEATURE_DATA_FLAG_VOLATILEThe feature is volatile. FEATURE_DATA_FLAG_ENCRYPTEDThe feature is encrypted.

When nInfo is FEATURE_FIELD_PASSWORD, nvResult returns one of the following values: TRUEThe feature is password protected. If the feature is password protected, you must get the correct password from the end user and validate it with FeatureValidate before calling FeatureTransferData to transfer the files in the file media library. FALSEThe feature is not password protected.

svResult

When nInfo is FEATURE_FIELD_SELECTED, nvResult returns one of the following values: TRUEThis feature is selected. FALSEThis feature is not selected.

When nInfo is FEATURE_FIELD_VISIBLE, nvResult returns one of the following values: TRUEThis feature is visible. FALSEThis feature is not visible.

Returns a string value when nInfo produces a string result.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

769

Appendix B: Built-In Functions (E-G) FeatureGetData

Return Values
Table B-61: FeatureGetData Return Values Return Value 0 <0 Description FeatureGetData was successful. FeatureGetData failed. Call FeatureError for additional information. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

FeatureGetData Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureGetData function. * * This example script demonstrates a function that retrieves * information about a specified feature. * * Comments: To run this example script, create a project (or * insert into a project) with features and/or * subfeatures with components containing files. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" // Include iswi.h for Windows Installer API function prototypes and constants, // and to declare code for the OnBegin and OnEnd events. #include "iswi.h" // The keyword export identifies MyFunction() as an entry-point function. // The argument it accepts must be a handle to the Installer database. export prototype MyFunction(HWND); // To Do: // Declare global variables, define constants, and prototype userdefined and DLL functions here.

function MyFunction(hMSI) STRING NUMBER begin svDir = INSTALLDIR; szTitle = "Select Features"; szMsg = "Select the features you want to install on your computer."; // Display available features. SdFeatureTree (szTitle, szMsg, svDir, "", 2); svDir, szTitle, szMsg, svResult; nvResult;

770

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureGetItemSize

// Get the description property for Feature1. FeatureGetData (MEDIA, "Feature1", feature_FIELD_DESCRIPTION, nvResult, svResult); // Display the description for Feature1. MessageBox ("Feature1's description is: " + svResult, INFORMATION); // Determine whether or not Feature2 is selected. FeatureGetData (MEDIA, "Feature2", feature_FIELD_SELECTED, nvResult, svResult); // Display a message indicating whether or not Feature2 is selected. if nvResult=0 then MessageBox ("Feature2 is not selected.", INFORMATION); else MessageBox ("Feature2 is selected.", INFORMATION); endif; end;

FeatureGetItemSize
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureGetItemSize function retrieves the sizein bytesof a specified feature. The sizes of subfeatures are not included.

Note: This function cannot be used with script-created feature sets.

Syntax
FeatureGetItemSize ( szFeatureSource, szFeature, nvSize );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

771

Appendix B: Built-In Functions (E-G) FeatureGetItemSize

Parameters
Table B-62: FeatureGetItemSize Parameters Parameter szFeatureSource Description Specifies the media name of the file media that contains the feature whose size is to be retrieved. Specifies the name of the feature whose size is to be retrieved. Returns the size in bytes of the specified feature. You can also call FeatureGetData to get the total original file size of a specified feature. Call FeatureTotalSize to determine the total size of all selected features and subfeatures.

szFeature nvSize

Return Values
Table B-63: FeatureGetItemSize Return Values Return Value 0 <0 Description FeatureGetItemSize was successful. FeatureGetItemSize failed. Call FeatureError for additional information.

FeatureGetItemSize Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureGetItemSize function. * * This example calls FeatureGetItemSize to get the size of * a feature and a subfeature. The sizes are displayed * in a dialog. * * Notes: To run this example script, create a project (or * insert into a project) with several features and/or * subfeatures with components containing files. * You must name one feature and one subfeature as * indicated in the #define statements in this example, * or change the #define statements to reference your * feature names. * \*--------------------------------------------------------------*/ #define FEAT_NAME1 "Program Files" #define FEAT_NAME2 "Example Files\\Graphics" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FeatureGetItemSize(HWND); function ExFn_FeatureGetItemSize(hMSI)
772 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureGetTotalCost

NUMBER nvSize; STRING szString; LIST listInfo; begin // Create a string list to store feature sizes. listInfo = ListCreate (STRINGLIST); // Get the size of FEAT_NAME1. FeatureGetItemSize (MEDIA, FEAT_NAME1, nvSize); // Convert the number to a string. NumToStr (szString, nvSize); // Put the string into the list. ListAddString (listInfo, "The size in bytes of " + FEAT_NAME1 + " is: " + szString, AFTER); // Get the size of FEAT_NAME2. FeatureGetItemSize (MEDIA, FEAT_NAME2, nvSize); // Convert the number to a string. NumToStr (szString, nvSize); // Put the string into the list. ListAddString (listInfo, "The size in bytes of " + FEAT_NAME2 + " is: " + szString, AFTER); // Display the list of feature sizes. SdShowInfoList ("Results of Calls to FeatureGetItemSize", "The feature sizes are:", listInfo); // Release the list from memory. ListDestroy (listInfo); end;

FeatureGetTotalCost
Note: This function is obsolete. Use the FeatureGetCostEx function instead.

Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureGetTotalCost function determines the total space, in kilobytes (KB), required on the target drive for the feature installations and uninstallations that have been specified (for example, by end user selections in feature or setup type dialogs). When determining required drive space, this function takes into account which features are currently selected, whether any components associated with the features are currently filtered by operating system or language, and the cluster size on the target drive.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

773

Appendix B: Built-In Functions (E-G) FeatureInitialize

Syntax
FeatureGetTotalCost ( szFeatureSource, szTargetDir, nvTotalRequiredSpace );

Parameters
Table B-64: FeatureGetTotalCost Parameters Parameter szFeatureSource Description Specifies the media name of the file media whose features have been specified for installation and uninstallation. Typically, you would pass the system variable MEDIA in this parameter. Specifies the drive that is used, or the path whose drive is used, in determining required drive space. Typically, you would pass the system variable TARGETDIR in this parameter. Returns the required drive space, in KB.

szTargetDir

nvTotalRequiredSpace

Return Values
Table B-65: FeatureGetTotalCost Return Values Return Value 0 <0 Description Indicates that the function successfully determined the required drive space. Indicates that the function could not determine the required drive space. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

FeatureInitialize
Project: This information applies to InstallScript projects.

The FeatureInitialize function is supported only for compatibility with scripts created in earlier versions of InstallShield. It is recommended that you avoid using multiple file media libraries in InstallShield because they are no longer necessary and they can break your installation. The FeatureInitialize function associates a media name with a file media library and prepares that media library for access.

Syntax
FeatureInitialize ( szMediaLibrary, szMediaLibraryFile );

774

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureInitialize

Parameters
Table B-66: FeatureInitialize Parameters Parameter szMediaLibrary Description Specifies the media name to associate with the file media library whose files are to be transferred with FeatureMoveData Example. The media name Data is reserved for use with Data1.cab, the default file media library. You may not pass Data in the parameter szMediaLibrary. szMediaLibraryFile Specifies the file name of the file media library to be initialized. The file name must be in the format xxx1.cab; for example, second1.cab or wow1.cab. Do not specify a path; this file must reside in the installation's source folder (SRCDIR).

Return Values
Table B-67: FeatureInitialize Return Values Return Value 0 <0 Description FeatureInitialize was successful. FeatureInitialize failed. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
This function cannot be used with script-created feature sets. A file media library that is initialized with FeatureInitialize must be installed by calling FeatureMoveData. FeatureTransferData fails if called to install such a media library. If an installation installs file media libraries that are initialized with FeatureInitialize, the uninstallation must be enabled by calling DeinstallStart rather than MaintenanceStart. (This is the case because files must be installed by calling FeatureMoveData, which does not support maintenance setups.) The maintenance/uninstallation feature that is stored in szMediaLibraryFile is not installed by
FeatureMoveData; only the first call to FeatureMoveData, before calling FeatureInitialize, can install a file

media library's maintenance/uninstallation feature. It is not necessary to call FeatureInitialize before accessing the default file media library (Data1.cab) using the default media name Data. The default media is initialized automatically during installation initialization. The file media library must reside in the installations source folder. The name of this folder is assigned to the system variable SRCDIR during installation initialization.

FeatureInitialize Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script *
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 775

Appendix B: Built-In Functions (E-G) FeatureInitialize

* Demonstrates the FeatureInitialize function. * \*--------------------------------------------------------------*/ NUMBER nResult, n; program // Set a target directory. TARGETDIR = "C:\\temp" ^ MEDIA; // Select features to transfer. nResult = FeatureDialog ("", "", TARGETDIR,""); if (nResult < 0) then SprintfBox (SEVERE, "FeatureDialog ERROR", "%ld", nResult); endif; // Transfer files associated with data1.cab (Data Media). nResult = FeatureMoveData (MEDIA, n, 0); if (nResult < 0) then SprintfBox (SEVERE, "FeatureMoveData ERROR", "%ld", nResult); endif; // Set up for second media. MEDIA = "second"; // Set a target directory. TARGETDIR = "C:\\temp" ^ MEDIA; // Associate new media with second1.cab cab file. nResult = FeatureInitialize (MEDIA, "second1.cab"); if (nResult < 0) then SprintfBox (SEVERE, "FeatureInitialize ERROR", "%ld", nResult); endif; // Select features to transfer. nResult = FeatureDialog ("", "", TARGETDIR,""); if (nResult < 0) then SprintfBox (SEVERE, "FeatureDialog ERROR", "%ld", nResult); endif; // Reinitialize FeatureMoveData function. nResult = FeatureMoveData ("", n ,0); if (nResult < 0) then SprintfBox (SEVERE, "FeatureMoveData ERROR", "%ld", nResult); endif; // Transfer files associated with second1.cab (second Media). nResult = FeatureMoveData (MEDIA, n, 0); if (nResult < 0) then SprintfBox (SEVERE, "FeatureMoveData ERROR", "%ld", nResult); endif; endprogram // Source file: Is5fn628.rul

776

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureIsItemSelected

FeatureIsItemSelected
Project: This information applies to the following project types:

InstallScript InstallScript MSI

In Windows Installerbased projects, FeatureIsItemSelected determines the current installed state of the specified feature. In InstallScript projects, FeatureIsItemSelected determines the current selection state of the specified feature. You can also use FeatureGetData to determine if a feature is selected.
FeatureIsItemSelected is typically called to perform feature-specific tasks before or after file transfer. To perform feature-specific tasks during file transfer in an InstallScript installation, it is recommended that you place code in feature event handler functions.

Syntax
FeatureIsItemSelected ( szFeatureSource, szFeature );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

777

Appendix B: Built-In Functions (E-G) FeatureIsItemSelected

Parameters
Table B-68: FeatureIsItemSelected Parameters Parameter szFeatureSource Description Specifies the media name of the script-created feature set or (in InstallScript projects) file media library for which the installed state or selection setting is determined. Specifies the name of the feature for which the installed state or selection setting is determined. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls.

szFeature

Return Values
Table B-69: FeatureIsItemSelected Return Values Return Value TRUE (1) Description In Windows Installer based projects, szFeature's installed state is INSTALLSTATE_LOCAL (feature was installed on the local drive). In InstallScript projects, szFeature is selected. FALSE (0) In Windows Installer based projects, szFeature's installed state is INSTALLSTATE_ABSENT (feature was uninstalled). In InstallScript projects, szFeature is deselected. <0 The function failed to determine if the feature was installed or selected. Call FeatureError for additional information.

FeatureIsItemSelected Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureIsItemSelected function. * * This example script displays a dialog that displays a list * of features in the setup that the user can install and the * amount of space that each feature occupies. When the user * selects features, the installed state of the features is * provided. * * Comments: To run this example script, create a project (or * insert into a project) with several features and/or * subfeatures with components containing files. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" // Include iswi.h for Windows Installer API function prototypes and constants,

778

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureListItems

// and to declare code for the OnBegin and OnEnd events. #include "iswi.h" // The keyword export identifies MyFunction() as an entry-point function. // The argument it accepts must be a handle to the Installer database. export prototype MyFunction(HWND); // To Do: // Declare global variables, define constants, and prototype userdefined and DLL functions here.

function MyFunction(hMSI) STRING NUMBER begin svDir = INSTALLDIR; szTitle = "Select Features"; szMsg = "Select the features you want to install on your computer."; // Display available features. SdFeatureTree (szTitle, szMsg, svDir, "", 2); // Determine the installed state of Subfeature1. nResult = FeatureIsItemSelected (MEDIA, "Feature1\\Subfeature1"); // Display if nResult MessageBox else MessageBox endif; end; message indicating the installed state of Subfeature1. = 1 then ("Subfeature1 is installed locally.", INFORMATION); ("Subfeature1 is uninstalled.", INFORMATION); szTitle, szMsg, svDir; nResult;

FeatureListItems
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureListItems function lists all subfeatures under the feature specified in szFeature. The list of fully qualified subfeature names is stored in listFeatures. If szFeature has subfeatures, listFeatures returns an empty list.

Syntax
FeatureListItems ( szFeatureSource, szFeature, listFeatures );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

779

Appendix B: Built-In Functions (E-G) FeatureListItems

Parameters
Table B-70: FeatureListItems Parameters Parameter szFeatureSource Description Specifies the media name of the script-created feature set whose subfeatures are listed. Specifies the feature whose subfeatures are listed. Pass a null string ("") in this parameter to list all top-level features. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls. Returns the list of features. You must call ListCreate before calling FeatureListItems to initialize the string list identified by listFeatures.

szFeature

listFeatures

Return Values
Table B-71: FeatureListItems Return Values Return Value 0 <0 Description FeatureListItems listed the features. FeatureListItems was unable to list the features. Call FeatureError for additional information.

FeatureListItems Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureListItems function. * * This example script demonstrates a function that lists all * subfeatures under a specified feature. * * Comments: To run this example script, create a project (or * insert into a project) with several features and/or * subfeatures with components containing files. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" // Include iswi.h for Windows Installer API function prototypes and constants, // and to declare code for the OnBegin and OnEnd events. #include "iswi.h" // The keyword export identifies MyFunction() as an entry-point function. // The argument it accepts must be a handle to the Installer database. export prototype MyFunction(HWND);

780

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureLoadTarget

// To Do: //

Declare global variables, define constants, and prototype userdefined and DLL functions here.

function MyFunction(hMSI) STRING szTitle, szMsg; NUMBERlistID; begin szTitle = "List MEDIA Features"; szMsg = "MEDIA contains the following top-level features:"; // Initialize the string list. listID = ListCreate (STRINGLIST); // Create a list of top-level features in the specified media. FeatureListItems (MEDIA, "", listID); // Display the list of top-level features. SdShowInfoList (szTitle, szMsg, listID); end;

FeatureLoadTarget
Project: This information applies to InstallScript projects.

The FeatureLoadTarget function is called automatically during the initialization of any installation for which a valid log file exists.

Syntax
FeatureLoadTarget( szReserved );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

781

Appendix B: Built-In Functions (E-G) FeatureMoveData

Parameters
Table B-72: FeatureLoadTarget Parameters Parameter szReserved Description Pass a null string ("") in this parameter. No other value is allowed.

Return Values
Table B-73: FeatureLoadTarget Return Values Return Value 0 Description This function always returns zero (0).

Additional Information
FeatureLoadTarget reads the log file and retrieves the target directory of all filegroups in the setup. FeatureLoadTarget retrieves the values of all text substitutions used by the setup; this includes the target directory of all filegroups and the value of all target-directory-related system variables, as well as all other text substitution values.

FeatureMoveData
Project: This information applies to InstallScript projects:

The FeatureMoveData function transfers and decompresses files associated with selected features in the file media referenced by szFeatureSource. The function automatically prompts the end user for the next disk when it is needed.

Tip: If you are transferring files to WINSYSDIR64, you must first disable file system redirection using WOW64FSREDIRECTION. Otherwise, files being transferred to WINSYSDIR64 are incorrectly redirected to the 32-bit Windows system folder. Since some Windows functionality which could be used by the setup requires that redirection be enabled to work, Windows documentation recommends that you disable redirection only for as long as necessary. It is recommended that you then enable file system redirection as soon as you have completed installing the necessary files to WINSYSDIR64.

When you call FeatureMoveData, Do (SELFREGISTRATIONPROCESS) is called automatically after the files are installed but before the call returns. Therefore, if your installation needs to perform additional actions after the file transfer but before self-registration, place these actions in the OnMoved event; the OnMoved event is called after the file transfer but before the batch self-registration occurs. You can call FeatureMoveData more than once on the same media, but you must reset internal structures before the second and subsequent calls by calling FeatureMoveData with a null string ("") in the first parameter position. InstallShield automatically initializes the default media and internal structures before your first call to FeatureMoveData.
782 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureMoveData

Note: This function cannot be used with script-created feature sets.

Syntax
FeatureMoveData ( szFeatureSource, nvReserved, nReserved );

Parameters
Table B-74: FeatureMoveData Parameters Parameter szFeatureSource nvReserved nReserved Description Specifies the media name of the file media whose files are to be transferred. Pass a number variable in this argument. No useful data is returned. Pass zero in this parameter. No other value is allowed.

Return Values
Table B-75: FeatureMoveData Return Values Return Value 0 <0 Description FeatureMoveData was successful. FeatureMoveData failed. Call FeatureError for additional information.

FeatureMoveData Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions SdSetupTypeEx, SdFeatureDialog, * FeatureMoveData, FeatureError, and PlaceWindow. * * Notes: To run this example script, create a project with * the following features (f), subfeatures (sf), * and components (c): * * (f) Program_Files * (c) Program_DLLS * (c) Program_EXEs * (f) Example_Files * (sf) Small_Documents * (c) Small_Document_Examples * (sf) Books * (c) Book_Examples * (sf) Graphics * (c) Graphic_Examples * (f) Help_Files * (c) Help_Files
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 783

Appendix B: Built-In Functions (E-G) FeatureMoveData

* (f) Utilities * (sf) Grammar_Checker * (c) Grammar_Checker * (sf) Art Studio * (c) Art_Studio * (f) Evaluation_Copy * (c) Evaluation_Copy * (c) Help_Files * * Insert "dummy" files into the components. Make sure you * define the correct file name for the main EXE (MAIN_EXE, * below) that you insert into the Program_EXEs component. * * This example script installs files, adds an icon to the * Start Programs menu, and provides uninstallation * functionality. * \*--------------------------------------------------------------*/ // Define strings. In a real installation, you would define these in the String Editor // view and precede each string identifier in the script with the at symbol (@). #define FEAT_SELECT_TITLE "Select features" #define FEAT_SELECT_MSG "Select features and subfeatures to install." #define FEAT_PROGRAMFILES_DISPLAYNAME "Program Files" #define PASSWORD_PROMPT "Please enter the password." #define PASSWORD_ERRMSG "Password incorrect. Please enter again." #define TITLE_MAIN "Word Processor" #define TITLE_CAPTIONBAR "Word Processor Setup" #define APPBASE_PATH "Your Company\\Word Processor" #define COMPANY_NAME "Your Company" #define PRODUCT_NAME "Word Processor" #define PRODUCT_VERSION "1.0" #define PRODUCT_KEY "Word Processor" #define DEINSTALL_KEY "Word Processor" #define UNINSTALL_NAME "Word Processor" #define ADDINGICON "Adding program icon to the Start Programs menu..." #define PROGRAMDIR "Program" #define DEFAULT_FOLDER_NAME "" #define APP_NAME "Word Processor" #define COMPLETE_MSG "Setup is complete. You can run Word Processor from the Start Programs menu." #define MAIN_EXE "WRITE.EXE" #define SETUPTYPE_TITLE "Setup Type Selection" #define SETUPTYPE_MSG "Please select a setup type." #define SETUPTYPE_CUSTOM "Custom" // Global variable declarations. // Function declarations. prototype SetUpFileTransfer (); prototype HandleFeatureError (NUMBER); prototype FinishSetup (); // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FeatureMoveData(HWND); function ExFn_FeatureMoveData(hMSI) STRING svData, svLogFile, szProgram, szFeature; STRING svResult, svSetupType, svDir; BOOL bInitStepsDone, bPwdValid;
784 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureMoveData

NUMBER begin

nvData, nvDisk, nResult;

SetUpFileTransfer (); // Disable the Back button in installation dialogs. Disable (BACKBUTTON); // Get the setup type. svDir = INSTALLDIR; SdSetupTypeEx (SETUPTYPE_TITLE, SETUPTYPE_MSG, "", svSetupType, 0); // If user selected Custom setup type, display feature selection dialog. if (svSetupType = SETUPTYPE_CUSTOM) then SdFeatureDialog (FEAT_SELECT_TITLE, FEAT_SELECT_MSG, svDir, ""); endif; // Enable the Back button in installation dialogs. Enable (BACKBUTTON); // Set up the progress indicator, including locations for // progress indicator, information gauges, and billboards. PlaceWindow (FEEDBACK, LOWER_LEFT, LOWER_LEFT, LOWER_LEFT); PlaceWindow (STATUSDLG, CENTERED, LOWER_RIGHT, LOWER_RIGHT); PlaceWindow (BILLBOARD, CENTERED, CENTERED, CENTERED); Enable (STATUSDLG); Enable (INDVFILESTATUS); // Indicate the final percentage the progress bar is to show when the // following file transfer operation is complete. StatusUpdate (ON, 95); // Transfer files to the target system. FeatureMoveData prompts // for next disk in a floppy disk installation. nResult=FeatureMoveData (MEDIA, nvDisk, 0); // See the FeatureError function in action. HandleFeatureError (nResult); FinishSetup(); end; /*--------------------------------------------------------------------------*\ * * Function: SetupFileTransfer() * * Purpose: This function sets up file transfer. The main reason for * abstracting this process into this function is to make it * easy to see the function calls this sample script demonstrates. * \*--------------------------------------------------------------------------*/ function SetUpFileTransfer() begin // Set up the installation screen. Enable (FULLWINDOWMODE);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 785

Appendix B: Built-In Functions (E-G) FeatureMoveData

SdProductName ( PRODUCT_NAME ); SetTitle (TITLE_MAIN, 24, WHITE); SetTitle (TITLE_CAPTIONBAR, 0, BACKGROUNDCAPTION); Enable (BACKGROUND); // Welcome the user, check that the system meets minimum requirements, // and verify the destination location. bInitStepsDone = FALSE; while (!bInitStepsDone) Disable (BACKBUTTON); Welcome ("", 0); Enable (BACKBUTTON); INSTALLDIR = PROGRAMFILES ^ APPBASE_PATH; if (AskDestPath ("", "", INSTALLDIR, 0) != BACK) then bInitStepsDone = TRUE; endif; endwhile; // Set installation information required for registry entries and for // the following call to DeinstallStart. InstallationInfo (COMPANY_NAME, PRODUCT_NAME, PRODUCT_VERSION, PRODUCT_KEY); // Initialize the uninstallation log file, including registry entry. svLogFile = "Uninst.isu"; DeinstallStart (INSTALLDIR, svLogFile, DEINSTALL_KEY, 0); RegDBSetItem (REGDB_UNINSTALL_NAME, UNINSTALL_NAME); end; /*--------------------------------------------------------------------------*\ * * Function: HandleFeatureError * * Purpose: This function evaluates the value returned by a feature * function and if the value is less than zero, displays the error * number and aborts the installation. * \*--------------------------------------------------------------------------*/ function HandleFeatureError (nResult) NUMBER nvError; STRING svFeatureSource, svFeature, svComponent, svFile; begin if (nResult < 0) then FeatureError (svFeatureSource, svFeature, svComponent, svFile, nvError); SprintfBox (INFORMATION, "Data Transfer Error Information", "FeatureError returned the " + "following data transfer error.\n" + "Setup will now abort.\n\n" + "Media Name: %s\nFeature: %s\nComponent: %s\n" + "File: %s\nError Number: %ld", svFeatureSource, svFeature, svComponent, svFile, nvError); abort; endif; end; /*--------------------------------------------------------------------------*\ * * Function: FinishSetup() *
786 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeaturePatch

* Purpose: This function finishes the installation. The main reason for * abstracting this process into this function is to make it * easy to see the function calls this sample script demonstrates. * \*--------------------------------------------------------------------------*/ function FinishSetup() begin // Indicate the final percentage the progress bar is to show when the // following file transfer operation is complete. StatusUpdate(ON, 99); // Increment progress bar to 99% for creation of Start Programs menu icon. SetStatusWindow (96 , ADDINGICON); // Add the APP_NAME icon to the DEFAULT_FOLDER_NAME folder. szProgram = INSTALLDIR ^ PROGRAMDIR ^ MAIN_EXE; LongPathToQuote (szProgram, TRUE); AddFolderIcon (DEFAULT_FOLDER_NAME, APP_NAME, szProgram, INSTALLDIR ^ PROGRAMDIR, "", 0, "", REPLACE); Delay (1); // Disable the progress indicator and its settings. Disable (INDVFILESTATUS); Disable (STATUSDLG); // Announce installation complete and offer to view Readme file. MessageBox (COMPLETE_MSG, INFORMATION); end;

FeaturePatch
Project: This information applies to InstallScript projects.

The FeaturePatch function is called only in installations that use differential media. (You can check the media format by calling MediaGetData with MEDIA_FIELD_MEDIA_FLAGS as its second argument).
FeaturePatch causes the next call to FeatureTransferData or FeatureMoveData to reinstall all features that are already installed when FeatureTransferData is called, including all of the maintenance/ uninstallation features files except for Data1.hdr, Data1.cab, and Layout.bin. (Note that the maintenance/uninstallation feature is automatically placed in your disk image by the release builder and is not displayed in InstallShield.) A copy of the running file media library is stored on the target machine for use during subsequent maintenance operations, that is, modifying, repairing, or uninstalling.

Syntax
FeaturePatch ( );

Parameters
None.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

787

Appendix B: Built-In Functions (E-G) FeatureReinstall

Return Values
Table B-76: FeaturePatch Return Values Return Value 0 <0 Description Indicates that the function succeeded. Indicates that the function failed.

Additional Information
FeaturePatch is called in the default code for the OnUpdateUIBefore event handler function.

FeatureReinstall
Project: This information applies to the following project types:

InstallScript InstallScript MSI

In a setup that has already been run, after the FeatureReinstall function is called, the next call to FeatureTransferData performs the file transfer that was specified the last time the setup was run.

Syntax
FeatureReinstall ( );

Parameters
None

Return Values
Table B-77: FeatureReinstall Return Values Return Value 0 <0 Description Indicates that the function successfully prepared the setup for reinstallation. Indicates that the function was unable to prepare the setup for reinstallation.

FeatureRemoveAll
Project: This information applies to the following project types:

788

InstallScript
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureRemoveAllInLogOnly

InstallScript MSI

FeatureRemoveAll is used during a maintenance install to force the removal of all features that were installed previously. FeatureRemoveAll is generally called when the user selects the Remove option in the SdWelcomeMaint dialog.

Calling FeatureRemoveAll causes all features to be deselected. As a result, when FeatureTransferData is called, any features that have already been installed (determined by reading the setup log file, if it exists) are removed (uninstalled). Setup determines whether or not features have been previously installed by reading the setup log file. If no valid log file is found during setup initialization, all features are considered not installed. In this case, calling FeatureRemoveAll clears all feature selections, but does not force uninstallation of the features when FeatureTransferData is called.

Note: FeatureRemoveAll also deselects all internal features, including the features containing the Disk 1 setup files that are automatically installed to the DISK1TARGET location.

Syntax
FeatureRemoveAll ( );

Parameters
None

Return Values
Table B-78: FeatureRemoveAll Return Values Return Value 0 <0 Description Indicates that the function successfully deselected all feature selections. Indicates that the function was unable to deselect all feature selections.

FeatureRemoveAllInLogOnly
Project: This information applies to InstallScript projects.

The FeatureRemoveAllInLogOnly function is called during an update installation to force the removal of all features that are not in the current media but were installed previously, as recorded in the setup log file.

Syntax
FeatureRemoveAllInLogOnly ( );

Parameters
None.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 789

Appendix B: Built-In Functions (E-G) FeatureRemoveAllInMedia

Return Values
Table B-79: FeatureRemoveAllInLogOnly Return Values Return Value 0 <0 Description Indicates that the function successfully deselected the feature selections. Indicates that the function was unable to deselect the feature selections. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
Calling FeatureRemoveAllInLogOnly causes all features that are not in the current media but were installed previously to be deselected. As a result, when FeatureTransferData is called, those features will be removed (uninstalled).

Caution: Do not call FeatureRemoveAllInLogOnly in an "add-on" installationthat is, an installation with the same INSTANCE_GUID as a application already on the system that includes a subset of the features in the earlier installation. The result would be the uninstallation (removal) of all features that were contained in the earlier installation, but not the features in the current installation.

If no valid log file is found during installation initialization, calling FeatureRemoveAllInLogOnly has no effect.

FeatureRemoveAllInMedia
Project: This information applies to InstallScript projects.

The FeatureRemoveAllInMedia is used during a maintenance installation to force the removal of all features that are in the current media and were installed previously. This function is generally called when the user selects the Remove option in the SdWelcomeMaint dialog. When you call FeatureRemoveAllInMedia, only the features listed in the media header are removed; however, in the case of an updated application in which features were removed but not uninstalled during the updatethat is, the features did not exist in the update media but did exist in the original media (and the update did not call FeatureRemoveAllInLogOnly)whether or not these features are removed during uninstallation depends on whether the application was updated via a differential media or a full update media:

If the application was updated via a full media, the full media header replaces the original media header; therefore, these features are not removed during uninstallation. If the application was updated via a differential media, both header files are present; therefore, FeatureRemoveAllInMedia removes these features.

790

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureRemoveAllInMediaAndLog

To ensure that all installed features are uninstalled, an installation should call FeatureRemoveAllInMediaAndLog. This ensures that all features are removed.

Syntax
FeatureRemoveAllInMedia ( );

Parameters
None.

Return Values
Table B-80: FeatureRemoveAllInMedia Return Values Return Value 0 <0 Description Indicates that the function successfully deselected all feature selections. Indicates that the function was unable to deselect all feature selections. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
Calling FeatureRemoveAllInMedia causes all features that are in the current media to be deselected. As a result, when FeatureTransferData is called, any features that have already been installed (determined by reading the installation log file, if it exists) are removed (uninstalled). The installation determines whether or not features have been previously installed by reading the installation log file. If no valid log file is found during installation initialization (MAINTENANCE is FALSE), all features are considered not installed. In this case, calling FeatureRemoveAllInMedia causes all features to be deselected and not installed. However, a subsequent call to FeatureTransferData does not uninstall anything (since the log file contains the information regarding what to uninstall). Calling FeatureRemoveAllInMedia in this case is not recommended.

Note: FeatureRemoveAll also deselects all internal features, including the maintenance/uninstallation feature.

FeatureRemoveAllInMediaAndLog
Project: This information applies to InstallScript projects.

The FeatureRemoveAllInMediaAndLog function is called during an update installation to force the removal of all features that were installed previouslyboth those that are in the current media, and those that are not in the current media but are recorded in the setup log file.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

791

Appendix B: Built-In Functions (E-G) FeatureSaveTarget

Syntax
FeatureRemoveAllInMediaAndLog ( );

Parameters
None.

Return Values
Table B-81: FeatureRemoveAllInMediaAndLog Return Values Return Value 0 <0 Description Indicates that the function successfully deselected all feature selections. Indicates that the function was unable to deselect all feature selections. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
Calling FeatureRemoveAllInMediaAndLog is equivalent to calling both FeatureRemoveAllInMedia and FeatureRemoveAllInLogOnly. Calling FeatureRemoveAllInMediaAndLog causes all features that were installed previously to be deselected. As a result, when FeatureTransferData is called, those features will be removed (uninstalled). The installation determines whether or not features have been previously installed by reading the setup log file. If no valid log file is found during installation initialization (MAINTENANCE is FALSE), all features are considered not installed. In this case, calling FeatureRemoveAllInMediaAndLog will cause all features to be deselected and not installed. However, a subsequent call to FeatureTransferData will not uninstall anything (since the log file contains the information regarding what to uninstall). Calling FeatureRemoveAllInMediaAndLog in this case is not recommended.

Note: FeatureRemoveAllInMediaAndLog will also deselect all internal features, including the maintenance/uninstallation feature.

FeatureSaveTarget
Project: This information applies to the following project types:

InstallScript InstallScript MSI

FeatureSaveTarget gets the current values of all text substitutions used by the setup project and stores

them in the installation log file. This includes the current target directory of all components and the value of all target-directory-related system variables, as well as all other text substitution values.
792 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureSelectItem

When the setup initializes and a valid log file is found, any values previously stored with this function are automatically restored. This allows a maintenance setup to update previously installed components and install new components to the appropriate location.

Syntax
FeatureSaveTarget ( szReserved );

Parameters
Table B-82: FeatureSaveTarget Parameters Parameter szReserved Description Pass a null string ("") in this parameter. No other value is allowed.

Return Values
This function always returns zero (0).

FeatureSelectItem
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureSelectItem function sets a features selection status to either selected or not selected. You can use FeatureSelectItem to change selection status before displaying features in feature dialogs, and you can use it to change or override selections afterward, depending on your installations requirements.

If you call a setup type selection function (such as FeatureSetupTypeSet, SetupType2, SdSetupType, or SdSetupTypeEx) after calling FeatureSelectItem, the feature selections set by FeatureSelectItem are overridden by the selections in the setup type. (This applies to features that you add to your installation project and does not affect internal features.) Be aware that SetupType2 is called in the default code for the OnFirstUIBefore event handler function, which is called after the OnBegin, OnCCPSearch, and OnAppSearch event handler functions are called. You can override or customize the OnFirstUIBefore event handler. If you use FeatureSelectItem to deselect a feature, note that the same rules that apply to deselecting a feature through the feature dialog apply. That is, a feature cannot be deselected if it is required by a currently selected feature. Therefore, to deselect a feature that is required by another feature, ensure to deselect the requiring feature before attempting to deselect the required feature. It is usually not necessary to call FeatureSelectItem during maintenance mode, since the previous feature selections are automatically loaded from the existing log file.

Syntax
FeatureSelectItem ( szFeatureSource, szFeature, bSelect );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

793

Appendix B: Built-In Functions (E-G) FeatureSelectItem

Parameters
Table B-83: FeatureSelectItem Parameters Parameter szFeatureSource Description Specifies the media name of the script-created feature set or (in InstallScript projects) file media library containing the feature whose selection status is to be set. Specifies the feature whose selection status is to be set. You can specify a null string ("") for this parameter. If you specify a null string, all features from szFeatureSource are either selected or deselected, depending on the value of bSelect. For more information about specifying features and subfeatures in InstallScript, see Specifying Features and Subfeatures in Function Calls. bSelect Specifies whether the feature should be selected. Pass one of the following predefined constants in this parameter:

szFeature

TRUESelect the specified feature. FALSEDo not select the specified feature.

Return Values
Table B-84: FeatureSelectItem Return Values Return Value 0 <0 Description FeatureSelectItem successfully set the features selection status. FeatureSelectItem was unable to set the features selection status. For additional information, call FeatureError.

FeatureSelectItem Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureSelectItem function. * * This example script demonstrates a function that sets a * feature's status to either selected or not selected. * * Comments: To run this example script, create a project (or * insert into a project) with several features and/or * subfeatures with components containing files. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" // Include iswi.h for Windows Installer API function prototypes and constants,
794 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureSelectNew

// and to declare code for the OnBegin and OnEnd events. #include "iswi.h" // The keyword export identifies MyFunction() as an entry-point function. // The argument it accepts must be a handle to the Installer database. export prototype MyFunction(HWND); // To Do: // Declare global variables, define constants, and prototype userdefined and DLL functions here.

function MyFunction(hMSI) STRING begin svDir = INSTALLDIR; szTitle = "Select Features"; szMsg = "Select the features you want to install on your computer."; // Set the selection status of Subfeature2 to not selected. FeatureSelectItem (MEDIA, "Feature1\\Subfeature2", FALSE); // Display available features. SdFeatureTree (szTitle, szMsg, svDir, "", 2); end; svDir, szTitle, szMsg;

FeatureSelectNew
Project: This information applies to InstallScript projects.

The FeatureSelectNew function sets the selection status of all new features to either selected or unselected.

Syntax
FeatureSelectNew (szFeatureSource, bSelect);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

795

Appendix B: Built-In Functions (E-G) FeatureSetData

Parameters
Table B-85: FeatureSelectNew Parameters Parameter szFeatureSource Description Specifies the media name of the file media library containing the new features whose selection status is to be set. Typically, this argument is set equal to the system variable MEDIA. Specifies whether the new features are selected or deselected. Pass one of the following predefined constants in this parameter:

bSelected

TRUESelects the new features. FALSEDeselects the new features.

Return Values
Table B-86: FeatureSelectNew Return Values Parameter 0 <0 Description FeatureSelectNew successfully set the new features' selection status. FeatureSelectNew was unable to set the new features' selection status. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
New features are features that exist in the installation's file media library but not in the existing log file. FeatureSelectNew is typically called in an update installation to select new features before displaying features in features dialogs. FeatureSelectNew is called in the default code for the OnUpdateUIBefore event handler function.

Note: If you call a setup type selection function after calling FeatureSelectNew, the feature selections set by FeatureSelectNew are overridden by the selections in the setup type.

It is usually unnecessary to call FeatureSelectNew during maintenance mode because the previous feature selections are automatically loaded from the existing log file.

FeatureSetData
Project: This information applies to the following project types:

796

InstallScript InstallScript MSI

ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureSetData

The FeatureSetData function sets properties and data for the specified feature. Most of the settings correspond to the properties in the Features view.

Syntax
FeatureSetData ( szFeatureSource, szFeature, nInfo, nData, szData );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

797

Appendix B: Built-In Functions (E-G) FeatureSetData

Parameters
Table B-87: FeatureSetData Parameters Parameter szFeatureSource Description Specifies the media name of the script-created feature set or (in InstallScript projects) file media library that contains the feature for which properties and data are to be set. Specifies the name of the feature. For more information about specifying features and subfeatures in InstallScript, see Specifying Features and Subfeatures in Function Calls. Specifies the type of information to be set. Pass one of the following predefined constants in this parameter:

szFeature

nInfo

FEATURE_FIELD_DESCRIPTIONThis text is displayed in the Description field of selection dialogs. FEATURE_FIELD_FTPLOCATIONAn FTP location. FEATURE_FIELD_HTTPLOCATIONAn HTTP location. FEATURE_FIELD_STATUS (not for script-created feature sets)This text is displayed in the progress indicator during file transfer. FEATURE_FIELD_VISIBLEIndicates whether or not the feature is visible in a feature selection dialog. The parameter nData can be one of the following: TRUE: The feature is visible. FALSE: The feature is not visible.

FEATURE_FIELD_SELECTEDSets the selection status of the feature. This setting has the same effect as FeatureSelectItem. The parameter nData can be one of the following: TRUE: Select the feature. FALSE: Do not select the feature.

FEATURE_FIELD_SIZE (not for file media)The total original file size for the feature. FEATURE_FIELD_MISCMiscellaneous text. FEATURE_FIELD_DISPLAYNAME (not for object projects)Indicates the name displayed in feature selection dialogs for the feature specified in szFeature. FEATURE_FIELD_IMAGEOverrides a feature's default icon assignment. Pass the index of the icon to display in nData. To specify that no icon should be displayed for the feature, pass -1 in nData.

nData szData

Specifies a numeric value to set when the information indicated by nInfo is numeric. Specifies a string value to set when the information indicated by nInfo is a string.

Return Values
Table B-88: FeatureSetData Return Values Return Value 0 Description FeatureSetData was successful.

798

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureSetData

Table B-88: FeatureSetData Return Values (cont.) Return Value <0 Description FeatureSetData failed. Call FeatureError for additional information. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

FeatureSetData Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureSetData function. * * This example script demonstrates a function that sets data * and properties for a specified feature. * * Comments: To run this example script, create a project (or * insert into a project) with several features and/or * subfeatures with components containing files. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" // Include iswi.h for Windows Installer API function prototypes and constants, // and to declare code for the OnBegin and OnEnd events. #include "iswi.h" // The keyword export identifies MyFunction() as an entry-point function. // The argument it accepts must be a handle to the Installer database. export prototype MyFunction(HWND); // To Do: // Declare global variables, define constants, and prototype userdefined and DLL functions here.

function MyFunction(hMSI) STRING NUMBER begin svDir szTitle szMsg szData = = = = INSTALLDIR; "Select Features"; "Select the features you want to install on your computer."; "Required Feature"; svDir, szTitle, szMsg, szData; nData;

// Hide Feature1 from the end user. FeatureSetData (MEDIA, "Feature1", FEATURE_FIELD_VISIBLE, FALSE, szData); // Set the display name for Feature2. FeatureSetData (MEDIA, "Feature2", FEATURE_FIELD_DISPLAYNAME, nData, szData); // Display available features.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

799

Appendix B: Built-In Functions (E-G) FeatureSetTarget

SdFeatureTree (szTitle, szMsg, svDir, "", 2); end;

FeatureSetTarget
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureSetTarget function assigns the value of szLocation to the public property (in InstallScript MSI projects) or property variable (in InstallScript projects) that is specified by szPropertyVar. Properties or property variables can be used in the Destination field of the Components view and in the Target field of a shortcut in the Shortcuts view. Call FeatureSetTarget before calling FeatureMoveData.

Note: This function cannot be used with script-created feature sets.

This function cannot set the value of an objects property variable. To set the value of an objects property variable, you must use the objects ScriptDefinedVar property; see the objects help page for details. (You can display an objects help page by selecting the object in the Objects view or, if the object is included in your project, the Features or Setup Design view.) For information on adding the ScriptDefinedVar property to an object that you have created, see Add a ScriptDefinedVar Property to My Object . In InstallScript MSI projects, this function was designed to set paths for public properties that are in the Directory table. You can create a new directory by clicking a components destination or a shortcuts target, and creating a new directory. This newly created directory has TARGETDIR as its Directory_Parent. Through script, you can use FeatureSetTarget to set this public property (directory).

Syntax
FeatureSetTarget ( szFeatureSource, szPropertyVar, szLocation );

800

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureSetTarget

Parameters
Table B-89: FeatureSetTarget Parameters Parameter szFeatureSource Description Specifies the media name of the file media library whose user-defined variable is to be set. Specifies the user-defined variable. In InstallShield, user-defined variables take the form <variable name>.

szPropertyVar

Project: (InstallScript MSI only:) The property used in this parameter must be a public property. You do not need to create an entry in the Property Manager for this property. If you intend to use the property as a destination, you must use it as a components destination, not a features destination. szLocation Specifies the path expression to substitute for the user-defined variable. This string should not include extra quotation marks, even if it specifies a long path. The value of szLocation can be a complete pathincluding drive letter and colonor a partial path, depending on how szPropertyVar is used.

Return Values
This function always returns 0.

FeatureSetTarget Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureSetTarget function. After adding this * to a script for an InstallScript project, you will see the * modified value of INSTALLDIR in the SdAskDestPath * dialog. In a project that had any components with OTHERLOC as * their destination, that would also be changed. * \*--------------------------------------------------------------*/ function OnBegin( ) begin // change values of directory properties INSTALLDIR and OTHERLOC for a first-time // installation if (!MAINTENANCE) then FeatureSetTarget(MEDIA, "<INSTALLDIR>", "C:\\RightHere"); FeatureSetTarget(MEDIA, "<OTHERLOC>", "C:\\SomewhereElse"); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

801

Appendix B: Built-In Functions (E-G) FeatureSetupTypeEnum

FeatureSetupTypeEnum
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureSetupTypeEnum function enumerates all setup types associated with the specified media. These setup types are defined by you in the IDE and stored in the file media. You must create the listSetupTypes string list using the ListCreate function.

Note: This function cannot be used with script-created feature sets.

Syntax
FeatureSetupTypeEnum ( szFeatureSource, listSetupTypes );

Parameters
Table B-90: FeatureSetupTypeEnum Parameters Parameter szFeatureSource Description Specifies the media name of the file media whose setup types are to be enumerated. Returns a list of all setup types in the specified media. The string list identified by listSetupTypes must already have been initialized by a call to ListCreate.

listSetupTypes

Return Values
Table B-91: FeatureSetupTypeEnum Return Values Return Value 0 <0 Description FeatureSetupTypeEnum was successful. FeatureSetupTypeEnum failed.

FeatureSetupTypeEnum Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureSetupTypeEnum function, *

802

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureSetupTypeGetData

* This script enumerates the setup types in the media. * * Note: To run this example script, create a project (or * insert into a project) with several setup types * defined. The value of DEFTYPE must be the name * of one of your setup types. * \*--------------------------------------------------------------*/ #define #define #define #define #define SDSHOWTITLE SDSHOWMSG SETUPTITLE SETUPMSG DEFTYPE "Setup Type Enumeration" MEDIA + " media's enumerated setup types are:" "Setup Type Selection" "Select a setup type." "Typical"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FeatureSetupTypeEnum(HWND); function ExFn_FeatureSetupTypeEnum(hMSI) LIST listID; STRING svSetupType; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Create a list to store setup types. listID = ListCreate ( STRINGLIST ); // Get the setup type names from the media into the list. if (FeatureSetupTypeEnum( MEDIA, listID) < 0 ) then MessageBox ("FeatureSetupTypeEnum failed.", WARNING); endif; // Display the setup types. SdShowInfoList (SDSHOWTITLE, SDSHOWMSG, listID); // Now show setup types in a selection dialog. svSetupType = DEFTYPE; SdSetupTypeEx (SETUPTITLE, SETUPMSG, "", svSetupType, 0); // Release the list from memory. ListDestroy (listID); end;

FeatureSetupTypeGetData
Project: This information applies to the following project types:

InstallScript InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

803

Appendix B: Built-In Functions (E-G) FeatureSetupTypeGetData

The FeatureSetupTypeGetData function retrieves data associated with a specified setup type. You can then use this data for any purpose. A typical application of FeatureSetupTypeGetData might be to display setup type information in a custom setup type-related dialog. You would call FeatureSetupTypeGetData inside the switch-case statement following the call to WaitOnDialog that displays the custom dialog.

Note: This function cannot be used with script-created feature sets.

Syntax
FeatureSetupTypeGetData ( szFeatureSource, szSetupType, nInfo, nvResult, svResult );

Parameters
Table B-92: FeatureSetupTypeGetData Parameters Parameter szFeatureSource Description Specifies the media name of the file media from which data associated with a setup type is to be retrieved. Specifies the setup type name. This name must be specified exactly as it appears in the InstallShield interfacefor example, Typical. Specifies the information to retrieve. Pass one of the following predefined constants in this parameter:

szSetupType

nInfo

nvResult svResult

SETUPTYPE_INFO_DESCRIPTIONRetrieves the description of the specified setup type. The description is returned in svResult. SETUPTYPE_INFO_DISPLAYNAMERetrieves the display name of the setup type. The name is returned in svResult.

Returns a NUMBER or LONG value when nInfo specifies information of that type. Returns a STRING value when nInfo specifies information of that type.

Return Values
Table B-93: FeatureSetupTypeGetData Return Values Return Value 0 <0 Description FeatureSetupTypeGetData was successful. FeatureSetupTypeGetData failed. Call FeatureError for additional information.

FeatureSetupTypeGetData Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script
804 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureSetupTypeGetData

* * Demonstrates the functions FeatureSetupTypeGetData, * FeatureGetData, FeatureSetData, SdFeatureDialog2, * and FeatureSelectItem. * * Notes: To run this example script, create a project with * the following features (f), subfeatures (sf), * and components (c): * * (f) Program_Files * (c) Program_DLLS * (c) Program_EXEs * (f) Example_Files * (sf) Small_Documents * (c) Small_Document_Examples * (sf) Books * (c) Book_Examples * (sf) Graphics * (c) Graphic_Examples * (f) Help_Files * (c) Help_Files * (f) Utilities * (sf) Grammar_Checker * (c) Grammar_Checker * (sf) Art_Studio * (c) Art_Studio * * Be sure to enter descriptions into the Description fields of * the feature properties sheets for the Program_Files and * Example_Files features and their subfeatures. * \*--------------------------------------------------------------*/ // Define strings. In a real installation, you would define these in the String Editor // view and precede each string identifier in the script with the at symbol (@). #define FEAT_SELECT_TITLE "Select Features" #define FEAT_SELECT_MSG1 "IMPORTANT! Note the various feature" #define FEAT_SELECT_MSG2 "and subfeature names, descriptions," #define FEAT_SELECT_MSG3 "and selection settings." #define FEAT_SELECT_MSG4 "IMPORTANT! Note the CHANGED feature" #define FEAT_SELECT_MSG5 "and subfeature name, description, " #define FEAT_SELECT_MSG6 "and selection settings." #define FEAT_PROGRAMFILES_DISPLAYNAME "Program Files" #define FEAT_EXAMPLEFILES_DISPLAYNAME "Example Files" #define FEAT_SMALLDOCUMENTS_DISPLAYNAME "Small Documents" #define FEAT_BOOKS_DISPLAYNAME "Books" #define FEAT_GRAPHICS_DISPLAYNAME "Graphics" #define SETUP_TYPE "Typical" // Global variable declarations. // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FeatureSetupTypeGetData(HWND); function ExFn_FeatureSetupTypeGetData(hMSI) STRING svInfo, szInfo, szFeature; NUMBER nvInfo, nInfo, nResult; begin // Get the description field data for the SETUP_TYPE setup type. FeatureSetupTypeGetData (MEDIA, SETUP_TYPE, SETUPTYPE_INFO_DESCRIPTION,
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 805

Appendix B: Built-In Functions (E-G) FeatureSetupTypeGetData

nvInfo, svInfo ); SprintfBox (INFORMATION, "FeatureSetupTypeGetData demo", "FeatureSetupTypeGetData got the following " + "value from the " + SETUP_TYPE + " description field:\n\n%s", svInfo); // Get the description field data for the FEAT_PROGRAMFILES_DISPLAYNAME // feature using FeatureGetData. szFeature = FEAT_PROGRAMFILES_DISPLAYNAME; nResult = FeatureGetData (MEDIA, szFeature, FEATURE_FIELD_DESCRIPTION, nvInfo, svInfo); SprintfBox (INFORMATION, "FeatureGetData demo", "FeatureGetData got the following value " + "from the " + FEAT_PROGRAMFILES_DISPLAYNAME + " description field:\n\n%s", svInfo); // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Show the original description field values // in the feature selection dialog. SdFeatureDialog2 (FEAT_SELECT_TITLE, FEAT_SELECT_MSG1 + FEAT_SELECT_MSG2 + FEAT_SELECT_MSG3, INSTALLDIR, ""); // Change the displayed names for the Program_Files feature and the // Example_Files feature and subfeatures. szInfo = "CHANGED Feature Name!"; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DISPLAYNAME, nInfo, szInfo); szFeature = FEAT_EXAMPLEFILES_DISPLAYNAME; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DISPLAYNAME, nInfo, szInfo); szFeature = FEAT_EXAMPLEFILES_DISPLAYNAME + "\\" + FEAT_SMALLDOCUMENTS_DISPLAYNAME; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DISPLAYNAME, nInfo, szInfo); szFeature = FEAT_EXAMPLEFILES_DISPLAYNAME + "\\" + FEAT_BOOKS_DISPLAYNAME; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DISPLAYNAME, nInfo, szInfo); szFeature = FEAT_EXAMPLEFILES_DISPLAYNAME + "\\" + FEAT_GRAPHICS_DISPLAYNAME; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DISPLAYNAME, nInfo, szInfo); // Change the descriptions displayed for the Program_Files feature // and the Example_Files feature and subfeatures. szFeature = FEAT_PROGRAMFILES_DISPLAYNAME; szInfo = "CHANGED description field value!"; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DESCRIPTION,
806 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureSetupTypeSet

nInfo, szInfo); szFeature = FEAT_EXAMPLEFILES_DISPLAYNAME; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DESCRIPTION, nInfo, szInfo); szFeature = FEAT_EXAMPLEFILES_DISPLAYNAME + "\\" + FEAT_SMALLDOCUMENTS_DISPLAYNAME; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DESCRIPTION, nInfo, szInfo); szFeature = FEAT_EXAMPLEFILES_DISPLAYNAME + "\\" + FEAT_BOOKS_DISPLAYNAME; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DESCRIPTION, nInfo, szInfo); szFeature = FEAT_EXAMPLEFILES_DISPLAYNAME + "\\" + FEAT_GRAPHICS_DISPLAYNAME; nResult = FeatureSetData (MEDIA, szFeature, FEATURE_FIELD_DESCRIPTION, nInfo, szInfo); // Deselect the Program_Files and Example_Files features (and all their // subfeatures, by extension). FeatureSelectItem (MEDIA, FEAT_PROGRAMFILES_DISPLAYNAME, FALSE); FeatureSelectItem (MEDIA, FEAT_EXAMPLEFILES_DISPLAYNAME, FALSE); // Display the features again, noting the changed names, descriptions, // and selection settings. SdFeatureDialog2 (FEAT_SELECT_TITLE, FEAT_SELECT_MSG4 + FEAT_SELECT_MSG5 + FEAT_SELECT_MSG6, INSTALLDIR, ""); end;

FeatureSetupTypeSet
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureSetupTypeSet function sets the specified setup type in the file media referenced by szFeatureSource. You can use FeatureSetupTypeSet to override the selection made in a setup type dialog, such as SdSetupTypeEx.

Note: This function cannot be used with script-created feature sets.

Syntax
FeatureSetupTypeSet ( szFeatureSource, szSetupType );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

807

Appendix B: Built-In Functions (E-G) FeatureSetupTypeSet

Parameters
Table B-94: FeatureSetupTypeSet Parameters Parameter szFeatureSource Description Specifies the media name of the file media whose setup type is to be set. Specifies which setup type to set.

szSetupType

Return Values
Table B-95: FeatureSetupTypeSet Return Values Return Value 0 <0 Description FeatureSetupTypeSet was successful. FeatureSetupTypeSet failed.

FeatureSetupTypeSet Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureSetupTypeSet function. * * Note: To run this example script, create a project (or * insert into a project) with several setup types and * features. Make sure you specify the setup types' * default feature selections. If you do not include * a Compact setup type, then define one of your setup * types as SETUP_TYPE in the #define SETUP_TYPE line * below. * \*--------------------------------------------------------------*/ #define #define #define #define #define #define #define #define SETUP_TYPE SDSETUPTITLE SDSETUPMSG SDFEATTITLE SDFEATMSG1 SDFEATMSG2 MSG1 MSG2 "Compact" "Setup Type Selection" "Select a setup type other than " + SETUP_TYPE + "." "Feature Selection" "Feature selection before FeatureSetupTypeSet." "Feature selection after FeatureSetupTypeSet." "FeatureSetupTypeSet will now select all\n" "features in the " + SETUP_TYPE + " setup type."

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FeatureSetupTypeSet(HWND); function ExFn_FeatureSetupTypeSet(hMSI) STRING szSetupType, svSetup, svDir; begin
808 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureSpendCost

// Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Select a setup type other than SETUP_TYPE to show default // selection settings. SdSetupTypeEx (SDSETUPTITLE, SDSETUPMSG, "", svSetup, 0); // Display the feature selections for the selected setup type. svDir = INSTALLDIR; SdFeatureMult (SDFEATTITLE, SDFEATMSG1, svDir, ""); MessageBox (MSG1 + MSG2, INFORMATION); // Now change/override the previous setup type // selecting SETUP_TYPE's features. All others szSetupType = SETUP_TYPE; if (FeatureSetupTypeSet (MEDIA, szSetupType) < MessageBox ("FeatureSetupTypeSet failed.", endif; selection by are deselected. 0) then SEVERE);

// Display the new feature selections. SdFeatureMult (SDFEATTITLE, SDFEATMSG2, svDir, ""); end;

FeatureSpendCost
Project: This information applies to InstallScript projects:

The FeatureSpendCost function tells the setup that the progress bar should be updated for a certain amount of cost that has been spent by an event external to the setup. This function has the effect of updating the progress bar appropriately as if the setup itself had spent the corresponding amount of cost. This function can only be called during a standard file operation event, such as an event resulting from calling FeatureTransferData or FeatureMoveData. Typically, this function is called during the OnInstalling or OnInstalled event as a result of an external event occurring that spends cost.

Note: It is not necessary to call this function for file transfer operations that the setup engine carries out, such as XCopyFile or CopyFile. These mechanisms automatically update the status bar during operation. However, FeatureAddCost must be called in this case (before file transfer operations begin) so the installation is aware of the additional cost.

Syntax
FeatureSpendCost ( nCostHigh, nCostLow );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

809

Appendix B: Built-In Functions (E-G) FeatureSpendUninstallCost

Parameters
Table B-96: FeatureSpendCost Parameters Parameter nCostHigh Description Specifies the upper 31 bits of the installation cost that should be spent. Specifies the lower 31 bits of the installation cost that should be spent.

nCostLow

Return Values
Table B-97: FeatureSpendCost Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully updated the progress bar. Indicates that the function was unable to update the progress bar.

FeatureSpendUninstallCost
Project: This function applies to InstallScript projects.

The FeatureSpendUninstallCost function is used to tell the setup that the progress bar should be updated for a certain amount of uninstall cost that has been spent by an event external to the setup. This function has the effect of updating the progress bar appropriately as if the setup itself had spent the corresponding amount of cost. This function can only be called during a standard file operation event, such as an event resulting from calling FeatureTransferData or FeatureMoveData. Typically, this function is called during the OnInstalling or OnInstalled event as a result of an external event occurring that spends cost.

Note: It is not necessary to call this function for file transfer operations that are listed the uninstall log file., such as XCopyFile or CopyFile operations. The status bar is updated automatically for items listed in the log file, note also that you do not need to call FeatureAddUninstallCost for items listed in the log file, as the setup automatically accounts for all items listed in the log file. However, FeatureAddCost must be called in this case so the file transfer operation is aware of the additional cost.

Syntax
FeatureSpendUninstallCost ( nOps, nOpType);

810

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureStandardSetupTypeSet

Parameters
Table B-98: FeatureSpendUninstallCost Parameters Parameter nOps nOpType Description The number of operations to spend. Indicates the type of operation. Pass one of the following predefined constants in this parameter:

FEATURE_OPCOST_UNINSTALL_FILESpecifies the operation as uninstalling a file. You can also specify this constant using the value 4096. This enables you to experiment with different sizes to determine what size to use for your custom operation. FEATURE_OPCOST_UNINSTALL_REGORINISpecifies the operation as uninstalling a registry file. You can also specify this constant using the value 2048. This enables you to experiment with different sizes to determine what size to use for your custom operation. FEATURE_OPCOST_UNINSTALL_UNREGFILESpecifies the operation as unregistering a file. You can also specify this constant using the value 16384. This enables you to experiment with different sizes to determine what size to use for your custom operation.

Note: You can also pass a numeric value in this parameter to indicate an operation of a specific cost. You may need to experiment with different values to determine the appropriate value for a specified custom operation. Note that the total uninstall cost added is nOps multiplied by nOpType.

Return Values
Table B-99: FeatureSpendUninstallCost Parameters Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully updated the progress bar. Indicates that the function was unable to update the progress bar.

FeatureStandardSetupTypeSet
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureStandardSetupTypeSet function sets the current setup type to the standard setup type specified by nSetupType. This function attempts to set the setup type by calling the FeatureSetupTypeSet function with the appropriate string to set the setup type. See the table with explanations of the parameters for this function for more information.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

811

Appendix B: Built-In Functions (E-G) FeatureStandardSetupTypeSet

Syntax
FeatureStandardSetupTypeSet ( szFeatureSource, nSetupType );

Parameters
Table B-100: FeatureStandardSetupTypeSet Parameters Parameter szFeatureSource nSetupType Description Specifies the media name of the file media whose setup type is to be set. Specifies which setup type to set. Pass one of the following predefined constants in this parameter:

TYPICAL COMPLETE COMPACT CUSTOM

You can customize the string setup type value associated with each numeric constant by customizing the global predefined script variables listed below. The function sets the setup or installation type by trying the appropriate script variable, then tries the setup type name in English and Japanese (see below). Also, when the COMPLETE setup type is specified, the function tries all TYPICAL values after checking the values for COMPLETE. If the setup type cannot be set to any of these values, the function returns failure. The following global predefined script variables can be customized:

SETUPTYPE_STR_TYPICALDefines the setup type that will be set by default if TYPICAL is specified. SETUPTYPE_STR_COMPLETEDefines the setup type that will be set by default if COMPLETE is specified. SETUPTYPE_STR_COMPACTDefines the setup type that will be set by default if COMPACT is specified. SETUPTYPE_STR_CUSTOMDefines the setup type that will be set by default if CUSTOM is specified.

The following table shows the values the FeatureStandardSetupTypeSet function uses when each constant is specified in the nSetupType parameter.
Table B-101: nSetupType Constants Constant TYPICAL Strings Used SETUPTYPE_STR_TYPICAL Typical Standard W (represents Japanese text)

812

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureTotalSize

Table B-101: nSetupType Constants (cont.) Constant COMPLETE Strings Used SETUPTYPE_STR_COMPLETE Complete Vollstndig (represents Japanese text) COMPACT SETUPTYPE_STR_COMPACT Compact Minimal (represents Japanese text) CUSTOM SETUPTYPE_STR_CUSTOM Custom Benutzer Benutzerdefiniert (represents Japanese text)

Return Values
Table B-102: FeatureStandardSetupTypeSet Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description FeatureStandardSetupTypeSet was able to set the specified setup type. FeatureStandardSetupTypeSet was unable to set the specified setup type.

FeatureTotalSize
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The FeatureTotalSize function returns the total sizein bytesof the features referenced by szFeature.

To include subfeatures in the size calculation, set bIncludeSubcomp to TRUE. To get the total size of all the features in the specified media, set szFeature to a null string ("") and set bIncludeSubcomp to TRUE.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

813

Appendix B: Built-In Functions (E-G) FeatureTotalSize

Note: There might be a difference between the value returned by FeatureTotalSize and the space required values displayed in the SdFeatureDialog, SdFeatureDialog2, SdFeatureDialogAdv, and SdFeatureMult dialogs. This difference is due to the fact that this function does not take into account whether any components associated with the feature are currently filtered by operating system or language, or the cluster size on the target drive. To obtain a drive space calculation that takes these factors into account, call FeatureGetCost.

Syntax
FeatureTotalSize ( szFeatureSource, szFeature, bIncludeSubcomp, bTargetSize );

Parameters
Table B-103: FeatureTotalSize Parameters Parameter szFeatureSource Description Specifies the name of the file media from which the total size of selected features is to be returned. Specifies the name of the feature whose size is to be retrieved. To retrieve the size of the entire media, pass a null string ("") in this parameter. Indicates whether to include selected subfeatures of szFeature. Pass one of the following predefined constants in this parameter:

szFeature

bIncludeSubcomp

bTargetSize

TRUEInclude selected subfeatures in the size calculation. FALSEDo not include subfeatures in the size calculation.

Indicates whether to retrieve the original, uncompressed size or the size in the media library. Pass one of the following predefined constants in this parameter:

TRUERetrieve the original, uncompressed size. FALSERetrieve the size in the media library.

Return Values
Table B-104: FeatureTotalSize Return Values Return Value XXXX <0 Description The total size, in bytes, of the selected features. FeatureTotalSize failed. Call FeatureError for additional information.

FeatureTotalSize Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FeatureListItems, SdFeatureMult, and
814 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureTotalSize

* FeatureTotalSize functions. * * Comments: To run this example script, create a project with * the following features (f), subfeatures (sf), * and components (c): * * (f) Program_Files * (c) Program_DLLS * (c) Program_EXEs * (f) Example_Files * (sf) Small_Documents * (c) Small_Document_Examples * (sf) Books * (c) Book_Examples * (sf) Graphics * (c) Graphic_Examples * (f) Help_Files * (c) Help_Files * (f) Utilities * (sf) Grammar_Checker * (c) Grammar_Checker * (sf) Art_Studio * (c) Art_Studio * \*--------------------------------------------------------------*/ #define #define #define #define FEAT_SELECT_TITLE FEAT_SELECT_MSG FEATTOTSIZEMSG1 FEATTOTSIZEMSG2 "Select Features" "Select features and subfeatures to install." "Want to change feature selections and see\n" "size change reflected in FeatureTotalSize call?"

// Global variable declarations. // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FeatureTotalSize(HWND); function ExFn_FeatureTotalSize(hMSI) STRING szDir, svString; NUMBER nResult, nDone; LIST listCompList, listTemp; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Create a string list of all top-level features. listCompList = ListCreate (STRINGLIST); FeatureListItems (MEDIA, "", listCompList); // Display the string list of top-level features. SdShowInfoList ("List MEDIA Features", "MEDIA contains " + "the following top-level features:", listCompList); // Get each top-level feature in listCompList, in turn, and // list and display all of its subfeatures, if any. nResult = ListGetFirstString ( listCompList, svString ); while ( nResult != END_OF_LIST ) listTemp = ListCreate (STRINGLIST); FeatureListItems (MEDIA, svString, listTemp); SdShowInfoList ("Subfeature Listing", svString + " contains " +
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 815

Appendix B: Built-In Functions (E-G) FeatureTransferData

"the following subfeatures:", listTemp); ListDestroy (listTemp); nResult = ListGetNextString (listCompList, svString); endwhile; // Show feature selection dialog and total size of all selected // features. Loop to change selections and see total size change // reflected in the call to FeatureTotalSize. nDone = YES; while (nDone = YES) szDir = INSTALLDIR; SdFeatureMult (FEAT_SELECT_TITLE, FEAT_SELECT_MSG, szDir, "" ); nResult = FeatureTotalSize(MEDIA, "", TRUE, TRUE); SprintfBox (INFORMATION, "", "Total size of all files " + "in SELECTED features:\n\n%ld", nResult); nDone = AskYesNo (FEATTOTSIZEMSG1 + FEATTOTSIZEMSG2, YES); endwhile; ListDestroy (listCompList); end;

FeatureTransferData
Project: This information applies to the following project types:

InstallScript InstallScript MSIif the InstallScript user interface (UI) style is the traditional style (which uses the InstallScript engine as an external UI handler)

This information does not apply to InstallScript MSI projects in which the InstallScript UI style is the new style (which uses the InstallScript engine as an embedded UI handler). To learn more, see Using the InstallScript Engine as an External vs. Embedded UI Handler for InstallScript MSI Installations.

If you use an event-based script, the FeatureTransferData function is called automatically after the OnFirstUIBefore event and interacts with the OnMoving, OnMoved, and feature events. FeatureTransferData installs or uninstalls features appropriately based on their selection state and whether they are currently installed. FeatureTransferData does the following:

Installs features that are selected (for example, by end user selections in feature or setup type dialogs) and are currently not installed. Uninstalls features that are not selected and are currently installed. The installation determines whether a feature is currently installed by reading the existing log file during installation initialization. If no valid log file is found during installation initialization, all features are considered to be not installed.

The installation determines whether a feature is currently installed by reading the existing log file during installation initialization. If no valid log file is found during installation initialization, all features are considered to be not installed.

816

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureUpdate

When you call FeatureTransferData, Do (SELFREGISTRATIONPROCESS) is called automatically after the files are installed but before the call returns. Therefore, if your installation needs to perform additional actions after the file transfer but before self-registration, place these actions in the OnMoved event; the OnMoved event is called after the file transfer but before the batch self-registration occurs.

Syntax
FeatureTransferData ( szFeatureSource );

Parameters
Table B-105: FeatureTransferData Parameters Parameter szFeatureSource Description Specifies the media name of the file media whose features have been specified for installation and uninstallation. Typically, you would pass the system variable MEDIA in this parameter.

Return Values
Table B-106: FeatureTransferData Return Values Return Value 0 Description Indicates that the function successfully performed the feature installations and uninstallations. Indicates that the function could not perform the feature installations and uninstallations.

<0

Additional Information
You can call one of the following functions before calling FeatureTransferData to affect the result of the call:

FeatureReinstallReinstalls all features that are currently selected when FeatureTransferData is called. FeatureRemoveAllRemoves (uninstalls) all features when FeatureTransferData is called.

FeatureUpdate
Project: This information applies to InstallScript project.

The FeatureUpdate function causes the next call to FeatureTransferData (or FeatureMoveData) to reinstall all features that are already installed when FeatureTransferData is called, except the maintenance/uninstallation feature. (Note that this feature is automatically placed in your .cab files by the media builder and is not displayed in InstallShield.)

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

817

Appendix B: Built-In Functions (E-G) FeatureUpdate

Syntax
FeatureUpdate ( szReserved );

Parameters
Table B-107: FeatureUpdate Parameters Parameter szReserved Description Pass a null string ("") in this parameter. No other value is allowed.

Return Values
Table B-108: FeatureUpdate Return Values Return Value 0 <0 Description Indicates that the function succeeded. Indicates that the function failed.

Additional Information
Call FeatureUpdate in an installation whose maintenance/uninstallation feature you do not want to be used during subsequent maintenance operations (modifying, repairing, or uninstalling). FeatureUpdate is typically called in an update or add-on installation, in which the installation media does not contain all the elements of the previous media and thus should not be used for subsequent maintenance operations. FeatureUpdate is similar to FeatureReinstall, but FeatureReinstall also reinstalls the maintenance/ uninstallation feature.

Note: If you call both FeatureUpdate and FeatureReinstall, the call to FeatureUpdate will not have any effect; so if you call FeatureUpdate, do not call FeatureReinstall in the same installation. Call FeatureUpdate to update only applications that were installed with the same version of InstallShield as the update installation. If you call FeatureUpdate to update an application that was installed with a previous version of InstallShield, the maintenance/uninstallation files will not be updated, so any subsequent maintenance operations will use the maintenance/ uninstallation files that were created with the previous version.

The following information applies in this situation: A previously released version of your application was installed by an installation that aborts if a newer version of the application is present. In this case, FeatureUpdate should not be called in an update installation that changes the version number of the installed application. Otherwise, after the update installation runs, the currently installed application cannot be uninstalled. For sample projects using FeatureUpdate in patch or maintenance pack installations, see Knowledge Base article Q104431 INFO: The Creating Updates/ Maintenance Packs Sample.

818

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FeatureValidate

FeatureValidate
Project: This information applies to InstallScript projects.

Note: This function cannot be used with script-created feature sets.

The FeatureValidate function validates the password of the file media library or of a specified feature.

Syntax
FeatureValidate ( szMediaLibrary, szFeature, szPassword );

Parameters
Table B-109: FeatureValidate Parameters Parameter szMediaLibrary szFeature Description Specifies the name of the file media library whose password is to be validated. Specifies the name of the feature. If this parameter is a null string (""), the entire media library is assumed. Specifies the password to be validated.

szPassword

Return Values
Table B-110: FeatureValidate Return Values Return Value 0 <0 Description FeatureValidate was successful. FeatureValidate failed. Call FeatureError for additional information. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

FeatureValidate Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions SdSetupTypeEx, SdFeatureDialog, * FeatureIsItemSelected, FeatureGetData, and FeatureValidate. * * Notes: To run this example script, create a project with * the following features (f), subfeatures (sf), * and components (c):
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 819

Appendix B: Built-In Functions (E-G) FeatureValidate

* * (f) Program Files * (c) Program DLLS * (c) Program EXEs * (f) Example Files * (sf) Small Documents * (c) Small Document Examples * (sf) Books * (c) Book Examples * (sf) Graphics * (c) Graphic Examples * (f) Help Files * (c) Help Files * (f) Utilities * (sf) Grammar Checker * (c) Grammar Checker * (sf) Art Studio * (c) Art Studio * (f) Evaluation Copy * (c) Evaluation Copy * (c) Help Files * * Insert "dummy" files into the components. Make sure you * define the correct file name for the main EXE (MAIN_EXE, * below) that you insert into the Program EXEs components. * Run the setup with and without a password assigned to the * Program Files feature (remember to rebuild your media * each time). * * You can also create billboards (name them Bbrd1.bmp, * Bbrd2.bmp, and Bbrd3.bmp) and add them to the project in * the Support Files/Billboards's Language Independent folder. * * This example script installs files, adds an icon to the * Start Programs menu, and provides uninstallation * functionality. * \*--------------------------------------------------------------*/ // Define strings. In a real installation, you would define these in the String Editor // view and precede each string identifier in the script with the at symbol (@). #define FEATURE_SELECT_TITLE "Select Features" #define FEATURE_SELECT_MSG "Select features and subfeatures to install." #define FEATURE_PROGRAMFILES_DISPLAYNAME "Program Files" #define PASSWORD_PROMPT "Please enter the password." #define PASSWORD_ERRMSG "Password incorrect. Please enter again."

// Global variable declarations. STRING svData, svLogFile, szProgram, szFeature, svResult, svSetupType, svDir; BOOL bInitStepsDone, bPwdValid; NUMBER nvData, nResult; #include "ifx.h" function OnFirstUIBefore() begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Get the setup type.
820 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FileCompare

svDir = TARGETDIR; SdSetupTypeEx (SETUPTYPE_TITLE, SETUPTYPE_MSG, "", svSetupType, 0); // If user selected Custom setup type, display feature selection dialog. if (svSetupType = SETUPTYPE_CUSTOM) then SdFeatureDialog (FEATURE_SELECT_TITLE, FEATURE_SELECT_MSG, svDir, ""); endif; // Enable the Back button in setup dialogs. Enable (BACKBUTTON); // If the Program Files feature is selected and there is a password // associated with it, the user must input the password and // it must be validated. nResult = FALSE; nvData = FALSE; nResult = FeatureIsItemSelected (MEDIA, FEATURE_PROGRAMFILES_DISPLAYNAME); FeatureGetData (MEDIA, FEATURE_PROGRAMFILES_DISPLAYNAME, FEATURE_FIELD_PASSWORD, nvData, svData); if (nResult && nvData) then bPwdValid = FALSE; Disable (BACKBUTTON); // Back button not needed or supported here. while (!bPwdValid) AskText (PASSWORD_PROMPT, "", svResult); nResult = FeatureValidate (MEDIA, FEATURE_PROGRAMFILES_DISPLAYNAME, svResult); if (nResult = 0) then bPwdValid = TRUE; else MessageBox (PASSWORD_ERRMSG, SEVERE); endif; endwhile; Enable (BACKBUTTON); // Restore Back button's default status. endif; end;

FileCompare
The FileCompare function compares the size, dates, contents, or versions of two files.

Syntax
FileCompare ( szFileName1, szFileName2, nCompareFlag );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

821

Appendix B: Built-In Functions (E-G) FileCompare

Parameters
Table B-111: FileCompare Parameters Parameter szFileName1 Description Specifies the name of the first file to compare. The installation uses the system variable SRCDIR as the path of the file. Specifies name of the second file to compare. The installation uses one of the following system variables as the path of the file:

szFileName2

nCompareFlag

TARGETDIR (in an InstallScript installation) INSTALLDIR (in an Basic MSI or InstallScript MSI installation)

Specifies comparison options. Pass one of the following predefined constants in this parameter:

COMPARE_SIZECompares the size of the two files. COMPARE_DATECompares the dates of the two files. COMPARE_VERSIONCompares the version resource of the two files. COMPARE_MD5_SIGNATURECompares the MD5 signature of the two files. If the MD5 signatures match, the contents of the files are identical.

Return Values (when COMPARE_MD5_SIGNATURE is specified)

Table B-112: FileCompare Return Values (COMPARE MD5_SIGNATURE) Return Value >= ISERR_SUCCESS Description The function successfully compared the files, specifically:

<= ISERR_SUCCESS

EQUALSThe files MD5 signatures are the same (the files contents are the same). NOT_EQUALSThe files MD5 signatures are not the same.

The function failed to compare the files.

Return Values (when COMPARE_SIZE, COMPARE_DATE, or COMPARE_VERSION is specified)

Table B-113: FileCompare Return Values (COMPARE_SIZE, COMPARE_DATE, or COMPARE_VERSION) Return Value >= ISERR_SUCCESS Description The function successfully compared the files, specifically:

<= ISERR_SUCCESS

EQUALSThe first file's date, size, or version is equal to that of the second file. GREATER_THANThe first file is newer or larger than the second file. LESS_THANThe first file is older or smaller than the second file.

The function failed to compare the files.

822

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FileCompare

FileCompare Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FileCompare function. * * This example script calls FileCompare three times: * * -- The first call compares the version of FILE_COMP1 in SDIR * to the version of FILE_COMP2 in TDIR. * * -- The second call checks if FILE_COMP1 was created earlier * than FILE_COMP2. * * -- The third call checks if FILE_COMP1 is smaller than * FILE_COMP2. * * Note: Before you run this script, set the preprocessor * constants so that they reference existing files in * existing directories on the target computer. * \*--------------------------------------------------------------*/ #define #define #define #define #define SDIR TDIR FILE_COMP1 FILE_COMP2 MSG_TITLE "C:\\" "C:\\" "Example1.dll" "Example2.dll" "FileCompare Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FileCompare(HWND); function ExFn_FileCompare(hMSI) NUMBER nResult; begin /*-----------------------------------------------------------*\ * * Compare the versions of the two files. * \*-----------------------------------------------------------*/ nResult = FileCompare (SDIR ^ FILE_COMP1, TDIR ^ FILE_COMP2, COMPARE_VERSION); // Report an error and terminate if either file is not found. if (nResult = FILE_NOT_FOUND) then SprintfBox (INFORMATION, MSG_TITLE, "%s and/or %s not found.", FILE_COMP1, FILE_COMP2); abort; endif;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

823

Appendix B: Built-In Functions (E-G) FileCompare

// Files are present so report the result of the comparison. switch (nResult) case EQUALS: SprintfBox (INFORMATION, MSG_TITLE, "%s is the same version as %s.", FILE_COMP1, FILE_COMP2); case GREATER_THAN: SprintfBox (INFORMATION, MSG_TITLE, "%s is a newer version than %s.", FILE_COMP1, FILE_COMP2); case LESS_THAN: SprintfBox (INFORMATION, MSG_TITLE, "%s is an older version than %s.", FILE_COMP1, FILE_COMP2); case OTHER_FAILURE: SprintfBox (INFORMATION, MSG_TITLE, "Version information not available in %s and/or %s.", FILE_COMP1, FILE_COMP2); endswitch; /*-----------------------------------------------------------*\ * * Compare the creation dates. * \*-----------------------------------------------------------*/ nResult = FileCompare (SDIR ^ FILE_COMP1, TDIR ^ FILE_COMP2, COMPARE_DATE); switch (nResult) case LESS_THAN: SprintfBox (INFORMATION, MSG_TITLE, "%s was created earlier than %s.", FILE_COMP1, FILE_COMP2); case GREATER_THAN: SprintfBox (INFORMATION, MSG_TITLE, "%s was created earlier than %s.", FILE_COMP2, FILE_COMP1); case EQUALS: SprintfBox (INFORMATION, MSG_TITLE, "%s and %s have the same creation date and time.", FILE_COMP1, FILE_COMP2); default: SprintfBox (INFORMATION, MSG_TITLE, "Unable to compare the creation date and time of %s and %s.", FILE_COMP2, FILE_COMP1); endswitch; /*-----------------------------------------------------------*\ * * Compare the file sizes. * \*-----------------------------------------------------------*/ nResult = FileCompare (SDIR ^ FILE_COMP1, TDIR ^ FILE_COMP2, COMPARE_SIZE); switch (nResult) case LESS_THAN: SprintfBox (INFORMATION, MSG_TITLE, "%s is smaller than %s.", FILE_COMP1, FILE_COMP2); case GREATER_THAN: SprintfBox (INFORMATION, MSG_TITLE,
824 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FileDeleteLine

"%s is smaller than %s.", FILE_COMP2, FILE_COMP1); case EQUALS: SprintfBox (INFORMATION, MSG_TITLE, "%s and %s are the same size.", FILE_COMP1, FILE_COMP2); default: SprintfBox(INFORMATION, MSG_TITLE, "Unable to compare the size of %s and %s.", FILE_COMP1, FILE_COMP2); endswitch; end;

FileDeleteLine
The FileDeleteLine function deletes a range of lines (including the starting line and ending line) from a text file using a starting and ending line number. This function works on line-oriented text filesit does not work with binary files. You can use FileDeleteLine with the FileGrep function to search and delete text lines in a file.

Caution: The file specified by szFileName must not already have been opened by a call to OpenFile. If szFileName is already open, call CloseFile before calling FileDeleteLine.

Syntax
FileDeleteLine ( szFileName, nStartLineNum, nEndLineNum );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

825

Appendix B: Built-In Functions (E-G) FileDeleteLine

Parameters
Table B-114: FileDeleteLine Parameters Parameter szFileName Description Specifies the unqualified name of a file located in the directory specified by the system variable SRCDIR, or the fully qualified path to the file. The lines specified by nStartLineNum and nEndLineNum will be deleted from that file if it exists. Specifies the number of the first line to delete from the file. Note that line numbering begins at 0. Specifies the number of the last line to delete from the file. Note that line numbering begins at 0. To delete from the line specified by nStartLineNum to the end of the file, pass the predefined constant DELETE_EOF in this parameter.

nStartLineNum

nEndLineNum

Return Values
Table B-115: FileDeleteLine Return Values Return Value 0 <0 Description FileDeleteLine successfully deleted the specified lines from the file. FileDeleteLine failed because of one of the following conditions:

FILE_NOT_FOUND (-2)The installation could not find the file in szFileName. FILE_RD_ONLY (-5)The file is write-protected. LINE_NUMBER (-7)One of the line numbers you specified is less than zero, or the line number does not exist in the file. OUT_OF_DISK_SPACE (-6)There is insufficient space on the disk drive to complete the specified operation. OTHER_FAILURE (-1)Some other unspecified error has occurred.

FileDeleteLine Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FileDeleteLine function. * * This script searches a file for the first line that includes * the string "PATH". If a line with that string is found, it * is deleted. Finally, a new line is added to the file at the * position of the deleted line. If a line with the word * "PATH" was not found, the new line is inserted at the top of
826 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FileDeleteLine

* the file. * * Note: Before running this script, create a batch file * named ISExampl.bat in the root of drive C. For * best effect, that file should include PATH command. * \*--------------------------------------------------------------*/ #define SDIR #define EXAMPLE_BAT #define TITLE "C:\\" "ISExampl.bat" "FileDeleteLine Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FileDeleteLine(HWND); function ExFn_FileDeleteLine(hMSI) STRING szSearchStr, svReturnLine, szNewString, szMsg; NUMBER nvResult, nvLineNum; begin // Set up the search string parameter for FileGrep. szSearchStr = "PATH"; // Find the search string in the specified file. nvResult = FileGrep (SDIR ^ EXAMPLE_BAT, szSearchStr, svReturnLine, nvLineNum, RESTART); switch(nvResult) case FILE_NOT_FOUND: // Report error; then terminate. MessageBox (EXAMPLE_BAT + " not found.", WARNING); abort; case FILE_LINE_LENGTH: // Report error; then terminate. MessageBox (EXAMPLE_BAT + "lines too long.", WARNING); abort; case OTHER_FAILURE: // Report error; then terminate. MessageBox (EXAMPLE_BAT + "Unknown failure on call to FileGrep.", WARNING); abort; case END_OF_FILE: // Report that the search string was not found. szMsg = "\"%s\" not found in %s."; SprintfBox (INFORMATION, TITLE, szMsg, szSearchStr, EXAMPLE_BAT); // Set the line number parameter for FileInsertLine. nvLineNum = 0; case 0: // Delete the line with the search string. if (FileDeleteLine (EXAMPLE_BAT, nvLineNum, nvLineNum) < 0) then MessageBox ("Failed on call to FileDeleteLine.", SEVERE); abort; else // Report the deletion. szMsg = "\"%s\" found in line %d of %s:\n\n%s\n\n\Line deleted. "; SprintfBox (INFORMATION, TITLE, szMsg, szSearchStr, nvLineNum, EXAMPLE_BAT, svReturnLine); endif; endswitch;
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 827

Appendix B: Built-In Functions (E-G) FileGrep

// Set up the new string parameter for FileInsertLine. szNewString = "PATH=C:\\Windows\\Bin;C:\\Bin;C:\\Ishield;"; // Insert the new string. if (FileInsertLine (EXAMPLE_BAT, szNewString, nvLineNum, BEFORE) < 0) then // Report an error. MessageBox ("Failed on call to FileInsertLine.", SEVERE); else // Report success. szMsg = "The following string was inserted as line %d of %s:\n\n %s"; SprintfBox (INFORMATION, TITLE, szMsg, nvLineNum, EXAMPLE_BAT, szNewString); endif; end;

FileGrep
The FileGrep function searches a text file for a specified string. If the string is found, the line containing that string is returned in svReturnLine and the number of the line is returned in nvLineNumber. The search is not case-sensitive. FileGrep works on line-oriented text files; it will not work with binary files.

Note: It is not necessary to open a file before searching it with FileGrep; nor do you need to close it after the call to FileGrep. File open and file close are performed automatically by FileGrep. Although FileGrep will perform successfully in most cases on a file that is already open as a result of a previous call to OpenFile, it will return FILE_NOT_FOUND if the file was opened in append mode.

Syntax
FileGrep ( szFileName, szSearchStr, svReturnLine, nvLineNumber, nFlag );

828

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FileGrep

Parameters
Table B-116: FileGrep Parameters Parameter szFileName szSearchStr svReturnLine nvLineNumber nFlag Description Specifies the fully qualified name of the file to search. Specifies the search string. Returns the line in which szSearchStr was found. Return the number of the line in which szSearchStr was found. Line numbering starts at 0. Specifies search options. Pass one of the following predefined constants in this parameter:

CONTINUERetrieves the next occurrence (if any) of the search string. RESTARTRetrieves the first instance of the search string.

Return Values
Table B-117: FileGrep Return Values Return Value 0 <0 Description FileGrep found the specified string. FileGrep failed because of one of the following conditions:

END_OF_FILE (-4)The end of file was reached without finding the search string. FILE_NOT_FOUND (-2)InstallShield was unable to find the file in szFileName. FILE_LINE_LENGTH (-3)The line exceeds the maximum length allowed. OTHER_FAILURE (-1)An unspecified error has occurred.

FileGrep Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FileGrep function. * * FileGrep is called to search a file for the first line that * contains the word "PATH". The results are displayed in a * message box. Note that the FileGrep function is not case * sensitive. * * Note: Before running this script, create a batch file

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

829

Appendix B: Built-In Functions (E-G) FileGrep

* named ISExampl.bat in the root of drive C. For * best effect, that file should include PATH command. * \*--------------------------------------------------------------*/ #define #define SOURCE_DIR "C:\\" SOURCE_FILE "ISExampl.bat"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FileGrep(HWND); function ExFn_FileGrep(hMSI) STRING svLine, szNewString, svReturnLine, szMsg; NUMBER nvLineNumber, nvResult; begin // Find the search string in the source file. nvResult = FileGrep (SOURCE_DIR ^ SOURCE_FILE, "PATH", svReturnLine, nvLineNumber, RESTART); switch(nvResult) case FILE_NOT_FOUND: // Report error; then abort. MessageBox( SOURCE_FILE + " not found.", WARNING); abort; case FILE_LINE_LENGTH: // Report error; then abort. MessageBox (SOURCE_FILE + "lines too long.", WARNING); abort; case OTHER_FAILURE: // Report error; then abort. MessageBox (SOURCE_FILE + "Unknown failure on call to FileGrep.", WARNING); abort; endswitch; // Loop until end of file. while (nvResult != END_OF_FILE) // Set up message string for SprintfBox. szMsg = "'PATH' found in line %d of %s:\n\n'%s'"; // Report matching line from file. SprintfBox (INFORMATION, "FileGrep", szMsg, nvLineNumber, SOURCE_FILE, svReturnLine); // Search again. nvResult = FileGrep (SOURCE_DIR ^ SOURCE_FILE, "PATH", svReturnLine, nvLineNumber, CONTINUE); endwhile; end;

830

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FileInsertLine

FileInsertLine
The FileInsertLine function inserts or replaces a line using line numbers. You can use FileInsertLine with FileGrep, which finds lines and returns their line numbers. FileInsertLine works on line-oriented text files with lines that are no longer than 1,024 bytes. With InstallShield, a line longer than the maximum allowed length indicates a binary file and causes FileInsertLine to fail.

Caution: The file specified by szFileName must not already have been opened by a call to OpenFile. If szFileName is already open, call CloseFile before calling FileInsertLine.

Syntax
FileInsertLine (szFileName, szInsertLine, nLineNumber, nInsertFlag);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

831

Appendix B: Built-In Functions (E-G) FileInsertLine

Parameters
Table B-118: FileInsertLine Parameters Parameter szFileName Description Specifies the unqualified name of a file located in the directory specified by the system variable SRCDIR, or the fully qualified path to the file. The value of szInsertLine is inserted into that file if it exists. Specifies the string to insert into the file. Specifies the line number at which you want to insert szInsertLine. The first line number is 0. Specifies an insertion location option. Pass one of the following predefined constants in this parameter:

szInsertLine nLineNumber nInsertFlag

BEFOREInserts the line before nLineNumber. AFTERInserts the line after nLineNumber. APPENDAppends szInsertLine to the line indicated by nLineNumber. REPLACEReplaces the line indicated by nLineNumber with szInsertLine.

Return Values
Table B-119: FileInsertLine Return Values Return Value 0 <0 Description FileInsertLine successfully inserted the line into the specified file. FileInsertLine failed because of one of the following conditions:

FILE_LINE_LENGTH (-3)Indicates that the length of the line exceeds the maximum length allowed for text files. FILE_NOT_FOUND (-2)FileInsertLine was unable to find the file in szFileName. FILE_RD_ONLY (-5)Indicates that the file is write-protected. LINE_NUMBER (-7)Indicates that one of the line numbers you specified is less than zero, or the line number does not exist in the file. OUT_OF_DISK_SPACE (-6)Indicates that there is insufficient space on the disk drive to complete the specified operation. OTHER_FAILURE (-1)An unspecified error has occurred.

FileInsertLine Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ *
832 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FileInsertLine

* InstallShield Example Script * * Demonstrates the FileInsertLine function. * * The AskText dialog is displayed to obtain a line of text * from the user. This text is then inserted as the first line * in the text file specified by TARGET_FILE. * * FileInsertLine is then called again to append the same text * to the first line, leaving two copies of the same text in * the first line of the file. * * Note: Before running this script, create a batch file named * ISExampl.bat in the root of drive SRCDIR. * \*--------------------------------------------------------------*/ #define TARGET_FILE #define TITLE "ISExampl.bat" "FileInsertLine Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FileInsertLine(HWND); function ExFn_FileInsertLine(hMSI) STRING szMsg, svText; begin // Set up message parameter for call to AskText. szMsg = "Please enter a line to insert into EXAMPLE.BAT."; // Get line to add to file. AskText (szMsg, "", svText); // Insert the text as the first line of the specified file. if (FileInsertLine (TARGET_FILE, svText, 0, BEFORE) < 0) then MessageBox ("FileInsertLine failed.", SEVERE); else // Set up message parameter for call to SprintfBox. szMsg = "'%s' successfully inserted as first line of %s."; // Display message. SprintfBox (INFORMATION, TITLE, szMsg, svText, TARGET_FILE); endif; // Append the same string to the same line. if (FileInsertLine(TARGET_FILE, svText, 0, APPEND) < 0) then MessageBox("FileInsertLine failed.", SEVERE); else // Set up message parameter for call to SprintfBox. szMsg = "'%s' successfully appended to first line of %s."; // Display message. SprintfBox(INFORMATION, TITLE, szMsg, svText, TARGET_FILE); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

833

Appendix B: Built-In Functions (E-G) FindAllDirs

FindAllDirs
The FindAllDirs function searches an entire hierarchical disk or directory structure starting with the specified directory, and it returns a string list of subdirectory names. You can use FindAllDirs to find either subdirectories of a certain directory, or you can use it to find all the directories on a disk. If nOp is INCLUDE_SUBDIR, the search starts at the directory specified by szDir and continues searching the subdirectory structure. If the specified directory is a root directory and nOp contains INCLUDE_SUBDIR, all the directory names on the entire disk are returned.

Syntax
FindAllDirs ( szDir, nOp, listDirs );

834

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FindAllDirs

Parameters
Table B-120: FindAllDirs Parameters Parameter szDir Description Specifies the name of the directory to search.

Note: If the directory is enclosed in quotation marks, FindAllDirs fails. To ensure that the folder name is not enclosed in quotation marks, call LongPathToQuote (szPath, FALSE) before calling FindAllDirs. nOp Specifies whether or not to search all of the subdirectories below szDir. Pass one of the following predefined constants in this parameter:

listDirs

EXCLUDE_SUBDIRExcludes subdirectories. INCLUDE_SUBDIRIncludes subdirectories.

Returns a list of fully qualified directory names. The string list identified by listDirs must already have been initialized by a call to ListCreate.

Return Values
Table B-121: FindAllDirs Return Values Return Value 0 <0 Description FindAllDirs successfully generated the list of subdirectory names. FindAllDirs function was unable to generate a list.

FindAllDirs Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * This example demonstrates the FindAllDirs function. * * FindAllDirs is called to retrieve all directories located * in a specified directory. Subdirectories are included at * the user's discretion. * \*--------------------------------------------------------------*/ #define TITLE "FindAllDirs Example"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

835

Appendix B: Built-In Functions (E-G) FindAllFiles

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FindAllDirs(HWND); function ExFn_FindAllDirs(hMSI) LIST listDirs; STRING svSearchPath, szMsg; NUMBER nOp, nResult; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Ask the user for a path. AskPath ("Enter an existing path.", "", svSearchPath); // Ask whether or not to include subdirectories. if (AskYesNo ("Include subdirectories?", YES) = YES) then nOp = INCLUDE_SUBDIR; szMsg = "Directories and Subdirectories"; else nOp = EXCLUDE_SUBDIR; szMsg = "Directories only"; endif; // Display a message while building the list. SdShowMsg ("Searching . . . please wait.", TRUE); // Create a STRING list for directory names. listDirs = ListCreate (STRINGLIST); // Find requested elements place them into the list. nResult = FindAllDirs (svSearchPath, nOp, listDirs); // Close the message box. SdShowMsg ("", FALSE); if ( nResult< 0) then // Report no matches. SprintfBox (INFORMATION, TITLE, "No directories in %s", svSearchPath); else // Display the list. SdShowInfoList (TITLE, szMsg, listDirs); endif; end;

FindAllFiles
The FindAllFiles function searches an entire hierarchical subdirectory structure starting with the specified directory, and it returns the name of the first file with a particular file specification. If the specified directory is the root directory, InstallShield searches the entire disk. The function stops at the first matching file name it finds.

836

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FindAllFiles

Note: If the argument passed to nOp is RESET, InstallShield starts searching at the directory specified in the parameter szDir and continues searching the subdirectory structure until it finds a file matching szFileName. If nOp equals CONTINUE, the search continues where it finished the last time the function was called. Call this function repeatedly to find all occurrences of files that match szFileName. The first time you call this function to begin a new search, set nOp to RESET. You can continue to search for all other occurrences of the specified file by setting nOp to CONTINUE and placing the function call in a loop that ends when the FindAllFiles function fails.

Finding Files that Match a File Specification

Task

To find all files matching a file specification:

1.
2. 3. 4. 5.

Assign to szDir the name of the folder to search. Assign to szFileName the file specification, such as IS5*.txt. Call FindAllFiles with nOp set to RESET. While the return code from FindAllFiles is 0, save the file name in svResult; then call FindAllFiles with nOp set to CONTINUE. Call FindAllFiles with nOp set to CANCEL.

Caution: You cannot use the XCopyFile function within a FindAllFiles(..., RESET), and FindAllFiles(..., CONTINUE) loop. If you call XCopyFile inside a FindAllFiles loop, the file name returned by FindAllFiles(..., CONTINUE) may be incorrect.

Syntax
FindAllFiles ( szDir, szFileName, svResult, nOp );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

837

Appendix B: Built-In Functions (E-G) FindAllFiles

Parameters
Table B-122: FindAllFiles Parameters Parameter szDir szFileName Description Specifies the name of the directory to search. Specifies the file specification to search for. Wild-card characters are allowed in this parameter. Returns the fully qualified name of the first matching file if found. If FindAllFiles fails, svResult remains unchanged. Indicates search options. Pass one of the following predefined constants in this parameter:

svResult

nOp

CONTINUEResumes the search at the location where the previous search stopped. RESETStarts the search at the beginning of the directory specified by szDir. CANCELFrees all files and folders that were accessed by previous calls to FindAllFiles. Call FindAllFiles with this parameter to ensure the success of subsequent file and folder operations on files and folders that have been accessed by FindAllFiles.

Return Values
Table B-123: FindAllFiles Return Values Return Value 0 <0 Description Indicates that the function retrieved and returned a file that matched the specification. Indicates that the function was unable to find a file that matched the specifications.

FindAllFiles Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FindAllFiles function. * * This script gets a directory name and filespec from the * user. Then it calls FindAllFiles repeatedly to build a * list of files that are located in the specified directory * and whose names match the filespec. Finally, the list of * matching files is displayed in a listbox. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "FindAllFiles Example"
838 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FindAllFiles

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FindAllFiles(HWND); function ExFn_FindAllFiles(hMSI) STRING szMsg, svDir, svFileSpec, svMatchingFileName, svNumFiles; NUMBER nResult, nNumFiles; LIST listFiles; begin selectdir: // Set up parameters for call to SelectDir. szMsg = "Select a directory to search."; svDir = ""; // Select a search directory. SelectDir (TITLE_TEXT, szMsg, svDir, FALSE); askfile: szMsg = "Enter a file specification to search for in " + svDir + ":"; // Get a file specification from the user. if (AskText (szMsg , "*.*", svFileSpec) = BACK) then goto selectdir; endif; // Create a string list for the file listing. listFiles = ListCreate (STRINGLIST); if listFiles = LIST_NULL then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Set the file count to zero. nNumFiles = 0; // Show a message while the file list is being built. SdShowMsg ("Searching . . . ", TRUE); // Get the first file that matches the file spec. nResult = FindAllFiles (svDir, svFileSpec, svMatchingFileName, RESET); while(nResult = 0) // Add the file to the list. if ListAddString (listFiles, svMatchingFileName, AFTER) < 0 then MessageBox ("Unable to build complete file list", WARNING); goto showmatches; endif; // Increment the file counter. nNumFiles = nNumFiles + 1; // Find the next matching file name. nResult = FindAllFiles(svDir, svFileSpec, svMatchingFileName, CONTINUE); endwhile; showmatches:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

839

Appendix B: Built-In Functions (E-G) FindFile

// Free all files and folders accessed by FindAllFiles. If your // setup does not target the Windows NT platform, this step is // not necessary. FindAllFiles(svDir, svFileSpec, svMatchingFileName, CANCEL); // Convert the file count to a string for display. NumToStr(svNumFiles, nNumFiles); // Clear the message that displayed while the file list was being built. SdShowMsg("", FALSE); // Display the files that match the file specification. szMsg = "Number of matching files : " + svNumFiles; if (SdShowInfoList(TITLE_TEXT, szMsg, listFiles) = BACK) then ListDestroy(listFiles); goto askfile; endif; // Remove the list from memory. ListDestroy(listFiles); end;

FindFile
The FindFile function searches a directory for a specified file. InstallShield returns the first matching file in the parameter svResult.

Note: This function searches only the specified subdirectory. It does not search an entire disk or directory tree.

Syntax
FindFile ( szPath, szFileName, svResult );

840

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FindFile

Parameters
Table B-124: FindFile Parameters Parameter szPath Description Specifies the name of the directory to search. Subdirectories beneath this directory are not searched.

Note: If the directory is enclosed in quotation marks, FindFile fails. To ensure that the folder name is not enclosed in quotation marks, call LongPathToQuote (szPath, FALSE) before calling FindFile. szFileName Specifies the name of the file to search for. Wild-card characters are allowed in this parameter. Returns the name of the first file that matches szFileName. This parameter contains the unqualified file name; that is, the drive designation and path are not included.

svResult

Return Values
Table B-125: FindFile Return Values Return Value 0 <0 Description Indicates that the function successfully found and returned the specified file. Indicates that the function was unable to find the file.

FindFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FindFile function. * * FindFile is called to search for the file Config.sys in the * root of drive C. * \*--------------------------------------------------------------*/ #define FILE_SPEC "Config.sys" #define SEARCH_DIR "C:\\" #define TITLE_TEXT "FindFile Example"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

841

Appendix B: Built-In Functions (E-G) FindWindow

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_FindFile(HWND); function ExFn_FindFile(hMSI) STRING svResult; begin if (FindFile (SEARCH_DIR, FILE_SPEC, svResult) < 0) then MessageBox ("FindFile failed.", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, "Found: %s in %s.", svResult, SEARCH_DIR); endif; end;

FindWindow
The FindWindow function provides a way for advanced developers to get a handle to a window by specifying its window class and window name. If you know the class and window name of an application, you can get its handle. You can then use that handle to send messages directly to the window.

Tip: To find the class and name of a window, run the Microsoft Spy.exe program.

Syntax
FindWindow ( szClassName, szWinName );

842

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) FindWindow

Parameters
Table B-126: FindWindow Parameters Parameter szClassName Description Specifies the name of the class to which the window belongs. To specify any class, pass a null string in this parameter. Specifies the window caption (title). To return the handle of the topmost window in the specified class, pass a null string ("") in this parameter.

szWinName

Return Values
Table B-127: FindWindow Return Values Return Value XXXX NULL (0) Description The handle of the window. FindWindow was unable to find a window with the specified name and class name.

FindWindow Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the FindWindow and SendMessage functions. * * This script launches Windows Notepad and then calls * FindWindow to locate the Notepad window. Next, it calls * SendMessage to maximize the window; after a three-second * delay, it calls SendMessage again to minimize the * window. When the script ends, Windows NotePad remains * open but minimized. Note that the parameters passed to * SendMessage are Windows system messages whose values * are defined as constants in this script. * * Note: Before running this script, set the preprocessor * constant NOTEPAD so that it references the fully* qualified name of the Windows Notepad executable. * \*--------------------------------------------------------------*/ #define NOTEPAD "C:\\Windows\\Notepad.exe" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

843

Appendix B: Built-In Functions (E-G) FormatMessage

export prototype ExFn_FindWindow(HWND); function ExFn_FindWindow(hMSI) NUMBER nMsg, nwParam, nlParam; HWND nHwnd; begin // Do not display the setup's background window. Disable (BACKGROUND); // Open the Windows Notepad. if (LaunchApp (NOTEPAD, "") < 0 ) then MessageBox ("Unable to launch Notepad.", SEVERE); abort; endif; // Wait three seconds so we can view the window before // it's maximized. Delay (3); // Retrieve the handle of the Notepad window. The first // parameter is the window class. A null string in the // second parameter specifies the topmost Notepad window. nHwnd = FindWindow ("NotePAD", ""); if (nHwnd = NULL) then MessageBox ("Unable to find the Notepad window.", SEVERE); else // Send system command to maximize the window. SendMessage (nHwnd, WM_SYSCOMMAND, SC_MAXIMIZE, 0); // Wait three seconds so we can view the window // before it's minimized. Delay (3); // Send system command to minimize the window. SendMessage (nHwnd, WM_SYSCOMMAND, SC_MINIMIZE, nlParam); endif; end;

FormatMessage
The FormatMessage function provides the error message text associated with a large error code returned by a built-in InstallScript function.

Syntax
FormatMessage ( nErrorReturnCode );

844

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetAndAddAllFilesCost

Parameters
Table B-128: FormatMessage Parameters Parameter nErrorReturnCode Description Pass a large error codefor example, 2147024891 (0x80070005) that was returned by a built-in InstallScript function. Passing the error code -1 will not produce useful results.

Return Value
A string containing the error message text associated with the error code nErrorReturnCode.

FormatMessage Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
//--------------------------------------------------------------------------// // InstallShield Example Script // // Demonstrates the FormatMessage function. // // To demonstrate, deliberately call XCopyFile with a nonexistent source // directory, which should cause the function to fail. To provide system // details about the error, call FormatMessage and display the message // string in a MessageBox. // //--------------------------------------------------------------------------function OnBegin( ) NUMBER nReturn; begin // call XCopyFile on a nonexistent directory nReturn = XCopyFile("C:\\no_such_directory", "C:\\destination", COMP_NORMAL); // when XCopyFile fails, display the error message and exit the installer if (nReturn < 0) then MessageBox(FormatMessage(nReturn), SEVERE); abort; endif; end;

GetAndAddAllFilesCost
The GetAndAddAllFilesCost function determines the cost of all of the files that are in szSrcDir and that match the wild-card pattern that is identified by szWildcard; the function adds this cost to the current value of nvCostHigh and/or nvCostLow. This cost can then be passed to FeatureAddCost.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 845

Appendix B: Built-In Functions (E-G) GetAndAddAllFilesCost

Note: Note that GetAndAddAllFilesCost does not actually set any information to be used directly by the installation. You must call FeatureAddCost (as appropriate) after calling this function to add the additional cost to an existing feature.

Syntax
GetAndAddAllFilesCost (szSrcDir, szWildcard, szTargetDir, nClusterSize, nvInstallCostHigh, nvInstallCostLow, nvUninstallCost);

846

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetAndAddFileCost

Parameters
Table B-129: GetAndAddAllFilesCost Parameters Parameter szSrcDir Description The fully qualified path of the source location containing the files to determine the cost of. The wild card to match files against. Note that the function returns failure if no files that match szWildcard are found. If nClusterSize is 0, the fully qualified path that the file is being installed to. This path is used to determine the cluster size of the target drive. If nClusterSize is non-zero, this parameter is ignored. Specifies the cluster size of the target drive. If this parameter is 0, the function determines this information from szTargetDir. The upper 31 bits of the install cost (in bytes) of this file is added to the current value of this variable. The lower 31 bits of the install cost (in bytes) of this file is added to the current value of this variable. The uninstall cost of these files is added to the current value of this variable. This value equals 1 per file to be uninstalled. Therefore, 100 files to be uninstalled returns a value of 100.

szWildcard

szTargetDir

nClusterSize

nvInstallCostHigh

nvInstallCostLow

nvUninstallCost

Return Values
Table B-130: GetAndAddAllFilesCost Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

GetAndAddFileCost
The GetAndAddFileCost function determines the cost of the specified file and adds it to the current value of nvCostHigh and/or nvCostLow. This allows you to calculate and add up the cost of multiple files by calling the function multiple times in a loop. Set nvCostHigh and nvCostLow to zero before calling the function to determine the cost of a single file. This function is typically used when you need to determine the cost of an existing file on disk so this cost can then be passed to FeatureAddCost.

Note: Note that this function does not actually set any information to be used directly by the installation. You must call FeatureAddCost (as appropriate) after calling this function to add the additional cost to an existing feature.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

847

Appendix B: Built-In Functions (E-G) GetCArrayFromISArray

Syntax
GetAndAddFileCost ( szSrcFile, szTargetDir, nClusterSize, nvCostHigh, nvCostLow );

Parameters
Table B-131: GetAndAddFileCost Parameters Parameter szSrcFile Description The fully qualified path and file name of the existing file on disk to determine the cost of. If nClusterSize is 0, the target folder for the file. This path is used to determine the cluster size of the target drive. If nClusterSize is non-zero, this parameter is ignored. Specifies the cluster size of the target drive. If this parameter is 0, the function determines this information from szTargetDir. The upper 31 bits of the installation cost (in bytes) of this file is added to the current value of this variable. The lower 31 bits of the installation cost (in bytes) of this file is added to the current value of this variable.

szTargetDir

nClusterSize

nvCostHigh

nvCostLow

Return Values
Table B-132: GetAndAddFileCost Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

GetCArrayFromISArray
The GetCArrayFromISArray function returns a pointer to an array of pointers that point to the actual data of the specified array. This function does not allocate any additional memory, but it returns a pointer to the data in the existing array. If vArray is a string array, the returned pointer can be passed to functions that take LPCWSTR* or LPWSTR* arguments; if vArray is a numeric array, the returned pointer can be passed to functions that take LPCDWORD* or LPDWORD* arguments.

Syntax
GetCArrayFromISArray (vArray);

848

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetCHARArrayFromISStringArray

Parameters
Table B-133: GetCArrayFromISArray Parameters Parameter vArray Description Specifies the array to which you want a pointer.

Return Values
Table B-134: GetCArrayFromISArray Return Values Return Value pointer < ISERR_SUCCESS Description A pointer to an array of pointers that point to the actual data of the specified array. Indicates that the function failed.

Additional Information
Be careful when using the returned pointer to modify strings that are contained in the array. The length of the strings that are contained in string arrays are managed internally by the installation. Therefore, if you change the length of a string, the installation is no longer able to manage the data that are contained in the string array.

GetCHARArrayFromISStringArray
The GetCHARArrayFromISStringArray function returns a pointer to an array of pointers to ANSI character strings that corresponds to the wide character strings that are contained in the specified array.

Syntax
GetCHARArrayFromISStringArray ( vArray );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

849

Appendix B: Built-In Functions (E-G) GetCurrentDialogName

Parameters
Table B-135: GetCHARArrayFromISStringArray Parameters Parameter vArray Description Specifies the string array to which you want a pointer.

Return Values
Table B-136: GetCHARArrayFromISStringArray Return Values Return Value pointer < ISERR_SUCCESS Description A pointer to an array of pointers to ANSI character strings. Indicates that the function failed.

Additional Information
The GetCHARArrayFromISStringArray function allocates additional memory for the array of pointers and the ANSI character strings. This pointer can be passed to functions that take LPCSTR* or LPSTR* arguments. After you are done with the newly created array, call DeleteCHARArray to delete the array from memory. If you call CopyCHARArrayToISStringArray to write the data from the array of pointers back to the original string array, be careful when modifying strings that are contained in the array. Since the lengths of the strings that are contained in string arrays are managed internally by the installation, if you change the length of a string the entire string will not be copied back to the original array when you call CopyCHARArrayToISStringArray.

GetCurrentDialogName
Project: This information applies to InstallScript projects.

The GetCurrentDialogName function retrieves the name of the currently displayed dialog as it was specified in the call to EzDefineDialog when the dialog was defined. This information can be used to close the dialog by calling EndDialog.

Syntax
GetCurrentDialogName ( svDialogName );

850

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetCurrentDir

Parameters
Table B-137: GetCurrentDialogName Parameters Parameter svDialogName Description Returns the name of the currently displayed dialog, or a null string ("") if no dialog is currently displayed.

Return Values
Table B-138: GetCurrentDialogName Return Values Return Value >= ISERR_SUCCESS Description GetCurrentDialogName successfully retrieved the name of the currently displayed dialog. No dialog is currently displayed. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

< ISERR_SUCCESS

GetCurrentDir
The GetCurrentDir function returns the current directory.

Note: When you are specifying a file in your script, always specify the full path (using the appropriate InstallShield system variable, for example, SRCDIR) rather than depend on the current folder having the appropriate value. The script internally executes code that can change the current folder, so its value may not be what you expect.

Syntax
GetCurrentDir( svCurrentDir );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

851

Appendix B: Built-In Functions (E-G) GetDir

Parameters
Table B-139: GetCurrentDir Parameters Parameter svCurrentDir Description Returns the current directory.

Return Values
Table B-140: GetCurrentDir Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully retrieved the current directory. Indicates that the function was unable to retrieve the current directory.

GetDir
The GetDir function removes the drive designation from the fully qualified path or file name passed in szPath and returns the remainder of the path or file name in svDir. The path must include a drive designation. It may be a UNC path. In the following example, the fully qualified path C:\Windows is returned in svDir as \Windows.
GetDir("C:\\Windows", svDir);

In the next example, the UNC path \\TheServer\TheSharedDevice\Programs is returned in svDir as \Programs.
GetDir("\\\\TheServer\\TheSharedDevice\\Programs", svDir);

Syntax
GetDir ( szPath, svDir );

852

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetDir

Parameters
Table B-141: GetDir Parameters Parameter szPath svDir Description Specifies a path that includes a drive designation. Returns the path without the drive designation. If szPath is a UNC path, GetDir returns the path without the server name and shared device name.

Return Values
Table B-142: GetDir Return Values Return Value 0 <0 Description Indicates that the function successfully returned a path without a drive designation. Indicates that the function was unable to return a path without a drive designations.

GetDir Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetDir function. * * This script gets a fully qualified directory name from the * user. Next, it calls GetDir to return the selected directory * name without the drive designation. The resulting path is * then displayed. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "GetDir example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetDir(HWND); function ExFn_GetDir(hMSI) STRING szMsg, svSelectedDir, svDirNameOnly; begin // Get a fully qualified directory name from the user. AskPath ("Select a directory.", INSTALLDIR, svSelectedDir);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

853

Appendix B: Built-In Functions (E-G) GetDisk

// Get the directory name minus the drive designation. if (GetDir (svSelectedDir, svDirNameOnly) < 0) then // Report the error. MessageBox ("GetDir failed.", SEVERE); else // Display the directory name as it was returned by GetDir. SprintfBox (INFORMATION, TITLE_TEXT, "Selected directory without drive designation: %s", svDirNameOnly); endif; end;

GetDisk
The GetDisk function extracts the disk drive designation from the fully qualified path or file name specified by szPath and returns it in svDisk.

Syntax
GetDisk ( szPath, svDisk );

Parameters
Table B-143: GetDisk Parameters Parameter szPath Description Specifies a fully qualified path or file name that includes a drive designation. If a drive designation is not included, GetDisk will fail. The value passed in szPath may be a UNC path. Returns the drive designation (which includes the colon). If szPath is a UNC path, GetDisk returns the server name and shared device name in the format \\server\sharedevice.

svDisk

Return Values
Table B-144: GetDisk Return Values Return Value 0 <0 Description Indicates that the function successfully returned the drive designation. Indicates that the function was unable to return the drive designation.

GetDisk Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
854 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetDiskInfo

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetDisk function. * * This script gets a fully qualified directory name from * the user. Next, it calls GetDisk to return the disk drive * designation. The drive designation is then displayed. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "GetDisk example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetDisk(HWND); function ExFn_GetDisk(hMSI) STRING svSelectedDir, svDisk; begin // Get a fully qualified directory name from the user. AskPath ("Select a directory.", INSTALLDIR, svSelectedDir); // Get the drive designation from the selected directory name. if (GetDisk (svSelectedDir, svDisk) < 0) then // Report the error. MessageBox ("GetDir failed.", SEVERE); else // Display the drive designation as it was returned by GetDisk. SprintfBox (INFORMATION, TITLE_TEXT, "Disk drive: %s", svDisk); endif; end;

GetDiskInfo
The GetDiskInfo function gets information about a specified disk drive. By inspecting the values assigned to members of this variable, your script can determine the information about a disk drive.

Syntax
GetDiskInfo ( _DISK_INFO& pdi );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

855

Appendix B: Built-In Functions (E-G) GetDiskInfo

Parameters
Table B-145: GetDiskInfo Parameters Parameter _DISK_INFO& pdi Description Specifies a pointer to an existing _DISK_INFO structure (allocated by the installation before calling the function) that specifies the information to retrieve and contains the specified information after the function returns.

The following table shows the meaning of each _DISK_INFO member:

Table B-146: _DISK_INFO Members Member szDiskPath[_MAX_PATH] nInfoToQuery Meaning Specifies the fully qualified path of the drive to return the information for. Specifies the information to query. Possible values are the following:

nBytesPerCluster

DISK_INFO_QUERY_ALLQueries all information about the disk drive. DISK_INFO_QUERY_BYTES_PER_CLUSTERQueries the bytes per cluster (cluster-size) of the drive. DISK_INFO_QUERY_DISK_TOTAL_SPACEQueries the total space on the drive. DISK_INFO_QUERY_DISK_FREE_SPACEQueries the free space on the drive. DISK_INFO_QUERY_DRIVE_TYPEQueries the drive type.

Returns the number of bytes per cluster if DISK_INFO_QUERY_BYTES_PER_CLUSTER was specified in nInfoToQuery. Returns the upper 31 bits of the total space on the target drive. Returns the lower 31 bits of the total space on the target drive. Returns the upper 31 bits of the free space on the target drive. Returns the lower 31 bits of the free space on the target drive. Returns the drive type using the same constants returned by the Windows API GetDriveType. For convenience, the following constants are predefined:

nTotalSpaceHigh nTotalSpaceLow nFreeSpaceHigh nFreeSpaceLow nDriveType

DRIVE_UNKNOWNThe drive type is unknown. DRIVE_NO_ROOT_DIRThe drive type is defined as no root directory. DRIVE_REMOVABLEThe drive type is defined as removable. DRIVE_FIXEDThe drive type is defined as fixed. DRIVE_REMOTEThe drive type is defined as remote. DRIVE_CDROMThe drive type is defined as a CD-ROM. DRIVE_RAMDISKThe drive type is defined as a RAM DISK.

856

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetDiskInfo

Table B-146: _DISK_INFO Members (cont.) Member nResultDiskSpace Meaning This member contains valid information on return when any of the following flags are specified:

DISK_INFO_QUERY_BYTES_PER_CLUSTER DISK_INFO_QUERY_DISK_TOTAL_SPACE DISK_INFO_QUERY_DISK_FREE_SPACE

This member returns the result of querying the information.

Return Values
Table B-147: GetDiskInfo Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was unsuccessful. If a null pointer is passed to the function, this value is returned.

You can check the nResultDiskSpace member to determine whether the query was successful.

GetDiskInfo Example
Note: To call this function in a Basic MSI installation, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetDiskInfo function. * * This script gets the amount of free disk space on a Windows drive * and displays that amount in a message box. * \*--------------------------------------------------------------*/ function OnBegin( ) _DISK_INFO di; NUMBER n; // to do: something with function return values NUMBER nvSizeTargetHigh, nvSizeTargetLow, nUnitsTarget; begin // init. _DISK_INFO members: what drive, what info di.szDiskPath = WINDISK; di.nInfoToQuery = DISK_INFO_QUERY_DISK_FREE_SPACE; n = GetDiskInfo(&di);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 857

Appendix B: Built-In Functions (E-G) GetDiskSpace

// change to desired unit for free space nUnitsTarget = MBYTES; n = ConvertSizeToUnits( di.nFreeSpaceHigh, di.nFreeSpaceLow, BYTES, nvSizeTargetHigh, nvSizeTargetLow, nUnitsTarget); SprintfBox(INFORMATION, "Free Space", "Free space: %d MB", nvSizeTargetLow); end;

GetDiskSpace
This function is obsolete. Use the GetDiskInfo function instead. The GetDiskSpace function returns the amount of free spacein byteson the drive or path specified in szPath.

Syntax
GetDiskSpace ( szDrive );

Parameters
Table B-148: GetDiskSpace Parameters Parameter szPath Description Specifies the path for which the function returns the amount of space available. The value specified can be a UNC path.

Return Values
Table B-149: GetDiskSpace Return Values Return Value >0 Description The number of bytes free in the specified directory. The maximum value returned is 2 GB. Free disk space greater than that returns as 2 GB. Call GetDiskSpaceEx when your setup needs to check for free space greater than 2 GB. Indicates that GetDiskSpace was unable to obtain the amount of free space.

<0

GetDiskSpace Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
858 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetDiskSpace

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetDiskSpace function. * * This script gets a fully qualified path from the end user. * It then extracts the drive designation from the path, gets * the amount of free space on that drive, and displays the * amount of free space in a message box. * * A script-defined function is used to insert commas if * necessary into the number before it's displayed. * \*--------------------------------------------------------------*/

// User-defined function to format a number in a string. prototype FormatIntString (BYREF STRING); // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetDiskSpace(HWND); function ExFn_GetDiskSpace(hMSI) STRING svResultPath, svDrive; LONG lFreeSpace; STRING svFreeSpace; begin // Prompt for a target path; use C as the default. AskPath ("Select drive:", "C:\\", svResultPath); // Get the drive designation from the path. GetDisk (svResultPath, svDrive); // Get the amount of free disk space on that drive. lFreeSpace = GetDiskSpace (svDrive); if (lFreeSpace < 0) then // Handle an error from GetDiskSpace. MessageBox ("GetDiskSpace failed.", SEVERE); else // Convert the free disk space value to a string. NumToStr (svFreeSpace, lFreeSpace); // Insert commas into the number if necessary. FormatIntString (svFreeSpace) ; // Report the amount of free space. MessageBox (svFreeSpace + " bytes free on drive " + svDrive + ".", INFORMATION); endif; end;

function FormatIntString(svInteger) // Insert commas if necessary into an integer // that's been stored in a string variable. INT nLen;
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 859

Appendix B: Built-In Functions (E-G) GetDiskSpaceEx

STRING svSubStr, svTemp; begin nLen = StrLength (svInteger); if nLen > 3 then nLen = nLen - 3; StrSub (svTemp , svInteger, nLen, 3); while nLen > 3 nLen = nLen - 3; StrSub (svSubStr, svInteger, nLen, 3); svTemp = svSubStr + "," + svTemp; endwhile; StrSub (svSubStr, svInteger, 0,nLen); svInteger = svSubStr + "," + svTemp; endif; end;

GetDiskSpaceEx
This function is obsolete. Use the GetDiskInfo function instead. The GetDiskSpaceEx function returns the amount of free space on the specified path. The value passed in nUnits determines whether the value returned by GetDiskSpaceEx is a measure of bytes, kilobytes, megabytes, or gigabytes.

Syntax
GetDiskSpaceEx ( szDrive, nUnits );

860

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetDiskSpaceEx

Parameters
Table B-150: GetDiskSpaceEx Parameters Parameter szPath Description Specifies the path for which the function returns the amount of space available. The value specified can be a UNC path. Pass one of the following predefined constants to indicate the measurement unit:

nUnits

BYTESIndicates that GetDiskSpaceEx should return the number of free bytes. KBYTESIndicates that GetDiskSpaceEx should return the number of free kilobytes. MBYTESIndicates that GetDiskSpaceEx should return the number of free megabytes. GBYTESIndicates that GetDiskSpaceEx should return the number of free gigabytes.

Return Values
Table B-151: GetDiskSpaceEx Return Values Return Value >0 Description The number of free bytes, kilobytes, megabytes, or gigabytes in the specified directory, depending on the value of nUnits. Indicates that GetDiskSpaceEx was unable to obtain the amount of free space.

<0

Additional Information
The limit of GetDiskSpaceEx is 2 giga-units (2 31) of the measurement unit you pass in nUnits. When you specify BYTES, the limit is 2 GB; when you specify KBYTES, the limit is 2 TB; and so on. You should specify KBYTES for most setups. GetDiskSpaceEx returns the available space rounded down to the nearest single unit specified in nUnits. For example, if you specify GBYTES, a path that has 2.5 GB available will return 2. For setups that require more precise space information, call the Windows API function GetDiskFreeSpaceEx directly.

GetDiskSpaceEx Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

861

Appendix B: Built-In Functions (E-G) GetEnvVar

* Demonstrates the GetDiskSpaceEx function. * * This script gets a fully qualified path from the end user. * It then extracts the drive designation from the path, gets * the amount of free space on that drive, and displays the * amount of free space in a message box. * \*--------------------------------------------------------------*/ STRING INT szPath; iResult;

#include "ifx.h" program // Prompt for a target path. szPath = PROGRAMFILES; iResult = SdAskDestPath ("Select Folder\nSelect the folder to check for available disk space.", " ", szPath, 0); if (iResult < 0) then MessageBox("Unable to display dialog.", SEVERE); endif; // Get the amount of free disk space (in kilobytes) for the specified path. iResult = GetDiskSpaceEx(szPath, KBYTES); if (iResult < 0) then MessageBox("Unable to get available disk space.", SEVERE); endif; // Display the amount of space available. SprintfBox(INFORMATION, "Space Available", "%d KB available on %s.", iResult, szPath); endprogram

GetEnvVar
The GetEnvVar function retrieves the current value of an environment variable.

Syntax
GetEnvVar ( szParameter, svValue );

862

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetEnvVar

Parameters
Table B-152: GetEnvVar Parameters Parameter szParameter svValue Description Specifies the name of the environment variable whose value is to be retrieved. Returns the current value of the environment variable.

Return Values
Table B-153: GetEnvVar Return Values Return Value 0 <0 Description Indicates that the function retrieved the value of the environment variable. Indicates that the function was unable to retrieve the value of the environment variable.

GetEnvVar Example
This script is structured for use in a Basic MSI installation. To call this function in a Basic MSI installation, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release. To run this code in an InstallScript or InstallScript MSI installation, copy only the code that is in between the begin and end statements and paste it into your script's OnBegin event handler function.

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetEnvVar function. * * GetEnvVar is called to get the value of the environment * variable named TEMP. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "GetEnvVar Example" #define ENV_TEMP "TEMP" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetEnvVar(HWND); function ExFn_GetEnvVar(hMSI)
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 863

Appendix B: Built-In Functions (E-G) GetExtendedErrInfo

STRING svEnvVar; begin // Get the value of the environment variable specified by ENV_TEMP. if (GetEnvVar (ENV_TEMP, svEnvVar) < 0) then // Report the error. MessageBox ("Environment variable " + ENV_TEMP + " not found.", SEVERE); else // Display the value of the environment variable. SprintfBox (INFORMATION, TITLE_TEXT, "%s = %s", ENV_TEMP, svEnvVar); endif; end;

GetExtendedErrInfo
Project: This information applies to InstallScript projects.

The GetExtendedErrInfo function returns the error information that was set by SetExtendedErrInfo. Many InstallScript functions call SetExtendedErrInfo(__FILE__, __LINE__, nError) internally.

Syntax
GetExtendedErrInfo ( svScriptFile, nvLineNumber, nvError );

864

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetExtents

Parameters
Table B-154: GetExtendedErrInfo Parameters Parameter svScriptFile nvLineNumber nvError Description Returns the script file in which the error occurred. Returns the line number in which the error occurred. Returns the error code for the error.

Return Values
Table B-155: GetExtendedErrInfo Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description The function successfully retrieved the error information. The function failed to retrieve the error information.

GetExtents
The GetExtents function retrieves the dimensions of a screenin pixels. The width of the screen is returned in nvDx and the height is returned in nvDy. For example, a standard VGA monitor returns 640 in nvDx and 480 in nvDy.

Note: The screen dimensions of the target machine can be gotten natively through the Windows Installer service by using the ScreenX and ScreenY properties.

Syntax
GetExtents ( nvDx, nvDy );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

865

Appendix B: Built-In Functions (E-G) GetExtents

Parameters
Table B-156: GetExtents Parameters Parameter nvDx nvDy Description Returns the width of the screen in pixels. Returns the height of the screen in pixels.

Return Values
Table B-157: GetExtents Return Values Return Value 0 <0 Description Indicates that the function successfully retrieved the dimensions of a screen. Indicates that the function was unable to retrieve the values.

GetExtents Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetExtents function. * * This script calls GetExtents to obtain the current video * resolution of the target system. It then displays that * information in a dialog. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "GetExtents example" #define MSG_TEXT "Video Resolution: %d by %d" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetExtents(HWND); function ExFn_GetExtents(hMSI) NUMBER nvDx, nvDy; begin // Get the video resolution of the target system. if (GetExtents (nvDx, nvDy) < 0) then // Report the error. MessageBox ("GetExtents failed.", SEVERE);

866

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetFileInfo

else // Display the information SprintfBox (INFORMATION, TITLE_TEXT, MSG_TEXT, nvDx, nvDy); endif; end;

GetFileInfo
Call the GetFileInfo function to determine a file's or directory's attributes, date, time, MD5 signature, or size. In each GetFileInfo statement, you can request only one of the data. For example, to obtain the date and time information for a file or directory, you must call GetFileInfo twiceonce to obtain the date and once to obtain the time.

Syntax
GetFileInfo ( szPathName, nType, nvResult, svResult );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

867

Appendix B: Built-In Functions (E-G) GetFileInfo

Parameters
Table B-158: GetFileInfo Parameters Parameter szPathName Description Specifies the fully qualified name of the file or directory about which you want to retrieve information. You can specify a valid Uniform Resource Locator (URL) in this parameter unless you pass FILE_ATTRIBUTE or FILE_SHARED_COUNT as the nType parameter, in which case the function fails and returns ISERR_INVALID_ARG. To check the validity of a URL, call Is(VALID_PATH, szURL). Specifies the type of file or directory information to retrieve. If the information is a number, GetFileInfo places it in nvResult. If the information is a string, GetFileInfo places it in svResult. Pass one of the following predefined constants in this parameter:

nType

FILE_ATTRIBUTEThe attribute of the file or directory is returned in nvResult. FILE_DATEThe date of the file or directory in the format YYYY\MM\DD is returned in svResult. FILE_MD5_SIGNATUREReturns the MD5 signature of the file specified in svResult. Generating and returning an MD5 signature is an expensive operation that requires reading the contents of the entire file. Only use this parameter when absolutely necessary. FILE_MD5_SIGNATURE is not supported for URLs.

Note: Raw MD5 signature data for a particular file consists of 16 generated numeric values of 16 bit each (between 0x00 abd 0xFF). These values are usually stored in a string of unsigned characters. However, the InstallScript language does not support unsigned characters, so instead of returning the raw MD5 file data, each of the 16 numeric values are converted to their string equivalent and placed in the resulting string. This results in a string of 32 characters, where each set of two characters represent a single numeric value. This is sometimes referred to as a MD5 hex string.

FILE_SHARED_COUNTThe file's reference count. FILE_SIZEThe size in bytes is returned in nvResult (same as FILE_SIZE_LOW). FILE_SIZE_LOWThe lower 31 bits of the file's size (in bytes) is returned in nvResult. If the size of the file is more than 2GB, the size of the file is equal to the value returned for FILE_SIZE_HIGH multiplied by 2GB added to the value returned for FILE_SIZE_LOW. FILE_SIZE_HIGHThe upper 31 bits of the file's size (in bytes) is returned in nvResult. This value is 0 (zero) if the file is less than 2GB. If not, the size of the file is equal to the value returned for FILE_SIZE_HIGH multiplied by 2GB added to the value returned for FILE_SIZE_LOW. FILE_TIMEThe time of the file or directory in the format HH:MM:SS is returned in svResult.

868

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetFileInfo

Table B-158: GetFileInfo Parameters (cont.) Parameter Description

Note: After calling GetFileInfo with FILE_ATTRIBUTE as the second parameter (nType), use ifthen-else logic to determine the file's or directory's attributes. If nvResult = FILE_ATTR_NORMAL, then no attributes are set. If nvResult != FILE_ATTR_NORMAL, test the result of bitwise AND (&) operations on nvResult and one or more of the following file attribute constants to determine which attributes are set: FILE_ATTR_NORMAL: The file is a normal file. FILE_ATTR_ARCHIVED: The file is archived. FILE_ATTR_DIRECTORY: The file is a directory. FILE_ATTR_HIDDEN: The file is hidden. FILE_ATTR_READONLY: The file is read-only. FILE_ATTR_SYSTEM: The file is a system file.
if (nvResult = FILE_ATTR_NORMAL) then //The file is NORMAL. else if (FILE_ATTR_HIDDEN & nvResult) then //The file is HIDDEN. endif; if (FILE_ATTR_READONLY & nvResult) then //The file is READ-ONLY. endif; endif;

nvResult svResult

Returns numeric information. Returns string information.

Return Values
Table B-159: GetFileInfo Return Values Return Value 0 ISERR_INVALID_ARG (-2) All other negative values Description Indicates that the function successfully retrieved the requested file information. Indicates that an invalid argument was passed to the function. Indicates that the function was unable to retrieve the requested information.

GetFileInfo Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

869

Appendix B: Built-In Functions (E-G) GetFileInfo

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetFileInfo function. * * GetFileInfo is called to retrieve the time, date, and * attributes of a file. * * Note: In order for this script to run correctly, you * must set the constant EXAMPLE_TXT to the name * of an existing file on the target system. * \*--------------------------------------------------------------*/ #define EXAMPLE_FILE "C:\\IO.sys" #define TITLE_TEXT "GetFileInfo Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetFileInfo(HWND); function ExFn_GetFileInfo(hMSI) STRING svResult, szAttributes; NUMBER nvResult; LIST listID; begin // Create a list to store information about the file. listID = ListCreate (STRINGLIST); // Get the date the file was created or last updated into svResult. if (GetFileInfo (EXAMPLE_FILE, FILE_DATE, nvResult, svResult) = 0) then // Add the file date to the list. ListAddString (listID, "File date: " + svResult, AFTER); endif; // Get the time the file was created or last updated into svResult. if (GetFileInfo (EXAMPLE_FILE, FILE_TIME, nvResult, svResult) = 0) then // Add the file time to the list. ListAddString (listID, "File time: " + svResult, AFTER); endif; // Get the file attributes into nvResult. if (GetFileInfo (EXAMPLE_FILE, FILE_ATTRIBUTE, nvResult, svResult) = 0) then // Test for no attribute. if (nvResult = FILE_ATTR_NORMAL) then // No attributes are set. Add that info to the list ListAddString(listID, "File attributes: Normal", AFTER); else // Append attributes to this string. szAttributes = "File attributes: "; // Is it archived? if (FILE_ATTR_ARCHIVED & nvResult) then szAttributes = szAttributes + "archived "; endif; // Is it hidden? if (FILE_ATTR_HIDDEN & nvResult) then szAttributes = szAttributes + "hidden ";
870 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetFolderNameList

endif; // Is it read-only? if (FILE_ATTR_READONLY & nvResult) then szAttributes = szAttributes + "read-only "; endif; // Is it a system file? if (FILE_ATTR_SYSTEM & nvResult) then szAttributes = szAttributes + "system "; endif; // Is it a directory? if (FILE_ATTR_DIRECTORY & nvResult) then szAttributes = szAttributes + "directory "; endif; endif; // Add the file attributes to the list. ListAddString (listID, szAttributes, AFTER); endif; // Display the list. SdShowInfoList (TITLE_TEXT, EXAMPLE_FILE, listID); // Remove the list from memory. ListDestroy (listID); end;

GetFolderNameList
The GetFolderNameList function is used to enumerate all program item shortcuts and subfolders in a specified folder. This function can also be used to enumerate program item shortcuts and subfolders in the root folder.

Syntax
GetFolderNameList ( szFolderName, listItemsID, listSubFoldersID );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

871

Appendix B: Built-In Functions (E-G) GetFolderNameList

Parameters
Table B-160: GetFolderNameList Parameters Parameter szFolderName Description Specifies the name of the folder to be queried. You can specify a fully qualified path for szFolderName, such as:
C:\\Windows\\Start Menu\\Programs\\Accessories\\Games

If szFolderName is null, GetFolderNameList searches the default Programs directory. If you do not specify an absolute path (a path that includes a drive specification, for example, "C:\\Program Files\\AppName") for szFolderName, GetFolderNameList searches for a subfolder under the default Programs directory; the location depends on the value of the InstallScript variable ALLUSERS, as well as the version of Windows on the target system. You can also use an InstallScript system variable:

FOLDER_DESKTOPSearches the Desktop folder. FOLDER_STARTUPSearches the Startup menu. FOLDER_STARTMENUSearches the Start menu. FOLDER_PROGRAMSSearches the Start Menu\Programs folder.

Or you could use a relative path, such as:

FOLDER_PROGRAMS ^ "ACCESSORIES\\GAMES"

listItemsID

Returns a list with the names of the program item shortcuts in szFolderName. Note that if szFolderName includes both personal and common program items, the list returned in this parameter will contain either the common or personal program item shortcuts, but not both. The list identified by listItemsID must already have been initialized by a call to ListCreate. Returns a list with the names of the subfolders in szFolderName. Note that if szFolderName includes both personal and common folders, the list returned in this parameter will contain either the common or personal folders, but not both. The list identified by listSubFoldersID must already have been initialized by a call to ListCreate.

listSubFoldersID

Return Values
Table B-161: GetFolderNameList Return Values Return Value 0 Description GetFolderNameList successfully retrieved all the programs items and subfolder names. GetFolderNameList was unable to retrieve the program items and subfolder names. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

<0

872

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetFolderNameList

GetFolderNameList Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetFolderNameList function. * * GetFolderNameList is called to retrieve all of the folders * and program items on the desktop. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetFolderNameList(HWND); function ExFn_GetFolderNameList(hMSI) NUMBER nResult; LIST listItemsID, listFoldersID; begin // Create lists for folders and program names. listItemsID = ListCreate (STRINGLIST); listFoldersID = ListCreate (STRINGLIST); if (listItemsID = LIST_NULL) || (listFoldersID = LIST_NULL) then MessageBox ("Unable to create lists.", SEVERE); else // Display a message box while building the list. SdShowMsg ("Searching . . . please wait.", TRUE); // Place the folder and program names into the lists. nResult = GetFolderNameList (FOLDER_DESKTOP, listItemsID, listFoldersID); // Close the message box. SdShowMsg ("", FALSE); if (nResult < 0) then MessageBox ("Unable to retrieve desktop folder and program names.", SEVERE); else // Display the lists. repeat // Disable the Back button. Disable (BACKBUTTON); // Display the list of items. nResult = SdShowInfoList ("", "Items list:", listItemsID); // Enable the Back button. Enable (BACKBUTTON);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

873

Appendix B: Built-In Functions (E-G) GetFont

// Display the list of folders. nResult = SdShowInfoList ("", "Folders list:", listFoldersID); until (nResult = NEXT); endif; endif; end;

GetFont
The GetFont function builds a font and retrieves its handle. You can use the font handle to specify the font used by the controls in a custom dialog.

Note: InstallShield deletes all fonts created with this function when the installation terminates. In addition, InstallShield releases all system resources upon termination.

Syntax
GetFont ( szFontName, nPointSize, nAttributes );

874

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetFont

Parameters
Table B-162: GetFont Parameters Parameter szFontName nPointSize nAttributes Description Specifies the name of the font that you want to build. Specifies the point size of the font that you want to build. Specifies the style of the font. Pass one or more of the following predefined constants in this parameter. Specify multiple styles by combining constants with the bitwise OR operator ( | ).

STYLE_BOLDSpecifies a bold style font. STYLE_ITALICSpecifies that you want the font to be italicized. STYLE_NORMALSpecifies a normal style font. STYLE_UNDERLINESpecifies that you want the characters to be underlined.

Return Values
Table B-163: GetFont Return Values Return Value XXXX Description The handle to the font.

If GetFont cannot find the font that is named in szFontName, the function builds the Arial font and returns a handle to that font.

GetFont Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetFont and CtrlSetFont functions. * * This example script calls GetFont to retrieve the handles * of four fonts. These handles are then passed to CtrlSetFont * to set the font of the static text fields in a custom dialog * box. * * The "custom" dialog used in this script is actually the * InstallShield dialog that is displayed by the built-in * function SetupType. Because this dialog is stored in * the file _isres.dll, which is already compressed in
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 875

Appendix B: Built-In Functions (E-G) GetFont

* the installation, it can be used in a script as a custom * dialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 10203 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_TEXT_1 202 #define RES_TEXT_2 #define RES_TEXT_3 #define RES_TEXT_4 210 220 230

// // // //

ID ID ID ID

of of of of

the custom dialog Next button Cancel button first static text box

// ID of second static text box // ID of third static text box // ID of fourth static text box

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetFont(HWND); function ExFn_GetFont(hMSI) STRING szDialogName; NUMBER nResult, nCmdValue; HWND hFont1, hFont2, hFont3, hFont4; BOOL bDone; begin // Get the handle of the fonts to use for the static text // that is displayed by the custom dialog. hFont1 = GetFont("Arial", 14, STYLE_BOLD); hFont2 = GetFont("Times New Roman", 11, STYLE_ITALIC); hFont3 = GetFont("Arial", 10, STYLE_BOLD); hFont4 = GetFont("Courier New", 9, STYLE_NORMAL); if (hFont1 = 0 || hFont2 = 0 || hFont3 = 0 || hFont4 = 0) then // Report an error; then terminate. MessageBox ("Unable to get all fonts. ", SEVERE); abort; endif; // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // // // // Define to get string by its the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter.

nResult = EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID); if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog.", SEVERE); abort; endif; // Initialize indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat

876

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetFont

// Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog (szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); // Set the font and text for static text box 1. if (CtrlSetFont (szDialogName, hFont1, RES_TEXT_1) = 0) then CtrlSetText (szDialogName, RES_TEXT_1, "This text is set in 14-point Arial bold."); else CtrlSetText (szDialogName, RES_TEXT_1, "Unable to set font for first static text box."); endif; // Set font and text for static text box 2. if (CtrlSetFont (szDialogName, hFont2, RES_TEXT_2) = 0) then CtrlSetText (szDialogName, RES_TEXT_2, "This text is set in 11-point Times New Roman italic."); else CtrlSetText (szDialogName, RES_TEXT_2, "Unable to set font for second static text box."); endif; // Set font and text for static text box 3. if (CtrlSetFont (szDialogName, hFont3, RES_TEXT_3) = 0) then CtrlSetText (szDialogName, RES_TEXT_3, "This text is set in 10-point Arial bold."); else CtrlSetText (szDialogName, RES_TEXT_3, "Unable to set font for third static text box."); endif; // Set font and text for static text box 4. if (CtrlSetFont (szDialogName, hFont4, RES_TEXT_4) = 0) then CtrlSetText (szDialogName, RES_TEXT_4, "This text is set in 9-point Courier New."); else CtrlSetText (szDialogName, RES_TEXT_4, "Unable to set font for fourth static text box."); endif; case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); endswitch; until bDone;
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 877

Appendix B: Built-In Functions (E-G) GetLine

// Close the dialog. EndDialog (szDialogName); // Free the dialog from memory. ReleaseDialog (szDialogName); end;

GetLine
The GetLine function reads a line of text from a text file opened in read-only mode. Before you call GetLine, you must first call OpenFileMode to set the file mode to read-only and then call OpenFile to open the file (which can be a file on the Internet). The first call to GetLine reads the first line of text from the file. After reading a line, GetLine repositions the file pointer to the next line. The second call to GetLine reads the second line, and so forth. GetLine strips the carriage return and line feed characters from the end of the line it returns. When GetLine has read all the lines in a file, it returns an end-of-file error. If you open a file in append mode, the GetLine function fails if you call it because the file pointer is at the end of the file. The function also fails if the file specified by nvFileHandle was opened in a binary mode. The maximum size of a line is 4,096 characters. To read multiple lines from a file, use a separate GetLine call for each line or place the GetLine statement in a loop.

Tip: To write to a text file, use the WriteLine function. WriteLine always produces lines that have a carriage return and line feed character combination at the end of the line.

Syntax
GetLine ( nvFileHandle, svLine );

878

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetLine

Parameters
Table B-164: GetLine Parameters Parameter nvFileHandle svLine Description Specifies the handle of a file that has been opened by a call to OpenFile. Returns a line of text from the file specified by nvFileHandle.

Return Values
Table B-165: GetLine Return Values Return Value 0 Description Indicates that the function successfully retrieved a line of text from an open text file. Indicates that the function failed due to an end-of-file error or another error condition. This condition also indicates GetLine has read all the lines in the file.

<0

GetLine Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetLine function. * * GetLine is called in this script to read a text file line by * line. * * Note: In order for this script to run properly, you must set * the preprocessor constants so that they reference an * existing text file on the target system. * \*--------------------------------------------------------------*/ #define EXAMPLE_FILE "Readme.txt" #define EXAMPLE_DIR "C:\\Windows" #define TITLE_TEXT "GetLine example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetLine(HWND); function ExFn_GetLine(hMSI) STRING szFileName, szPath, szText, svLine;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

879

Appendix B: Built-In Functions (E-G) GetMemFree

NUMBER nFlag, nFileHandle; LIST listID; begin // Create a list to store lines from the file. listID = ListCreate (STRINGLIST); // Set the file mode to normal. OpenFileMode (FILE_MODE_NORMAL); // Open the file for editing. OpenFile (nFileHandle, EXAMPLE_DIR, EXAMPLE_FILE); // Get lines from the file into the list. while (GetLine (nFileHandle, svLine) = 0) ListAddString (listID, svLine, AFTER); endwhile; // Close the file. CloseFile (nFileHandle); // Display the list. SdShowInfoList (TITLE_TEXT, EXAMPLE_FILE, listID); // Remove the list from memory. ListDestroy (listID); end;

GetMemFree
The GetMemFree function is obsolete and should not be used. This function always returns 1048576.

Syntax
GetMemFree ( );

Tip: To determine the amount of actual physical memory available on the target system, call GetSystemInfo.

GetObject
The GetObject function initializes the szObjectName object and returns a reference that can be assigned to a variable of type OBJECT by using the set keyword. To get a reference to a new or existing COM object (as Visual Basic's GetObject function does), call CoGetObject.

Tip: To check whether the object was initialized successfully, call the IsObject function.

Syntax
GetObject ( szObjectName );

880

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetObjectByIndex

Parameters
Table B-166: GetObject Parameters Parameter szObjectName Description Specifies the name of the InstallShield object to be initialized as that name is displayed in the IDE's Features view, for example:
"New BDE 5.11 1"

Note: To ensure that the correct InstallShield object is initialized, give each InstallShield object in your project a unique name. If szObjectName is set to a null string (""), in an object project GetObject returns a reference to the object that is calling it (in a setup project GetObject returns an invalid reference). Setting szObjectName to a null string is useful for reading and writing object properties within the object itself. For example, the following code displays the current status description for the object:
OBJECT oThis; set oThis = GetObject(""); if( IsObject( oThis ) ) then MessageBox( oThis.Status.Description, INFORMATION ); endif;

Return Values
A reference that can be assigned to a variable of type OBJECT by using the set keyword.

GetObjectByIndex
Project: This information applies to InstallScript projects.

The GetObjectByIndex function finds the setup's or object's subobject that is specified by nIndex and returns a reference that can be assigned to a variable of type OBJECT by using the set keyword.

Syntax
GetObjectByIndex ( nIndex );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

881

Appendix B: Built-In Functions (E-G) GetObjectCount

Parameters
Table B-167: GetObjectByIndex Parameters Parameter nIndex Description Specifies the index of a subobject. Index numbers start at one (1); if an object passes zero (0) as the argument to GetObjectByIndex, the function returns a reference to the object or setup that is calling the function rather than any subobject. (This is the same as calling GetObject("").) If a setup calls GetObjectByIndex(0), the reference that is returned does not contain any meaningful information.

Return Values
A reference that can be assigned to a variable of type OBJECT by using the set keyword.

Additional Information
To check whether the object was initialized successfully, call the IsObject function. To get the number of subobjects contained by the object or setup, call GetObjectCount.

GetObjectCount
Project: This information applies to InstallScript projects.

The GetObjectCount function returns the number of subobjects contained by the object or setup.

Syntax
GetObjectCount ( );

Parameters
None

Return Values
Table B-168: GetObjectCount Return Values Return Value >= 0 < ISERR_SUCCESS Description The number of subobjects. GetObjectCount cannot determine the number of subobjects.

Additional Information
To get a reference to a subobject that is specified by its index within the setup or object, call GetObjectByIndex.
882 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetProfInt

GetProfInt
The GetProfInt function retrieves an integer from an .ini file. GetProfInt works like the Windows API GetPrivateProfileInt with the nDefault parameter specified as 0.

Syntax
GetProfInt ( szFileName, szSectionName, szKeyName, nvValue );

Parameters
Table B-169: GetProfInt Parameters Parameter szFileName Description Specifies the name of the .ini file from which to get the current integer value of a key. If szFileName is unqualified (that is, if a drive designation and path are not included), InstallShield searches for the file in the Windows folder. Specifies the name of the .ini file section to search for szKeyName. The section name should not be enclosed within delimiting brackets ( [ ] ). The search for this name is not case-sensitive. Specifies the key whose integer value is to be returned in nvValue. The search for this key is not case-sensitive. Returns an integer value currently assigned to szKeyName. Due to limitations of the GetPrivateProfileInt function, this function can return only a 16-bit value from the profile. Therefore, the maximum value that can be returned is 65,535; larger values may not be returned correctly. If you need to return a larger value, use the general file handling functions, such as FileGrep and FileInsertLine, and then convert the returned string into an integer by calling StrToNum.

szSectionName

szKeyName

nvValue

Return Values
GetProfInt always returns 0.

Additional Information
As with the Windows API function GetPrivateProfileInt, no error is returned if an error occurs because the file, section, or key name cannot be found. Instead, nvValue will contain 0. For that reason, it is not possible to distinguish between an error and a returned value of zero. To distinguish between zero and an error, call GetPrivateProfileInt directly and specify an alternate default value. Some calls to GetPrivateProfileIntand therefore to GetProfIntare mapped automatically to the Windows registry instead of the profile.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

883

Appendix B: Built-In Functions (E-G) GetProfSectionKeyCount

GetProfInt Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetProfInt function. * * GetProfInt is called to retrieve the value of a key in * the file specified by EXAMPLE_INI. * * Note: Before running this script, create a file called * ISExample.ini in the root of drive C. Include the * following lines in that file. * * [ISExample] * ISKey=100 * \*--------------------------------------------------------------*/ #define EXAMPLE_INI "C:\\ISExampl.ini"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetProfInt(HWND); function ExFn_GetProfInt(hMSI) STRING szSectionName, szKeyName; NUMBER nvValue; begin szSectionName = "ISExample"; szKeyName = "ISKey"; // Get the value of szKeyName under the szSectionName section. GetProfInt (EXAMPLE_INI, szSectionName, szKeyName, nvValue); SprintfBox (INFORMATION, "GetProfInt Example", "The value of %s is: %d.", szKeyName, nvValue); end;

GetProfSectionKeyCount
Project: This information applies to InstallScript projects.

The GetProSectionKeyCount function returns the number of keys in the section specified by szSectionName in the initialization file specified by szFilename.

884

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetProfString

Syntax
GetProfSectionKeyCount ( szFilename, szSectionName );

Parameters
Table B-170: GetProfSectionKeyCount Parameters Parameter szFilename szSectionName Description Specifies the fully qualified name of the .ini file in which to count the keys. Specifies the name of the .ini file section in which to count the keys. The section name should not be enclosed within delimiting brackets ( [ ] ). The search for this name is not case-sensitive.

Return Values
Table B-171: GetProfSectionKeyCount Return Values Return Value X < ISERR_SUCCESS Description The number of keys in the specified section of the specified file. Indicates that the function could not determine the number of keys. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

GetProfString
The GetProfString function retrieves a profile string from the specified .ini file. GetProfString works like the Windows API GetPrivateProfileString.

Note: GetProfString uses the functions provided by your operating environment's API to access the .ini file. Because of this, InstallShield's functionality might be limited by the operating environment.

Syntax
GetProfString ( szFileName, szSectionName, szKeyName, svResult );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

885

Appendix B: Built-In Functions (E-G) GetProfString

Parameters
Table B-172: GetProfString Parameters Parameter szFileName Description Specifies the name of the .ini file from which to get the current value of a key. If szFileName is unqualified (that is, if a drive designation and path are not included), InstallShield searches for the file in the Windows folder. Specifies the name of the .ini file section to search for szKeyName. The section name should not be enclosed within delimiting brackets ( [ ] ). The search for this name is not case-sensitive. To obtain a list of all section names in the initialization file, pass a null string ("") in this parameter.

szSectionName

Tip: To obtain a list of all section names in the initialization file, pass a null string ("") in szSectionName. The section names, delimited by null characters, are returned in the parameter svResult. svResult must be long enough to accept all of the section names. Use the StrGetTokens function to extract the individual section names from this string. szKeyName Specifies the key whose value is to be returned in svResult. The search for this key is not case-sensitive. To obtain a list of all key names in the section, pass a null string ("") in this parameter.

Tip: To obtain a list of all key names in the section specified by szSectionName, pass a null string ("") in szKeyName. The key names, delimited by null characters, are returned in the parameter svResult. svResult must be long enough to accept all of the key names. Use the StrGetTokens function to extract the individual key names from this string. svResult If szSectionName specifies a section name and szKeyName specifies a key name, the value of that key is returned in this parameter. If szSectionName specifies a null string (""), all of the section names are returned in svResult. If szKeyName specifies a null string (""), all of the key names in the section specified szSectionName are returned in svResult.

Return Values
Table B-173: GetProfString Return Values Return Value 0 <0 -2 Description GetProfString successfully returned the value of the profile string. GetProfString was unable to return the value. The length of the key's value exceeded 2048 characters, which is the maximum number of characters that can be returned in svResult by GetProfString.

886

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetProfString

GetProfString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions AddProfString and GetProfString. * * This script adds a profile string to a file; then it * retrieves and displays the string that was added. * * Note: The first time you run this script, it will create a * file named ISExampl.ini in the root of drive C. You * may delete that file when you have finished analyzing * this script. * \*--------------------------------------------------------------*/ #define EXAMPLE_INI "C:\\ISExampl.ini" // The new section, #define NEW_SECTION #define NEW_KEY #define NEW_VALUE key, and value to add to the file. "New Section" "New Key" "Test"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetProfString(HWND); function ExFn_GetProfString(hMSI) STRING svResult; begin // Add the profile string to the file. if (AddProfString (EXAMPLE_INI, NEW_SECTION, NEW_KEY, NEW_VALUE) != 0) then // Display an error message if the string could not be added. MessageBox ("AddProfString failed.", SEVERE); else // Retrieve the value of a key from the file. if (GetProfString (EXAMPLE_INI, NEW_SECTION, NEW_KEY, svResult) != 0) then // Display an error message if the string could not be retrieved. MessageBox ("GetProfString failed.", SEVERE); else // Display the key and its current value. MessageBox (NEW_KEY + "=" + svResult, INFORMATION); endif; endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

887

Appendix B: Built-In Functions (E-G) GetProfStringList

GetProfStringList
The GetProfStringList function retrieves lists of key names and string values from the specified section of the specified initialization file.

Syntax
GetProfStringList ( szFileName, szSectionName, listKeyNames, listValues );

Parameters
Table B-174: GetProfStringList Parameters Parameter szFileName Description Specifies the name of the .ini file from which to get the key names and string values. If szFileName is unqualified (that is, if a drive designation and path are not included), InstallShield searches for the file in the Windows folder. Specifies the name of the .ini file section to search for the key names and string values. The section name should not be enclosed within delimiting brackets ( [ ] ). The search for this name is not case-sensitive. Returns a list of key names. The string list identified by listKeyNames must already have been initialized by a call to ListCreate. Returns a list of string values. The string list identified by listValues must already have been initialized by a call to ListCreate.

szSectionName

listKeyNames

listValues

Return Values
Table B-175: GetProfStringList Return Values Return Value >= ISERR_SUCCESS (0) Description Indicates that the function successfully read the section and inserted key names and string values into the specified lists. Indicates that the function could not read the section or insert key names and string values into the specified lists.

< ISERR_SUCCESS (0)

Additional Information
GetProfStringList calls the Windows API GetPrivateProfileSection and specifies a 32 KB buffer for the data.

Therefore, the function returns only the first 32 KB of data from the section. An installation that needs to handle sections with more than 32 KB of data should call the Windows API GetPrivateProfileSection directly and specify a larger buffer size (and parse the returned information manually).

GetProfStringList Example
/*--------------------------------------------------------------*\ *
888 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetProfStringList

* InstallShield Example Script * * Demonstrates the function GetProfStringList. * * This script retrieves keys and their values from an * initialization file. \*--------------------------------------------------------------*/ #define EXAMPLE_INI "C:\\ISExampl.ini" // The new section, key, and value to add to the file. #define SECTION "InstallShield" #define KEY1 "Key1" #define KEY2 "Key2" #define KEY3 "Key3" #define KEY4 "Key4" #define KEY5 "Key5" #define VALUE1 1 #define VALUE2 2 #define VALUE3 3 #define VALUE4 4 #define VALUE5 5 // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetProfString(HWND); function ExFn_GetProfString(hMSI) STRING svResult, svKeyName, svKeyVal; LIST listKeyNames, listKeyValues; NUMBER nVal; begin // Add the profile strings WriteProfInt (EXAMPLE_INI, WriteProfInt (EXAMPLE_INI, WriteProfInt (EXAMPLE_INI, WriteProfInt (EXAMPLE_INI, WriteProfInt (EXAMPLE_INI, to the file. SECTION, KEY1, SECTION, KEY2, SECTION, KEY3, SECTION, KEY4, SECTION, KEY5,

VALUE1); VALUE2); VALUE3); VALUE4); VALUE5);

// Create a list to hold the key names; listKeyNames = ListCreate(STRINGLIST); // If an error occurred, report it; then terminate. if (listKeyNames = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); //Add your custom error handling code here. abort; endif; // Create a list to hold the key values; listKeyValues = ListCreate(STRINGLIST); // If an error occurred, report it; then terminate. if (listKeyValues = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); //Add your custom error handling code here. abort; endif; // Retrieve the keys from the specified section of the file.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 889

Appendix B: Built-In Functions (E-G) GetStatus

nVal = GetProfStringList (EXAMPLE_INI, SECTION, listKeyNames, listKeyValues); if (nVal = 0) then nVal = ListGetFirstString (listKeyNames, svKeyName); if (nVal = END_OF_LIST) then MessageBox("No keys found in [" + SECTION + "]", WARNING); else ListGetFirstString (listKeyValues, svKeyVal); repeat // Display the keys and their values. MessageBox(svKeyName + "=" + svKeyVal, INFORMATION); nVal = ListGetNextString (listKeyNames, svKeyName); if !(nVal = END_OF_LIST) then ListGetNextString (listKeyValues, svKeyVal); endif; until nVal = END_OF_LIST; endif; endif; end;

GetStatus
Project: The GetStatus function applies to InstallScript Object projects.

The GetStatus function retrieves the current status of the object; that is, the current value of Status.Number.

Tip: To retrieve additional information or to retrieve the status of an object from the installation that contains the object, use the objects Status object.

Syntax
number GetStatus();

Parameters
GetStatus takes no parameters.

Return Values
GetStatus returns the status of the object.

890

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetSystemInfo

GetSystemInfo
The GetSystemInfo function retrieves information about the target system. GetSystemInfo collects the information that it returns by using the Windows API.

Syntax
GetSystemInfo ( nItem, nvResult, svResult );

Parameters
Table B-176: GetSystemInfo Parameters Parameter nItem nvResult svResult Description Specifies the type of information to retrieve. Returns system information in the form of numeric data. Returns system information in the form of string data

The following table contains a list of constants that you can pass in the nItem parameter to retrieve system information. When using certain constants (such as DISK_TOTALSPACE_EX), you must specify additional information in the parameters nvResult and/or svResult before calling the function.
Table B-177: nItem Options nItem Option BOOTUPDRIVE nvResult Returns The ID of the bootup drive, where 1= A:, 2 = B:, 3 = C:. It is possible to convert this number to the appropriate drive letter by adding 64 (DECIMAL) to the value and then setting a string variable to this value. Use the following syntax to convert:
svResult[0] = 64 + nvResult;

svResult Returns Returns the drive designation (the drive letter followed by a colon) of the bootup drive.

CDROM

TRUE or FALSE Indicates whether a CD-ROM is available. Returns the number of colors available on the users system. The result is retrieved from the video driver on the target system, rather than from the monitor card. If the card can support 256 colors but the driver can handle only 16 colors, the number of colors returned is 16.

Not applicable

COLORS

Not applicable

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

891

Appendix B: Built-In Functions (E-G) GetSystemInfo

Table B-177: nItem Options (cont.) nItem Option CPU Note: This parameter is deprecated. Use the structure members of SYSPROCESSORINFO to determine the processor type. One of the following constants is returned: nvResult Returns svResult Returns Not applicable

DATE

IS_UNKNOWNThe user's CPU is unknown. IS_386The user has a 386 processor. IS_486The user has a 486 processor. IS_PENTIUMThe user has a PENTIUM processor. IS_ALPHAThe user has an ALPHA processor. The current system date in the format MM-DD-YYYY. Leading zeroes are suppressed in the month and day fields. The letter of the drive. Note that this parameter is passed to the function; that is, you must assign a value to svResult before calling GetSystemInfo. Also note that you must include the colon (:) after the drive letter; otherwise the function will fail. You can also specify a UNC path in this parameter. The letter of the drive. Note that this parameter is passed to the function; that is, you must assign a value to svResult before calling GetSystemInfo. Also note that you must include the colon (:) after the drive letter; otherwise the function will fail. You can also specify a UNC path in this parameter.

Not applicable

DISK_TOTALSPACE Note: This parameter is obsolete. Use the parameters available with the GetDiskInfo function instead. Returns the total capacity of the disk drive specified in svResult. The maximum value returned is 2 GB. Total disk space greater than that still returns as 2 GB. DISK_TOTALSPACE_EX Note: This parameter is obsolete. Use the parameters available with the GetDiskInfo function instead. Specifies the measurement unit; pass one of the following predefined constants in this parameter: BYTES, KBYTES, MBYTES or GBYTES. Returns the total capacity of the disk drive specified in svResult.

892

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetSystemInfo

Table B-177: nItem Options (cont.) nItem Option DRIVE Note: This parameter is obsolete. Use the parameters available with the GetDiskInfo function instead. Returns the type of the drive specified in svResult. One of the following constants is returned: nvResult Returns svResult Returns The letter of the drive followed by a colon (:). Note this parameter is passed to the function; that is, you must assign a value to svResult before calling GetSystemInfo. Due to operating system limitations, UNC paths are not supported for svResult. If you pass a UNC path in svResult, the function returns IS_UNKNOWN.

EXTENDEDMEMORY

IS_UNKNOWNTarget drive is unknown. IS_REMOVABLETarget drive is a floppy drive. IS_FIXEDTarget drive is a fixed drive. IS_CDROMTarget drive is a CD-ROM drive. IS_REMOTETarget drive is a network drive.

Returns the total amount of memory installed on the machine. Due to operating system limitations, the value returned may be slightly different than the actual amount of physical memory installed on the system. This value will normally be within 100K (0.1 MB) of the actual value. Note that the value returned is a measurement in kilobytes. GetSystemInfo (EXTENDEDMEMORY, ... ) accurately returns the amount of extended memory up to 2 terabytes (TB). If a system has more than 2 TB of extended memory, 2 TB is returned.

Not applicable

LANGUAGE

The InstallScript language constants for the target system are returned in this parameter. For more information, see Creating Multilingual Installations.

The equivalent language name string for the language constant returned in nvResult is returned in this parameter. Not applicable

OS

This parameter is deprecated. Use the WIN9X.bWin9X or WINNT.bWinNT members of the SYSINFO structure variable to obtain operating system information. You can conditionally install some or all of your product based upon operating system by using conditional logic for components, features, and custom actions. For more information, see Building Conditional Statements.

OSMAJOR

This parameter is deprecated. Use the nOSMajor member of the SYSINFO structure variable to obtain operating system information. This parameter is deprecated. Use the nOSMinor member of the SYSINFO structure variable to obtain operating system information.

Not applicable

OSMINOR

Not applicable

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

893

Appendix B: Built-In Functions (E-G) GetSystemInfo

Table B-177: nItem Options (cont.) nItem Option PARALLEL nvResult Returns Returns the number of physical parallel ports available. Returns the number of physical serial ports available. Not applicable svResult Returns Not applicable

SERIAL

Not applicable

TIME

Returns current system time in HH:MM:SS format. Not applicable

VIDEO

Returns the type of video adapter installed. (InstallShield cannot detect CGA or monochrome video drivers.) One of the following constants is returned:

VIRTUAL_MACHINE_TY PE

IS_UNKNOWNThe user's video is unknown. IS_EGAEGA resolution. IS_VGAVGA resolution. IS_SVGASuper VGA (800 x 600) resolution. IS_XVGAXVGA (1024 x 768) resolution. IS_UVGAGreater than 1024 x 768 resolution. Not applicable

Returns the type of virtual machine that is running the installation. One of the following constants is returned:

IS_VM_TYPE_HYPERVThe installation is running on a Microsoft Hyper-V machine. IS_VM_TYPE_VMWAREThe installation is running on a VMware product such as VMware Player, VMware Workstation, or VMware Server. IS_VM_TYPE_VIRTUALPCThe installation is running on a Microsoft Virtual PC machine. IS_VM_TYPE_NONENo virtual machine has been detected. IS_VM_TYPE_UNKNOWNThe type of virtual machine is not known.

For more information, see Detecting Whether the Installation Is Being Run on a Virtual Machine. VOLUMELABEL Not applicable Pass the drive designationthe drive letter followed by a colonof the disk whose volume label you want to retrieve. The volume label of the specified drive is then returned in this parameter. If the drive has no volume label, a null string ("") is returned.

894

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetSystemInfo

Table B-177: nItem Options (cont.) nItem Option WINMAJOR nvResult Returns This parameter is deprecated. Use the nWinMajor member of the SYSINFO structure variable to obtain operating system information. This parameter is deprecated. Use the nWinMinor member of the SYSINFO structure variable to obtain operating system information. svResult Returns Not applicable

WINMINOR

Not applicable

Return Values
Table B-178: GetSystemInfo Return Values Return Value 0 <0 Description Indicates that the function successfully returned the specified information. Indicates that the function was unable to return the specified information.

GetSystemInfo Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetSystemInfo function. * * This script uses many of the constants available for * GetSystemInfo and tests for all possible return values. * The results are displayed in a dialog. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetSystemInfo(HWND); function ExFn_GetSystemInfo(hMSI) STRING szTitle, szMsg, svResult, szInfo; NUMBER nvResult; LIST listInfo; begin // Create a list for system information. listInfo = ListCreate (STRINGLIST); // Get the amount of extended memory.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 895

Appendix B: Built-In Functions (E-G) GetSystemInfo

if (GetSystemInfo (EXTENDEDMEMORY, nvResult, svResult) < 0) then szInfo = "Couldn't get EXTENDEDMEMORY info."; else Sprintf(szInfo, "Extended memory: %d K", nvResult); endif; // Add the information to the list. ListAddString(listInfo, szInfo, AFTER); // Get the boot drive. if (GetSystemInfo (BOOTUPDRIVE, nvResult, svResult) < 0) then szInfo = "Couldn't get BOOTUPDRIVE info."; else Sprintf(szInfo, "Boot drive: %s", svResult); endif; // Add the information to the list. ListAddString(listInfo, szInfo, AFTER); // Get info about the CD-ROM. if (GetSystemInfo (CDROM, nvResult, svResult) < 0) then szInfo = "Couldn't get CD-ROM info."; else if (nvResult = 0) then svResult = "No"; else svResult = "Yes"; endif; Sprintf(szInfo, "CDROM: %s", svResult); endif; // Add the information to the list. ListAddString(listInfo, szInfo, AFTER); // Get the video adapter. if (GetSystemInfo (VIDEO, nvResult, svResult) < 0) then szInfo = "Couldn't get VIDEO info."; else switch (nvResult) case IS_UNKNOWN: szInfo = "VIDEO: UNKNOWN"; case IS_SVGA: szInfo = "VIDEO: SVGA"; case IS_XVGA: szInfo = "VIDEO: XVGA"; case IS_UVGA: szInfo = "VIDEO: UVGA"; endswitch; endif; // Add the information to the list. ListAddString(listInfo, szInfo, AFTER); // Get number of available colors. if (GetSystemInfo (COLORS, nvResult, svResult) < 0) then szInfo = "Couldn't get COLORS info."; else Sprintf(szInfo, "Number of colors: %d", nvResult); endif; // Add the information to the list.
896 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetSystemInfo

ListAddString(listInfo, szInfo, AFTER); // Get the current date. if (GetSystemInfo (DATE, nvResult, svResult) < 0) then szInfo = "Couldn't get DATE info."; else Sprintf(szInfo, "DATE: %s", svResult); endif; // Add the information to the list. ListAddString(listInfo, szInfo, AFTER); // Get the current time. if (GetSystemInfo (TIME, nvResult, svResult) < 0) then szInfo = "Couldn't get TIME info."; else Sprintf(szInfo, "TIME: %s", svResult); endif; // Add the information to the list. ListAddString(listInfo, szInfo, AFTER); // Get the operating system. if (GetSystemInfo (OS, nvResult, svResult) < 0) then szInfo = "Couldn't get Operating System info."; else switch (nvResult) case IS_WINDOWSNT: szInfo = "OS: Windows NT"; case IS_WINDOWS9X: GetSystemInfo (WINMINOR, nvResult, svResult); if (nvResult < 10) then szInfo = "OS: Windows 95"; else szInfo = "OS: Windows 98"; endif; endswitch; endif; // Add the information to the list. ListAddString(listInfo, szInfo, AFTER); // Display the information. szTitle = "System Information"; szMsg = "The following is some information related to your system:\n"; SdShowInfoList (szTitle, szMsg, listInfo); ListDestroy(listInfo); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

897

Appendix B: Built-In Functions (E-G) GetTempFileNameIS

GetTempFileNameIS
The GetTempFileNameIS function calls the Windows API GetTempFileName to create a temporary file and perform related actions. Note that unlike the Windows API GetTempFileName, GetTempFileNameIS creates the folder specified by szPathName if it does not already exist. Note that as with the CreateDir function, the newly created folder or folders are not logged for uninstallation.

Syntax
GetTempFileNameIS( byval string szPathName, byval string szPrefixString, byval number nUnique, byref string svTempFileName, byval number nOptions );

898

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetTempFileNameIS

Parameters
Table B-179: GetTempFileNameIS Parameters Parameter szPathName Description Specifies the path for the lpPathName parameter of the Windows API GetTempFileName. You can use text substitutions for this parameter. szPrefixString Specifies the string for the lpPrefixString parameter of the Windows API GetTempFileName. You can use text substitutions for this parameter. nUnique Specifies the integer for the nUnique parameter of the Windows API GetTempFileName. Specifies the value for the lpTempFileName parameter of the Windows API GetTempFileName.

svTempFileName

Note: InstallScript strings are automatically _MAX_PATH or greater in length. Therefore, there is no need to manually size this string. nOptions Specifies an InstallScript-specific option. Pass any of the following predefined constants in this parameter:

GTFIS_OPTION_NONENo InstallScript-specific options. This is the default option. GTFIS_OPTION_DONT_RESOLVE_TEXTSUBSDo not call TextSubSubstitute to resolve text substitutions in szPathName and szPrefixString. GTFIS_OPTION_DONT_CREATE_DIRDo not create the directory specified by szPathName if it does not already exist. Note that if this option is specified and szPathName does not exist, the function fails. GTFIS_OPTION_DELETE_TEMP_FILEDelete the created temporary file before returning. (Note that this option is useful only if you specify nUnique such that the function creates a temporary file. For more information, see GetTempFileName.) The function does not return failure if the temporary file cannot be deleted.

Return Values
Table B-180: GetTempFileNameIS Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

899

Appendix B: Built-In Functions (E-G) GetTrueTypeFontFileInfo

GetTrueTypeFontFileInfo
The GetTrueTypeFontFileInfo function returns in svResult information about the TrueType font file that is specified by szTrueTypeFontFile.

Syntax
GetTrueTypeFontFileInfo ( szTrueTypeFontFile, nInfo, nLanguage, svResult );

Parameters
Table B-181: GetTrueTypeFontFileInfo Parameters Parameter szTrueTypeFontFile Description Specifies the fully qualified file name of the TrueType font file from which you want information. Note that non-TrueType files such as .fon and .fot files are not supported by this function, nor are TrueType collection files (.ttc files) supported. Specifies the information to be returned in svResult. Pass one of the following constants in this parameter:

nInfo

nLanguage

TTFONTFILEINFO_FONTTITLESpecifies the fonts title. name IDYou can use a name ID to get font information.

Specifies the language of the string to be returned in svResult. Pass a predefined language constant, numeric language ID, the system variable SELECTED_LANGUAGE, or 0 (zero)which has the same effect as passing SELECTED_LANGUAGEin this parameter. Note that not all information for a particular font may be available in all languages. Returns the font information that you specified in nInfo. An ANSI (non-Unicode) string is returned even if the data in the file is stored in a Unicode format.

svResult

Return Values
Table B-182: GetTrueTypeFontFileInfo Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully retrieved the requested information. Indicates that the function was unable to retrieve the requested information.

GetUpdateStatus
The GetUpdateStatus function is obsolete. If this function is called, it returns FALSE.

Syntax
BOOL GetUpdateStatus();
900 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetUpdateStatusReboot

GetUpdateStatusReboot
The GetUpdateStatusReboot function is obsolete. If this function is called, it returns FALSE.

Syntax
BOOL GetUpdateStatusReboot();

GetValidDrivesList
The GetValidDrivesList function retrieves a list of all the drives attached to the target system that meet a certain criterion. This criterion includes the type of drive and the minimum amount of space on the drive. If a drive door is open, the drive name is still inserted into the list.

Syntax
GetValidDrivesList (listID, nDriveType, nMinDriveSpace);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

901

Appendix B: Built-In Functions (E-G) GetValidDrivesList

Parameters
Table B-183: GetValidDrivesList Parameters Parameter listID Description Returns a list of valid drive letters. The string list identified by listID must already have been initialized by a call to ListCreate. Specifies the type of drive to search for. Pass one of the following predefined constants in this parameter:

nDriveType

nMinDriveSpace

-1Searches for all drive types. FIXED_DRIVESearches only for fixed drives. REMOTE_DRIVESearches only for remote drives. Remote drives are generally located on a network. REMOVEABLE_DRIVESearches only for removable drives. Floppy drives are removable drives. CDROM_DRIVESearches only for CD-ROM drives.

Specifies the minimum amount of disk space in bytes that must be free on the drive to allow the drive to be included in the return list. If nMinDriveSpace is less than zero, GetValidDrivesList will not check for the minimum space on the drive. This is useful for floppy drives.

Return Values
Table B-184: GetValidDrivesList Return Values Return Value 0 <0 Description GetValidDrivesList successfully retrieved the requested list. GetValidDrivesList was unable to retrieve the list.

Additional Information
You can specify the type of drive to search for and the minimum amount of disk space that must be available before the drive is listed. Network mapping drives can be returned as remote drives. GetValidDrivesList might not return all drives on the network. Those drives designated as mapping drives only are returned.

GetValidDrivesList Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

902

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetValidDrivesList

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetValidDrivesList function. * * GetValidDrivesList is called twice: once to return a list of * removable drives that have a minimum of 120,000 bytes free, * then again to return a list of fixed drives that have a * minimum of 1,000,000 bytes free. * \*--------------------------------------------------------------*/ #define #define #define #define TITLE MSG_REMOVABLE MSG_FIXED MSG_ERR "GetValidDrivesList Example" "Removable drives with 120,000 bytes free:" "Fixed drives with 1,000,000 bytes free." "GetValidDrivesList failed."

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetValidDrivesList(HWND); function ExFn_GetValidDrivesList(hMSI) LIST listID; begin // Create a list to hold the removable drive names. listID = ListCreate (STRINGLIST); // Get removable drives with at least 120,000 bytes free. if (GetValidDrivesList (listID, REMOVEABLE_DRIVE, 120000) < 0) then // Report an error; then terminate. MessageBox (MSG_ERR, SEVERE); abort; else // Display the list of removable drives. SdShowInfoList (TITLE, MSG_REMOVABLE, listID); endif; // Destroy the list of removable drives. ListDestroy (listID); // Create a list to hold the fixed drive names. listID = ListCreate (STRINGLIST); // Get fixed drives with at least one million bytes free. if (GetValidDrivesList (listID, FIXED_DRIVE, 1000000) < 0) then // Report an error; then terminate. MessageBox (MSG_ERR, SEVERE); abort; else // Display the list of fixed drives. SdShowInfoList (TITLE, MSG_FIXED, listID); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

903

Appendix B: Built-In Functions (E-G) GetWCHARArrayFromISStringArray

GetWCHARArrayFromISStringArray
The GetWCHARArrayFromISStringArray function returns a pointer to an array of pointers to Unicode character strings that are contained in the specified array.

Syntax
GetWCHARArrayFromISStringArray ( vArray );

Parameters
Table B-185: GetWCHARArrayFromISStringArray Parameters Parameter vArray Description Specifies the string array to which you want a pointer.

Return Values
Table B-186: GetWCHARArrayFromISStringArray Return Values Return Value pointer < ISERR_SUCCESS Description A pointer to an array of pointers to Unicode character strings. Indicates that the function failed.

Additional Information
The GetWCHARArrayFromISStringArray function allocates additional memory for the array of pointers and the Unicode character strings. This pointer can be passed to functions that take LPWSTR* arguments. After you are done with the newly created array, call DeleteWCHARArray to delete the array from memory. If you call CopyCHARArrayToISStringArray to write the data from the array of pointers back to the original string array, be careful when modifying strings that are contained in the array. Since the lengths of the strings that are contained in string arrays are managed internally by the installation, if you change the length of a string the entire string will not be copied back to the original array when you call CopyCHARArrayToISStringArray.

GetWindowHandle
The GetWindowHandle function gets the handle of the main window of the installation.

Syntax
GetWindowHandle ( nHwndFlag );

904

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix B: Built-In Functions (E-G) GetWindowHandle

Parameters
Table B-187: GetWindowHandle Parameters Parameter nHwndFlag Description Specifies the window handle of InstallShield's main window. Pass the predefined constant HWND_INSTALL in this parameter.

Return Values
Table B-188: GetWindowHandle Parameters Return Value X <0 Description Where X is the handle of the window. GetWindowHandle was unable to retrieve the handle.

GetWindowHandle Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the GetWindowHandle function. * * This script starts the setup in a normal window. After three * seconds, the window is minimized. Then after another pause, * the window is maximized and a message box is displayed. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_GetWindowHandle(HWND); function ExFn_GetWindowHandle(hMSI) NUMBER nHwnd; HWND hInstallHwnd; begin // Specify a standard window for this setup. Enable (DEFWINDOWMODE); // Display the background window. Enable (BACKGROUND); // Get the setup's window handle. nHwnd = GetWindowHandle (HWND_INSTALL); // Wait three seconds. Delay (3); // Send system command to minimize the window.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 905

Appendix B: Built-In Functions (E-G) GetWindowHandle

SendMessage (nHwnd, WM_SYSCOMMAND, SC_MINIMIZE, 0); // Wait three seconds. Delay (3); // Send system command to maximize the window. SendMessage (nHwnd, WM_SYSCOMMAND, SC_MAXIMIZE, 0); // Display a message. MessageBox ("Demo completed.", INFORMATION); end;

906

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

C
Built-In Functions (H-P)
For a list of functions by category, see Built-In Functions by Category.

Handler
The Handler function is obsolete. Use HandlerEx instead.

HandlerEx
The HandlerEx function creates custom handlers for events such as the Help accelerator key (F1) and the Cancel button. If the end user presses the F1 key, the currently defined HELP handler is executed. If the user presses the Cancel button, the currently defined EXIT handler is executed. If you have not defined custom HELP or EXIT handlers using the HandlerEx function, the default handlers are executed. The default EXIT handler displays the Exit dialog. The default HELP handler does nothing. To execute custom handlers defined using HandlerEx, the InstallScript engine calls a unique label that is specified in the parameter Label when the nObject event occurs. When the InstallScript engine reaches a return statement in the handler code (under the label), control returns to the statement that would have executed next if the handler label were not called. Using HandlerEx, you can specify custom handling of EXIT or HELP. You can display the MessageBox, SprintfBox, and AskYesNo dialogs inside Exit handlers; however, you cannot display Sd dialogs.

Syntax
HandlerEx (nObject, Label);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

907

Appendix C: Built-In Functions (H-P) HandlerEx

Parameters
Table C-1: HandlerEx Parameters Parameter nObject Description Specifies the event to trap. Pass one of the following predefined constants in this parameter:

EXITSpecifies that a custom handler is called when the Cancel button is pressed. If you do not define a handler, a default Exit dialog appears when the Cancel button is pressed. HELPSpecifies that a custom handler is called when the F1 accelerator key is pressed. If you do not define a handler, nothing happens when the F1 accelerator key is pressed.

Label

Specifies the name of the label to which the program should jump if the specified button or accelerator key is pressed. Do not define this label as a numeric value or as a string variable. To cancel a currently defined handler and reinstall the default handler, pass -1 in this parameter. This method is useful in scripts that install a custom handler only for certain processes and then revert to the default handler.

Caution: Do not define the label name as a numeric value or as a string variable.

Return Values
Table C-2: HandlerEx Return Values Return Value 0 <0 Description HandlerEx successfully created the handle. HandlerEx was unable to create the handle.

Additional Information
The only accelerator available is the F1 function key (Help). Help (F1) allows you to launch the help engine or provide other suitable help. When the end user presses the F1 key, the InstallScript engine calls the currently defined Help handler. You can provide any type of help functionality in the Help handler. If you want to provide context-sensitive help, you must keep track of the context in your script. For example, you can have a string variable that contains a current context string. You can then use that string variable in a switch-case statement inside the Help handler to execute the appropriate Help events based on the value of the context string. You can also test the value of the nSdDialog global variable in your Help handling routine. nSdDialog is set to the dialog ID (as described in _isres.h in the InstallShield Program Files Folder\Script\Isrt\Include folder) of the currently executing Sd dialog. (When no Sd dialog is executing, nSdDialog is not defined.) You can therefore give the user access to Sd dialog-specific help when an Sd dialog is executing.
908 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) HandlerEx

As with Help handlers, you can also define and execute custom and Sd dialog-specific EXIT handlers.

HandlerEx Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the HandlerEx function. * * This script shows how to install error and help handlers in * an installation. * * First, the handlers are installed. Then Sd dialogs are * displayed to the end user. The handler code is invoked if * the end user presses F1 (help) or clicks the cancel * button while the dialogs are displayed. * * Note that the script uses the InstallScript Language * Reference and Help Library help files for demonstration purposes. * Insert copies of these files (Langref.chm and HelpLib.chm from * the InstallShield Program Files Folder\Program folder) in the * Language Independent area of the Support Files/Billboards view. \*--------------------------------------------------------------*/ // Included header files ---------------------------------------------------#include "ifx.h" export prototype void ExFn_Handler(); prototype OnHelp_Handler(); prototype OnExit_Handler(); // Define help topic IDs #define HELP_WELCOME 101 #define HELP_REGISTERUSER 102 INT nHelpID;

function void ExFn_Handler() STRING svName, svCompany, szMsg; begin // Install the help handler. HandlerEx (HELP, OnHelp_Handler); // Install the exit handler. HandlerEx (EXIT, OnExit_Handler); // Set message for display in dialogs. szMsg = "Press F1 to display InstallShield's " + "help for this dialog.\n" + "Press Cancel to invoke the custom exit handler."; WelcomeDialog:
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 909

Appendix C: Built-In Functions (H-P) HIBYTE

// Set the help topic ID. nHelpID = HELP_WELCOME; // Display the Welcome dialog. SdWelcome ("SdWelcome Dialog", szMsg); // Set the help topic ID. nHelpID = HELP_REGISTERUSER; if SdRegisterUser ("Register", szMsg, svName, svCompany) = BACK then // Go back to the Welcome dialog. goto WelcomeDialog; endif; end; function OnHelp_Handler() STRING szHelpTopic; begin // Set the topic to be displayed from the help. switch (nHelpID) case HELP_WELCOME : szHelpTopic = "5223 "; case HELP_REGISTERUSER : szHelpTopic = "5211 "; endswitch; // Launch the InstallScript language reference and // display the selected help topic. LaunchApplication (WINDIR ^ "hh.exe", "-mapid " + szHelpTopic + SUPPORTDIR ^ "Help_Lib.chm", "", SW_SHOW, INFINITE, LAAW_OPTION_WAIT); end; function OnExit_Handler() begin // Ask for confirmation to abort. if AskYesNo ("Do you really want to exit?", FALSE) = YES then // Abort the setup. abort; else // Return to the setup. return 0; endif; end;

HIBYTE
Project: This information applies to InstallScript projects.

The HIBYTE function extracts the high-order byte from the 16-bit integer value specified by shValue.

Syntax
HIBYTE ( shValue );

910

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) HIWORD

Parameters
Table C-3: HIBYTE Parameters Parameter shValue Description Specifies the 16-bit integer from which you want to extract the higher byte.

Return Values
This function returns the high-order byte of the integer.

HIWORD
The HIWORD function extracts and returns the high-order word (upper two bytes) from the 32-bit integer value specified by lValue. InstallShield's HIWORD differs from the corresponding C macro in that it uses sign extension. As a result, the high-order bytes of the value returned by HIWORD are filled with ones if lValue is negative. If necessary, you can use the bitwise AND operator (&) to combine the result with 0xFFFF to produce a positive value, as shown below:
lValue = HIWORD(lValue); lValue = lValue & 0xFFFF;

Syntax
HIWORD ( lValue );

Parameters
Table C-4: HIWORD Parameters Parameter lValue Description Specifies the 32-bit integer from which to extract the upper two bytes.

Return Values
HIWORD returns the high-order word (upper two bytes) of lValue.

HIWORD Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

911

Appendix C: Built-In Functions (H-P) InstallationInfo

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates HIWORD and LOWORD. * * This example script shows how to use HIWORD and LOWORD to * to get the low-order word and the high-order word from a value. \*--------------------------------------------------------------*/ #define TITLE_TEXT "LOWORD/HIWORD Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_HIWORD(HWND); function ExFn_HIWORD(hMSI) STRING szMsg; NUMBER nData, nLOWORD, nHIWORD; begin nData = 305419896; // hex value: 12345678 // Get the low-order word, 22136 (hex value: 5678). nLOWORD = LOWORD (nData); // Get the high-order word, 4660 (hex value: 1234). nHIWORD = HIWORD (nData); // Display the results. szMsg = "LOWORD: %ld\nHIWORD: %ld"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, nLOWORD, nHIWORD); end;

InstallationInfo
The InstallationInfo function is obsolete. Use the CreateInstallationInfo function instead.

Syntax
InstallationInfo (szCompany, szProduct, szVersion, szProductKey);

Is
The Is function retrieves information commonly needed in a script.

Syntax
Is ( nIsFlag, szIsData );

912

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) Is

Parameters
Table C-5: Is Parameters Parameter nIsFlag Description Specifies the type of information to retrieve. Pass one of the following predefined constants in this parameter:

BACKBUTTONIs the Back button that is displayed in some built-in dialogs enabled? CANCELBUTTONIs the Cancel button that is displayed in some built-in dialogs enabled? DOTNETFRAMEWORKINSTALLEDIs a particular version of the .NET Framework or language pack installed? For more information on the predefined values that are supported, see the Additional Information section. DOTNETSERVICEPACKINSTALLEDIs a particular service packor a later version of the service packof the .NET Framework installed? For more information on the predefined values that are supported, see the Additional Information section. DIR_WRITEABLECan the installation write to the directory that is specified in szIsData? FILE_EXISTSDoes the file that is specified in szIsData exist? FILE_LOCKEDIs the file locked? Note that Is returns TRUE if the file is not accessible because of insufficient privileges. FILE_WRITEABLECan the installation write to the file specified in szIsData? FONT_AVAILABLEIs the font with the title that is specified in szIsData installed? Note that the function searches for the font in all character sets. To search in a single character set, call the Windows API function EnumFontFamiliesEx; for details on this function, see Microsoft's Windows API documentation. FUNCTION_EXPORTEDDoes the DLL that is specified in szIsData export the function specified in szIsData? Is returns TRUE if the DLL exists and can be loaded, and if the function is exported. Otherwise, Is returns FALSE. LANGUAGE_SUPPORTED(InstallScript and InstallScript MSI projects) Does the installation support the language that is specified in szIsData? LOGGING(InstallScript projects only) Is logging of uninstallation information enabled? MATH_COPROCESSORDoes a math coprocessor exist in the target system? NEXTBUTTONIs the Next button that is displayed by some built-in dialogs enabled? On most dialogs, the Next button is enabled by default. PATH_EXISTSDoes the path that is specified in szIsData exist? REGDBREMOTEREGCONNECTEDIs a remote registry currently connected? REBOOTEDIs the installation running after a reboot?

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

913

Appendix C: Built-In Functions (H-P) Is

Table C-5: Is Parameters (cont.) Parameter nIsFlag (cont.) Description

SETUP_PACKAGE(InstallScript projects only) Is the setup running from a self-extracting executable file? During maintenance mode or during uninstallation, Is(SETUP_PACKAGE, szIsData) returns TRUE if the original installation was a self-extracting executable file (although maintenance or uninstallation runs not from the self-extracting executable file, but from the copy of Setup.exe in the DISK1TARGET folder).

SKIN_LOADEDIs a dialog skin loaded? URLIs the string that is specified in szIsData a URL? (That is, does the string begin with "http:// " or "https://" or "file://" or "ftp://"?) USER_ADMINISTRATORDoes the current user have administrator privileges? Is returns TRUE when USER_ADMINISTRATOR is passed in nFlag in all cases, except for some cases on Windows Vista and later systems; on these later systems, Is returns TRUE if the USER_ADMINISTRATOR is passed in nFlag and the SE_GROUP_USE_FOR_DENY_ONLY security identifier (SID) attribute is not set for the group. That is, if the current user is in the Administrators group but that user is running the installation with a standard access token on Windows Vista or later, Is returns FALSE. USER_INADMINGROUPIs the current user in the Administrators group? Is returns TRUE for this constant, regardless of whether the SE_GROUP_USE_FOR_DENY_ONLY SID attribute is set for the group (that is, regardless of whether the user with administrative privileges is running the installation with a standard access token). USER_POWERUSERDoes the current user belong to the Power Users group? VALID_PATHIs the path specified in szIsData a legal path? This will not confirm the existence of a path, it will only check its syntax. You can use this constant when you retrieve path information from the user. The function will then check to see if the path information was entered correctly. A valid URL string meets the following criteria: (1) It begins with http://, https://, or file://. (2) It contains only numbers, letters, and the following characters: ! $ % & ' ( ) * + - . / \ _

nIsFlag (cont.)

WEB_BASED_SETUP(InstallScript projects only) Is the installation being run from the Internet?

Note: Is(WEB_BASED_SETUP,szIsData) checks whether the current instance of the installation is being run from the Web. For this reason, when the installation is run from Add or Remove Programs, Is(WEB_BASED_SETUP,szIsData) always returns FALSE, since in that case the installation is always being run from the local files even if the original installation was run from the Web.

WINDOWS_SHAREDIs Microsoft Windows running a shared copy from a network? A shared copy of Microsoft Windows is installed on a network and has common files that are shared by many users.

914

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) Is

Table C-5: Is Parameters (cont.) Parameter szIsData Description Specifies information that is dependent on the constant that is passed in nIsFlag, as shown below. Note that if the path or file name is enclosed in quotation marks, Is fails. To ensure that the path or file name is not enclosed in quotation marks, call LongPathToQuote(szIsData, FALSE) before calling Is. The following list provides an explanation of what szIsData should contain when each nIsFlag option is specified:

DIR_WRITEABLEszIsData specifies the fully qualified path to be checked. DOTNETFRAMEWORKINSTALLEDszIsData specifies the version of the .NET Framework or language pack to check. For more information on the predefined values that are supported, see the Additional Information section. DOTNETSERVICEPACKINSTALLEDszIsData specifies the minimum service pack and version of the .NET Framework to check, in the following format:
Service Pack Number|.NET Version Registry Constant or Path Service Pack Number indicates the number of the minimum service pack. For the .NET Framework 1.0, the value can be 0 through 3. For the .NET Framework 1.1 and later, all numeric values are supported. Both the service pack number and the pipe character (|) delimiter must be included; otherwise, the function returns failure. .NET Version Registry Constant or Path indicates the registry constant or registry path

that shows the version of the .NET Framework to check. For more information on the predefined values that are supported and to learn how the Is function performs the check, see the Additional Information section.

FILE_EXISTSszIsData specifies the fully qualified file name. You can specify a valid URL in this parameter. To check the validity of a URL, call Is(VALID_PATH, szIsData). FILE_LOCKEDszIsData specifies the fully qualified file name. FILE_WRITEABLEszIsData specifies the fully qualified file name. FONT_AVAILABLEszIsData specifies the font title. FUNCTION_EXPORTEDszIsData specifies the fully qualified file name of the DLL followed by a pipe character (|) and the name of the function; for example:
C:\\MyDLLFolder\\MyDLL.dll|MyFunction

LANGUAGE_SUPPORTEDszIsData specifies the path to the Setup.ini file and the language ID, in the following format:
Path to Setup.ini|Language ID

If the path to Setup.ini is not specified, the current installation is used. If the language ID is not specified, SELECTED_LANGUAGE is used. The language ID should be a four-digit hexadecimal language code, including the 0x prefix. For example, if for English, the value should be 0x0409. To build a string with STANDARD_SELECTED_LANGUAGE in this format, use a statement such as:
Sprintf (szLang, "0x%.04lx", STANDARD_SELECTED_LANGUAGE);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

915

Appendix C: Built-In Functions (H-P) Is

Table C-5: Is Parameters (cont.) Parameter szIsData (cont.) Description

LOGGINGszIsData is ignored. MATH_COPROCESSORszIsData specifies szIsData is ignored. PATH_EXISTSszIsData specifies the fully qualified path. You can specify a valid URL in this parameter. To check the validity of a URL, call Is(VALID_PATH, szIsData). REGDBREMOTEREGCONNECTEDszIsData is ignored. SETUP_PACKAGEszIsData is ignored. SKIN_LOADEDszIsData is ignored. USER_ADMINISTRATORszIsData is ignored. USER_POWERUSERszIsData is ignored. VALID_PATHszIsData specifies the fully qualified path. WEB_BASED_SETUPszIsData is ignored. WINDOWS_SHAREDszIsData is ignored.

Return Values
Table C-6: Is Return Values Return Value TRUE (1) FALSE (0) <0 Description Indicates that the answer is true. Indicates that the answer is false. The Is function was unable to answer the question.

Additional Information
.NET Framework Version and Service Details The following predefined constants are supported for specifying a particular version of the .NET Framework using DOTNETFRAMEWORKINSTALLED or DOTNETSERVICEPACKINSTALLED:

916

REGDB_KEYPATH_DOTNET_40_CLIENT REGDB_KEYPATH_DOTNET_40_FULL REGDB_KEYPATH_DOTNET_35 REGDB_KEYPATH_DOTNET_30_SPUse this variable to detect whether the SP1 (or a later service pack) of the .NET Framework 3.0 is installed. REGDB_KEYPATH_DOTNET_30Use this variable to detect whether the RTM version of the .NET Framework 3.0 is installed. REGDB_KEYPATH_DOTNET_20 REGDB_KEYPATH_DOTNET_11

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) Is

REGDB_KEYPATH_DOTNET_10

Tip: Since each of these predefined constants correspond to the appropriate registry path under HKEY_LOCAL_MACHINE, you can also specify a registry path directly in szIsData for DOTNETFRAMEWORKINSTALLED or DOTNETSERVICEPACKINSTALLED.

The installation of the .NET Framework 3.0 writes the registry value InstallSuccess, with 1 as the value data, in the following registry location:
HKEY_LOCAL_MACHINE\Software\Microsoft\NET Framework Setup\NDP\v3.0\Setup\

Therefore, REGDB_KEYPATH_DOTNET_30 is set to that location. The installations of all other versions of the .NET Framework write the registry value Install with a value data of 1 in the following registry location:
HKEY_LOCAL_MACHINE\Software\Microsoft\NET Framework Setup\NDP\Version Number\

The REGDB_KEYPATH_DOTNET_35, REGDB_KEYPATH_DOTNET_20, REGDB_KEYPATH_DOTNET_11, and REGDB_KEYPATH_DOTNET_10 constants are set to the appropriate values, based on that path. Note that the installation of the .NET Framework 3.0 SP1 also writes the registry value Install with a value data of 1 in the following registry location:
HKEY_LOCAL_MACHINE\Software\Microsoft\NET Framework Setup\NDP\v3.0\

Therefore, REGDB_KEYPATH_DOTNET_30_SP is set to that location. If you use the Is function with the DOTNETFRAMEWORKINSTALLED constant, the function automatically checks for both the Install and InstallSuccess values. If the Install or InstallSuccess value exists and its value data is set to 1, Is returns TRUE. Otherwise, Is returns FALSE. The .NET Framework 1.0 service pack installations do not create registry values that indicate the service pack number. Therefore, if you use DOTNETSERVICEPACKINSTALLED to test for the .NET Framework 1.0, the Is function compares the version of the mscorlib.dll file in FOLDER_DOTNET_10 against known version numbers to determine the service pack:

SP3 is present if the version of mscorlib.dll is 1.0.3705.6018 or later. SP2 is present if the version of mscorlib.dll is 1.0.3705.288 or later, but earlier than 1.0.3705.6018. SP1 is present if the version of mscorlib.dll is 1.0.3705.209 or later, but earlier than 1.0.3705.288. The original RTM version is present if the version of mscorlib.dll is 1.0.3705.0 or later, but earlier than 1.0.3705.209.

If you use DOTNETSERVICEPACKINSTALLED to test for any of the other .NET Framework versions, the function compares the REGDB_VALUENAME_SP value under the .NET version registry constant or path that is specified in szIsData with the service pack number that is specified in szIsData. Note that the comparison is an equal-to-or-later-than version comparison; therefore, if you specify a service pack of 2 in szIsData, the function returns true whenever service pack 2 or later is installed. .NET Framework Language Pack Details Version 1.1 and later of the .NET Framework includes support for language packs; version 1.0 does not. For version 1.1 and later of the .NET Framework, you can test whether a particular .NET language pack is installed through the DOTNETFRAMEWORKINSTALLED constant by specifying the appropriate
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 917

Appendix C: Built-In Functions (H-P) Is

.NET version constant and the locale identifier (LCID) of the language (converted to a string). Separate the .NET version constant and the LCID with the caret operator. For example, use the following syntax to test whether the German language pack for .NET Framework 1.1 is installed:
NumToStr( szLang, ISLANG_GERMAN_STANDARD ); REGDB_KEYPATH_DOTNET_11 ^ szLang;

As documented by Microsoft, the .NET Framework 1.1 supports the following LCIDs:
Table C-7: Supported .NET LCIDs Language Chinese (Simplified) Chinese (Traditional) Czech Danish Dutch Finnish French German Greek Hungarian Italian Japanese Korean Norwegian Polish Portuguese (Brazilian) Portuguese (Portugal) Russian Spanish Swedish Turkish LCID 2052 (0x0804) 1028 (0x0404) 1029 (0x0405) 1030 (0x0406) 1043 (0x0413) 1035 (0x040B) 1036 (0x040C) 1031 (0x0407) 1032 (0x0408) 1038 (0x040E) 1040 (0x0410) 1041 (0x0411) 1042 (0x0412) 1044 (0x0414) 1045 (0x0415) 1046 (0x0416) 2070 (0x0816) 1049 (0x0419) 3082 (0x0C0A) 1053 (0x041D) 1055 (0x041F) Corresponding Is Constant ISLANG_CHINESE_SIMPLIFIED ISLANG_CHINESE_TRADITIONAL ISLANG_CZECH_STANDARD ISLANG_DANISH_STANDARD ISLANG_DUTCH_STANDARD ISLANG_FINNISH_STANDARD ISLANG_FRENCH_STANDARD ISLANG_GERMAN_STANDARD ISLANG_GREEK_STANDARD ISLANG_HUNGARIAN_STANDARD ISLANG_ITALIAN_STANDARD ISLANG_JAPANESE_STANDARD ISLANG_KOREAN_STANDARD ISLANG_NORWEGIAN_BOKMAL ISLANG_POLISH_STANDARD ISLANG_PORTUGUESE_BRAZILIAN ISLANG_PORTUGUESE_STANDARD ISLANG_RUSSIAN_STANDARD ISLANG_SPANISH_MODERNSORT ISLANG_SWEDISH_STANDARD ISLANG_TURKISH_STANDARD

918

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) Is

Is Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the Is function. * * The Is function is first called to check if a file is write * protected. It is called a second time to check if the * directory is write protected. This is useful for checking * the write protection of directories on a network. The third * time the Is function is called, the function checks if Windows * is installed on a network server or if it is installed on the * local system. * * Note: Before running this script, set the defined constants * so that they point to an existing file on the target * system. * \*--------------------------------------------------------------*/ #define EXAMPLE_DIR #define EXAMPLE_FILE #define TITLE "C:\\WINDOWS" EXAMPLE_DIR^"Win.com" "Is Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_Is(HWND); function ExFn_Is(hMSI) NUMBER nResult; begin // Check if the EXAMPLE_FILE file is write-protected. nResult = Is (FILE_WRITEABLE, EXAMPLE_FILE); // Report the results. if (nResult = TRUE) then SprintfBox (INFORMATION, TITLE, "%s is writeable.", EXAMPLE_FILE); elseif (nResult = FALSE) then SprintfBox (INFORMATION, TITLE, "%s is not writeable.", EXAMPLE_FILE); else SprintfBox (INFORMATION, TITLE, "Unable to determine if %s is writeable.", EXAMPLE_FILE); endif; // Check if the directory is write-protected. nResult = Is (DIR_WRITEABLE, EXAMPLE_DIR); // Report the results. if (nResult = TRUE) then SprintfBox (INFORMATION, TITLE, "%s is writeable.", EXAMPLE_DIR); elseif (nResult = FALSE) then

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

919

Appendix C: Built-In Functions (H-P) ISCompareServicePack

SprintfBox (INFORMATION, TITLE, "%s is not writeable.", EXAMPLE_DIR); else SprintfBox (INFORMATION, TITLE, "Unable to determine if %s is writeable.", EXAMPLE_DIR); endif; // Check if Windows is being shared on a network. nResult = Is (WINDOWS_SHARED, ""); // Report the results. if (nResult = TRUE) then MessageBox ("Windows is shared.", INFORMATION); elseif (nResult = FALSE) then MessageBox ("Windows is not shared.", INFORMATION); else MessageBox ("Unable to determine if Windows is shared.", SEVERE); endif; end;

ISCompareServicePack
The ISCompareServicePack function is supported only for compatibility with scripts created in InstallShield Professional. It is recommended that you determine the Windows service pack number by checking the value of SYSINFO.WINNT.nServicePack instead. The ISCompareServicePack function compares the service pack number installed on a Windows system to the service pack number specified by szServicePack.

Syntax
ISCompareServicePack ( szServicePack );

920

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ISCompareServicePack

Parameters
Table C-8: ISCompareServicePack Parameters Parameter szServicePack Description Specifies the Service Pack number to be compared with the Service Pack number on the target computer. This string must be in the format Service Pack n, where n is the Service Pack number. The comparison is case sensitive.

Return Values
Table C-9: ISCompareServicePack Return Values Return Value LESS_THAN (1) Description No Service Pack is installed or the Service Pack number on the target system is less than the value passed in szServicePack. The Service Pack numbers match. The Service Pack number on the target system is greater than the number passed in szServicePack. ISCompareServicePack failed to compare the Service Pack numbers.

EQUALS (2) GREATER_THAN (0)

-1

ISCompareServicePack Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ISCompareServicePack function. * * Note: ISCompareServicePack is defined in Sdint.rul. * \*--------------------------------------------------------------*/ #define SERVICE_PACK "Service Pack 3" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ISCompareServicePack(HWND); function ExFn_ISCompareServicePack(hMSI)

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

921

Appendix C: Built-In Functions (H-P) ISDeterminePlatform

BOOL bWinNT; NUMBER nvResult; STRING svResult; begin // Determine which operating system is running. GetSystemInfo (OS, nvResult, svResult); if (nvResult = IS_WINDOWSNT) then // Running Windows NT. bWinNT = TRUE; // Check if Service Pack 3 is installed. nvResult = ISCompareServicePack (SERVICE_PACK); if (nvResult < 0) then MessageBox ("Error: ISCompareServicePack failed.", SEVERE); elseif (nvResult = LESS_THAN) then MessageBox ("No service pack or the service pack is less than " + SERVICE_PACK, INFORMATION); elseif (nvResult = EQUALS) then MessageBox ("The service pack is " + SERVICE_PACK, INFORMATION); elseif (nvResult = GREATER_THAN) then MessageBox ("The service pack is greater than " + SERVICE_PACK, INFORMATION); endif; else MessageBox ("The target system is not running Windows NT.", SEVERE); endif; end;

ISDeterminePlatform
The ISDeterminePlatform function sets the system variable SYSINFO, a structured variable whose members are used to specify information about the operating platform of the target computer. ISDeterminePlatform is called directly by the setup engine during setup initialization.

Parameters
None

Return Values
None

IsEmpty
The IsEmpty function checks whether a variable of type VARIANT has been initialized. To check whether a variable of type OBJECT has been assigned a reference to a valid object, call IsObject.

922

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) IsEmpty

Syntax
IsEmpty ( vVariant );

Parameters
Table C-10: IsEmpty Parameters Parameter vVariant Description Specifies the variable to be checked.

Return Values
Table C-11: IsEmpty Return Values Return Value TRUE (1) FALSE (0) Description vVariant has been initialized. vVariant has not been initialized.

IsEmpty Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the IsEmpty function. * \*--------------------------------------------------------------*/ function OnBegin() VARIANT vVariant; BOOL bEmpty; STRING szString; begin bEmpty = IsEmpty ( vVariant ); /* The message "vVariant is empty." is displayed. */ if bEmpty then MessageBox ( "vVariant is empty." , INFORMATION ); else MessageBox ( "vVariant is not empty." , INFORMATION ); endif; /* Initialize vVariant. */ vVariant = szString; bEmpty = IsEmpty ( vVariant ); /* The message "vVariant is not empty." is displayed. */ if bEmpty then MessageBox ( "vVariant is empty." , INFORMATION ); else MessageBox ( "vVariant is not empty." , INFORMATION ); endif;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

923

Appendix C: Built-In Functions (H-P) IsObject

/* Terminate example setup script. */ abort; end;

IsObject
The IsObject function checks whether a variable of type OBJECT has been assigned a reference to a valid object, using the CreateObject or GetObject functions.

Syntax
IsObject ( oObject );

Parameters
Table C-12: IsObject Parameters Parameter oObject Description Specifies the variable to be checked.

Return Values
Table C-13: IsObject Return Values Return Value TRUE Description oObject has been assigned a reference to a valid object. oObject has not been assigned a reference to a valid object.

FALSE

LaunchApp
The LaunchApp function enables you to launch another application from within the script. LaunchApp calls LaunchAppAndWait( szCommand, szCmdLine, LAAW_OPTION_NOWAIT ). For information on LaunchApp parameters and return values, see LaunchAppAndWait.

LaunchApp Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script

924

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LaunchAppAndWait

* * Demonstrates the LaunchApp function. * * LaunchApp is called to execute an application. * * Note: Before running this script, set the preprocessor * constants so that they reference the fully qualified * names of the Windows Notepad executable and a valid * text file on the target system. * \*--------------------------------------------------------------*/ #define APPLICATION WINDIR^"Notepad.exe" #define CMD_LINE WINDIR^"Readme.txt" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_LaunchApp(HWND); function ExFn_LaunchApp(hMSI) begin // Launch the Windows Notepad application to edit // the Windows Readme.txt file. if (LaunchApp (APPLICATION, CMD_LINE) < 0) then MessageBox ("Unable to launch "+APPLICATION+".", SEVERE); endif; end;

LaunchAppAndWait
The LaunchAppAndWait function enables you to launch another application from within the script. LaunchAppAndWait calls the following:
LaunchApplication( szProgram, szCmdLine, "", LAAW_STARTUPINFO.wShowWindow, LAAW_PARAMETERS.nTimeOut, nOptions | LAAW_OPTION_CHANGEDIRECTORY | LAAW_OPTION_FIXUP_PROGRAM );

For more information on parameters and return values for LaunchAppAndWait, see LaunchApplication.

Syntax
LaunchAppAndWait ( szProgram, szCmdLine, nOptions );

LaunchAppAndWait Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the LaunchAppAndWait function.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 925

Appendix C: Built-In Functions (H-P) LaunchAppAndWait

* * This script presents the user with three options: * * -- Launch Notepad; after it closes, continue setup * -- Launch Notepad and continue setup immediately * -- Exit installation * * If the user selects the first option, the installation * launches Notepad and then waits for it to close before * continuing. If the user selects the second option, the * installation launches Notepad and then continues immediately * to execute the script. If the user selects the third option, * the installation exits. * \*--------------------------------------------------------------*/ #define #define #define #define PROGRAM LAUNCH_WAIT_TEXT LAUNCH_GO_TEXT EXIT_TEXT WINDIR^"NotePAD.EXE" "Launch Notepad; after it closes, continue setup" "Launch Notepad and continue setup immediately" "Exit installation"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_LaunchAppAndWait(HWND); function ExFn_LaunchAppAndWait(hMSI) STRING szProgram, szCmdLine, szMsg; BOOL bLaunchAndGo, bLaunchAndWait, bExit; NUMBER nWait; begin // Run the installation in a normal Window; Enable (BACKGROUND); Enable (DEFWINDOWMODE); // Disable the Back button in installation dialogs. Disable (BACKBUTTON); // Get an option from the user. AskOptions (EXCLUSIVE, "Test", LAUNCH_WAIT_TEXT, bLaunchAndWait, LAUNCH_GO_TEXT, bLaunchAndGo, EXIT_TEXT, bExit); if !bExit then // Set variable to pass to LaunchAppAndWait // to indicate whether or not to wait. if bLaunchAndWait then nWait = WAIT; else nWait = NOWAIT; endif; // Launch Notepad; the value of nWait determines // when execution of the installation continues. if (LaunchAppAndWait (PROGRAM, "", nWait) < 0) then MessageBox ("Unable to launch "+ PROGRAM +".",SEVERE); endif; MessageBox ("Setup will now exit.", INFORMATION);
926 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LaunchAppAndWaitInitStartupInfo

endif; end;

LaunchAppAndWaitInitStartupInfo
Project: This information applies to InstallScript projects.

The LaunchAppAndWaitInitStartupInfo function initializes the LAAW_STARTUPINFO and LAAW_PARAMETERS system variables to the appropriate default values. This function is called automatically during installation initialization.

Syntax
LaunchAppAndWaitInitStartupInfo ( );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

927

Appendix C: Built-In Functions (H-P) LaunchAppAndWaitInitStartupInfo

System Variables
Table C-14: LaunchAppAndWaitInitStartupInfo System Variables System Variable LAAW_STARTUPINFO.cb LAAW_STARTUPINFO.lpReserved LAAW_STARTUPINFO.lpDesktop LAAW_STARTUPINFO.lpTitle LAAW_STARTUPINFO.wShowWindow LAAW_STARTUPINFO.lpReserved2 LAAW_STARTUPINFO.cbReserved2 LAAW_STARTUPINFO.dwFlags LAAW_PARAMETERS.szStatusText LAAW_PARAMETERS.szCommandLineResult LAAW_PARAMETERS.lpProcessAttributes LAAW_PARAMETERS.lpThreadAttributes LAAW_PARAMETERS.bInheritHandles LAAW_PARAMETERS.dwCreationFlags LAAW_PARAMETERS.lpEnvironment LAAW_PARAMETERS.lpCurrentDirectory LAAW_PARAMETERS.nCallbackInterval LAAW_PARAMETERS.nLaunchResult Default Value SizeOf(LAAW_STARTUPINFO) NULL NULL NULL SW_SHOWDEFAULT NULL 0 STARTF_USESHOWWINDOW "" "" NULL NULL FALSE NORMAL_PRIORITY_CLASS NULL NULL 1000 0

Parameters
None.

928

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LaunchApplication

Return Values
Table C-15: LaunchAppAndWaitInitStartupInfo Return Values Return Value ISERR_SUCCESS Description This function always returns ISERR_SUCCESS.

LaunchApplication
The LaunchApplication function launches and optionally waits for the specified application.
LaunchApplication uses either the Windows API function CreateProcess or the Windows API function ShellExecuteEx (if nOptions includes LAAW_OPTION_USE_SHELLEXECUTE) to launch the specified application. After the application is launched, if the LAAW_OPTION_WAIT or LAAW_OPTION_WAIT_INCL_CHILD options are specified, the installation calls WaitForApplication to wait for the application to terminate; once the process has completed or the specified timeout value has elapsed, the installation continues.

Syntax
LaunchApplication( byval string szProgram, byval string szCmdLine, byval string szDirectory, byval number nShowWindow, byval number nTimeOut, byval number nOptions );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

929

Appendix C: Built-In Functions (H-P) LaunchApplication

Parameters
Table C-16: LaunchApplication Parameters Parameter szProgram Description Specifies the complete path and file name of the application to be launched. If nOptions does not include LAAW_OPTION_USE_SHELLEXECUTE, you can instead specify the file name of the application to be launched in the szCmdLine parameter; if you do so, pass an empty string ("") in the szProgram parameter. The szProgram parameter supports URLs only if the LAAW_OPTION_USE_SHELLEXECUTE option is used. szCmdLine Specifies the command-line parameters to pass to the launched application. To launch the application with no command-line parameters, pass a null string (""). If nOptions does not include LAAW_OPTION_USE_SHELLEXECUTE, you can also specify the file name of the application to be launched in the szCmdLine parameter; if you do so, be sure to do the following:

Separate the path to the application and the command line with a single space. If the fully qualified name of the application includes long folder names and/or a long file name, pass it to LongPathToQuote before adding it to szCmdLine. For example:

szApplicationPath = WINDIR ^ "Notepad.exe"; szApplicationCmdLine = SRCDIR ^ "Readme.txt"; LongPathToQuote( szApplicationPath, TRUE ); szCmdLine = szApplicationPath + " " + szApplicationCmdLine;

szDirectory

Specifies the working directory for the application. Note that if an empty string ("") is specified (and LAAW_OPTION_USE_SHELLEXECUTE is not specified), the function passes NULL to CreateProcess instead of an empty string.

930

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LaunchApplication

Table C-16: LaunchApplication Parameters (cont.) Parameter nShowWindow Description Specifies the initial window state of the application as passed to CreateProcess in the wShowWindow parameter of the STARTUPINFO structure, or passed to ShellExecuteEx in the nShow parameter of the SHELLEXECUTEINFO structure (if LAAW_OPTION_USE_SHELLEXECUTE is specified). You can specify any documented value for the aforementioned functions; some values are predefined in ISRTWindows.h:

nTimeOut

SW_FORCEMINIMIZE SW_HIDE SW_MAX SW_MAXIMIZE SW_MINIMIZE SW_NORMAL SW_RESTORE SW_SHOW SW_SHOWDEFAULT SW_SHOWMAXIMIZED SW_SHOWMINIMIZED SW_SHOWMINNOACTIVE SW_SHOWNA SW_SHOWNOACTIVATE SW_SHOWNORMAL

Specifies the nTimeOut value (in milliseconds) passed to the WaitForApplication function. Note that if you do not specify LAAW_OPTION_WAIT, the specified value is ignored.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

931

Appendix C: Built-In Functions (H-P) LaunchApplication

Table C-16: LaunchApplication Parameters (cont.) Parameter nOptions Description Specifies various options, including whether the installation should wait for the launched application to terminate before continuing. Pass one of the following predefined constants in this parameter. You can combine these constants by using the bitwise OR operator ( | ), with the following exceptions: you cannot combine LAAW_OPTION_NOWAIT with LAAW_OPTION_WAIT, and you cannot combine LAAW_OPTION_HIDDEN, LAAW_OPTION_MINIMIZED, and LAAW_OPTION_MAXIMIZED.

LAAW_OPTION_USE_SHELLEXECUTEIndicates that the function should call the Windows API function ShellExecuteEx instead of calling CreateProcess to launch the application. LAAW_OPTION_NOWAITPassed through the function to WaitForApplication. Note that using this parameter is equivalent to calling the function LaunchApp. LAAW_OPTION_WAITPassed through the function to WaitForApplication. LAAW_OPTION_USE_CALLBACKPassed through the function to WaitForApplication. LAAW_OPTION_SET_BATCH_INSTALLSpecifies that the function internally sets BATCH_INSTALL to a non-zero value if it detects that the launched application causes a change that requires a reboot, such as updating the RunOnce key. The function attempts to determine this by checking the state of the system before launching the specified application and then comparing the current system state after launching the application (and waiting for the application to complete if LAAW_OPTION_WAIT is specified.) This flag can be used when launching third-party installations that do not return status information indicating that a reboot is needed. LAAW_OPTION_SHOW_HOURGLASSSpecifies that the cursor changes to an hourglass while the launched application is running. LAAW_OPTION_WAIT_INCL_CHILDPassed through the function to WaitForApplication.

Note: When LAAW_OPTION_WAIT_INCL_CHILD is used, the function detects and waits for only direct child processes of the launched processnot for any additional child processes that are launched by child processes of the initially launched process. For details about using LAAW_OPTION_USE_SHELLEXECUTE with LAAW_OPTION_WAIT_INCL_CHILD, see the Additional Information.

932

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LaunchApplication

Table C-16: LaunchApplication Parameters (cont.) Parameter nOptions (cont.) Description This parameter also supports the following options, but they are no longer recommended:

LAAW_OPTION_HIDDENSpecifies that the launched application's main window is initially hidden. LAAW_OPTION_MINIMIZEDSpecifies that the launched application's main window is initially minimized. LAAW_OPTION_MAXIMIZEDSpecifies that the launched application's main window is initially maximized. LAAW_OPTION_NO_CHANGEDIRECTORYThis is obsolete. This parameter is ignored. LAAW_OPTION_CHANGEDIRECTORYSpecifies that LaunchApplication should temporarily update the current directory of the installation to that of the application about to be launched. By default, LaunchApplication does not modify the current directory of the installation. Note that LaunchApplication resets the current directory of the installation back to the original value before LaunchApplication returns.

Note: Calling LaunchAppAndWait instead of LaunchApplication automatically includes this option.

LAAW_OPTION_FIXUP_PROGRAM Specifies that LaunchApplication should call LongPathFromShortPath on szProgram in order to ensure that the call to CreateProcess or ShellExecuteEx works correctly. In most cases, this should not be needed.

Note: Calling LaunchAppAndWait instead of LaunchApplication automatically includes this option.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

933

Appendix C: Built-In Functions (H-P) LaunchApplication

Return Values
Table C-17: LaunchApplication Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the application was launched successfully. Indicates that the application was not launched successfully.

Note: If the application cannot be launched, the LAAW_PARAMETERS system variables nLaunchResult member contains the result of calling the Windows API function GetLastError after the CreateProcess or ShellExecuteEx call. If the function is successful and the LAAW_OPTION_WAIT option was specified, the LAAW_PARAMETERS system variables nLaunchResult member contains the return code of the launched application.

Additional Information
If you are not using LAAW_OPTION_USE_SHELLEXECUTE, update the LAAW_STARTUPINFO system variable before calling LaunchApplication to customize the behavior of the application. If you are using LAAW_OPTION_USE_SHELLEXECUTE, customize the LAAW_SHELLEXECUTEINFO structure to customize the behavior of the application. If you are using LAAW_OPTION_USE_SHELLEXECUTE on systems running Windows Vista or later and you want to launch the application using the full administrator account (similar to rightclicking the executable file to be run and clicking Run as Administrator), set LAAW_SHELLEXECUTEVERB to runas before using LaunchApplication in your script:
LAAW_SHELLEXECUTEVERB = "runas";

This ensures that the application is always run with full administrator privileges regardless of whether the application to be launched has an application manifest with relevant settings. Note that this may trigger a User Account Control (UAC) prompt for consent or credentials. On systems running operating systems earlier than Windows Vista, if runas is used, a Run As dialog box is displayed. The behavior is similar to right-clicking the executable file to be run and clicking Run As. This dialog box enables the end user to select the user account that should be used to run the application.

To obtain identification information about the launched process, use the LAAW_PROCESS_INFORMATION system variable or the LAAW_SHELLEXECUTEINFO system variable (if you are using LAAW_OPTION_USE_SHELLEXECUTE). Note that if you are using LAAW_OPTION_USE_SHELLEXECUTE, the LAAW_PROCESS_INFORMATION is not used, except for the hProcess member. The hProcess member is updated to the process handle of the launched process (from the LAAW_SHELLEXECUTEINFO.hProcess member).
ShellExecuteEx does not return the process ID of the launched process. Thus, if LAAW_OPTION_USE_SHELLEXECUTE is used, the LAAW_OPTION_WAIT_INCL_CHILD

934

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LaunchApplicationInit

option works only if the Windows API GetProcessId is available so that the function can determine the process ID. According to the Windows API documentation, GetProcessId is available on Windows XP SP1 and later and Windows Server 2003 and later. If this API is not available, LAAW_OPTION_WAIT_INCL_CHILD behaves as LAAW_OPTION_WAIT.

When the installation is run from any removable media, such as a CD or a DVD, the Setup.exe file on Disk1 may not be available during the entire installation. (If Setup.exe becomes unavailable while it is running, the operating system sometimes displays a prompt to request that the end user insert the correct disk, and this may cause the installation to fail.) Therefore, to avoid this problem, the Setup.exe file is copied to a Temp folder, and the installation is relaunched from there. The original Setup.exe then terminates. However, when this happens, LaunchApplication behaves as if the installation has completed, and it does not wait. To avoid this issue, you may want to use the /clone_wait parameter when you are launching the child installation; when this occurs, the launched installation keeps the original launched process running, and the parent installation then waits. Note, however, that this may cause problems if the original CD containing Setup.exe is not available throughout the entire installation. This includes multiple-CD installations, where the first CD is not available during some parts of the installation. The only other way to avoid this problem is to add code that determines the ID of the child processes of the launched process and wait for the child process to complete.

LaunchApplicationInit
Project: This information applies to InstallScript projects.

The LaunchApplicationInit function initializes the LAAW_STARTUPINFO and LAAW_PARAMETERS system variables to the appropriate default values. This function is called automatically during installation initialization. This function supersedes the LaunchAppAndWaitInitStartupInfo function.

Syntax
LaunchApplicationInit( );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

935

Appendix C: Built-In Functions (H-P) LaunchApplicationInit

System Variables
Table C-18: LaunchApplicationInit System Variables System Variable LAAW_PARAMETERS.bCallbackEndedWait LAAW_PARAMETERS.bInheritHandles LAAW_PARAMETERS.dwCreationFlags LAAW_PARAMETERS.lpCurrentDirectory LAAW_PARAMETERS.lpEnvironment LAAW_PARAMETERS.lpProcessAttributes LAAW_PARAMETERS.lpThreadAttributes LAAW_PARAMETERS.nCallbackInterval LAAW_PARAMETERS.nLaunchResult LAAW_PARAMETERS.nTimeOut LAAW_PARAMETERS.nTimeOutCheckInterval LAAW_PARAMETERS.nWaitForInputIdleMax LAAW_PARAMETERS.nWaitResult LAAW_PARAMETERS.szCommandLineResult LAAW_PARAMETERS.szStatusText LAAW_SHELLEXECUTEINFO.cbSize LAAW_SHELLEXECUTEINFO.dwHotKey LAAW_SHELLEXECUTEINFO.fMask Default Value FALSE FALSE NORMAL_PRIORITY_CLASS NULL NULL NULL NULL 1000 0 INFINITE 1000 2000 WAIT_OBJECT_0 "" "" SizeOf(LAAW_SHELLEXECUTEINFO) 0 SEE_MASK_NOCLOSEPROCESS | SEE_MASK_FLAG_NO_UI NULL NULL NULL NULL GetWindowHandle( HWND_INSTALL ) NULL NULL

LAAW_SHELLEXECUTEINFO.hIconMonitor LAAW_SHELLEXECUTEINFO.hInstApp LAAW_SHELLEXECUTEINFO.hkeyClass LAAW_SHELLEXECUTEINFO.hProcess LAAW_SHELLEXECUTEINFO.hwnd LAAW_SHELLEXECUTEINFO.lpClass LAAW_SHELLEXECUTEINFO.lpDirectory

936

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListAddItem

Table C-18: LaunchApplicationInit System Variables (cont.) System Variable LAAW_SHELLEXECUTEINFO.lpFile LAAW_SHELLEXECUTEINFO.lpIDList LAAW_SHELLEXECUTEINFO.lpParameters LAAW_SHELLEXECUTEINFO.lpVerb LAAW_SHELLEXECUTEINFO.nShow LAAW_SHELLEXECUTEVERB LAAW_STARTUPINFO.cb LAAW_STARTUPINFO.cbReserved2 LAAW_STARTUPINFO.dwFlags LAAW_STARTUPINFO.lpDesktop LAAW_STARTUPINFO.lpReserved LAAW_STARTUPINFO.lpReserved2 LAAW_STARTUPINFO.lpTitle LAAW_STARTUPINFO.wShowWindow Default Value NULL NULL NULL &LAAW_SHELLEXECUTEVERB SW_SHOWDEFAULT "open" SizeOf(LAAW_STARTUPINFO) 0 STARTF_USESHOWWINDOW NULL NULL NULL NULL SW_SHOWDEFAULT

Parameters
None.

Return Values
Table C-19: LaunchApplicationInit Return Values Return Value ISERR_SUCCESS Description This function always returns ISERR_SUCCESS.

ListAddItem
The ListAddItem function adds a numeric element to a number list before or after the current element.

Note: ListAddItem works only with numbered lists.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

937

Appendix C: Built-In Functions (H-P) ListAddItem

Task

To traverse a list: 1. 2.

Call ListGetFirstItem to get the first element in the list. Call ListGetNextItem repeatedly until you reach the end of the list.

To make a specific element in the list the current element, call ListSetIndex.

Syntax
ListAddItem ( listID, nItem, nPlacementFlag );

Parameters
Table C-20: ListAddItem Parameters Parameter listID Description Specifies the name of a number list. The list identified by listID must already have been initialized by a call to ListCreate. Specifies the numeric element to add to the list. Specifies where to put nItem relative to the current element. The new element will go either before or after the current element. Pass one of the following predefined constants in this parameter:

nItem nPlacementFlag

AFTERAdds the new element after the current element in the list. BEFOREAdds the new element before the current element in the list.

Return Values
Table C-21: ListAddItem Return Values Return Value > = ISERR_SUCCESS (0) < ISERR_SUCCESS (0) ISERR_LIST_NOSUCHLIST (-501) Description The function was successful. The function was not successful. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

ListAddItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

938

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListAddItem

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListAddItem function. * * First, an empty list is created by a call to ListCreate. * Then ListAddItem is called three times to add the numbers * 1, 3, and 2 to the list. Although the numbers are not added * in ascending order, they are arranged in that order in the * list by means of the placement flag that is passed in the * third parameter of each call to ListAddItem. After the list * has been built, it is displayed. Finally the current element * is displayed. * \*--------------------------------------------------------------*/ #define TITLE "ListAddItem Example" #define MSSG "The following is a list of the items added:\n\n" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListAddItem(HWND); function ExFn_ListAddItem(hMSI) NUMBER nvItem, nvResult; LIST listID; STRING szMsg, svItem; begin // Create an empty number list. listID = ListCreate (NUMBERLIST); //If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add the number 1 to the list. if (ListAddItem (listID, 1, AFTER) < 0) then MessageBox ("First call to ListAddItem failed.", INFORMATION); abort; endif; // The integer 1, in position 1, is the current element. // Add the number 3 after the current element. if (ListAddItem (listID, 3, AFTER) < 0) then MessageBox ("Second call to ListAddItem failed.", INFORMATION); abort; endif; // The integer 3, in position 2, is the current element. // Add the number 2 to the list before the current element. if (ListAddItem (listID, 2, BEFORE) < 0) then MessageBox ("Third call to ListAddItem failed.", INFORMATION); abort; endif; // Retrieve and display the current element. ListCurrentItem (listID, nvItem);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 939

Appendix C: Built-In Functions (H-P) ListAddList

SprintfBox (INFORMATION, TITLE, "Current Item: %d", nvItem); // Start building the message to report the numbers. szMsg = MSSG; // Get the numbers and add them to the message. nvResult = ListGetFirstItem (listID, nvItem); while (nvResult != END_OF_LIST) NumToStr (svItem, nvItem); szMsg = szMsg + svItem + " "; nvResult = ListGetNextItem (listID, nvItem); endwhile; // Display the numbers. MessageBox (szMsg, INFORMATION); // Remove the list from memory. ListDestroy (listID); end;

ListAddList
The ListAddList function adds elements to the destination list.

Syntax
ListAddList ( listDest, listAdd, nPlacementFlag);

940

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListAddString

Parameters
Table C-22: ListAddList Parameters Parameter listDest listAdd Description The specified destination list to have elements added. The list containing the elements to be added. All elements including current elements are added to listDest. Value can be BEFORE or AFTER indicating whether to add the list elements before or after the current element on the destination list.

nPlacementFlag

Return Values
Table C-23: ListAddList Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

ListAddString
The ListAddString function adds a string to a string list before or after the current element.

Note: ListAddString works only with string lists.

Task

To traverse a list: 1. 2.

Call ListGetFirstItem to get the first element in the list. Call ListGetNextItem repeatedly until you reach the end of the list.

To make a specific element in the list the current element, call ListSetIndex.

Syntax
ListAddString ( listID, szString, nPlacementFlag );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

941

Appendix C: Built-In Functions (H-P) ListAddString

Parameters
Table C-24: ListAddString Parameters Parameter listID Description Specifies the name of a string list. The list identified by listID must already have been initialized by a call to ListCreate. Specifies the string to add to the list. Specifies where to put szString relative to the current element. The new string will go either before or after the current element. Pass one of the following predefined constants in this parameter:

szString nPlacementFlag

AFTERAdds the new string after the current element in the list. BEFOREAdds the new string before the current element in the list.

Return Values
Table C-25: ListAddString Return Values Return Value > = ISERR_SUCCESS (0) < ISERR_SUCCESS (0) ISERR_LIST_NOSUCHLIST (-501) Description The function was successful. The function was not successful. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

ListAddString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListAddString function. * * ListAddString is called to add a string to the string list. * Then it is called again to add another string after the * first. This string is also set as the current element. * ListAddString is called for the third time to add a string * before the current element. * \*--------------------------------------------------------------*/ #define #define TITLE_TEXT "ListAddString Example" MSG_TEXT "Hardware devices:"

942

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListAppendFromArray

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListAddString(HWND); function ExFn_ListAddString(hMSI) STRING szString, svString; LIST listID; begin // Create an empty string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add a string to the list. This string becomes the current element. szString = "Keyboard"; if (ListAddString (listID, szString, AFTER) < 0) then MessageBox ("ListAddString failed.", INFORMATION); endif; // Add a second string; insert it after the current element. // This string then becomes the current element. szString = "Mouse"; if (ListAddString (listID, szString, AFTER) < 0) then MessageBox ("ListAddString failed.", INFORMATION); endif; // Add a third string; insert it before the current element. szString = "Monitor"; if (ListAddString (listID, szString, BEFORE) < 0) then MessageBox ("ListAddString failed.", INFORMATION); endif; // Show the list of strings. SdShowInfoList (TITLE_TEXT, MSG_TEXT, listID); // Retrieve and display the current element. ListCurrentString (listID, svString); MessageBox (svString, INFORMATION); // Remove the list from memory. ListDestroy (listID); end;

ListAppendFromArray
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

943

Appendix C: Built-In Functions (H-P) ListAppendToArray

The ListAppendFromArray function appends the elements in the array that is specified by varSource to the list that is specified by listResult.

Syntax
ListAppendFromArray ( listResult, varSource, bString );

Parameters
Table C-26: ListAppendFromArray Parameters Parameter listResult Description Specifies the name of a list. The list identified by listResult must already have been initialized by a call to ListCreate. Specifies the array to append to the list. Set this parameter to TRUE if varSource is a string array and listResult is a string list; set this parameter to FALSE if varSource is a number array and listResult is a number list.

varSource bString

Return Values
Table C-27: ListAppendFromArray Return Values Return Value >= 0 < ISERR_SUCCESS Description The new number of elements in the list. Indicates that the function was unable to append the array to the list.

Comments
The array and list types must match (that is, both be string or both be numeric) or the function will fail. If necessary, convert the data appropriately by calling ListConvertNumToStr or ListConvertStrToNum before calling ListAppendToArray.

ListAppendToArray
Project: This information applies to InstallScript projects.

The ListAppendToArray function appends the elements in the list that is specified by listSource to the array that is specified by varResult, resizing the array appropriately to store the new elements.

Syntax
ListAppendToArray ( varResult, listSource, bString );

944

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListConvertNumToStr

Parameters
Table C-28: ListAppendToArray Parameters Parameter varResult listSource Description Specifies an array. Specifies the list to append to the array. The list identified by listSource must already have been initialized by a call to ListCreate. Set this parameter to TRUE if varResult is a string array and listSource is a string list; set this parameter to FALSE if varResult is a number array and listSource is a number list.

bString

Return Values
Table C-29: ListAppendToArray Return Values Return Value >= 0 < ISERR_SUCCESS Description The new number of elements in the array. Indicates that the function was unable to append the list to the array.

Comments
The array and list types must match (that is, both be string or both be numeric) or the function will fail. If necessary, convert the data appropriately by calling ListConvertNumToStr or ListConvertStrToNum before calling ListAppendToArray. The current size of the array determines where the end of the array is and thus where the new elements are placed. For example, if the size of the array is 10 but only one element contains a string, the new data is still added as the 11th and later elements. If you use an autosized array the new elements are added to the end of the array.

ListConvertNumToStr
Project: This information applies to InstallScript projects.

The ListConvertNumToStr function converts each numeric element in listNumber to its string equivalent and appends it to listString.

Syntax
ListConvertNumToStr (listString, listNumber);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

945

Appendix C: Built-In Functions (H-P) ListConvertStrToNum

Parameters
Table C-30: ListConvertNumToStr Parameters Parameter listString Description Specifies the string list to which to append the converted numbers. The list identified by listString must already have been initialized by a call to ListCreate. Specifies a number list. The list identified by listNumber must already have been initialized by a call to ListCreate.

listNumber

Return Values
Table C-31: ListConvertNumToStr Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully converted the number list to a string list. Indicates that the function was unable to convert the number list to a string list.

Comments
The function uses NumToStr to convert the numeric elements to strings; if the conversion fails for an element in listNumber, a null string ("") is appended to listString for that element.

ListConvertStrToNum
Project: This information applies to InstallScript projects.

The ListConvertStrToNum function converts each string element in listString to its numeric equivalent and appends it to listNumber.

Syntax
ListConvertStrToNum (listNumber, listString );

946

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListCount

Parameters
Table C-32: ListConvertStrToNum Parameters Parameter listNumber Description Specifies the number list to which to append the converted strings. The list identified by listNumber must already have been initialized by a call to ListCreate. Specifies a string list. The list identified by listString must already have been initialized by a call to ListCreate.

listString

Return Values
Table C-33: ListConvertStrToNum Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully converted the string list to a number list. Indicates that the function was unable to convert the string list to a number list.

Comments
The function uses StrToNum to convert the strings to numbers; if the conversion fails for an element in listString, 0 is appended to listNumber for that element.

ListCount
The ListCount function returns the number of elements in a list.

Note: This function works with both strings and number lists.

Syntax
ListCount ( listID );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

947

Appendix C: Built-In Functions (H-P) ListCount

Parameters
Table C-34: ListCount Parameters Parameter listID Description Specifies the name of a string or number list.

Return Values
Table C-35: ListCount Return Values Return Value >= 0 ISERR_LIST_NOSUCHLIST (-501) Description The number of items in the list. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function. ListCount was unable to determine the number of elements in the list.

<0

ListCount Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListCount function. * * The following adds the names of the program folders to a * string list and then displays the number of strings in * the list. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListCount(HWND); function ExFn_ListCount(hMSI) STRING svString; LIST listID; NUMBER nCount; begin // Create a string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate.

948

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListCreate

if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Get the names of the program folders into a list. GetGroupNameList (listID); // Count the number of program folders in the list. nCount = ListCount (listID); // Report error or display the folder count. if (nCount < 0) then MessageBox ("ListCount failed.", SEVERE); else SprintfBox (INFORMATION, "ListCount", "There are %i program folders.", nCount); endif; // Remove the list from memory. ListDestroy (listID); end;

ListCreate
The ListCreate function creates an empty string or number list. You can create any number of lists in a script. A list may contain any number of elements. The only constraint is the amount of available free memory. When calling any of the list functions, you must pass a valid ID of the list returned by this function. Verify this function was successful in creating the list. Otherwise, all the list functions will fail on the invalid list. When you no longer need the list, you can destroy the list with the ListDestroy function. Each list has a pointer that identifies an element as the current element of the list. The various list functions reposition the current element of the list.

Note: A list cannot contain both types of elementsnumbers and strings. InstallScript provides separate functions to work with string lists and with number lists. You cannot use the ID of a number list with the string list functions and vice versa. Use list functions that end in Item for number lists and use list functions that end in String for string lists.

Syntax
ListCreate ( nListType );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

949

Appendix C: Built-In Functions (H-P) ListCreate

Parameters
Table C-36: ListCreate Parameters Parameter nListType Description Specifies the type of list to create. Pass one of the following predefined constants in this parameter:

NUMBERLISTSpecifies a number list. STRINGLISTSpecifies a string list.

Return Values
Table C-37: ListCreate Return Values Return Value ListID Description The ID of the newly created, empty list. You must use this ID whenever you want to use this list in other InstallScript list functions. You must check this variable and be sure the function did not return LIST_NULL. Indicates that InstallShield is unable to create a list. This is a seldom seen condition that is the result of a serious memory problem. You might experience difficulties in continuing the setup with such memory problems.

LIST_NULL (-1)

Additional Information
Before you can pass a valid list ID to any function that requires a list, you must build the list using ListCreate.

ListCreate Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListCreate and ListDestroy functions. * * ListCreate is called to create a numbered list. ListDestroy * is called to destroy it. * \*---------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListCreate(HWND);

950

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListCurrentItem

function ExFn_ListCreate(hMSI) LIST listID; NUMBER nvItem; begin // Create an empty number list. listID = ListCreate (NUMBERLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add the number 1078 to the list. ListAddItem (listID, 1078, AFTER); // Add the number 304 to the list ListAddItem (listID, 304, AFTER); // Retrieve the current item in the list (304). ListCurrentItem (listID, nvItem); // Display the current item. SprintfBox (INFORMATION, "ListCreate", "Current item in list: %d", nvItem); // Retrieve the first item in the list (1078). ListGetFirstItem (listID, nvItem); // Display the first item. SprintfBox (INFORMATION, "ListCreate", "First item in list: %d", nvItem); // Remove the list from memory. ListDestroy (listID); end;

ListCurrentItem
The ListCurrentItem function retrieves the current element from the number list specified in listID. You can also use the ListGetFirstItem and ListGetNextItem functions to traverse the list and make any element the current element.

Note: ListCurrentItem works only with numbered lists.

Syntax
ListCurrentItem ( listID, nvItem );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

951

Appendix C: Built-In Functions (H-P) ListCurrentItem

Parameters
Table C-38: ListCurrentItem Parameters Parameter listID nvItem Description Specifies a number list. Returns the value of the current element in the list.

Return Values
Table C-39: ListCurrentItem Return Values Return Value 0 <0 END_OF_LIST (1) ISERR_LIST_NOSUCHLIST Description Indicates that the function successfully retrieved the current element in a number list. Indicates that the function was unable to retrieve the current element in a number list. Indicates that the list is empty and therefore does not have a current element. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

ListCurrentItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListCurrentItem function. * * This script adds three numbers to a list and then retrieves * and displays the value of the current list item. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListCurrentItem Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListCurrentItem(HWND); function ExFn_ListCurrentItem(hMSI) STRING szMsg; LIST listID; NUMBER nItem;
952 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListCurrentString

begin // Create the number list. listID = ListCreate (NUMBERLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add the numbers 100, 200, and 300 to the list. for nItem = 100 to 300 step 100 ListAddItem (listID, nItem, AFTER); endfor; // Get the current element from the number list. if (ListCurrentItem (listID, nItem) < 0) then MessageBox ("ListCurrentItem failed.", SEVERE); else // Report the value of the current item. szMsg = "Value of current element in list: %d"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, nItem); endif; end;

ListCurrentString
The ListCurrentString function retrieves the current element from the string list specified in listID. You can also use the ListGetFirstString and ListGetNextString functions to traverse the list and make any element the current element.

Note: ListCurrentString works only with string lists.

Syntax
ListCurrentString ( listID, svString );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

953

Appendix C: Built-In Functions (H-P) ListCurrentString

Parameters
Table C-40: ListCurrentString Parameters Parameter listID svString Description Specifies a string list. Returns the value of the current element in the list.

Return Values
Table C-41: ListCurrentString Return Values Return Value 0 <0 END_OF_LIST (1) ISERR_LIST_NOSUCHLIST (501) Description Indicates that the function successfully retrieved the current element in a string list. Indicates that the function was unable to retrieve the current element in a string list. Indicates that the list is empty and therefore does not have a current element. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

ListCurrentString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListCurrentString function. * * ListAddString retrieves the current string element from a * string list. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListCurrentString Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListCurrentString(HWND); function ExFn_ListCurrentString(hMSI) STRING szString, svString, szMsg; LIST listID; begin

954

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListDeleteAll

// Create the string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add three strings to the list. ListAddString (listID, "First string", AFTER); ListAddString (listID, "Second string", AFTER); ListAddString (listID, "Third string", AFTER); // Get the current element in the string list. if (ListCurrentString (listID, svString) < 0) then MessageBox ("ListCurrentString failed.", SEVERE); else // Report the value of the current item. szMsg = "Current element in list: '%s'"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svString); endif; end;

ListDeleteAll
The ListDeleteAll function deletes all elements in the specified list. This function can be used for both string and number lists.

Syntax
ListDeleteAll ( list);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

955

Appendix C: Built-In Functions (H-P) ListDeleteItem

Parameters
Table C-42: ListDeleteAll Parameters Parameter list Description The list specified to have all elements deleted.

Return Values
Table C-43: ListDeleteAll Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

ListDeleteItem
The ListDeleteItem function removes the current element from the number list you specify in listID. You can also use the ListGetFirstItem and ListGetNextItem functions to traverse the list and make any element the current element.

Note: ListDeleteItem works only with numbered lists.

Syntax
ListDeleteItem ( listID );

956

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListDeleteItem

Parameters
Table C-44: ListDeleteItem Parameters Parameter listID Description Specifies the number list from which to delete the current element.

Return Values
Table C-45: ListDeleteItem Return Values Return Value 0 Description Indicates that the function successfully deleted the current element from a number list. Indicates that the list is empty and therefore does not have a current element. Indicates that the list is empty and therefore does not have a current element. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

<0 END_OF_LIST (1) ISERR_LIST_NOSUCHLIST

ListDeleteItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListDeleteItem function. * * This script first creates a list of numbers and prompts the * user for a number to delete. Then ListFindItem is called to * make the selected number the current item. Next, * ListDeleteItem is called to delete the selected number from * the list. Finally, the numbers remaining in the list are * displayed. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListDeleteItem Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListDeleteItem(HWND); function ExFn_ListDeleteItem(hMSI) STRING svItem, szMsg;
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 957

Appendix C: Built-In Functions (H-P) ListDeleteItem

LIST NUMBER begin

listID; nvItem, nvResult;

// Create the number list. listID = ListCreate (NUMBERLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add the numbers 1, 2, 3, and 4 to the list. for nvItem = 1 to 4 ListAddItem (listID, nvItem, AFTER); endfor; repeat // Disable the Back button. Disable (BACKBUTTON); // Prompt user to select a number to delete. if AskText ("The numbers 1, 2, 3, and 4 have been added to a list.\n"+ "Select one of those numbers to delete.", "", svItem)then endif; // Convert the value from string data to a number data. nvResult = StrToNum (nvItem, svItem); (nvItem < 1) || (nvItem > 4) then MessageBox ("You must enter a number between 1 and 4.", WARNING); endif; until (nvItem > 0) && (nvItem <5); // Make the first list element the current element // so ListFindItem will search from the top of the list. ListSetIndex (listID, 0); // Search for the selected number. nvResult = ListFindItem(listID, nvItem); // Delete the selected number from the list. if (ListDeleteItem (listID) < 0) then MessageBox ("Unable to delete selected number.", SEVERE); else // Start building the message to report the remaining numbers. szMsg = "The list now contains the following numbers:\n\n"; // Get the remaining numbers and add them to the message. nvResult = ListGetFirstItem (listID, nvItem); while (nvResult != END_OF_LIST) NumToStr (svItem, nvItem); szMsg = szMsg + svItem + " "; nvResult = ListGetNextItem (listID, nvItem); endwhile; // Display the remaining numbers. MessageBox (szMsg, INFORMATION); endif; // Remove the list from memory.
958 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

if

Appendix C: Built-In Functions (H-P) ListDeleteString

ListDestroy (listID); end;

ListDeleteString
The ListDeleteString function removes the current element from the string list you specify in listID. You can also use the ListGetFirstString and ListGetNextString functions to traverse the list and make any element the current element.

Note: ListCurrentString works only with string lists.

Syntax
ListDeleteString ( listID );

Parameters
Table C-46: ListDeleteString Parameters Parameter listID Description Specifies the string list from which to delete the current element.

Return Values
Table C-47: ListDeleteString Return Values Return Value 0 Description Indicates that the function successfully deleted the current element from a string list. Indicates that the function was unable to delete the current element from a string list. Indicates that the list is empty and therefore does not have a current element. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

<0

END_OF_LIST (1)

ISERR_LIST_NOSUCHLIST (-501)

ListDeleteString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 959

Appendix C: Built-In Functions (H-P) ListDeleteString

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListDeleteString function. * * This script first creates a list of strings and then displays * the current string in a dialog. Next, ListDeleteString * is called twice, deleting the last two strings in the list. * The current string is then displayed again. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListDeleteString & ListCurrentString" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListDeleteString(HWND); function ExFn_ListDeleteString(hMSI) STRING szString, svString, szMsg; LIST listID; begin // Create the string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add three strings to the list. ListAddString (listID, "First string", AFTER); ListAddString (listID, "Second string", AFTER); ListAddString (listID, "Third string", AFTER); // Display the current string in the list. if (ListCurrentString (listID, svString) < 0) then MessageBox ("First call to ListCurrentString failed.", SEVERE); else szMsg = "Current string in list: %s"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svString); endif; // Remove the current string ("Value three"). if (ListDeleteString (listID) < 0) then MessageBox ("First call to ListDeleteString failed.", SEVERE); endif; // Remove the current string ("Value two"). if (ListDeleteString (listID) < 0) then MessageBox ("Second call to ListDeleteString failed.", SEVERE); endif; // Display the current string in the list. if (ListCurrentString(listID, svString) < 0) then MessageBox ("Second call to ListCurrentString failed.", SEVERE);
960 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListDestroy

else szMsg = "Current string in list: %s"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svString); endif; // Remove the list from memory. ListDestroy (listID); end;

ListDestroy
The ListDestroy function destroys the contents of a list and the list itself. Use this function to remove the string or number list identified in listID. You should destroy all the lists you create when you no longer need them or at the end of the setup script. When you destroy a list, you free all memory associated with the list.

Note: This function works with both string and number lists. After you destroy a list, do not use that in any list function.

Syntax
ListDestroy ( listID );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

961

Appendix C: Built-In Functions (H-P) ListDestroy

Parameters
Table C-48: ListDestroy Parameters Parameter listID Description Specifies the string or number list to destroy.

Return Values
Table C-49: ListDestroy Return Values Return Value 0 Description Indicates that the function successfully destroyed the list, removing it from memory. Indicates that the function was unable to destroy the list. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

<0 ISERR_LIST_NOSUCHLIST (-501)

ListDestroy Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListCreate and ListDestroy functions. * * ListCreate is called to create a number list. ListDestroy * is called to destroy it. * \*---------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListDestroy(HWND); function ExFn_ListDestroy(hMSI) LIST listID; NUMBER nvItem; begin // Create an empty number list. listID = ListCreate (NUMBERLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then

962

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListFindItem

MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add the number 1078 to the list. ListAddItem (listID, 1078, AFTER); // Add the number 304 to the list ListAddItem (listID, 304, AFTER); // Retrieve the current item in the list (304). ListCurrentItem (listID, nvItem); // Display the current item. SprintfBox (INFORMATION, "ListCreate", "Current item in list: %d", nvItem); // Retrieve the first item in the list (1078). ListGetFirstItem (listID, nvItem); // Display the first item. SprintfBox (INFORMATION, "ListCreate", "First item in list: %d", nvItem); // Remove the list from memory. ListDestroy (listID); end;

ListFindItem
The ListFindItem function searches for a specific element in a number list, starting at the current element and continuing through the list from that point. If you want to start the search from the beginning of the list, use the ListGetFirstItem function. When ListFindItem finds the element, it becomes the current element in the list.

Note: The ListFindItem function works only with number lists.

Syntax
ListFindItem ( listID, nItem );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

963

Appendix C: Built-In Functions (H-P) ListFindItem

Parameters
Table C-50: ListFindItem Parameters Parameter listID nItem Description Specifies the number list to search. Specifies the item to find in the list.

Return Values
Table C-51: ListFindItem Return Values Return Value 0 <0 Description The function successfully found the requested element. An error prevented the function from searching the specified list. This error occur, for example, if the list specified by listID does not exist. The function searched to the end of the list and did not find the requested element. A list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

END_OF_LIST (1)

ISERR_LIST_NOSUCHLIST (-501)

ListFindItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListFindItem function. * * This script creates a number list and adds three numbers * to it. The user is then asked to guess one of the numbers. * ListFindItem is called to search the list for the number the * user entered. A message box is displayed to tell the user * whether the guess was right or wrong. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListFindItem Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListFindItem(HWND);

964

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListFindKeyValueString

function ExFn_ListFindItem(hMSI) STRING svItem; NUMBER nItem, nResult; LIST listID; begin // Create a number list. listID = ListCreate (NUMBERLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add three numbers ListAddItem (listID, ListAddItem (listID, ListAddItem (listID, to 1, 5, 9, the list AFTER); AFTER); AFTER);

// Prompt user for a number. if AskText ("Three numbers between 1 and 10 have been added to a list.\n"+ "Try to guess one of those numbers.", "", svItem) = NEXT then // Convert the value from string data to number data. if StrToNum (nItem, svItem) < 0 then MessageBox ("You did not enter a number: operation canceled.", SEVERE); else // Make the first list element the current element // so ListFindItem searches from the top of the list. ListSetIndex (listID, 0); // Search for the list of numbers. nResult = ListFindItem (listID, nItem); // Display the results of the search. if (nResult < 0) then MessageBox ("ListFindItem failed.", SEVERE); elseif (nResult = END_OF_LIST) then SprintfBox (WARNING, TITLE_TEXT, "Sorry, %d is not in the list.", nItem); elseif (nResult = 0) then SprintfBox (INFORMATION, TITLE_TEXT, "Yes, %d is in the list.", nItem); endif; endif; endif; // Remove list from memory. ListDestroy (listID); end;

ListFindKeyValueString
The ListFindKeyValueString function searches a string or number list for a specified value. It returns a value from an additional list that corresponds with the position of the found string in the first list. This enables you to search lists of key-value pairs for a particular key and get the corresponding value.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

965

Appendix C: Built-In Functions (H-P) ListFindKeyValueString

Syntax
ListFindKeyValueString (byval LIST listKeys, byval LIST listValues, byval string szKey, byref string svValue);

966

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListFindString

Parameters
Table C-52: ListFindKeyValueString Parameters Parameter listKeys Description Indicate the list of keys to be searched. You can specify a string or number list. The list must be initialized by calling ListCreate before calling ListFindKeyValueString. Note that the starting point for the search is always the beginning of the list, regardless of the current position of the list. When the function returns, the current position in the list is the found element. listValues Indicate the list of values that corresponds with the list of keys. You can specify a string or number list. The list must be initialized by calling ListCreate before calling ListFindKeyValueString. Note that listKeys and listValues do not necessarily need to be the same type of list. szKey Specify the string for which you want to search. If listKeys is a number list, szKey is converted to a number by using the StrToNum function, which is then used to search the list. ListFindKeyValueString calls ListFindString (if the list is a string list) or ListFindItem (if the list is a number list) to search the list. Searches for string lists are case-sensitive, since ListFindString performs case-sensitive searches. svValue The value from the second list is returned in this parameter. If listValues is a number list, the number is converted to a string using NumToStr and then passed back as a string.

Return Values
Return Value 0 <0 Description The function successfully found the requested element. An error prevented the function from searching the specified list. This error occur, for example, if the list specified by listID does not exist. The function searched to the end of the list and did not find the requested element. A list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

END_OF_LIST (1)

ISERR_LIST_NOSUCHLIST (-501)

ListFindString
The ListFindString function searches for a specified element in a string list, starting at the current element and continuing from that point. If you want to start the search from the beginning of the string list, call
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 967

Appendix C: Built-In Functions (H-P) ListFindString

the ListGetFirstString function. When ListFindString finds the string, it becomes the current element in the list.

Note: The ListFindString function performs a case-sensitive comparison of the strings, and works only with string lists.

Syntax
ListFindString ( listID, szString );

Parameters
Table C-53: ListFindString Parameters Parameter listID szString Description Specifies the string list to search. Specifies the string to find in the list. InstallShield performs a case-sensitive comparison when searching for this string.

Return Values
Table C-54: ListFindString Return Values Return Value 0 <0 Description Indicates that the function successfully found the requested element. Indicates that an error prevented the function from searching the specified list. This error will occur, for example, if the list specified by listID does not exist. Indicates that InstallShield searched to the end of the list and did not find the requested element. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

END_OF_LIST (1)

ISERR_LIST_NOSUCHLIST (-501)

ListFindString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListFindString function. *

968

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListFindString

* This script prompts the user to input the name of a program * folder on the target system. ListFindString is then called * to search for this folder name in a list that contains all * folder names on the target system. A message is displayed * to report the results of the search. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListFindString Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListFindString(HWND); function ExFn_ListFindString(hMSI) STRING szString; LIST listID, listSubfoldersID; NUMBER nResult; begin // Create string lists listID = ListCreate (STRINGLIST); listSubfoldersID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) || (listSubfoldersID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Fill the list with the names of program folders. GetFolderNameList (FOLDER_PROGRAMS, listID, listSubfoldersID); // Prompt user to enter a folder name. AskText ("Please enter the name of an existing program folder:", "", szString); // Make the first list element the current element // so ListFindItem will search from the top of the list. ListSetIndex (listSubfoldersID, 0); // Search the list for the folder name entered by the user. // Reminder: The string comparison is case sensitive. nResult = ListFindString (listSubfoldersID, szString); // Report the search result. if (nResult < 0) then MessageBox ("ListFindString failed.", SEVERE); elseif (nResult = END_OF_LIST) then SprintfBox (WARNING, TITLE_TEXT, "%s could not be found.", szString); elseif (nResult = 0) then SprintfBox (INFORMATION, TITLE_TEXT, "ListFindString found: %s.", szString); endif; // Remove list from memory. ListDestroy (listID); ListDestroy (listSubfoldersID); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

969

Appendix C: Built-In Functions (H-P) ListGetFirstItem

ListGetFirstItem
The ListGetFirstItem function retrieves the first element from a number list. The first item becomes the current element in the list.

Note: The ListGetFirstItem function works only with number lists.

Syntax
ListGetFirstItem ( listID, nvItem );

Parameters
Table C-55: ListGetFirstItem Parameters Parameter listID Description Specifies the number list from which to retrieve the first element. Returns the first element of the number list.

nvItem

Return Values
Table C-56: ListGetFirstItem Return Values Return Value 0 Description Indicates that the function successfully retrieved the first element in a number list. Indicates that an error prevented the function from retrieving the first element in a number list. Indicates that the list is empty. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

-1

END_OF_LIST (1) ISERR_LIST_NOSUCHLIST (-501)

ListGetFirstItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script

970

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListGetFirstItem

* * Demonstrates the ListGetFirstItem and ListGetNextItem * functions. * * This script starts by creating a number list and adding * three numbers to it. ListGetFirstItem is called then to get * the first number from the list. This call also makes the * first number the current element. A loop process follows to * display the number retrieved from the list and then call * ListGetNextItem to get the next number. The loop executes * until ListGetFirstItem or ListGetNextItem reaches the end * of the list. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListGetFirstItem & ListGetNextItem" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListGetFirstItem(HWND); function ExFn_ListGetFirstItem(hMSI) STRING szMsg; LIST listID; NUMBER nvItem, nResult; begin // Create a number list. listID = ListCreate (NUMBERLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add three numbers ListAddItem (listID, ListAddItem (listID, ListAddItem (listID, to the list. 1024, AFTER); 360, AFTER); 777, AFTER);

// Get the first number from the list. nResult = ListGetFirstItem (listID, nvItem); // Loop while not at end of list. while (nResult != END_OF_LIST) // Display the number retrieved from the list. SprintfBox (INFORMATION, TITLE_TEXT, "%i", nvItem); // Get the next number from the list. nResult = ListGetNextItem (listID, nvItem); endwhile; // Remove the list from memory. ListDestroy (listID); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

971

Appendix C: Built-In Functions (H-P) ListGetFirstString

ListGetFirstString
The ListGetFirstString function retrieves the first element from a string list. The first string becomes the current element in the list. The ListGetFirstString function works only with string lists.

Syntax
ListGetFirstString ( listID, svString );

Parameters
Table C-57: ListGetFirstString Parameters Parameter listID Description Specifies the string list from which to retrieve the first element. Returns the first element of the string list.

svString

Return Values
Table C-58: ListGetFirstString Return Values Return Value 0 Description Indicates that the function successfully retrieved the first element in a string list. Indicates that an error prevented the function from retrieving the first element in a string list. Indicates that the list is empty. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

-1

END_OF_LIST (1) ISERR_LIST_NOSUCHLIST (-501)

ListGetFirstString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListGetFirstString and ListGetNextString * functions.
972 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListGetFirstString

* * This script starts by creating a string list and adding * program folder names to it. ListGetFirstString is called * then to get the first string from the list. This call also * makes the first string the current element. A loop process * follows to display the string retrieved from the list and * then call ListGetNextString to get the next string. The * loop executes until ListGetFirstString or ListGetNextString * reaches the end of the list. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListGetFirstString(HWND); function ExFn_ListGetFirstString(hMSI) STRING svString; LIST listID; NUMBER nResult; begin // Create a string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Get the names of the program folders into a list. if GetGroupNameList(listID) < 0 then ; // Report ListCreate failure. MessageBox ("Unable to retrieve program folder names.", SEVERE); else // Get the first string in the list. nResult = ListGetFirstString (listID, svString); // Loop while list items continue to be retrieved. while (nResult != END_OF_LIST) // Display the current element. MessageBox (svString, INFORMATION); // Get the next string in the list. nResult = ListGetNextString (listID, svString); endwhile; endif; // Remove the list from memory. ListDestroy (listID); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

973

Appendix C: Built-In Functions (H-P) ListGetIndex

ListGetIndex
Project: This information applies to InstallScript projects.

The ListGetIndex function retrieves the index of the specified list's current element. Index numbers starts at zero (0).

Syntax
ListGetIndex ( listID, nIndex );

Parameters
Table C-59: ListGetIndex Parameters Parameter listID Description Specifies the ID of the string or number list whose current element's index is to be retrieved. Returns the index of the list's current element.

nIndex

Return Values
Table C-60: ListGetIndex Return Values Return Value >= ISERR_SUCCESS Description Indicates that the function successfully retrieved the index of the list's current element. Indicates that the function was unable to retrieve the index of the list's current element. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

< ISERR_SUCCESS

ISERR_LIST_NOSUCHLIST

Additional Information
Use ListCurrentItem and ListCurrentString to retrieve the value of the current element. This function works on both string and number lists.

ListGetNextItem
The ListGetNextItem function retrieves the item after the current element in a number list. The retrieved item becomes the current element in the list.

974

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListGetNextItem

Note: The ListGetNextItem function works only with number lists.

Syntax
ListGetNextItem ( listID, nvItem );

Parameters
Table C-61: ListGetNextItem Parameters Parameter listID Description Specifies the number list from which to retrieve the next element. Returns the item that follows the current element in the number list. That item becomes the current element in the list.

nvItem

Return Values
Table C-62: ListGetNextItem Return Values Return Value 0 Description Indicates that the function successfully retrieved the element after the current element in a number list. Indicates that an error prevented the function from retrieving the specified element in a number list. Indicates that the current item is the last element in the list. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

-1

END_OF_LIST (1)

ISERR_LIST_NOSUCHLIST (-501)

ListGetNextItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListGetFirstItem and ListGetNextItem

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

975

Appendix C: Built-In Functions (H-P) ListGetNextItem

* functions. * * This script starts by creating a number list and adding * three numbers to it. ListGetFirstItem is called then to get * the first number from the list. This call also makes the * first number the current element. A loop process follows to * display the number retrieved from the list and then call * ListGetNextItem to get the next number. The loop executes * until ListGetFirstItem or ListGetNextItem reaches the end * of the list. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListGetFirstItem & ListGetNextItem" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListGetNextItem(HWND); function ExFn_ListGetNextItem(hMSI) STRING szMsg; LIST listID; NUMBER nvItem, nResult; begin // Create a number list. listID = ListCreate (NUMBERLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add three numbers ListAddItem (listID, ListAddItem (listID, ListAddItem (listID, to the list. 1024, AFTER); 360, AFTER); 777, AFTER);

// Get the first number from the list. nResult = ListGetFirstItem (listID, nvItem); // Loop while not at end of list. while (nResult != END_OF_LIST) // Display the number retrieved from the list. SprintfBox (INFORMATION, TITLE_TEXT, "%i", nvItem); // Get the next number from the list. nResult = ListGetNextItem (listID, nvItem); endwhile; // Remove the list from memory. ListDestroy (listID); end;

976

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListGetNextString

ListGetNextString
The ListGetNextString function retrieves the element after the current element in a string list. The retrieved element becomes the current element in the list.

Note: The ListGetNextString function works only with string lists.

Syntax
ListGetNextString ( listID, svString );

Parameters
Table C-63: ListGetNextString Parameters Parameter listID Description Specifies the string list from which to retrieve the next element. Returns the string that follows the current element of the string list. This string becomes the current element in the list.

svString

Return Values
Table C-64: ListGetNextString Return Values Return Value 0 Description Indicates that the function successfully retrieved the element after the current element in a string list. Indicates that an error prevented the function from retrieving the specified element in a string list. Indicates that the current item is the last element in the list. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

-1

END_OF_LIST (1)

ISERR_LIST_NOSUCHLIST (-501)

ListGetNextString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 977

Appendix C: Built-In Functions (H-P) ListGetNextString

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListGetFirstString and ListGetNextString * functions. * * This script starts by creating a string list and adding * program folder names to it. ListGetFirstString is called * then to get the first string from the list. This call also * makes the first string the current element. A loop process * follows to display the string retrieved from the list and * then call ListGetNextString to get the next string. The * loop executes until ListGetFirstString or ListGetNextString * reaches the end of the list. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListGetNextString(HWND); function ExFn_ListGetNextString(hMSI) STRING svString; LIST listID; NUMBER nResult; begin // Create a string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Get the names of the program folders into a list. if GetGroupNameList(listID) < 0 then ; // Report ListCreate failure. MessageBox ("Unable to retrieve program folder names.", SEVERE); else // Get the first string in the list. nResult = ListGetFirstString (listID, svString); // Loop while list items continue to be retrieved. while (nResult != END_OF_LIST) // Display the current element. MessageBox (svString, INFORMATION); // Get the next string in the list. nResult = ListGetNextString (listID, svString); endwhile; endif; // Remove the list from memory. ListDestroy (listID); end;

978

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListGetType

ListGetType
The ListGetType function determines whether a list is a STRINGLIST or NUMBERLIST.

Syntax
ListGetType (listID);

Parameters
Table C-65: ListGetType Parameters Parameter listID Description Specifies the name of a string list. The list identified by listID must already have been initialized by a call to ListCreate.

Return Values
Table C-66: ListGetType Return Values Return Value STRINGLIST NUMBERLIST <0 Description Indicates that the list is a string list. Indicates that the list is a number list. Indicates that the function was unable to determine the type of list.

ListGetType Example
Note: The list identified by listID must already have been initialized by a call to ListCreate<LangrefListCreate.htm>.
//Sample code LIST listID; int nType; program listID = ListCreate(STRINGLIST); if (LIST_NULL != listID) then nType = ListGetType(listID); if (STRINGLIST = nType) then MessageBox("It is a STRINGLIST", INFORMATION); else MessageBox("It is a NUMBERLIST", INFORMATION); endif; endif; ListDestroy(listID); listID = ListCreate(NUMBERLIST);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 979

Appendix C: Built-In Functions (H-P) ListReadFromFile

if (LIST_NULL != listID) then nType = ListGetType(listID); if (STRINGLIST = nType) then MessageBox("It is a STRINGLIST", INFORMATION); else MessageBox("It is a NUMBERLIST", INFORMATION); endif; endif; ListDestroy(listID); endprogram

ListReadFromFile
The ListReadFromFile function reads a text file into a list. After you load a text file into a list, you can use it for various functions in the setup, such as displaying a README file at the end of the setup or writing a string list to the disk with ListWriteToFile. This function detects the newline characters at the end of each string and uses the characters as delimiters for each element in the list.

Note: The ListReadFromFile function operates on string lists and text files only.

Syntax
ListReadFromFile ( listID, szFile );

980

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListReadFromFile

Parameters
Table C-67: ListReadFromFile Parameters Parameter listID Description Returns a list of the lines read from the file specified by szFile. The list identified by listID must already have been initialized by a call to ListCreate. Specifies the fully qualified name of the file that will be read into the list.

szFile

Return Values
Table C-68: ListReadFromFile Return Values Return Value 0 Description Indicates that the function successfully read the lines of text in a file into a list. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function. Indicates that the function was unable to read the lines from a text file into a list.

ISERR_LIST_NOSUCHLIST (-501)

<0

ListReadFromFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListReadFromFile and ListWriteToFile * functions. * * ListReadFromFile is called to read and display the * Autoexec.bat file. After the list has been displayed, * a remark is appended to the end of the list and the list * is written to a new file. The original file remains * unchanged. * * Note: In order for this script to run correctly, there must * be a batch file named Autoexec.bat in the root * directory of drive C. * \*--------------------------------------------------------------*/

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

981

Appendix C: Built-In Functions (H-P) ListSetCurrentItem

#define OLD_FILE "C:\\Autoexec.bat" #define NEW_FILE "C:\\Autoexec.lst" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListReadFromFile(HWND); function ExFn_ListReadFromFile(hMSI) LIST listID; begin // Create a string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Read the file into a string list. if (ListReadFromFile (listID, OLD_FILE) < 0) then // Report ListReadFromFile failure. MessageBox ("Unable to read" + OLD_FILE + ".", SEVERE); else // Display the list. SdShowInfoList ("Demo", "The example list file:", listID); // Add a new string to the list. ListAddString (listID, "REM Added by IS setup.", AFTER); // Write the list to a file. if (ListWriteToFile (listID, NEW_FILE) < 0) then MessageBox ("Unable to write list to "+ NEW_FILE + ".", SEVERE); else MessageBox ("Successfully wrote list "+ NEW_FILE + ".", INFORMATION); endif; endif; // Remove the list from memory. ListDestroy (listID); end;

ListSetCurrentItem
The ListSetCurrentItem function assigns the value of nItem to the current element in a number list.

Note: The ListSetCurrentItem function works only with number lists.

Syntax
ListSetCurrentItem ( listID, nItem );

982

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListSetCurrentItem

Parameters
Table C-69: ListSetCurrentItem Parameters Parameter listID Description Specifies the name of a number list whose current element is to be updated. The list identified by listID must already have been initialized by a call to ListCreate. Specifies the numeric value that will replace the current element.

nItem

Return Values
Table C-70: ListSetCurrentItem Return Values Return Value 0 Description Indicates that the function successfully updated the current element in a number list. Indicates that the function was unable to update the current element in a number list. Indicates that the list is empty. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

<0

END_OF_LIST (1) ISERR_LIST_NOSUCHLIST (-501)

ListSetCurrentItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListSetCurrentItem function. * * This script first creates a number list and then adds two * numbers to it. Next, the list is displayed in a dialog. * ListSetCurrentItem is then called to update the value of * the current element in the list. Finally, this new list is * displayed. * \*--------------------------------------------------------------*/ #define MSG_TEXT "Elements in listID:\n\n"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

983

Appendix C: Built-In Functions (H-P) ListSetCurrentItem

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListSetCurrentItem(HWND); function ExFn_ListSetCurrentItem(hMSI) LIST listID; NUMBER nItem, nvResult, nvItem; STRING szMsg, svItem; begin // Create an empty number list. listID = ListCreate (NUMBERLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add two numbers to the list. ListAddItem (listID, 1024, AFTER); ListAddItem (listID, 360, AFTER); // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Start building the message to report the numbers. szMsg = MSG_TEXT; // Get the numbers and add them to the message. nvResult = ListGetFirstItem (listID, nvItem); while (nvResult != END_OF_LIST) NumToStr (svItem, nvItem); szMsg = szMsg + svItem + " "; nvResult = ListGetNextItem (listID, nvItem); endwhile; // Display the numbers. MessageBox (szMsg, INFORMATION); // Replace the value of the second item with a new value. if (ListSetCurrentItem (listID, 777) < 0) then MessageBox ("ListSetCurrentItem failed.", SEVERE); else // Start building the message to report the numbers. szMsg = MSG_TEXT; // Get the numbers and add them to the message. nvResult = ListGetFirstItem (listID, nvItem); while (nvResult != END_OF_LIST) NumToStr (svItem, nvItem); szMsg = szMsg + svItem + " "; nvResult = ListGetNextItem (listID, nvItem); endwhile; // Display the numbers. MessageBox (szMsg, INFORMATION); endif;

984

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListSetCurrentString

// Remove list from memory. ListDestroy (listID); end;

ListSetCurrentString
The ListSetCurrentString function assigns the value of szString to the current element in the string list.

Note: The ListSetCurrentString function works only with string lists.

Syntax
ListSetCurrentString ( listID, szString );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

985

Appendix C: Built-In Functions (H-P) ListSetCurrentString

Parameters
Table C-71: ListSetCurrentString Parameters Parameter listID Description Specifies the name of a string list whose current element is to be updated. The list identified by listID must already have been initialized by a call to ListCreate. Specifies the string value that will replace the current element.

szString

Return Values
Table C-72: ListSetCurrentString Return Values Return Value 0 Description Indicates that the function successfully updated the current element in a number list. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function. Indicates that the function was unable to update the current element in a number list. A common reason for this error is that the index is out of range of available list elements.

ISERR_LIST_NOSUCHLIST (-501)

<0

ListSetCurrentString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListSetCurrentString function. * * In this script, two strings are added to an empty list. * The list is then displayed in a dialog. Next, * ListSetCurrentString is called to replace the current * element. The list is then displayed again in a * dialog. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListSetCurrentString Example"

986

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListSetIndex

#define

MSG_TEXT

"Elements in listID:"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListSetCurrentString(HWND); function ExFn_ListSetCurrentString(hMSI) LIST listID; begin // Create an empty string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Add two strings to the list. ListAddString (listID, "Keyboard", AFTER); ListAddString (listID, "Monitor", AFTER); // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Display the list. SdShowInfoList (TITLE_TEXT, MSG_TEXT, listID); // Replace the value of the second item with a new value. if (ListSetCurrentString(listID, "Mouse") < 0) then MessageBox ("ListSetCurrentString failed.", SEVERE); endif; // Display the new altered list. SdShowInfoList (TITLE_TEXT, MSG_TEXT, listID); // Remove the list from memory. ListDestroy (listID); end;

ListSetIndex
The ListSetIndex function makes a specific element in a string or number list the current element, using an index. You can also use constants to traverse a list one element at a time or to jump to the beginning or end of a list. By using indices to access items in a list, you can treat numeric and string lists as arrays. After you set the indexed element as the current element, you can use either the ListCurrentItem or ListCurrentString function in the script to retrieve the value of the indexed (current) item.

Note: The ListSetIndex function works with both string and number lists.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

987

Appendix C: Built-In Functions (H-P) ListSetIndex

Syntax
ListSetIndex (listID, nIndex);

988

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListSetIndex

Parameters
Table C-73: ListSetIndex Parameters Parameter listID Description Specifies the name of the string or number list whose index is to be set. Specifies the number of the element you want to set as the current element. List element numbering begins at zero (0). For example, if you enter 5 in the parameter nIndex, the item in the sixth physical location in the list becomes the current element. Pass a numeric value or one of the following predefined constants in this parameter:

nIndex

LISTFIRSTMoves to the first element in the list. LISTLASTMoves to the last element in the list. LISTNEXTMoves to the next element in the list. LISTPREVMoves to the previous element in the list.

Return Values
Table C-74: ListSetIndex Return Values Return Value 0 Description Indicates that the function successfully updated the current element in the list. Indicates that the function was unable to update the current element the list. Indicates that the index is out of range of available list elements. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function.

<0

END_OF_LIST (1)

ISERR_LIST_NOSUCHLIST (-501)

ListSetIndex Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

989

Appendix C: Built-In Functions (H-P) ListSetIndex

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListSetIndex function. * * This example script displays the last three items from a list * of program folders. * * Note: If the target system has a shell other than Explorer, * the GetGroupNameList function may return an error. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "ListSetIndex Example" #define MSG_TEXT "Please note the last three items in this list." // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListSetIndex(HWND); function ExFn_ListSetIndex(hMSI) STRING svString; LIST listID; NUMBER nResult, nIndex; begin // Create string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Get the names of the program folders into a list. if GetGroupNameList (listID) < 0 then ; // Report ListCreate failure. MessageBox ("Unable to retrieve program folder names.", SEVERE); else // Display the list. SdShowInfoList( TITLE_TEXT, MSG_TEXT, listID); // Make the third item from the end of the list the current // the current element. If there are fewer than three items, // display them all. List indexing begins at 0. nIndex = ListCount (listID); if nIndex > 3 then nIndex = nIndex - 3; endif; nResult = ListSetIndex (listID, nIndex); // Loop while there are items to display. while (nResult != END_OF_LIST) // Get the current list item. ListCurrentString (listID, svString); // Display the current list item.
990 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListValid

MessageBox (svString, INFORMATION); // Make the next item the current item. nResult = ListSetIndex (listID, LISTNEXT); endwhile; endif; // Remove the list from memory. ListDestroy (listID); end;

ListValid
The ListValid function indicates whether the list specified by listID is valid, that is, whether it has been initialized by calling ListCreate and not destroyed by calling ListDestroy. This function works with both string and number lists.

Syntax
ListValid ( listID );

Parameters
Table C-75: ListValid Parameters Parameter listID Description Specifies the string or number list to be checked.

Return Values
Table C-76: ListValid Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS ISERR_LIST_NOSUCHLIST Description Indicates that the list is valid. Indicates that the list is not valid. Indicates that the list has not been initialized.

ListValid Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListValid function. * \*---------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 991

Appendix C: Built-In Functions (H-P) ListValidType

#include "Ifx.h" function OnBegin() LIST listID; number nListValid; begin // Create an empty number list. listID = ListCreate (NUMBERLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Check whether the list ID is valid. nListValid = ListValid (listID); if (nListValid >= ISERR_SUCCESS) then MessageBox ("List ID is valid.", INFORMATION); else MessageBox ("List ID is not valid.", INFORMATION); endif; // Remove the list from memory. ListDestroy (listID); // Check whether the list ID is valid. nListValid = ListValid (listID); if (nListValid >= ISERR_SUCCESS) then MessageBox ("List ID is valid.", INFORMATION); else MessageBox ("List ID is not valid.", INFORMATION); endif; // If you cut and paste this sample script into a project // and run it, the following line aborts execution of the script. abort; end;

ListValidType
The ListValidType function indicates whether the list specified by listID is of the specified type and is valid, that is, whether it has been initialized by calling ListCreate and not destroyed by calling ListDestroy.

Syntax
ListValidType ( listID, nType );

992

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListValidType

Parameters
Table C-77: ListValidType Parameters Parameter listID nType Description Specifies the string or number list to be checked. Specifies the list type to which the specified list is compared. Pass one of the following predefined constants in this parameter:

NUMBERLISTSpecifies a number list. STRINGLISTSpecifies a string list.

Return Values
Table C-78: ListValidType Return Values Return Value >= ISERR_SUCCESS Description Indicates that the list is valid and is of the specified type. Indicates that the list is not valid or is not of the specified type. Indicates that the list has not been initialized. Indicates that the list is not of the specified type.

< ISERR_SUCCESS

ISERR_LIST_NOSUCHLIST ISERR_LIST_TYPEMISMATCH

ListValidType Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListValidType function. * \*---------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" function OnBegin() LIST listID; number nListValidType; begin // Create an empty string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

993

Appendix C: Built-In Functions (H-P) ListWriteToFile

endif; // Check whether the list ID is valid and what type it is. nListValidType = ListValidType (listID, NUMBERLIST); if (nListValidType >= ISERR_SUCCESS) then MessageBox ("List ID is valid and is a number list.", INFORMATION); else nListValidType = ListValidType (listID, STRINGLIST); if (nListValidType >= ISERR_SUCCESS) then MessageBox ("List ID is valid and is a string list.", INFORMATION); else MessageBox ("List ID is not valid.", INFORMATION); endif; endif; // Remove the list from memory. ListDestroy (listID); // Check whether the list ID is valid and what type it is. nListValidType = ListValidType (listID, NUMBERLIST); if (nListValidType >= ISERR_SUCCESS) then MessageBox ("List ID is valid and is a number list.", INFORMATION); else nListValidType = ListValidType (listID, STRINGLIST); if (nListValidType >= ISERR_SUCCESS) then MessageBox ("List ID is valid and is a string list.", INFORMATION); else MessageBox ("List ID is not valid.", INFORMATION); endif; endif; // If you cut and paste this sample script into a project // and run it, the following line aborts execution of the script. abort; end;

ListWriteToFile
The ListWriteToFile function writes a string list to a text file. Each string appears on a separate line in the text file.

Note: Note if the file already exists and the pre-existing file is Unicode, it writes the file as Unicode. Otherwise, it writes the file as ANSI.

Syntax
ListWriteToFile ( listID, szFileName );

994

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ListWriteToFile

Parameters
Table C-79: ListWriteToFile Parameters Parameter listID Description Specifies the name of a string list to write into a text file. Specifies the fully qualified name of the file to which the string list is to be written. If the file does not exist, it is created. If the file already exists, it is overwritten.

szFileName

Return Values
Table C-80: ListWriteToFile Return Values Return Value 0 ISERR_LIST_NOSUCHLIST (-501) Description The function was successful. Indicates that a list with the specified ID does not exist. Valid list IDs are return values from the ListCreate function. The function failed.

<0

ListWriteToFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ListReadFromFile and ListWriteToFile * functions. * * ListReadFromFile is called to read and display the * Autoexec.bat file. After the list has been displayed, * a remark is appended to the end of the list and the list * is written to a new file. The original file remains * unchanged. * * Note: In order for this script to run correctly, there must * be a batch file named Autoexec.bat in the root * directory of drive C. * \*--------------------------------------------------------------*/ #define OLD_FILE "C:\\Autoexec.bat"
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 995

Appendix C: Built-In Functions (H-P) ListWriteToFileEx

#define NEW_FILE "C:\\Autoexec.lst" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ListWriteToFile(HWND); function ExFn_ListWriteToFile(hMSI) LIST listID; begin // Create a string list. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list.", SEVERE); abort; endif; // Read the file into a string list. if (ListReadFromFile (listID, OLD_FILE) < 0) then // Report ListReadFromFile failure. MessageBox ("Unable to read" + OLD_FILE + ".", SEVERE); else // Display the list. SdShowInfoList ("Demo", "The example list file:", listID); // Add a new string to the list. ListAddString (listID, "REM Added by IS setup.", AFTER); // Write the list to a file. if (ListWriteToFile (listID, NEW_FILE) < 0) then MessageBox ("Unable to write list to "+ NEW_FILE + ".", SEVERE); else MessageBox ("Successfully wrote list "+ NEW_FILE + ".", INFORMATION); endif; endif; // Remove the list from memory. ListDestroy (listID); end;

ListWriteToFileEx
The ListWriteToFileEx function writes or appends a string list to a text file. Each string appears on a separate line in the text file.

Syntax
ListWriteToFileEx ( listID, szFileName, nOptions );

996

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LoadStringFromStringTable

Parameters
Table C-81: ListWriteToFileEx Parameters Parameter listID szFileName Description Specifies the name of a string list to write into a text file. Specifies the fully qualified name of the file to which the string list is to be written. If the file does not exist, it is created. If the file already exists and the LWTF_OPTION_APPEND_TO_FILE is not specified for nOptions, it is overwritten. Specifies the encoding of the file and whether the string list can be appended to it if it already exists. Choose one or more of the following predefined constants:

nOptions

0If the file already exists and the pre-existing file is Unicode, writes the file as Unicode. Otherwise, writes the file as ANSI. LWTF_OPTION_WRITE_AS_UNICODEWrites the file as Unicode. LWTF_OPTION_WRITE_AS_ANSIWrites the file as ANSI. LWTF_OPTION_APPEND_TO_FILEAppends the contents of the list to the existing file. If the file does not exist, the function creates the file (which is the same behavior as if this option was not specified).

You can combine two of these constants by using the bitwise OR operator (|). For example, combine the LWTF_OPTION_WRITE_AS_ANSI and LWTF_OPTION_APPEND_TO_FILE constants if you want the contents of the string list to be append to the file as ANSI.

Return Values
Table C-82: ListWriteToFileEx Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

LoadStringFromStringTable
The LoadStringFromStringTable function loads the value of the string entry specified by szID into svString. The svString buffer is automatically resized if necessary to accommodate the string value.

Syntax
LoadStringFromStringTable ( szID, svString );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

997

Appendix C: Built-In Functions (H-P) LOBYTE

Parameters
Table C-83: LoadStringFromStringTable Parameters Parameter szID Description Specifies the string identifier of the string entry. Do not prefix the identifier with the at sign (@). Returns the string value associated with the identifier that is specified by szID.

svString

Return Values
Table C-84: LoadStringFromStringTable Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the string value was successfully loaded into svString. Indicates that the string identifier was not found in the String Editor view.

Additional Information
The LoadStringFromStringTable function is case-insensitive when it comes to string identifiers. Therefore, when you use a string identifier in your script, you do not necessarily need to match the case of the string identifier that is specified in the String Editor view. However, mixing case may prevent InstallShield from matching the string entries in the script to the corresponding string entries in the String Editor view at build time. Therefore, it is recommended that you use uppercase for all instances of string identifiers. The LoadStringFromStringTable function is equivalent to the @ operator, with some exceptions:

When you build a project that includes an InstallScript file (.rul) and the InstallScript code contains one or more references to string entries that use the @ operator, InstallShield validates the string entries at build time. If a string identifier in the projects InstallScript file is not defined as one of the projects string entries in the String Editor view, InstallShield displays build warning -7174. If you use LoadStringFromStringTable, InstallShield does not validate the string entries at build time; scripts that use LoadStringFromStringTable are assumed to have their own string-not-found error handling. If the specified identifier does not exist in the String Editor view, the @ operator causes a message box to be displayed at run time; LoadStringFromStringTable simply returns failure (< ISERR_SUCCESS).

LOBYTE
Project: This information applies to InstallScript projects.

The LOBYTE function extracts the low-order byte from the 16-bit integer value specified by shValue.

998

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LogReadCustomNumber

Syntax
LOBYTE ( shValue );

Parameters
Table C-85: LOBYTE Parameters Parameter shValue Description Specifies the 16-bit integer from which you want to extract the lower byte.

Return Values
This function returns the low-order byte of the integer.

LogReadCustomNumber
Project: This information applies to InstallScript projects.

The LogReadCustomNumber function reads the number that is stored the log files custom logging section under the key name specified by szKey, and it returns the number data in nvValue.

Syntax
LogReadCustomNumber( szKey, nvValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

999

Appendix C: Built-In Functions (H-P) LogReadCustomNumber

Parameters
Table C-86: LogReadCustomNumber Parameters Parameter szKey nvValue Description Specifies the key name that identifies the number being read from the log file. Returns the number data that is read from the log file.

Return Values
Table C-87: LogReadCustomNumber Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully read the number from the log file. Indicates that the function was unable to read the number from the log file.

Additional Information
LogReadCustomNumber is not affected by whether logging is enabled or disabled. LogReadCustomNumber can read values that were entered with LogWriteCustomNumber and numbers that were entered as strings (for example, "123") with LogWriteCustomString. LogReadCustomNumber fails if used to read non-numeric data (for example, "123abc").

Custom log file entries do not affect maintenance or uninstallation of the product unless you add code to the script to read custom values and perform actions based on those values. LogReadCustomString cannot read data from the maintenance/uninstallation section of the log file (that is, the section where the installation automatically writes data, such as the files that are installed and the registry entries that are created, and from which it automatically reads data during maintenance or uninstallation). To execute script code only when the product is being completely uninstalled, use an if-then statement:
if REMOVEALLMODE!=0 then /* this code is executed only during uninstallation */ endif;

To perform specific uninstallation actions when a particular feature is uninstalled, override the features UnInstalling event with the appropriate code.

LogReadCustomNumber Example
Project: This information applies to InstallScript projects.
//--------------------------------------------------------------------------// // InstallShield Example Script // // Demonstrates the LogWriteCustomString, LogWriteCustomNumber, // LogReadCustomString, and LogReadCustomNumber functions.

1000

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LogReadCustomString

// //--------------------------------------------------------------------------// during installation, write some custom data to the log file function OnMoved( ) LIST listDrives; NUMBER nDriveCount, nvIgnore; STRING svDate; begin if (!MAINTENANCE) then // get current date GetSystemInfo(DATE, nvIgnore, svDate); // get current count of available drive letters listDrives = ListCreate(STRINGLIST); GetValidDrivesList(listDrives, -1, -1); nDriveCount = ListCount(listDrives); ListDestroy(listDrives); // write custom data to .ilg log file LogWriteCustomString("InstallDate", svDate); LogWriteCustomNumber("DriveCount", nDriveCount); endif; end;

// during a complete uninstallation, read custom data back from the log file function OnMoving( ) NUMBER nvDriveCount; STRING svInstallDate; begin if (REMOVEALLMODE) then LogReadCustomNumber("DriveCount", nvDriveCount); LogReadCustomString("InstallDate", svInstallDate); SprintfBox(INFORMATION, "Custom Log Data", "During installation, the drive count " + "was %d, and the date was %s.", nvDriveCount, svInstallDate); endif; end;

LogReadCustomString
Project: This information applies to InstallScript projects. LogReadCustomString reads the string that is stored the log files custom logging section under the key

name specified by szKey, and it returns the string data in svValue.

Syntax
LogReadCustomString( szKey, svValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1001

Appendix C: Built-In Functions (H-P) LogReadCustomString

Parameters
Table C-88: LogReadCustomString Parameters Parameter szKey svValue Description Specifies the key name that identifies the string being read from the log file. Returns the string data that is read from the log file.

Return Values
Table C-89: LogReadCustomString Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully read the string from the log file. Indicates that the function was unable to read the string from the log file.

Additional Information
LogReadCustomString is not affected by whether logging is enabled or disabled. LogReadCustomString can

read values that were entered with either LogWriteCustomString or LogWriteCustomNumber. Custom log file entries do not affect maintenance or uninstallation of the product unless you add code to the script to read custom values and perform actions based on those values. LogReadCustomString cannot read data from the maintenance/uninstallation section of the log file (that is, the section where the installation automatically writes data, such as the files that are installed and the registry entries that are created, and from which it automatically reads data during maintenance or uninstallation).

Note: If you selected the Show Password dialog box during setup initialization check box in the Password & Copyright panel of the Release Wizard or selected Yes for the Show Password Dialog setting in the Releases view, the default code for the OnCheckMediaPassword event handler function calls LogWriteCustomString with szKey set to MEDIA_PASSWORD_KEY in order to store a password-protected installations password (as entered by the end user) so that maintenance and upgrade operations do not require that the same password be reentered. That default code also calls LogWriteCustomString with szKey set to MEDIA_PASSWORD_KEY in order to check whether the password is already stored before querying the end user for the password.

To execute script code only when the product is being completely uninstalled, use an if-then statement:
if REMOVEALLMODE!=0 then /* this code is executed only during uninstallation */ endif;

To perform specific uninstallation actions when a particular feature is uninstalled, override the features UnInstalling event with the appropriate code.

1002

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LogReadCustomString

LogReadCustomString Example
Project: This information applies to InstallScript projects.
//--------------------------------------------------------------------------// // InstallShield Example Script // // Demonstrates the LogWriteCustomString, LogWriteCustomNumber, // LogReadCustomString, and LogReadCustomNumber functions. // //--------------------------------------------------------------------------// during installation, write some custom data to the log file function OnMoved( ) LIST listDrives; NUMBER nDriveCount, nvIgnore; STRING svDate; begin if (!MAINTENANCE) then // get current date GetSystemInfo(DATE, nvIgnore, svDate); // get current count of available drive letters listDrives = ListCreate(STRINGLIST); GetValidDrivesList(listDrives, -1, -1); nDriveCount = ListCount(listDrives); ListDestroy(listDrives); // write custom data to .ilg log file LogWriteCustomString("InstallDate", svDate); LogWriteCustomNumber("DriveCount", nDriveCount); endif; end;

// during a complete uninstallation, read custom data back from the log file function OnMoving( ) NUMBER nvDriveCount; STRING svInstallDate; begin if (REMOVEALLMODE) then LogReadCustomNumber("DriveCount", nvDriveCount); LogReadCustomString("InstallDate", svInstallDate); SprintfBox(INFORMATION, "Custom Log Data", "During installation, the drive count " + "was %d, and the date was %s.", nvDriveCount, svInstallDate); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1003

Appendix C: Built-In Functions (H-P) LogWriteCustomNumber

LogWriteCustomNumber
Project: This information applies to InstallScript projects. LogWriteCustomNumber writes the number specified by nValue to the log file in the custom logging

section under the key name specified by szKey.

Syntax
LogWriteCustomNumber( szKey, nValue );

Parameters
Table C-90: LogWriteCustomNumber Parameters Parameter szKey Description Specifies the key name that identifies the number being written to the log file. All key names written to a particular log file must be unique, regardless of whether they are written with LogWriteCustomNumber or LogWriteCustomString. If you specify a key name that already exists in the custom logging section, its value is overwritten. Specifies the number to be written to the log file.

nValue

Return Values
Table C-91: LogWriteCustomNumber Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully wrote the number to the log file. Indicates that the function was unable to write the number to the log file.

Additional Information
LogWriteCustomNumber fails if you call it while logging is disabled.

Custom log file entries do not affect maintenance or uninstallation of the product unless you add code to the script to read custom values and perform actions based on those values. LogWriteCustomNumber cannot write data to the maintenance/uninstallation section of the log file (that is, the section where the installation automatically writes data, such as the files that are installed and the registry entries that are created, and from which it automatically reads data during maintenance or uninstallation). To execute script code only when the product is being completely uninstalled, use an if-then statement:
if REMOVEALLMODE!=0 then /* this code is executed only during uninstallation */ endif;

To perform specific uninstallation actions when a particular feature is uninstalled, override the features UnInstalling event with the appropriate code.

1004

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LogWriteCustomNumber

LogWriteCustomNumber Example
Project: This information applies to InstallScript projects.
//--------------------------------------------------------------------------// // InstallShield Example Script // // Demonstrates the LogWriteCustomString, LogWriteCustomNumber, // LogReadCustomString, and LogReadCustomNumber functions. // //--------------------------------------------------------------------------// during installation, write some custom data to the log file function OnMoved( ) LIST listDrives; NUMBER nDriveCount, nvIgnore; STRING svDate; begin if (!MAINTENANCE) then // get current date GetSystemInfo(DATE, nvIgnore, svDate); // get current count of available drive letters listDrives = ListCreate(STRINGLIST); GetValidDrivesList(listDrives, -1, -1); nDriveCount = ListCount(listDrives); ListDestroy(listDrives); // write custom data to .ilg log file LogWriteCustomString("InstallDate", svDate); LogWriteCustomNumber("DriveCount", nDriveCount); endif; end;

// during a complete uninstallation, read custom data back from the log file function OnMoving( ) NUMBER nvDriveCount; STRING svInstallDate; begin if (REMOVEALLMODE) then LogReadCustomNumber("DriveCount", nvDriveCount); LogReadCustomString("InstallDate", svInstallDate); SprintfBox(INFORMATION, "Custom Log Data", "During installation, the drive count " + "was %d, and the date was %s.", nvDriveCount, svInstallDate); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1005

Appendix C: Built-In Functions (H-P) LogWriteCustomString

LogWriteCustomString
Project: This information applies to InstallScript projects. LogWriteCustomString writes the string specified by szValue to the log file in the custom logging section

under the key name specified by szKey.

Syntax
LogWriteCustomString( szKey, szValue );

Parameters
Table C-92: LogWriteCustomString Parameters Parameter szKey Description Specifies the key name that identifies the string being written to the log file. All key names written to a particular log file must be unique, regardless of whether they are written with LogWriteCustomString or LogWriteCustomNumber. If you specify a key name that already exists in the custom logging section, its value is overwritten. Specifies the value to be written to the log file.

szValue

Return Values
Table C-93: LogWriteCustomString Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully wrote the string to the log file. Indicates that the function was unable to write the string to the log file.

Additional Information
LogWriteCustomString fails if you call it while logging is disabled.

Custom log file entries do not affect maintenance or uninstallation of the product unless you add code to the script to read custom values and perform actions based on those values. LogWriteCustomString cannot write data to the maintenance/uninstallation section of the log file (that is, the section where the installation automatically writes data, such as the files that are installed and the registry entries that are created, and from which it automatically reads data during maintenance or uninstallation).

Note: If you selected the Show Password dialog box during setup initialization check box in the Password & Copyright panel of the Release Wizard or selected Yes for the Show Password Dialog setting in the Releases view, the default code for the OnCheckMediaPassword event handler function calls LogWriteCustomString with szKey set to MEDIA_PASSWORD_KEY in order to store a password-protected installations password (as entered by the end user) so that maintenance and upgrade operations do not require that the same password be reentered. That default code also
1006 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LogWriteCustomString

calls LogWriteCustomString with szKey set to MEDIA_PASSWORD_KEY in order to check whether the password is already stored before querying the end user for the password.

To execute script code only when the product is being completely uninstalled, use an if-then statement:
if REMOVEALLMODE!=0 then /* this code is executed only during uninstallation */ endif;

To perform specific uninstallation actions when a particular feature is uninstalled, override the features UnInstalling event with the appropriate code.

LogWriteCustomString Example
Project: This information applies to InstallScript projects.
//--------------------------------------------------------------------------// // InstallShield Example Script // // Demonstrates the LogWriteCustomString, LogWriteCustomNumber, // LogReadCustomString, and LogReadCustomNumber functions. // //--------------------------------------------------------------------------// during installation, write some custom data to the log file function OnMoved( ) LIST listDrives; NUMBER nDriveCount, nvIgnore; STRING svDate; begin if (!MAINTENANCE) then // get current date GetSystemInfo(DATE, nvIgnore, svDate); // get current count of available drive letters listDrives = ListCreate(STRINGLIST); GetValidDrivesList(listDrives, -1, -1); nDriveCount = ListCount(listDrives); ListDestroy(listDrives); // write custom data to .ilg log file LogWriteCustomString("InstallDate", svDate); LogWriteCustomNumber("DriveCount", nDriveCount); endif; end;

// during a complete uninstallation, read custom data back from the log file function OnMoving( ) NUMBER nvDriveCount; STRING svInstallDate; begin if (REMOVEALLMODE) then LogReadCustomNumber("DriveCount", nvDriveCount);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1007

Appendix C: Built-In Functions (H-P) LongPathFromShortPath

LogReadCustomString("InstallDate", svInstallDate); SprintfBox(INFORMATION, "Custom Log Data", "During installation, the drive count " + "was %d, and the date was %s.", nvDriveCount, svInstallDate); endif; end;

LongPathFromShortPath
Use the LongPathFromShortPath function to convert a short file name to its equivalent long file name. For an explanation of long file names, see Long File Names.

Syntax
LongPathFromShortPath ( svPath );

Parameters
Table C-94: LongPathFromShortPath Parameters Parameter svPath Description Specifies a short file name and returns its associated long file name.

Return Values
Table C-95: LongPathFromShortPath Return Values Return Value 0 <0 Description Indicates that the function was successful. Indicates that the function was not successful.

LongPathFromShortPath Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions LongPathToShortPath and * LongPathFromShortPath. * * First, LongPathToShortPath is called to convert a long path
1008 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LongPathToQuote

* to a short path. Then LongPathFromShortPath is called to * convert the short path to a long path. The result of each * is displayed in a message box. * \*--------------------------------------------------------------*/ #define LONG_PATH "C:\\Program files" #define TITLE "LongPathToShortPath & LongPathFromShortPath" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_LongPathFromShortPath(HWND); function ExFn_LongPathFromShortPath(hMSI) STRING svPath, szTitle, szMsg; begin // Prompt user to enter a long path. szMsg = "Please select an existing long path:"; AskPath (szMsg, LONG_PATH, svPath); // Display the long path. szMsg = "The long path is shown below: \n\n%s"; SprintfBox (INFORMATION, TITLE, szMsg, svPath); //Convert the long path to a short path. if (LongPathToShortPath (svPath) < 0) then; MessageBox ("LongPathToShortPath failed.", SEVERE); abort; else // Display the short path. szMsg = "The short path is shown below: \n\n%s"; SprintfBox (INFORMATION, TITLE, szMsg, svPath); endif; // Restore the long path from the short path. if (LongPathFromShortPath (svPath) < 0) then MessageBox ("LongPathFromShortPath failed.", SEVERE); else // Display the restored long path. szMsg = "The restored long path is shown below: \n\n%s"; SprintfBox (INFORMATION, TITLE, szMsg, svPath); endif; end;

LongPathToQuote
The LongPathToQuote function places double quotation marks around a long file name or removes the double quotation marks from a long file name. For an explanation of long file names, see Long File Names. Add double quotation marks to long file names that contain spaces before passing the long file names to the command line. You must remove the double quotation marks from long file names before converting them to short file names using the LongPathToShortPath function. If you do not, the quoted long file name remains intact.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1009

Appendix C: Built-In Functions (H-P) LongPathToQuote

Note: This function adds quotation marks only if there is a space character in the file name. For example, quotation marks are not added around C:\\ThisismyApp because it is a long file name without a space.

Syntax
LongPathToQuote ( svPath, nParameter );

Parameters
Table C-96: LongPathToQuote Parameters Parameter svPath Description Specifies a long file name and returns that name with or without quotation marks, depending on the value passed in nParameter. Specifies whether quotation marks are to be added to the long path or removed from the long path. Pass one of the following predefined constants in this parameter:

nParameter

TRUEQuotation marks are added to the long path. FALSEQuotation marks are removed from the long path.

Return Values
Table C-97: LongPathToQuote Return Values Return Value 0 <0 Description Indicates that the function was successful. Indicates that the function was not successful.

LongPathToQuote Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the LongPathToQuote function. * * This script calls LongPathToQuote to place double quotation

1010

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LongPathToShortPath

* marks around a long file name. The result is displayed in * in a dialog. Then, LongPathToQuote is called again to * remove the quotation marks and the result displayed in a * dialog. * \*--------------------------------------------------------------*/ // Define a constant for the base path (a long file name). #define BASE_PATH "C:\\Program Files" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_LongPathToQuote(HWND); function ExFn_LongPathToQuote(hMSI) STRING svPath, szMainDirectory, szMsg; begin // Set up parameter for call to LongPathToQuote. svPath = BASE_PATH; // Place double quotation marks around the long file name in svPath. if (LongPathToQuote (svPath, TRUE) < 0) then MessageBox ("First call to LongPathToQuote failed.", SEVERE); abort; endif; // Display the quoted long file name in svPath. szMsg = "The quoted long file name:\n\n" + svPath; MessageBox (szMsg, INFORMATION); // Remove the quotation marks from the long file name in svPath. if (LongPathToQuote (svPath, FALSE) < 0) then MessageBox ("Second call to LongPathToQuote failed.", SEVERE); abort; endif; // Display the long file name with quotation marks removed. szMsg = "The unquoted long file name is shown below: \n\n" + svPath; MessageBox (szMsg, INFORMATION); end;

LongPathToShortPath
The LongPathToShortPath function converts a long file name to its equivalent short file name. The parameter svPath can be an absolute path or a relative path, and it may include a file name; but the folder or file it specifies must exist on the target system. For an explanation of long file names, see Long File Names.

Syntax
LongPathToShortPath ( svPath );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1011

Appendix C: Built-In Functions (H-P) LongPathToShortPath

Parameters
Table C-98: LongPathToShortPath Parameters Parameter svPath Description Specifies a long file name and returns its associated short file name.

Note: LongPathToShortPath removes trailing backslashes from long file names.

Return Values
Table C-99: LongPathToShortPath Return Values Return Value 0 <0 Description Indicates that the function was successful. Indicates that the function was not successful.

Additional Information
Since LongPathToShortPath can succeed only if the specified folder or file can be found on the target system, you may need to set the current folder before specifying a relative path. For example, if svPath contains the relative path InstallShield, which exists in the folder C:\Program Files, the setup is not able to find it unless the current folder is C:\Program Files. Use the ChangeDirectory function to change the current folder when necessary before calling LongPathToShortPath so that the target folder or path can be found.

LongPathToShortPath Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions LongPathToShortPath and * LongPathFromShortPath. * * First, LongPathToShortPath is called to convert a long path * to a short path. Then LongPathFromShortPath is called to * convert the short path to a long path. The result of each * is displayed in a message box. * \*--------------------------------------------------------------*/

1012

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) LOWORD

#define LONG_PATH "C:\\Program Files" #define TITLE "LongPathToShortPath & LongPathFromShortPath" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_LongPathToShortPath(HWND); function ExFn_LongPathToShortPath(hMSI) STRING svPath, szTitle, szMsg; begin // Prompt user to enter a long path. szMsg = "Please select an existing long path:"; AskPath (szMsg, LONG_PATH, svPath); // Display the long path. szMsg = "The long path is shown below: \n\n%s"; SprintfBox (INFORMATION, TITLE, szMsg, svPath); //Convert the long path to a short path. if (LongPathToShortPath (svPath) < 0) then; MessageBox ("LongPathToShortPath failed.", SEVERE); abort; else // Display the short path. szMsg = "The short path is shown below: \n\n%s"; SprintfBox (INFORMATION, TITLE, szMsg, svPath); endif; // Restore the long path from the short path. if (LongPathFromShortPath (svPath) < 0) then MessageBox ("LongPathFromShortPath failed.", SEVERE); else // Display the restored long path. szMsg = "The restored long path is shown below: \n\n%s"; SprintfBox (INFORMATION, TITLE, szMsg, svPath); endif; end;

LOWORD
The LOWORD function extracts the low-order word (two bytes) from the 32-bit integer value specified by lValue.

Syntax
LOWORD ( lValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1013

Appendix C: Built-In Functions (H-P) LOWORD

Parameters
Table C-100: LOWORD Parameters Parameter lValue Description Specifies the 32-bit integer from which you want to extract the lower two bytes.

Return Values
This function returns the low-order word (lower two bytes) of the integer.

LOWORD Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates HIWORD and LOWORD. * * This example script shows how to use HIWORD and LOWORD to * to get the low-order word and the high-order word from a value. \*--------------------------------------------------------------*/ #define TITLE_TEXT "LOWORD/HIWORD Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_LOWORD(HWND); function ExFn_LOWORD(hMSI) STRING szMsg; NUMBER nData, nLOWORD, nHIWORD; begin nData = 305419896; // hex value: 12345678 // Get the low-order word, 22136 (hex value: 5678). nLOWORD = LOWORD (nData); // Get the high-order word, 4660 (hex value: 1234). nHIWORD = HIWORD (nData); // Display the results. szMsg = "LOWORD: %ld\nHIWORD: %ld"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, nLOWORD, nHIWORD); end;

1014

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) MaintenanceStart

MaintenanceStart
The MaintenanceStart function creates a registry key and associated values that are used during initialization for maintenance or uninstallation and that provide information about the application to Add or Remove Programs. This function is called by the default code for the OnMoveData event handler.

Note: The InstallScript engine currently does not support writing or reading Add or Remove Programs information for a product in the 64-bit part of the registry. Therefore, using the REGDB_OPTION_WOW64_64KEY option with the REGDB_OPTIONS system variable is not supported for this registry function. Enabling the REGDB_OPTION_WOW64_64KEY option has no effect on where registry entries are created by this function. MaintenanceStart creates the following values under the application uninstallation registry key: Table C-101: Application Uninstallation Registry Key Values Value Name Comments Value Data The value of the system variable IFX_PRODUCT_COMMENTS, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_PRODUCT_SUPPORT_CONTACT, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_PRODUCT_ICON, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_PRODUCT_NAME, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_PRODUCT_VERSION. The value of the system variable IFX_PRODUCT_SUPPORT_URL, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_PRODUCT_SUPPORT_PHONE, if non-null; otherwise, the function does not create an entry. The date on which the installation is run, in the format yyyymmdd. The value of the system variable TARGETDIR. The value of the system variable SRCDIR. The value of the system variable SELECTED_LANGUAGE. <DISK1TARGET>\Setup.ilg The value of the system variable MAINT_OPTION.

Contact

DisplayIcon

DisplayName

DisplayVersion HelpLink

HelpTelephone

InstallDate InstallLocation InstallSource Language LogFile LogMode

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1015

Appendix C: Built-In Functions (H-P) MaintenanceStart

Table C-101: Application Uninstallation Registry Key Values (cont.) Value Name ModifyPath Value Data The value of the system variable UNINSTALL_STRING if ADDREMOVE_HIDECHANGEOPTION is FALSE and either of the following two conditions is true:

ADDREMOVE_HIDEREMOVEOPTION is non-zero ADDREMOVE_HIDEREMOVEOPTION and ADDREMOVE_COMBINEDBUTTON are both FALSE

Otherwise, the function does not create an entry. NoModify NoRemove NoRepair The value of the system variable ADDREMOVE_HIDEREMOVEOPTION. The value of the system variable ADDREMOVE_HIDEREMOVEOPTION. 1 if either ADDREMOVE_HIDECHANGEOPTION or ADDREMOVE_HIDEREMOVEOPTION is non-zero; otherwise, the function does not create an entry. The value of the system variable PRODUCT_GUID. The value of the system variable IFX_PRODUCT_REGISTEREDSERIALNUM, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_COMPANY_NAME, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_PRODUCT_README, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_PRODUCT_REGISTEREDCOMPANY, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_PRODUCT_REGISTEREDOWNER, if non-null; otherwise, the function does not create an entry. 1 if the system variable ADDREMOVE_SYSTEMCOMPONENT is non-zero; otherwise, the function does not create an entry. The value of the system variable UNINSTALL_STRING. Additionally, the value of the system variable ADDREMOVE_STRING_REMOVEONLY is appended to this registry data if ADDREMOVE_HIDEREMOVEOPTION is FALSE and either of the following two conditions is true:

ProductGuid ProductId

Publisher

Readme

RegCompany

RegOwner

SystemComponent

UninstallString

URLInfoAbout

ADDREMOVE_HIDECHANGEOPTION is non-zero ADDREMOVE_HIDECHANGEOPTION and ADDREMOVE_COMBINEDBUTTON are both FALSE

The value of the system variable IFX_PRODUCT_URL, if non-null; otherwise, the function does not create an entry. The value of the system variable IFX_PRODUCT_UPDATE_URL, if non-null; otherwise, the function does not create an entry. The packed DWORD equivalent of the data in the DisplayVersion value.

URLUpdateInfo

Version

1016

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) MediaGetData

Table C-101: Application Uninstallation Registry Key Values (cont.) Value Name VersionMajor VersionMinor Value Data The first byte of the data in the Version value. The second byte of the data in the Version value.

Syntax
MaintenanceStart ( );

Parameters
None

Return Values
Table C-102: MaintenanceStart Return Values Return Value 0 Description Indicates that the function successfully created the registry key and its associated values. Indicates that the function was unable to create the registry key and its associated values. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

<0

Additional Information
InstallScript installations always create VersionMajor and VersionMinor registry values in the Uninstall key. This applies to new installations that are created in InstallShield 2012, as well as installations that are upgraded from InstallShield 2009 or earlier. Previously, in InstallShield 2009 and earlier, the names of the values that InstallScript installations created were MajorVersion and MinorVersion; these are no longer created. When the MaintenanceStart function is called, it creates the VersionMajor and VersionMinor value names in the registry. By default, it also deletes the MajorVersion and MinorVersion value names if they exist. If you do not want the MajorVersion and MinorVersion value names to be deleted from target systems, you can use the REGDB_OPTIONS option called REGDB_OPTION_NO_DELETE_OLD_MAJMIN_VERSION. If you want to continue using only the MajorVersion and MinorVersion value names, you must delete VersionMajor and VersionMinor after MaintenanceStart returns.

MediaGetData
Project: This information applies to InstallScript projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1017

Appendix C: Built-In Functions (H-P) MediaGetDataEx

The MediaGetData function retrieves information about a file media library.

MediaGetData calls MediaGetDataEx(szMediaSource, nInfo, nvResult, svResult, FALSE). For information on parameters and return values for MediaGetData, see MediaGetDataEx.

Syntax
MediaGetData ( szMediaSource, nInfo, nvResult, svResult );

MediaGetDataEx
Project: This information applies to InstallScript projects.

The MediaGetDataEx function retrieves information about a file media library, including media information that is stored in the projects string entries.

Syntax
MediaGetDataEx ( szMediaSource, nInfo, nvResult, svResult, bCheckStringTable );

1018

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) MediaGetDataEx

Parameters
Table C-103: MediaGetDataEx Parameters Parameter szMediaSource Description Specifies the name of the file media library whose information is to be retrieved; typically, the value of this argument is the system variable MEDIA. Specifies the type of information to retrieve. Pass one of the following predefined constants in this parameter:

nInfo

MEDIA_FIELD_ADDREMOVE_NOMODIFYRetrieves the setting that you specified in the Disable Change Button setting in the General Information view. The value is returned in nvResult; 0 corresponds to No and 1 corresponds to Yes. MEDIA_FIELD_ADDREMOVE_NOREMOVERetrieves the setting that you specified in the Disable Remove Button setting in the General Information view. The value is returned in nvResult; 0 corresponds to No and 1 corresponds to Yes. MEDIA_FIELD_COMPANY_NAMERetrieves the company name that you specified in the General Information view. The company name is returned in svResult. MEDIA_FIELD_MEDIA_FLAGSRetrieves the format of the specified file media library. The number returned in nvResult includes any applicable values from among the following bit flags: MEDIA_FLAG_FORMAT_DIFFERENTIAL: Indicates a differential file media library. MEDIA_FLAG_UPDATEMODE_SUPPORTED: Indicates an update enabled file media library. This flag is always set.

MEDIA_FIELD_PREVIOUS_VERSIONSRetrieves the version information that you specified in the Supported Version(s) property of the Releases view or in the Update panel in the Release Wizard. The version information is returned in svResult. MEDIA_FIELD_PRODUCT_COMMENTSRetrieves the comments that you specified in the ARP Comments setting in the General Information view. The value is returned in svResult. MEDIA_FIELD_PRODUCT_EXERetrieves the executable name that you specified in the General Information view. The executable name is returned in svResult.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1019

Appendix C: Built-In Functions (H-P) MessageBeep

Table C-103: MediaGetDataEx Parameters (cont.) Parameter nInfo (cont.) Description

MEDIA_FIELD_PRODUCT_ICONRetrieves the display icon that you specified in the Display Icon setting in the General Information view. The value is returned in svResult. MEDIA_FIELD_PRODUCT_NAMERetrieves the product name that you specified in the General Information view. The product name is returned in svResult. MEDIA_FIELD_PRODUCT_READMERetrieves the readme file that you specified in the Read Me setting in the General Information view. The value is returned in svResult. MEDIA_FIELD_PRODUCT_SUPPORT_CONTACTRetrieves the support contact that you specified in the Support Contact setting in the General Information view. The value is returned in svResult. MEDIA_FIELD_PRODUCT_SUPPORT_PHONERetrieves the support phone number that you specified in the Support Phone Number setting in the General Information view. The value is returned in svResult. MEDIA_FIELD_PRODUCT_SUPPORT_URLRetrieves the support URL that you specified in the Support URL setting in the General Information view. The value is returned in svResult. MEDIA_FIELD_PRODUCT_UPDATE_URLRetrieves the product update URL that you specified in the Product Update URL setting in the General Information view. The value is returned in svResult. MEDIA_FIELD_PRODUCT_URLRetrieves the publisher/product URL that you specified in the Publisher/Product URL setting in the General Information view. The value is returned in svResult. MEDIA_FIELD_PRODUCT_VERSIONRetrieves the version information that you specified in the General Information view. The version information is returned in svResult. MEDIA_FIELD_TARGETDIRRetrieves the value of TARGETDIR that you specified in the General Information view.

bCheckStringTable

Specifies whether svResult returns the string that you entered in InstallShield (FALSE) or, if the string that you entered in InstallShield is a string identifier, the string value that is associated with that identifier (TRUE). If bCheckStringTable is TRUE but the string that you entered in InstallShield is not a string identifier, svResult returns the string that you entered in InstallShield.

Return Values
Table C-104: MediaGetDataEx Return Values Return Value 0 <0 Description MediaGetData successfully retrieved the requested information. MediaGetData failed to retrieve the requested information.

MessageBeep
The MessageBeep function plays the default system sound.

1020

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) MessageBeep

Tip: You can also give audio cues by calling PlayMMedia to play an audio file.

Syntax
MessageBeep ( nReserved );

Parameters
Table C-105: MessageBeep Parameters Parameter nReserved Description Pass zero in this parameter. No other value is allowed.

Return Values
This function has no return values.

MessageBeep Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the MessageBeep function. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_MessageBeep(HWND); function ExFn_MessageBeep(hMSI) begin // Play the default system sound. MessageBeep (0); // Display a message box. MessageBox ("Please listen for a sound.", INFORMATION); // Play the default system sound. MessageBeep (0); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1021

Appendix C: Built-In Functions (H-P) MessageBox

MessageBox
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

The MessageBox function presents a dialog that contains a message, an icon that indicates the nature of the message (information, warning, or severe), and an OK button. The default title depends on the value of nType, which also indicates the icon type. For example, if you pass INFORMATION in nType, the title Information appears in the title bar. The titles are blank by default, unless you set them by calling SetDialogTitle before calling MessageBox. If the titles are blank, the title bar text for message box is the product name (from IFX_SETUP_TITLE). This function uses the Microsoft Windows API MessageBox. The operating environment, not the installation, determines the size and location of the message box. The operating environment also generates the text for the OK button in the local language (the language that the operating system is running under). You cannot change the text on this button. For more information regarding the use of Windows MessageBox types, consult the description of the MessageBox Windows API function in the appropriate Windows SDK. Note the following when using Windows message box constants:

Some Windows MessageBox type constants are predefined in the ISRTWindows.h file that is provided in the InstallShield Program Files Folder\Script\Isrt\Include folder. This file is automatically included in your installation when you include Ifx.h in your script. You do not need to redefine any constants that are defined in ISRTWindows.h; doing so will result in a compiler warning. To determine which constants are predefined, refer to the ISRTWindows.h file. To use constants that are not defined in ISRTWindows.h, you must define them (using #define) in the declaration block of your installation script. You cannot simply include the Windows.h file that is usually part of a C++ program. The values that you need to assign to the undefined constants can generally be found in an include file that is provided with the appropriate Windows SDK or development tool. (For Microsoft Visual C++, most constants can be found in the Winuser.h file, which is located in the InstallShield Program Files Folder\Script\Resource folder.) Windows and InstallShield message box constants cannot be used together in an installation. If an InstallShield message box constant is combined with a Windows message box constant using the OR operator (|), the Windows message box constant is ignored. Some Windows message box styles are not supported on some Windows platforms. To determine whether a particular style is supported on the operating systems that are targeted by the installation, consult the appropriate Windows SDK. When a Windows message box style is used by the MessageBox function, the caption (title) of the message box is Install. If you need to display a different caption, use the MessageBoxEx function.

Syntax
MessageBox ( szMsg, nType );

1022

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) MessageBox

Parameters
Table C-106: MessageBox Parameters Parameter szMsg Description Specifies the message to display. InstallShield does not automatically break the text of the message into separate lines to fit in the message box. If the message is too long for one line, insert a line break by embedding newline escape characters ( \n ) at appropriate places in the string. Specifies the type of message box to create and the type of icon to display in the message box. Pass one of the following predefined constants in this parameter:

nType

INFORMATION WARNING SEVERE

Any Windows API MessageBox type can also be specified in this parameter. Multiple styles can be combined logically using the OR operator to produce the required MessageBox type.

Return Values
The return value is not significant unless you are using standard Microsoft Windows message box styles. If you are using these styles, the return value is the same as the return value from the MessageBox API functions.

Additional Information
The dialog that is displayed by the MessageBox function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

MessageBox Example
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialogs control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the MessageBox function. *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1023

Appendix C: Built-In Functions (H-P) MessageBoxEx

* This script displays three message boxes, each with a * different message and icon. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_MessageBox(HWND); function ExFn_MessageBox(hMSI) STRING szMsg; begin // Display a message box that shows the information icon. szMsg = "This will install Example Program."; MessageBox (szMsg, INFORMATION); // Display a message box that shows the warning icon. szMsg = "Installing this version will replace previous one."; MessageBox (szMsg, WARNING); // Display a message box that shows the severe icon. szMsg = "Cannot install this application on floppy drives."; MessageBox (szMsg, SEVERE); end;

MessageBoxEx
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

The MessageBoxEx function presents a dialog that contains a message, an icon that indicates the nature of the message (information, warning, or severe), and an OK button. The title is set by szCaption. This function uses the Microsoft Windows API MessageBox. The operating environment, not InstallShield, determines the size and location of the message box. The operating environment also generates the text for the OK button in the local language (the language that the operating system is running under). You cannot change the text in this button. For more information regarding the use of Windows MessageBox types, consult the description of the MessageBox Windows API function in the appropriate Windows SDK. Note the following when using Windows message box constants:

Some Windows MessageBox type constants are predefined in the ISRTWindows.h file that is provided in the InstallShield Program Files Folder\Script\Isrt\Include folder. This file is automatically included in your installation when you include Ifx.h in your script. You do not need to redefine any constants that are defined in ISRTWindows.h; doing so will result in a compiler warning. To determine which constants are predefined, refer to the ISRTWindows.h file.

1024

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) MessageBoxEx

To use constants that are not defined in ISRTWindows.h, you must define them (using #define) in the declaration block of your installation script. You cannot simply include the Windows.h file that is usually part of a C++ program. The values that you need to assign to the undefined constants can generally be found in an include file that is provided with the appropriate Windows SDK or development tool. (For Microsoft Visual C++, most constants can be found in the Winuser.h file, which is located in the InstallShield Program Files Folder\Script\Resource folder.) Windows and InstallShield message box constants cannot be used together in an installation. If an InstallShield message box constant is combined with a Windows message box constant using the OR operator, the Windows message box constant will be ignored. Some Windows message box styles are not supported on some Windows platforms. To determine whether a particular style is supported on the operating system(s) targeted by the installation, consult the appropriate Windows SDK.

Syntax
MessageBoxEx( szMsg, szCaption, nType );

Parameters
Table C-107: MessageBoxEx Parameters Parameter szMsg Description Specifies the message to display. InstallShield does not automatically break the text of the message into separate lines to fit in the message box. If the message is too long for one line, insert a line break by embedding newline escape characters ( \n ) at appropriate places in the string. Specifies the title to display. If you pass a null string ("") in this parameter, the value of the system variable IFX_SETUP_TITLE is used as the dialog title. Specifies the type of message box to create and the type of icon to display in the message box. Pass one of the following predefined constants in this parameter (Explorer shell icons are shown):

szCaption

nType

INFORMATION WARNING SEVERE

Any Windows API MessageBox type can also be specified in this parameter. Multiple styles can be combined logically with the OR operator (|) to produce the required MessageBox type.

Return Values
The return value is not significant unless you are using standard Microsoft Windows message box styles. If you are using these styles, the return value is the same as the return value from the MessageBox API functions.

Additional Information
The message box that is displayed by the MessageBoxEx function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1025

Appendix C: Built-In Functions (H-P) NumToStr

NumToStr
The NumToStr function converts a number to a string.

Syntax
NumToStr ( svString, nValue );

Parameters
Table C-108: NumToStr Parameters Parameter svString nValue Description Returns the string equivalent of nValue. Specifies the number to convert to a string.

Return Values
Table 4: NumToStr Return Value 0 Description Indicates that the function successfully converted the number to a string. Indicates that the function failed to convert the number to a string.

<0

NumToStr Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the NumToStr function * * This script calls NumToStr convert the numeric value of free * disk space available on the system to a string so that it * can be displayed by the MessageBox function. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_NumToStr(HWND); function ExFn_NumToStr(hMSI)
1026 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) OpenFile

STRING NUMBER begin

svString; nSpace, nResult;

// Get the amount of free space on drive C. nSpace = GetDiskSpace ("C:"); // Convert the number to a string. nResult = NumToStr (svString, nSpace); if (nResult < 0) then MessageBox ("NumToStr failed.", SEVERE); else // Display the amount of free space on drive C. MessageBox (svString + " bytes free on drive C.", INFORMATION); endif; end;

OpenFile
The OpenFile function opens an existing text file or binary file. Before you open the file you must set the file mode by calling OpenFileMode.

Tip: Note the following:

After you open a text file, call GetLine and WriteLine to read from and write to the file. When you finish reading from or writing to a file with GetLine or WriteLine, you must close the file using the CloseFile function. After you open a binary file, call ReadBytes and WriteBytes to read from and write to the file. You can use SeekBytes to position the file pointer before writing to a binary file. You can also search, read from, and write to text files using the FileGrep, FileInsertLine, and FileDeleteLine functions. However, these functions do not require you to open or close the files (this is handled internally). Use CreateFile to create a file. CreateFile leaves the new file open in append mode (text files) or read/write mode (binary files).

Syntax
OpenFile ( nvFileHandle, szPath, szFileName );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1027

Appendix C: Built-In Functions (H-P) OpenFile

Parameters
Table C-1: OpenFile Parameters Parameter nvFileHandle Description Returns the file handle of the file that was opened. Use this handle to identify the file when you call other file-related InstallScript functions. Specifies the pathwhich may include a drive designationof the file you want to open. You can specify a valid Uniform Resource Locator (URL) in this parameter, after setting the file mode to FILE_MODE_NORMAL or FILE_MODE_BINARYREADONLY (by calling OpenFileMode). If you pass a CGI or ASP request (for example, "http://www.mydomain.net/ login.asp?name=Me&pwd=wow"), the response is sent to memory and can be read by ReadBytes. To check the validity of a URL, call Is(VALID_PATH, szURL). If you pass a null string ("") in this parameter, the function fails. Specifies the unqualified namethat is, without a drive designation or pathof the file you want to open. If you pass a null string ("") in this parameter, the function fails.

szPath

szFileName

Return Values
Table C-2: OpenFile Return Values Return Value 0 <0 Description Indicates that the function successfully opened the file. Indicates that the function was unable to open the file.

OpenFile Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the OpenFile and CloseFile functions. * * OpenFile is called to open a file, which is then read into * a list. The file is then closed and the list is displayed. * * Note: Before running this script, set the preprocessor * constants so that they reference an existing file * in an existing directory. * \*--------------------------------------------------------------*/ #define EXAMPLE_FILE "Readme.txt" #define EXAMPLE_DIR "C:\\Windows"
1028 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) OpenFileMode

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_OpenFile(HWND); function ExFn_OpenFile(hMSI) STRING svLine; NUMBER nvFileHandle; LIST listID; begin // Set the file mode to normal. OpenFileMode (FILE_MODE_NORMAL); // Open the text file. if (OpenFile (nvFileHandle, EXAMPLE_DIR, EXAMPLE_FILE) < 0) then MessageBox ("OpenFile failed.", SEVERE); abort; endif; // Create an empty string list. listID = ListCreate (STRINGLIST); // Read lines from the text file into the string list. while GetLine (nvFileHandle, svLine) = 0 ListAddString (listID, svLine, AFTER); endwhile; // Close the file. if (CloseFile (nvFileHandle) < 0) then MessageBox ("CloseFile failed.", SEVERE); endif; // Display the text that was read from the file. SdShowInfoList ("", "", listID); end;

OpenFileMode
The OpenFileMode function sets the mode of the file you want to open or create. The argument you pass as the parameter nMode sets the file mode to one of the following:

ANSI or Unicode text file in append mode. ANSI or Unicode text file in read-only mode. Binary file in read/write mode. Binary file in read-only mode.

After you set the file mode, call OpenFile to open an existing file or CreateFile to create and open a new file.

Syntax
OpenFileMode ( nMode );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1029

Appendix C: Built-In Functions (H-P) OpenFileMode

Parameters
Table C-3: OpenFileMode Parameters Parameter nMode Description Specifies which mode to use to open a file. Pass one of the following predefined constants in this parameter:

FILE_MODE_APPENDThis constant allows a text file to be opened or created in append mode. When a file is opened in append mode using OpenFile, the file pointer is at the end of the file. You can use the WriteLine function to append lines to the end of the file. Files created using CreateFile are new (empty), so lines appended to the files are written at the beginning of the files. Note that if you open a file in append mode, the GetLine function will fail if you call it because the file pointer is at the end of the file. FILE_MODE_APPEND_UNICODEIndicates that CreateFile should create new files as Unicode files, instead of the default of ANSI. This option does not affect how existing files are opened. Existing files are always opened and saved in the existing format. To convert a file from one type to another, use the ListReadFromFile and ListWriteToFile with the appropriate nOptions. FILE_MODE_NORMALThis constant allows a text file to be opened in read-only mode. When a file is opened in read-only mode using OpenFile, the file pointer is at the beginning of the file. You can use the GetLine function to read from the file. Files created using CreateFile when FILE_MODE_NORMAL is in effect will actually be created in FILE_MODE_APPEND mode. FILE_MODE_BINARYThis constant allows a binary file to be opened and created in read/write mode. When you open or create a file in binary mode with OpenFile or CreateFile, you can call ReadBytes to read from the file and WriteBytes to write to the file. Writing to a binary file begins at the current file pointer position, which for a newly opened or created file is position 0the beginning of the file. If you want to append to an existing binary file opened using OpenFile, you must use SeekBytes to position the file pointer before writing. To open a file on a CD-ROM or on a read-only drive, call OpenFileMode to set the file mode to read-only (FILE_MODE_BINARYREADONLY). FILE_MODE_BINARYREADONLYThis constant is just like the constant FILE_MODE_BINARY, except that it opens the binary file in read-only mode. When opening a binary file on CD-ROM or read-only drives, use this constant to open a binary file. FILE_MODE_BINARY will fail opening binary files on CD-ROM or read-only drives.

Return Values
Table C-4: OpenFileMode Return Values Return Value 0 <0 Description Indicates that the function successfully set the file mode. Indicates that the function was unable to set the file mode.

OpenFileMode Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point

1030

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) OpenFileMode

function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the OpenFileMode function. * * This script opens a text file in read-only (FILE_MODE_NORMAL) * mode. It then retrieves and displays the first line from * the file. * * Next, it opens a file in binary mode, positions the file * pointer at the 15th byte and reads 28 bytes from the file. * * Note: In order for this script to run correctly, you must set * the preprocessor constants so that they reference * existing files in an existing directory. * \*--------------------------------------------------------------*/ #define EXAMPLE_DIR "C:\\" #define EXAMPLE_TEXT_FILE "ISExampl.txt" #define EXAMPLE_BIN_FILE "ISExampl.bin" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_OpenFileMode(HWND); function ExFn_OpenFileMode(hMSI) STRING svLine, svString; NUMBER nvFileHandle; begin // Set the file mode to normal. OpenFileMode (FILE_MODE_NORMAL); // Open the file. if (OpenFile (nvFileHandle, EXAMPLE_DIR, EXAMPLE_TEXT_FILE) < 0) then MessageBox ("OpenFile failed.", SEVERE); abort; endif; // Get the first line of the text file. GetLine (nvFileHandle, svLine); // Display the line. MessageBox (svLine, INFORMATION); // Close the file. CloseFile (nvFileHandle); // Set the file mode to binary read/write. OpenFileMode (FILE_MODE_BINARY); // Open the file. if (OpenFile (nvFileHandle, EXAMPLE_DIR, EXAMPLE_BIN_FILE) < 0) then MessageBox ("OpenFile failed.", SEVERE); else // Move the file pointer to byte 15.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1031

Appendix C: Built-In Functions (H-P) ParsePath

SeekBytes (nvFileHandle, 15, FILE_BIN_START); // Read 28 bytes from the binary file into svString. if (ReadBytes (nvFileHandle, svString, 0, 28) < 0) then MessageBox ("ReadBytes failed.", SEVERE); else // Display the string. MessageBox (svString, INFORMATION); endif; // Close the binary file. CloseFile (nvFileHandle); endif; end;

ParsePath
The ParsePath function retrieves the specified part of an existing path. The function works with any valid path, including short paths, long paths, and UNC paths that may or may not include a specific file name. These are some sample paths that can be parsed with this function.

\Path1\Path2\Filename.exe FileName Filename.exe \Path1\Path2\Filename D: D:\ \\Server Name\Share Name\Share Directory Any other legal DOS path

Syntax
ParsePath ( svReturnString, szPath, nOperation );

1032

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ParsePath

Parameters
Table C-5: ParsePath Parameters Parameter svReturnString szPath Description Returns the part of the path in szPath that is specified by nOperation. Specifies the path to parse. When specifying a path that does not include a file name, you must append a backslash to the end of the path before passing it to ParsePath; otherwise the last part of the path will be interpreted as a file name. Specifies which element of the path to return. Pass one of the following predefined constants in this parameter:

nOperation

DIRECTORYIndicates that the path minus the disk drive letter and file name should be returned in svReturnString. When this option is used with a UNC path, ParsePath returns the path without the server and shared device name, and without the file name if one was specified. For example, the UNC path \\TheServer\TheSharedDevice\TheApp\TheFile.exe is returned in svReturnString as \TheApp\. DISKIndicates that the disk drive designation (drive letter followed by a colon) should be returned in svReturnString. When this option is used with a UNC path, ParsePath returns the server and shared device name. For example, the UNC path \\TheServer\TheSharedDevice\TheApp\TheFile.exe is returned in svReturnString as \\TheServer\TheSharedDevice. EXTENSION_ONLYIndicates that the file extension should be returned in svReturnString. It does not include the period. FILENAMEIndicates that the complete file name (that is, with its file extension) should be returned in svReturnString. FILENAME_ONLYIndicates that the file name only (that is, without its file extension) should be returned in svReturnString. PATHIndicates that the path minus the file name should be returned in svReturnString. This option differs from DIRECTORY in that the drive designation (if specified in szPath) is included in the returned path. When szPath specifies a UNC path the server and shared device name are included in the returned path. For example, the UNC path \\TheServer\TheSharedDevice\TheApp\TheFile.exe is returned in svReturnString as \\TheServer\TheSharedDevice\TheApp\.

Return Values
Table C-6: ParsePath Return Values Return Value 0 <0 Description Indicates that the function successfully parsed the path string. Indicates that the function was unable to parse the path string.

ParsePath Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1033

Appendix C: Built-In Functions (H-P) ParsePath

function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ParsePath function. * * The ParsePath is called six times to retrieve various * information from a fully-qualified file name. * \*--------------------------------------------------------------*/ #define EXAMPLE_PATH "C:\\Windows\\Readme.txt" #define TITLE_TEXT "ParsePath example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ParsePath(HWND); function ExFn_ParsePath(hMSI) STRING szMsg, svReturnString; begin // Get the disk letter from the path. if (ParsePath (svReturnString, EXAMPLE_PATH, DISK) < 0) then MessageBox ("ParsePath failed", SEVERE); else szMsg = "nOperation = DISK\n\nParsed Path: %s"; SprintfBox (INFORMATION, TITLE_TEXT , szMsg, svReturnString); endif; // Get the full path. szMsg = "nOperation = PATH\n\nParsed Path: %s"; if (ParsePath (svReturnString, EXAMPLE_PATH, PATH) < 0) then MessageBox ("ParsePath failed", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svReturnString); endif; // Get the directory name. if (ParsePath (svReturnString, EXAMPLE_PATH, DIRECTORY) < 0) then MessageBox ("ParsePath failed", SEVERE); else szMsg = "nOperation = DIRECTORY\n\nParsed Path: %s"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svReturnString); endif; // Get the file name and extension. if (ParsePath (svReturnString, EXAMPLE_PATH, FILENAME) < 0) then MessageBox ("ParsePath failed", SEVERE); else szMsg = "nOperation = FILENAME\n\nParsed Path: %s"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svReturnString); endif; // Get file name without extension. if (ParsePath (svReturnString, EXAMPLE_PATH, FILENAME_ONLY) < 0) then MessageBox ("ParsePath failed", SEVERE);
1034 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) ParseUrl

else szMsg = "nOperation = FILE_NAME_ONLY\n\nParsed Path: %s"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svReturnString); endif; // Get the file extension. if (ParsePath (svReturnString, EXAMPLE_PATH, EXTENSION_ONLY) < 0) then MessageBox ("ParsePath failed", SEVERE); else szMsg = "nOperation = EXTENSION_ONLY\n\nParsed Path: %s"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svReturnString); endif; end;

ParseUrl
The ParseUrl function retrieves the parts of the specified URL. The function works with any valid URL.

Syntax
ParseUrl ( szUrl, pISUrlComponents );

Parameters
Table C-7: ParseUrl Parameters Parameter szUrl pISUrlComponents Description Specifies the URL to parse. Returns a pointer to an ISURL_COMPONENTS data structure that contains the parts of the specified URL.

Return Values
Table C-8: ParseUrl Return Values Return Value 0 <0 Description Indicates that the function successfully parsed the path string. Indicates that the function was unable to parse the path string.

ParseUrl Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ParseUrl function. * \*--------------------------------------------------------------*/

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1035

Appendix C: Built-In Functions (H-P) PathAdd

function OnBegin() ISURL_COMPONENTS ISUrlComponents; STRING szUrl; begin szUrl = "http://myusername:mypassword@www.mydomain.com:8080/" + "myfolder/mypage.asp?mykey=myvalue"; ParseUrl ( szUrl, &ISUrlComponents ); SprintfBox ( INFORMATION , "ParseUrl" , "scheme = %s\nscheme number = %ld\nusername = %s\npassword = %s" + "\nhostname = %s\nport = %ld\nurlpath = %s\nextrainfo = %s", ISUrlComponents.szScheme, ISUrlComponents.nInternetScheme, /* nInternetScheme equals 3 for HTTP and 4 for HTTPS. */ ISUrlComponents.szUserName, ISUrlComponents.szPassword, ISUrlComponents.szHostName, ISUrlComponents.nInternetPort, ISUrlComponents.szUrlPath, ISUrlComponents.szExtraInfo ); abort; end;

That script produces the following output:

Figure C-1: ParseUrl Output

PathAdd
The PathAdd function adds a path to the search path in the path buffer. With this function you can specify the position of the directory in relation to an existing directory in the path buffer. In addition, you can add the directory as the first or the last directory of the path buffer. This function has no relationship to the path statement in the Autoexec.bat file or the path environment variable. It acts only on the path buffer, which helps you build, modify, and manipulate search paths. You can then add the modified path string to the Autoexec.bat file using the various batch file functions.

Syntax
PathAdd ( szDir, szRefDir, bRefDir, bPosition );

1036

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PathAdd

Parameters
Table C-9: PathAdd Parameters Parameter szDir Description Specifies a path to add to the path buffer.

Note: If you specify a directory in szDir that currently exists in the path buffer, InstallShield does not duplicate it, and the position of the pre-existing directory is not modified. InstallShield ignores a backslash at the end of the directory name. szRefDir bRefDir Specifies the path in the current path buffer relative to which the new path will be added. Specifies whether or not szRefDir is a fully qualified path. Pass one of the following predefined constants in this parameter:

bPosition

FULLszRefDir is a fully qualified pathit includes a drive designation and the complete path. PARTIALszRefDir is the directory name onlywithout drive or path information.

Specifies the position relative to szRefDir at which szDir is to be inserted. Pass one of the following predefined constants in this parameter:

AFTERSpecifies that szDir is to be inserted after szRefDir. If szRefDir specifies a null string (), szDir is inserted at the end of the path in the path buffer. BEFORESpecifies that szDir is to be inserted before szRefDir. If szRefDir specifies a null string (), szDir is inserted at the front of the path in the path buffer.

Return Values
Table C-10: PathAdd Return Values Return Value 0 <0 Description Indicates that the function successfully added a directory to the path buffer. Indicates that the function was unable to add a directory to the path buffer.

PathAdd Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the PathAdd function. * * This example script shows how to add paths to a search path
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1037

Appendix C: Built-In Functions (H-P) PathAdd

* in the path buffer. It begins by initializing the path buffer * with a search path. Then, it adds a new path to the front of * the search path. Next, it gets the modified search path from * the search buffer and displays it. * * It then initializes the path buffer with the modified search * path and adds a new path before the last path in the path * buffer. Finally, it gets the modified search path from the * search buffer and displays it. * * Note: PathGet is called after the first PathAdd statement * only so the value of the path buffer can be displayed * for demonstration purposes. In a production script, * you would finish building the search path in the buffer * before calling PathGet. * \*--------------------------------------------------------------*/ #define TITLE "Path buffer example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_PathAdd(HWND); function ExFn_PathAdd(hMSI) STRING svSearchPath; begin // Set up the search path to pass as a parameter to PathSet. svSearchPath = "C:\\DOS;C:\\Windows;C:\\Temp"; // Initialize the path buffer. PathSet (svSearchPath); // Display the initial search path. SprintfBox (INFORMATION,TITLE, "The starting search path is %s.",svSearchPath); // Add C:\MSOffice as the first path in the search path. if (PathAdd("C:\\MSOffice", "", FULL, BEFORE) < 0) then MessageBox ("Unable to add C:\\MsOffice to path buffer.", SEVERE); abort; endif; // Get the search path from the path buffer; this call also releases // the memory allocated for the path buffer. PathGet (svSearchPath); // Display the search path. // svSearchPath will contain C:\MSOffice;C:\DOS;C:\Windows;C:\Temp. SprintfBox (INFORMATION,TITLE, "C:\\MSOffice added before first path.\n\nThe search path is %s.", svSearchPath); // Initialize path buffer to hold the search path. PathSet (svSearchPath); // Add C:\APP2 before C:\Temp in the path buffer. if (PathAdd ("C:\\APP2", "Temp", PARTIAL, BEFORE) < 0) then MessageBox ("Unable to add C:\\APP2 to path buffer.", SEVERE); abort;
1038 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PathDelete

endif; // Get the search path from the path buffer; this call also releases // the memory allocated for the path buffer. PathGet (svSearchPath); // Display the modified search path. // svSearchPath will contain C:\MSOffice;C:\DOS;C:\Windows;C:\App2;C:\Temp. SprintfBox (INFORMATION,TITLE, "C:\\APP2 added before C:\\Temp.\n\nThe search path is %s.", svSearchPath); end;

PathDelete
The PathDelete function deletes a specific directory in the path buffer. You can specify the name of the directory or enter a fully qualified path. This function has no relationship to the path statement in the Autoexec.bat file or the path environment variable. It acts only on the path buffer, which helps you build, modify, and manipulate search paths.

Tip: Call PathGet to get the contents of the path buffer. Call PathSet to set contents of the path buffer.

Syntax
PathDelete ( szDir, bDir );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1039

Appendix C: Built-In Functions (H-P) PathDelete

Parameters
Table C-11: PathDelete Parameters Parameter szDir bDir Description Specifies the path to remove from the path buffer. Specifies whether or not szRefDir is a fully qualified path. Pass one of the following predefined constants in this parameter:

FULLszRefDir is a fully qualified pathit includes a drive designation and the complete path. PARTIALszRefDir is the directory name onlywithout drive or path information.

Return Values
Table C-12: PathDelete Return Values Return Value 0 <0 Description Indicates that the function successfully deleted a directory from the path buffer. Indicates that the function was unable to delete a directory from the path buffer.

PathDelete Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the PathDelete function. * * This example script shows how to delete paths from the path * buffer. It begins by initializing the path buffer with a * search path. Then, it deletes any path that includes a * reference to "Temp". Next, it gets the modified search path * from the search buffer and displays it. * * It then initializes the path buffer with the modfied search * path and deletes a specific path. Finally, it gets the * search path from the search buffer and displays it. * * Note: PathGet is called after the first PathDelete statement * only so the value of the path buffer can be displayed * for demonstration purposes. In a production script, * you would finish building the search path in the buffer * before calling PathGet. * \*--------------------------------------------------------------*/

1040

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PathDelete

#define TITLE "Path buffer example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_PathDelete(HWND); function ExFn_PathDelete(hMSI) STRING svSearchPath; begin // Set up the search path to pass as a parameter to PathSet. svSearchPath = "C:\\DOS;C:\\WINDOWS;C:\\TEMP;" + "C:\\EXAMPLE\\SOURCE;D:\\WORK\\TEMP"; // Initialize the path buffer. PathSet (svSearchPath); // Display the initial search path. SprintfBox (INFORMATION,TITLE, "The starting search path is %s.",svSearchPath); // Delete C:\Temp from the path buffer. if (PathDelete ("TEMP", PARTIAL) < 0) then MessageBox ("First call to PathDelete failed.", SEVERE); endif; // Get the search path from the path buffer; this call also releases // the memory allocated for the path buffer. PathGet (svSearchPath); // Display the search path. // svSearchPath will contain C:\DOS;C:\WINDOWS;C:\EXAMPLE\SOURCE. SprintfBox (INFORMATION, TITLE, "All paths referencing 'Temp' were deleted.\n\nThe search path is %s.", svSearchPath); // Set up the path buffer again. PathSet (svSearchPath); // Delete C:\\EXAMPLE\\SOURCE from the path buffer. if (PathDelete ("C:\\EXAMPLE\\SOURCE", FULL) < 0) then MessageBox ("Second call to PathDelete failed.",SEVERE); endif; // Get the search path from the path buffer; this call also releases // the memory allocated for the path buffer. PathGet (svSearchPath); // Display the search path. // svSearchPath will contain C:\DOS;C:\WINDOWS. SprintfBox (INFORMATION, TITLE, "C:\\EXAMPLE\\SOURCE was deleted.\n\nPath is %s.", svSearchPath); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1041

Appendix C: Built-In Functions (H-P) PathFind

PathFind
The PathFind function searches the path buffer for a specific directory. You can specify the directory with either a fully qualified path or the directory name only. This function has no relationship to the path statement in the Autoexec.bat file or the path environment variable. It acts only on the path buffer, which helps you build, modify, and manipulate search paths. You can then add this temporary path string to the Autoexec.bat file using the various batch file functions.

Syntax
PathFind ( szDir, svResult, bDir, bSearch );

1042

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PathFind

Parameters
Table C-13: PathFind Parameters Parameter szDir svResult bDir Description Specifies the path to find in the path buffer. Returns the full directory and path found in the path buffer returned by the function. Specifies whether or not szDir contains a fully qualified or an unqualified directory name. Pass one of the following predefined constants in this parameter:

bSearch

FULLszRefDir is a fully qualified pathit includes a drive designation and the complete path to a directory. PARTIALszRefDir is the directory name only, without drive or path information.

Specifies where to begin the search. Pass one of the following predefined constants in this parameter:

CONTINUEContinues searching the path buffer at the location where the previous search was terminated. RESTARTStarts the search from the beginning of the path buffer.

Return Values
Table C-14: PathFind Return Values Return Value 0 <0 Description Indicates that the function successfully searched the path buffer for a directory. Indicates that the function was unable to successfully search the path buffer for a directory.

PathFind Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the PathSet, PathFind, and PathGet functions. * * First, PathSet is called to place a search path into the path * buffer. Then PathFind is then called to search the path * buffer for instances of a specific path. Finally, PathGet * is called to return the contents of the path buffer. * \*--------------------------------------------------------------*/

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1043

Appendix C: Built-In Functions (H-P) PathFind

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_PathFind(HWND); function ExFn_PathFind(hMSI) STRING szString, szMsg, svResult, svString, szDir; NUMBER nResult; BOOL bDir, bSearch; begin // Set up the search path to pass as a parameter to PathSet. szString = "C:\\DOS;C:\\USERS\\BIN;C:\\MSC\\BIN;"; // Place the search path into the path buffer if (PathSet (szString) < 0) then // Report an error; then terminate. MessageBox ("PathSet failed.", SEVERE); abort; else szMsg = "PathSet set the path buffer to: %s"; SprintfBox (INFORMATION, "PathSet Example", szMsg, szString); endif; // Set PathFind variables. szDir = "BIN"; // Search the path buffer for paths that include a folder named "BIN". nResult = PathFind(szDir, svResult, PARTIAL, RESTART); // Error check PathFind. if (nResult < 0) then MessageBox("PathFind failed.", SEVERE); abort; endif; // Loop through the string to find all occurrences of the szDir string. while (nResult = 0) SprintfBox(INFORMATION, "PathFind example", "Search for %s.\n\nFound: %s", szDir, svResult); nResult = PathFind(szDir, svResult, PARTIAL, CONTINUE); endwhile; // Get the contents of the path buffer. if (PathGet (svString) < 0) then MessageBox ("PathGet failed.", SEVERE); else // Display the path string. SprintfBox (INFORMATION, "Path Get Example", "Path is: %s", svString); endif; end;

1044

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PathGet

PathGet
The PathGet function retrieves the search path currently stored in the path buffer, which is a temporary storage area created by a call to PathSet. The path buffer enables you to build and edit a search path. When the path you are editing is complete, call PathGet to place the search path into a string variable so that you can pass it to other functions in your setup. This function has no relationship to the path statement in the Autoexec.bat file or the path environment variable. It acts on the path buffer only, which helps you build, modify, and manipulate search paths. You can then add this temporary path string to the Autoexec.bat file using the appropriate batch file functions.

Tip: PathGet retrieves the search path from the path buffer and releases the memory allocated to the path buffer. A subsequent call to PathGet will fail unless the path buffer is reinitialized by a call to PathSet.

Syntax
PathGet ( svString );

Parameters
Table C-15: PathGet Parameters Parameter svString Description Returns the contents of the path buffer.

Return Values
Table C-16: PathGet Return Values Return Value 0 Description Indicates that the function successfully retrieved the path currently stored in the path buffer. Indicates that the function was unable to retrieve the path string currently stored in the temporary path string buffer.

<0

PathGet Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the PathSet, PathFind, and PathGet functions.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1045

Appendix C: Built-In Functions (H-P) PathGet

* * First, PathSet is called to place a search path into the path * buffer. Then PathFind is then called to search the path * buffer for instances of a specific path. Finally, PathGet * is called to return the contents of the path buffer. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_PathGet(HWND); function ExFn_PathGet(hMSI) STRING szString, szMsg, svResult, svString, szDir; NUMBER nResult; BOOL bDir, bSearch; begin // Set up the search path to pass as a parameter to PathSet. szString = "C:\\DOS;C:\\USERS\\BIN;C:\\MSC\\BIN;"; // Place the search path into the path buffer if (PathSet (szString) < 0) then // Report an error; then terminate. MessageBox ("PathSet failed.", SEVERE); abort; else szMsg = "PathSet set the path buffer to: %s"; SprintfBox (INFORMATION, "PathSet Example", szMsg, szString); endif; // Set PathFind variables. szDir = "BIN"; // Search the path buffer for paths that include a folder named "BIN". nResult = PathFind(szDir, svResult, PARTIAL, RESTART); // Error check PathFind. if (nResult < 0) then MessageBox("PathFind failed.", SEVERE); abort; endif; // Loop through the string to find all occurrences of the szDir string. while (nResult = 0) SprintfBox(INFORMATION, "PathFind example", "Search for %s.\n\nFound: %s", szDir, svResult); nResult = PathFind(szDir, svResult, PARTIAL, CONTINUE); endwhile; // Get the contents of the path buffer. if (PathGet (svString) < 0) then MessageBox ("PathGet failed.", SEVERE); else // Display the path string. SprintfBox (INFORMATION, "Path Get Example" ,"Path is: %s", svString); endif; end;

1046

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PathMove

PathMove
The PathMove function repositions a directory in the path buffer to another location. You can also use this function to position the directory relative to another directory or as the first or the last item in the path string. This function has no relation to the PATH statement in the Autoexec.bat file or the PATH environment variable. It acts only on the path buffer, which helps you build, modify, and manipulate search paths. You can then add this temporary path string to Autoexec.bat using the various batch file functions.

Tip: Call PathGet to get the contents of the path buffer. Call PathSet to set contents of the path buffer.

Syntax
PathMove ( szDir, szRefDir, bDir, bRefDir, bPosition );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1047

Appendix C: Built-In Functions (H-P) PathMove

Parameters
Table C-17: PathMove Parameters Parameter szDir szRefDir Description Specifies a full or partial path to reposition in the path buffer. Specifies the path in the path buffer relative to which the path in szDir will be moved. To move the path in szDir to the beginning or end of the path in the path buffer, pass a null string () in this parameter. Specifies whether szDir contains a fully qualified or an unqualified directory name. Pass one of the following predefined constants in this parameter:

bDir

bRefDir

FULLSpecifies that szDir contains a fully qualified directory name. PARTIALSpecifies that szDir contains the directory name only.

Specifies whether szRefDir contains a fully qualified or an unqualified directory name. Pass one of the following predefined constants in this parameter:

bPosition

FULLSpecifies that szRefDir contains a fully qualified directory name. PARTIALSpecifies that szRefDir contains the directory name only.

Specifies the position relative to szRefDir to which szDir is to be moved. Pass one of the following predefined constants in this parameter:

AFTERSpecifies that szDir is to be positioned after szRefDir. If szRefDir specifies a null string (), szDir is positioned at the end of the path in the path buffer. BEFORESpecifies that szDir is to be positioned before szRefDir. If szRefDir specifies a null string (), szDir is positioned at the front of the path in the path buffer.

Return Values
Table C-18: PathMove Return Values Return Value 0 <0 Description Indicates that the function successfully repositioned a directory in the path buffer. Indicates that the function was unable to reposition a directory in the path buffer.

PathMove Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script *
1048 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PathMove

* Demonstrates the PathMove functions. * * This example script shows how to reposition paths in the path * buffer. It begins by initializing the path buffer with a * search path. Then, it moves one path ahead of another. * Next, it gets the modfied search path from the search buffer * and displays it. * * It then initializes the path buffer with the modified search * path and moves one path after another path. Finally, it gets * the modfied search path from the search buffer and displays * it. * * Note: PathGet is called after the first PathMove statement * only so the value of the path buffer can be displayed * for demonstration purposes. In a production script, * you would finish building the search path in the buffer * before calling PathGet. * \*--------------------------------------------------------------*/ #define TITLE "Path buffer example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_PathMove(HWND); function ExFn_PathMove(hMSI) STRING svSearchPath; begin // Set up the search path to pass as a parameter to PathSet. svSearchPath = "C:\\MsOffice;C:\\DOS;C:\\Windows;C:\\App2;C:\\Temp"; // Initialize the path buffer. PathSet (svSearchPath); // Display the initial search path. SprintfBox (INFORMATION, TITLE, "The starting search path is %s.",svSearchPath); // Move C:\App2 before C:\DOS. if (PathMove("C:\\App2", "C:\\DOS", FULL, FULL, BEFORE) < 0) then MessageBox ("Unable to move C:\\App2.", SEVERE); abort; endif; // Get the search path from the path buffer and release // the memory allocated for the path buffer. PathGet (svSearchPath); // Display the search path. // svSearchPath will contain C:\MSOFFICE;C:\APP2;C:\DOS;C:\WINDOWS;C:\TEMP SprintfBox (INFORMATION, TITLE, "C:\\App2 moved before C:\\DOS.\n\nThe search path is %s.", svSearchPath); // Initialize the path buffer with the search path. PathSet (svSearchPath); // Move C:\DOS after C:\Temp.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1049

Appendix C: Built-In Functions (H-P) PathSet

if (PathMove ("C:\\DOS", "TEMP", FULL, PARTIAL, AFTER) < 0) then MessageBox ("Unable to move C:\\DOS.", SEVERE); endif; // Get the search path from the path buffer and release // the memory allocated for the path buffer. PathGet (svSearchPath); // Display the search path. // svSearchPath will contain C:\MSOFFICE;C:\APP2;C:\WINDOWS;C:\TEMP;C:\DOS SprintfBox (INFORMATION, TITLE, "C:\\DOS moved after C:\\Temp.\n\nThe search path is %s.", svSearchPath); end;

PathSet
The PathSet function stores a search path string in the path buffer. You can then manipulate this buffer using the other path functions. The value of szString should be an absolute path (a path that includes a drive specification, for example, "C:\\Program Files\\AppName"). This function has no relation to the PATH statement in the Autoexec.bat file or the PATH environment variable. It acts only on the path buffer, which helps you build, modify, and manipulate search paths. You can then add this temporary path string to the Autoexec.bat file or PATH environment variable.

Syntax
PathSet ( szString );

1050

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PathSet

Parameters
Table C-19: PathSet Parameters Parameter szString Description Specifies a search path to store in the path buffer. The search path should be fully qualified; that is it should include a drive designation and the complete path to a directory.

Return Values
Table C-20: PathSet Return Values Return Value 0 <0 Description Indicates that the function successfully stored a search path string in the path buffer. Indicates that the function was unable to store a search path string in the path buffer.

PathSet Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the PathSet, PathFind, and PathGet functions. * * First, PathSet is called to place a search path into the path * buffer. Then PathFind is then called to search the path * buffer for instances of a specific path. Finally, PathGet * is called to return the contents of the path buffer. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_PathSet(HWND); function ExFn_PathSet(hMSI) STRING szString, szMsg, svResult, svString, szDir; NUMBER nResult; BOOL bDir, bSearch; begin // Set up the search path to pass as a parameter to PathSet. szString = "C:\\DOS;C:\\USERS\\BIN;C:\\MSC\\BIN;"; // Place the search path into the path buffer if (PathSet (szString) < 0) then // Report an error; then terminate.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1051

Appendix C: Built-In Functions (H-P) PlaceBitmap

MessageBox ("PathSet failed.", SEVERE); abort; else szMsg = "PathSet set the path buffer to: %s"; SprintfBox (INFORMATION, "PathSet Example", szMsg, szString); endif; // Set PathFind variables. szDir = "BIN"; // Search the path buffer for paths that include a folder named "BIN". nResult = PathFind(szDir, svResult, PARTIAL, RESTART); // Error check PathFind. if (nResult < 0) then MessageBox("PathFind failed.", SEVERE); abort; endif; // Loop through the string to find all occurrences of the szDir string. while (nResult = 0) SprintfBox(INFORMATION, "PathFind example", "Search for %s.\n\nFound: %s", szDir, svResult); nResult = PathFind(szDir, svResult, PARTIAL, CONTINUE); endwhile; // Get the contents of the path buffer. if (PathGet (svString) < 0) then MessageBox ("PathGet failed.", SEVERE); else // Display the path string. SprintfBox (INFORMATION, "Path Get Example" ,"Path is: %s", svString); endif; end;

PlaceBitmap
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The PlaceBitmap function inserts an image into the installation window. The image source is specified by szName; it can be a bitmap file (.bmp), metafile (.wmf file), or dynamic link library (.dll).

Syntax
PlaceBitmap ( szName, nID_BITMAP, nDx, nDy, nDrawOp );

1052

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PlaceBitmap

Parameters
Table C-21: PlaceBitmap Parameters Parameter szName Description Specifies the fully qualified name of the bitmap file (.bmp), metafile (.wmf file), or dynamic link library (.dll) of the image to be displayed. InstallShield recognizes bitmap files and metafiles by their file extension. Bitmap files must have the extension .bmp. Metafiles must have the extension .wmf. Dynamic link libraries must have the extension .dll. If a file name is specified with no extension, InstallShield assumes the extension .dll. To specify an alternate transparent color, place a semicolon after the file name and follow it with a set of RGB color values. (RGB color is specified with three numeric values, separated by commas.) That color is then used as the transparent color for the bitmap specified by szName. Note that it does not affect bitmaps that are already displayed; nor does it become the default transparent color for bitmaps displayed by subsequent calls to PlaceBitmap. The parameter below specifies white as the transparent color:
SUPPORTDIR ^ "Bitmap.bmp;255,255,255" When nDrawOptions is set to REMOVE, this parameter is ignored.

nID_BITMAP

Specifies the bitmap's resource ID if the bitmap resides in a .dll. If the bitmap source is a metafile or bitmap file, specifies a value that is not in use for an image currently on display; images that are displayed simultaneously must have unique ID numbers. When nDrawOptions is set to REMOVE, this parameter must contain the ID of a displayed image. Pass either a number or the CENTERED constant in this parameter:

nDx

Pass a number to specify the horizontal distance in pixels between the edge of installation window and the edge of the image when nDrawOp is set to LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, or UPPER_RIGHT. Pass the CENTERED constant to center the image on the horizontal axis when nDrawOp is set to LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, or UPPER_RIGHT. The image will be offset from the upper or lower edge of the installation window by the number of pixels specified in nDy. Since the CENTERED constant when passed in nDx centers the image horizontally, the argument in nDrawOp will affect only the vertical placement of the image.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1053

Appendix C: Built-In Functions (H-P) PlaceBitmap

Table C-21: PlaceBitmap Parameters (cont.) Parameter nDy Description Pass either a number or the CENTERED constant in this parameter:

Pass a number to specify the vertical distance in pixels between the edge of installation window and the edge of the image when nDrawOp is set to LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, or UPPER_RIGHT. Pass the CENTERED constant to center the image on the vertical axis when nDrawOp is set to LOWER_LEFT, LOWER_RIGHT, UPPER_LEFT, or UPPER_RIGHT. The image will be offset from the right or left edge of the installation window by the number of pixels specified in nDx. Since the CENTERED constant when passed in nDy centers the image vertically, the argument in nDrawOp will affect only the horizontal placement of the image.

Note: You can pass the CENTERED constant in both the nDx and nDy parameters to center the image in the installation window. This is equivalent to passing the CENTERED constant in the nDrawOp parameter. nDrawOp Specifies the bitmap's placement location, sets placement options, or removes a previously placed bitmap. Pass one of the following predefined constants in this parameter:

BITMAPICONIndicates that the bitmap has transparent parts. You can use the bitwise OR operator ( | ) to combine this constant with any of the other constants except TILED, FULLSCREEN or FULLSCREENSIZE. When BITMAPICON is ORed with one of those constants, the bitwise operation is ignored and BITMAPICON is used. BITMAPICON has no effect when szName specifies a metafile or a 24-bit bitmap. Note that when you specify BITMAPICON, the bitmap is displayed normally, even if a special effect has been enabled with SetDisplayEffect.

TILEDThe bitmap is tiled across the main installation window. This constant is normally used to create an installation background. When this constant is specified, location options are ignored and the bitmap is displayed normally, even if a special effect has been enabled with SetDisplayEffect. FULLSCREENDraw the image to fill the entire installation window. The image is not resized when its drawn. If a bitmap image is smaller than the InstallShield main window, it is centered in the window and the background is filled with the current background color. The default value is teal; it can be changed using the SetColor function. When this constant is specified, location options are ignored and the bitmap is displayed normally, even if a special effect has been enabled with SetDisplayEffect. FULLSCREENSIZEDraw and stretch the image to fill the entire installation window. When this constant is specified, location options are ignored and the bitmap is displayed normally, even if a special effect has been enabled with SetDisplayEffect.

1054

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PlaceBitmap

Table C-21: PlaceBitmap Parameters (cont.) Parameter nDrawOp (continued) Description

CENTEREDPlaces the bitmap in the center of the installation window. LOWER_LEFTPlaces the bitmap in the lower left corner of the InstallShield installation window. LOWER_RIGHTPlaces the bitmap in the lower right corner of the InstallShield installation window. UPPER_LEFTPlaces the bitmap in the upper left corner of the InstallShield installation window. UPPER_RIGHTPlaces the bitmap in the upper right corner of the InstallShield installation window. REMOVERemoves a previously placed bitmap or metafile. Any special display effects that have been enabled with SetDisplayEffect are ignored.

Return Values
Table C-22: PlaceBitmap Return Values Return Value 0 <0 Description Indicates that the function successfully found and placed the image. Indicates that the function was unable to find or place the image.

Comments
InstallShield supports 2-color, 16-color, 256-color and true color (24-bit) bitmaps. Two-color, 16-color and 256-color bitmaps can have transparent portions. Transparent bitmaps are useful for displaying images that appear to be integrated with the background window. Pixels in the bitmap that match a specified transparent color are not displayed; the background pixel at that location remains visible. In setups, transparent bitmaps that incorporate the company name and its logo in an artful design are often used as titles in the installation window. To specify a transparent bitmap, you must pass the constant BITMAPICON in the parameter nDrawOp. You must also consider which color in the bitmap is to be transparent. The default transparent color is purple (RGB(255,0,255)). To specify a different transparent color, use the parameter szName as described below. Because metafiles are drawn rather than placed, they are intrinsically transparent. If BITMAPICON is specified for a metafile, that parameter is ignored.

Note: Many special display effects are available for non-transparent bitmaps by using the SetDisplayEffect function. That function also provides limited display effects for metafiles.

The location of the bitmap within the window can be specified in one of two ways:

By passing one of the location constants in the parameter nDrawOp. By passing a vertical and horizontal offset from the edge of the installation window in nDx and nDy.
ISP-1800-RG00 1055

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PlaceBitmap

By passing the CENTERED constant in either nDx or nDy in combination with a horizontal or vertical offset.

Always remove any bitmaps or metafiles that are no longer needed by calling PlaceBitmap with the constant REMOVE as the parameter nDrawOp. Removing an unneeded bitmap is recommended even if another bitmap covers that bitmap completely because the palette entries for the first bitmap will not be released until the bitmap is removed.

Tip: A true color bitmap that is displayed on a system running in 16-color or 256-color mode will use only those colors available in the color palette; no additional colors will be allocated for the bitmap, even when additional color palette entries are available. If you anticipate that a setup with 24-bit bitmaps will be run on 16- or 256-color systems, include 16or 256-color versions of the bitmaps. Then call GetSystemInfo with the COLORS parameter to determine the current color mode before selecting the bitmap to display.

Call SetDisplayEffect to set special effects for non-tiled, full-screen, transparent bitmaps; you can also set limited special effects for metafiles. InstallShield does not support 24-bit transparent bitmaps. If you include a transparent color in a 24-bit bitmap and specify the BITMAPICON constant, the color will be displayed normally. When you place a 256-color bitmap on a system running in 256-color mode, InstallShield attempts to allocate the bitmap's color palette into the system color palette. If multiple 256-color bitmaps are placed, InstallShield attempts to merge the color palettes of all visible bitmaps into the system color palette, giving precedence to the most recently placed bitmap. This behavior may cause previously placed bitmaps to change colors when additional bitmaps are displayed. On a system running in 256-color mode with a 256-color dithered background, bitmaps that include many colors may cause some of the color palette entries used for the background to be reallocated; this can cause a gradient effect to appear in the background. Setups with bitmaps that use many colors should not use a 256-color gradient background if they will run on 256-color systems. System color palettes exist only on systems that are running in 256-color mode. Systems running in high color (16-bit) or true color (24-bit) modes and systems running under in 65535 (16-bit) color mode do not have a system color palette. On these systems there are no color palette handling issues to consider; colors are displayed directly using the RGB color value. See Preventing Color Distortion for more information. Because metafiles are rendered, they do not include a custom color palette. When a metafile is displayed on a 256-color system, no color palette handling takes place; the metafile is drawn with the colors currently available in the color palette. For that reason, you should not use metafiles that display colors other than the standard 16 colors in setups that will run on 256-color systems.

PlaceBitmap Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the PlaceBitmap function. * * PlaceBitmap is called to display and remove bitmaps on the * screen. The SetDisplayEffect function sets the display * effect for the bitmap. *
1056 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PlaceWindow

* Note: Before running this script, set the constant BMP_PATH * so that it references an existing bitmap file on the * target system. * \*--------------------------------------------------------------*/ #define #define #define #define BMP_PATH "C:\\Windows\\Bubbles.bmp" BITMAP_ID_1 12 BITMAP_ID_2 13 BITMAP_ID_3 14

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_Placebitmap(HWND); function ExFn_Placebitmap(hMSI) begin Enable ( BACKGROUND ); // Display the bitmap in the upper left corner. PlaceBitmap (BMP_PATH, BITMAP_ID_1, 10, 12, UPPER_LEFT); // Set bitmap reveal effect. SetDisplayEffect (EFF_REVEAL); // Display the bitmap in the lower right corner. PlaceBitmap (BMP_PATH, BITMAP_ID_2, 10, 10, LOWER_RIGHT); Delay(3); // Remove the bitmap in the upper left corner. PlaceBitmap ("", BITMAP_ID_2, 0, 0, REMOVE); // Remove the bitmap in the lower right corner. PlaceBitmap ("", BITMAP_ID_1, 0, 0, REMOVE); // Set bitmap fade in effect. SetDisplayEffect (EFF_FADE); // Display the bitmap at the center of screen. PlaceBitmap (BMP_PATH, BITMAP_ID_3, CENTERED, CENTERED, 0); Delay (3); // Remove the bitmap at the center of the screen. PlaceBitmap ("", BITMAP_ID_3, 0, 0, REMOVE); Delay (1); end;

PlaceWindow
The PlaceWindow function changes the position of user interface objects. This includes billboards, Adobe Flash application files, and AVI files that are displayed at run time through PlayMMedia. Specify the distance between the sides of the object and the edges of the screen in nDx and nDy.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1057

Appendix C: Built-In Functions (H-P) PlaceWindow

When using this function, be aware that an installation runs on a variety of screen resolutions. You may want to determine the extents of the screen before you position the objects. The distance is measured in pixels and is between the edge of the object and the edge of the corner of the specified screen.

Note: The PlaceWindow function does not have any effect on the type of billboard that is displayed on a progress dialog. To learn more about the different types of billboards, see Billboard Styles and File Types for InstallScript and InstallScript MSI Projects.

Restrictions
This function cannot be used to position message boxes or custom dialogs.

Message boxes cannot be positioned with this function because they are created using the native Windows API. A message boxs position is determined by the Windows API and is not under the control of an installation. Custom dialogs cannot be positioned with this function. PlaceWindow does not work in conjunction with the AskOptions, AskPath, AskText, or EnterDisk functions. By default, a dialog appears in the center of the desktop, unless the background window mode is enabled. If the installation is in window mode, the dialog appears in the center of the background window.

Syntax
PlaceWindow ( nObject, nDx, nDy, nCorner );

1058

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PlaceWindow

Parameters
Table C-23: PlaceWindow Parameters Parameter nObject Description Specifies the object whose position is to be changed. Pass one of the following predefined constants in this parameter:

ASKOPTIONSMoves the AskOptions dialog. ASKPATHMoves the AskPath dialog. ASKTEXTMoves the AskText dialog. BACKGROUNDMoves the background window. BILLBOARDSets the location of billboards used during the file transfer process. ENTERDISKMoves the EnterDisk dialog. MMEDIA_AVISets the window position for the next .avi file to be played. By default, the .avi file is played at run time in a window in the left corner of the screen, 10 pixels from the left and 10 pixels from the top. MMEDIA_SWFSets the window position for the Adobe Flash application file (.swf) to be played. STATUSMoves the progress indicator. STATUSDLGMoves the dialog style progress indicator. STATUSEXMoves the Setup Status dialog. STATUSOLDMoves the old style progress indicator.

Tip: When you call PlaceWindow to move the progress indicator or status dialog, be sure to pass the correct constant for the feedback object you have enabled in your setup. For example, if you called Enable (STATUSOLD), you must pass STATUSOLD to PlaceWindow. nDx Specifies the distance in pixels between the appropriate edge of the object and the edge of the screen on the horizontal axis. Specifies the distance in pixels between the appropriate edge of the object and the edge of the screen on the vertical axis.

nDy

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1059

Appendix C: Built-In Functions (H-P) PlaceWindow

Table C-23: PlaceWindow Parameters (cont.) Parameter nCorner Description Specifies from which corner to measure the distances expressed in nDx and nDy. Pass one of the following predefined constants in this parameter:

LOWER_LEFTMeasures nDx from the left and nDy from the bottom of the main InstallShield window. LOWER_RIGHTMeasures the nDx from the right and nDy from the bottom of the main InstallShield window. UPPER_LEFTMeasures the nDx from the left and nDy from the top of the main InstallShield window. UPPER_RIGHTMeasures the nDx from the right and nDy from the top of the main InstallShield window. CENTEREDCenters the user interface object within the window.

Note: CENTERED can also be placed in nDx or nDy to center an object only horizontally or only vertically.

Return Values
Table C-24: PlaceWindow Return Values Return Value 0 <0 Description Indicates that the function successfully changed the position of the object. Indicates that the function was unable to change the position of the object.

Additional Information
Use the PlayMMedia function if you want your installation to play an Adobe Flash application file (.swf) or an AVI file.

PlaceWindow Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the PlaceWindow function. * * PlaceWindow is called to place the background window 50 * pixels to the right and below the upper left-hand corner * of the display.
1060 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PlayMMedia

* \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_PlaceWindow(HWND); function ExFn_PlaceWindow(hMSI) begin Enable ( BACKGROUND ); Enable ( DEFWINDOWMODE ); MessageBox ("This is the default position of the background window.", INFORMATION); // Delay calling PlaceWindow for three seconds. Delay(3); // Change the position of the background window. if (PlaceWindow (BACKGROUND, 50, 50, UPPER_LEFT) < 0) then MessageBox ("PlaceWindow failed.", SEVERE); else MessageBox ("This is the new position of the background window.", INFORMATION); // Delay exiting script for three seconds. Delay(3); endif; end;

PlayMMedia
The PlayMMedia function plays an Adobe Flash application file (.swf), an AVI file, or a sound file (MIDI or WAVE).

Tip: If you are using PlayMMedia to display an Flash file or an AVI file, the installation must display a background window. For more information, see Displaying a Background Window in InstallScript and InstallScript MSI Installations. InstallShield has support for displaying a Flash file as a billboard for your installation without displaying a background window. To learn more, see Billboard Styles and File Types for InstallScript and InstallScript MSI Projects.

Syntax
PlayMMedia (nType, szFileName, nOperation, nReserved);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1061

Appendix C: Built-In Functions (H-P) PlayMMedia

Parameters
Table C-25: PlayMMedia Parameters Parameter nType Description Specify the type of file that you want your installation to play. Pass one of the following predefined constants in this parameter:

szFileName nOperation

MMEDIA_AVIThe file is an AVI file. MMEDIA_MIDIThe file is of MIDI sound format. MMEDIA_SWFThe file is an Adobe Flash application file (.swf). MMEDIA_WAVEThe file is of WAVE sound format.

Specify the fully qualified name of the file to be played. Specify the play mode. Pass any of the following predefined constants in this parameter:

MMEDIA_PLAYSYNCHPlay synchronously. MMEDIA_PLAYASYNCHPlay asynchronously. This constant can be combined with MMEDIA_PLAYCONTINUOUS by using the OR operator (|). MMEDIA_PLAYCONTINUOUSPlay in a continuous loop. This value cannot be used when playing a sound/AVI file in synchronous mode. It can be used only with files being played in asynchronous mode. Combine it with MMEDIA_PLAYASYNCH by using the OR operator (|). MMEDIA_STOPStop playing.

Note: A Flash file plays only once asynchronously, regardless of whether any MMEDIA_PLAY* constants are passed in nOperation. nReserved Pass the number zero in this parameter. No other value is allowed.

Return Values
Table C-26: PlayMMedia Return Values Return Value 0 <0 Description The function successfully played the file. The function was unable to play the file. One example of when this occurs is if you specified a Flash file for PlayMMedia but the Flash Player is not present on the target system.

Additional Information
If you are using a Flash file or an AVI file, you can use SizeWindow and PlaceWindow to control the size and placement of the background window that displays the Flash or AVI file.

1062

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PlayMMedia

PlayMMedia Example
To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the PlayMMedia function. * * This script plays an AVI file during the setup. * * Note: To run this example script, create a project (or * insert into project) with several features and/or * subfeatures with components containing files. Then * add an AVI file to Disk 1 in the Support Files view in * the IDE. Change the file name in #define SOURCE line * below to specify your AVI file. * * Warning: Since this example does not include uninstallation * functionality, use this example only with projects * that do not overwrite important files, install * shared files, or update the registry. * \*--------------------------------------------------------------*/ #define SOURCE #define TITLE1 #define TITLE2 SRCDIR + "windy7(1).avi" "Playing AVI synchronously..." "Playing AVI asynchronously and continuously..."

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_PlayMMedia(HWND); function ExFn_PlayMMedia(hMSI) NUMBER nvDisk; begin Enable ( BACKGROUND ); // First, play the AVI synchronously to demonstrate how this causes // it to play by itself, with no other events taking place. SetTitle (TITLE1, 16, YELLOW); PlaceWindow (MMEDIA_AVI, 10, 10, UPPER_RIGHT); if (PlayMMedia (MMEDIA_AVI, SOURCE, MMEDIA_PLAYSYNCH, 0) < 0) then MessageBox ("Unable to play AVI file.", WARNING); endif; // Now play the AVI asynchronously. // as the file transfer occurs. SetTitle (TITLE2, 16, YELLOW); The AVI continues executing

PlaceWindow (MMEDIA_AVI, 10, 10, LOWER_RIGHT); if (PlayMMedia (MMEDIA_AVI, SOURCE, MMEDIA_PLAYASYNCH | MMEDIA_PLAYCONTINUOUS, 0) < 0) then MessageBox ("Unable to play AVI file.", WARNING);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1063

Appendix C: Built-In Functions (H-P) PostShowComponentDlg

endif; Enable (STATUSDLG); Enable (INDVFILESTATUS); StatusUpdate (ON, 99); // Transfer the files. ComponentMoveData (MEDIA, nvDisk, 0); Disable (INDVFILESTATUS); Disable (STATUSDLG); // The AVI will stop playing when the setup exits. // stop it explicitly like this: PlayMMedia (MMEDIA_AVI, SOURCE, MMEDIA_STOP, 0); end; But you can

PostShowComponentDlg
Caution: This function is not supported in InstallShield because it is no longer required. The functions that required PreShowComponentDlg in InstallShield Professional 2.03 are not supported for use in Basic MSI projects. If you want to use one of these functions in your setup project, you must convert your Basic MSI project to the InstallScript MSI project type and add the function to the script.

The PostShowComponentDlg function converts InstallShield Professional components back to InstallShieldWindows Installer Edition features. You must call PostShowComponentDlg after calling a component dialog or function in your script. This function selects Windows Installer features based upon component selection.

Syntax
PostShowComponentDlg (hMSI);

1064

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix C: Built-In Functions (H-P) PreShowComponentDlg

Parameters
Table C-27: PostShowComponentDlg Parameters Parameter hMSI Description The handle to the Windows Installer (MSI) database that is passed to your entry-point function.

Return Values
Table C-28: PostShowComponentDlg Return Values Return Value 0 Description Indicates that the function successfully converted InstallShield Professional components back to Windows Installer features. Indicates that the function was unable to convert InstallShield Professional components back to Windows Installer features.

<0

PreShowComponentDlg
Caution: This function is not supported in InstallShield because it is no longer required. The functions that required PreShowComponentDlg in InstallShield Professional 2.03 are not supported for use in Basic MSI projects. If you want to use one of these functions in your setup project, you must convert your Basic MSI project to the InstallScript MSI project type and add the function to the script.

The PreShowComponentDlg function converts InstallShieldWindows Installer Edition features to InstallShield Professional components. It also initializes feature costing functionality.

Syntax
PreShowComponentDlg (hMSI);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1065

Appendix C: Built-In Functions (H-P) ProgDefGroupType

Parameters
Table C-29: PreShowComponentDlg Parameters Parameter hMSI Description The handle to the Windows Installer (MSI) database that is passed to your entry-point function.

Return Values
Table C-30: PreShowComponentDlg Parameters Return Value 0 Description Indicates that the function successfully converted Windows Installer features to InstallShield Professional components. Indicates that the function was unable to convert Windows Installer features to InstallShield Professional components.

<0

ProgDefGroupType
The ProgDefGroupType function sets the value of the ALLUSERS system variable. For more details, see ALLUSERS.

Syntax
ProgDefGroupType ( nType );

Parameters
Table C-31: ProgDefGroupType Parameters Parameter nType Description Specifies the value to use for the InstallScript variable ALLUSERS. Pass one of the following predefined constants in this parameter:

PERSONALSet ALLUSERS equal to FALSE. COMMONSet ALLUSERS equal to TRUE.

Return Values
Table C-32: ProgDefGroupType Return Values Return Value 0 Description This function always returns zero.

1066

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

D
Built-In Functions (Q-R)
For a list of functions by category, see Built-In Functions by Category.

QueryProgItem
The QueryProgItem function checks for the existence of a specific program item or subfolder name. If the InstallScript engine finds the item or subfolder, QueryProgItem returns its attributes. The attributes include the products command line, working directory, icon path, shortcut key, and minimize flag. To use QueryProgItem, enter information in the parameters szFolderName and szItemName. The InstallScript engine fills the remaining parameters with the program items attributes.

Syntax
QueryProgItem ( szFolderName, szItemName, svCmdLine, svWrkDir, svIconPath, nvIconIndex, svShortCutKey, nvMinimizeFlag );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1067

Appendix D: Built-In Functions (Q-R) QueryProgItem

Parameters
Table D-1: QueryProgItem Parameters Parameter szFolderName Description Specifies the name of the folder that contains the item or subfolder. You can specify a fully qualified path for szFolderName, such as:
"C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Games"

If szFolderName is null, QueryProgItem searches the default Programs directory. If you do not specify an absolute path (a path that includes a drive specification, for example, "C:\\Program Files\\AppName") for szFolderName, QueryProgItem searches for a subfolder under the default Programs directory; the location depends on the value of the InstallScript variable ALLUSERS, as well as the version of Windows on the target system. You can also use an InstallScript system variable:

FOLDER_DESKTOPQueries items in the Desktop folder. FOLDER_STARTUPQueries items in the Startup menu. FOLDER_STARTMENUQueries items in the Start menu. FOLDER_PROGRAMSQueries items in the Start\Programs menu.

Or you could use a relative path, such as:

FOLDER_PROGRAMS ^ "ACCESSORIES\\GAMES"

szItemName svCmdLine

Specifies the name of the program item or subfolder to find. Returns either the command line of the item's executable file or the complete path to the subfolder. Returns the full path of the working directory of the program item. (Not applicable if szItemName is a subfolder.) Returns the fully qualified file name of the .ico file or .exe file. (Not applicable if szItemName is a subfolder.) Returns the index of the icon used for the program item. (Not applicable if szItemName is a subfolder.) Returns the item's shortcut key. (Not applicable if szItemName is a subfolder.) (Not applicable if szItemName is a subfolder.) Returns one of the following constants, indicating whether an application window is minimized when first displayed:

svWrkDir

svIconPath

nvIconIndex

svShortCutKey nvMinimizeFlag

NULLIndicates that the application's window is not minimized upon startup. RUN_MINIMIZEDIndicates that the application's window is minimized upon startup.

1068

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) QueryProgItem

Return Values
Table D-2: QueryProgItem Return Values Return Value IS_ITEM (0) IS_FOLDER (1) <0 Description Indicates szItemName is a program item or shortcut in szFolderName. Indicates szItemName is a subfolder in szFolderName. Indicates that the function was unable to find the program item or subfolder name. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
The location of the Start menu is different under different languages. The InstallScript engine automatically selects the correct path.

QueryProgItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the QueryProgItem function. * * QueryProgItem is called to find the attributes of a target * file or folder. * * Note: Before running this script, set the defined constants * FOLDER_NAME and ITEM_NAME so that they reference an * existing folder name and folder item. * \*--------------------------------------------------------------*/ // Define constants to reference the file or folder name. #define FOLDER_NAME "C:\\Windows\\Start Menu\\Programs" #define ITEM_NAME "InstallShield" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_QueryProgItem(HWND); function ExFn_QueryProgItem(hMSI) STRING svCmdLine, svWrkDir, svIconPath; STRING svShortCutKey, svGroupPath, szTitle, szMsg, szInfo, svMinFlag; STRING svMinimizeFlag; NUMBER nvIconIndex, nvMinimizeFlag, nResult, nvMinFlag; LIST listInfo, listID; begin
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1069

Appendix D: Built-In Functions (Q-R) QueryProgItem

// Search for an item in the FOLDER_NAME folder. nResult = QueryProgItem (FOLDER_NAME, ITEM_NAME, svCmdLine, svWrkDir, svIconPath, nvIconIndex, svShortCutKey, nvMinimizeFlag); // Create string list. listInfo = ListCreate (STRINGLIST); // Error check QueryProgItem. if (nResult < 0) then // Report the error; then abort. MessageBox("QueryProgItem failed.", SEVERE); abort; // Check if the item is an application. elseif (nResult = IS_ITEM) then // Add the command line to the string list. Sprintf(szInfo, "The command line of %s: %s", ITEM_NAME, svCmdLine); ListAddString(listInfo, szInfo, AFTER); // Add the working directory to string list. Sprintf(szInfo, "The working directory of %s: %s", ITEM_NAME, svWrkDir); ListAddString(listInfo, szInfo, AFTER); // Add the icon path to string list. Sprintf(szInfo, "The icon path of %s: %s", ITEM_NAME, svIconPath); ListAddString(listInfo, szInfo, AFTER); // Add icon index to string list. Sprintf(szInfo, "The index of the icon: %d", nvIconIndex); ListAddString(listInfo, szInfo, AFTER); // Add shortcut key to string list. Sprintf (szInfo, "The shortcut key of %s: %s", ITEM_NAME, svShortCutKey); ListAddString(listInfo, szInfo, AFTER); // Check if the item is a folder. elseif (nResult = IS_FOLDER) then // Add a message to string list. Sprintf (szInfo, "The item is a subfolder. QueryProgItem does not " + "retrieve very much information about subfolders."); ListAddString(listInfo, szInfo, AFTER); endif; // Display the string list. szTitle = "QueryProgItem Example"; szMsg = "The following are attributes of the item:"; SdShowInfoList(szTitle, szMsg, listInfo); // Destroy the list. ListDestroy (listID); end;

1070

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) QueryShellMgr

QueryShellMgr
The QueryShellMgr function obtains the name of the program shell being used by Microsoft Windows. For example, if the program shell is Explorer, QueryShellMgr returns the string Explorer.exe in svShellMgrName.

Syntax
QueryShellMgr ( svShellMgrName );

Parameters
Table D-3: QueryShellMgr Parameters Parameter svShellMgrName Description Returns the unqualified name (that is, without the drive designation or path) of the shell manager that is currently running.

Return Values
Table D-4: QueryShellMgr Return Values Return Value 0 Description Indicates that the function successfully retrieved the name of the program shell. Indicates that the function was unable to retrieve the name of the program shell. You can obtain the error message text associated with a large negative return valuefor example, 2147024891 (0x80070005)by calling FormatMessage.

<0

Additional Information
If the shell on the target system is not Explorer, you may need to launch that shell with the LaunchApp function. The InstallScript functions that create program folders and program icons use a DDE conversation with the shell to create the program folders and program items. Most alternate shells such as the Norton Desktop emulate the Explorer shell. Therefore, they can create program folders and items. In shells that do not emulate the Explorer shell, InstallShield cannot use the program folder and program item functions to create or modify the program folders and program items. Check with the manufacturer of the shell to determine how it handles the creation of program folders and program items using Microsoft DDE specifications.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1071

Appendix D: Built-In Functions (Q-R) ReadArrayProperty

QueryShellMgr Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the QueryShellMgr function. * * QueryShellMgr is called to find the name of the shell * manager. The name is then displayed in a message box. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_QueryShellMgr(HWND); function ExFn_QueryShellMgr(hMSI) STRING svShellMgrName, szTitle, szMsg; NUMBER nReturn; begin // Get the name of the program shell. nReturn = QueryShellMgr (svShellMgrName); if (nReturn < 0) then // Report an error. MessageBox ("Could not retrieve the program shell.", SEVERE); else // Display the name of the shell. MessageBox ("The shell manager is " + svShellMgrName + ".", INFORMATION); endif; end;

ReadArrayProperty
Project: This information applies to InstallScript projects.

The ReadArrayProperty function is called in an object script to read the value of a specified property whose value is an array.

Syntax
ReadArrayProperty ( nPropertyBag, szPropertyName, ArrayPointer );

1072

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) ReadBoolProperty

Parameters
Table D-5: ReadArrayProperty Parameters Parameter nPropertyBag Description Specifies a reference to the object's property bag object, in which property values are stored. (The value of nPropertyBag is passed by the setup engine to the ReadProperties function block within which ReadBoolProperty is called. This value is placed in the object script when you use the Add New Property dialog in the InstallScript view.) Specifies the name of the property whose value you want to read. Returns a pointer to the specified array property.

szPropertyName

ArrayPointer

Return Values
Table D-6: ReadArrayProperty Return Values Return Value 0 Description This function always returns zero (0).

ReadBoolProperty
Project: This information applies to InstallScript projects.

The ReadBoolProperty function is called in an object script to read the value of a specified property whose value is a Boolean.

Syntax
ReadBoolProperty ( nPropertyBag, szPropertyName, bvPropertyValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1073

Appendix D: Built-In Functions (Q-R) ReadBytes

Parameters
Table D-7: ReadBoolProperty Parameters Parameter nPropertyBag Description Specifies a reference to the object's property bag object, in which property values are stored. (The value of nPropertyBag is passed by the setup engine to the ReadProperties function block within which ReadBoolProperty is called. This value is placed in the object script when you use the Add New Property dialog in the InstallScript view.) Specifies the name of the property whose value you want to read. Returns the value of the specified property.

szPropertyName

bvPropertyValue

Return Values
Table D-8: ReadBoolProperty Return Values Return Value 0 Description This function always returns zero (0).

ReadBytes
The ReadBytes function reads a specific number of bytes from a file starting at the current file pointer location. When this function returns, InstallShield relocates the file pointer to the new position at the end of the bytes read from the file.

Note: Before you can read from the file, which may be a file on the Internet, you must open the file in binary mode by calling OpenFileMode and OpenFile.

The parameter nIndex is an index into the value specified by svString. Use the parameter nBytes to specify how many bytes beyond the parameter nIndex to read from the file. If the nIndex plus nBytes is a value larger than the length of the svString, only the number of bytes from the index of the string to the end of the string are read from the file. For example, if svString is declared to be 100 bytes long, the parameter nIndex is declared as 50 bytes and the parameter nBytes is 75 bytes, only the bytes between 49 and 99 (50 bytes instead of 75 bytes) are read.

Syntax
ReadBytes ( nFileHandle, svString, nIndex, nBytes );

1074

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) ReadBytes

Parameters
Table D-9: ReadBytes Parameters Parameter nFileHandle Description Specifies the file handle to a file opened in binary mode. Returns the bytes read from the file. The variable passed in this parameter must have been declared with an explicit size, and it must be large enough to accommodate the number of bytes specified by nBytes. Specifies an index into svString; data from the file is inserted into the string at this location. Specifies the number of bytes to read from the file. Bytes are read starting from the current location of the file pointer. InstallShield relocates the file pointer as the bytes are read.

svString

nIndex

nBytes

Return Values
Table D-10: ReadBytes Return Values Return Value X Description Indicates that the function successfully read bytes from the file, where X is the actual number of bytes returned in svString. Indicates that the function was unable to successfully read from the file.

<0

ReadBytes Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ReadBytes and SeekBytes functions. * * SeekBytes is called to position a file pointer to a * specific location in a file that has been opened in binary * mode. ReadBytes then reads a specific number of bytes, * starting at this location. The bytes are read into a string, * which is then displayed in a message box.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1075

Appendix D: Built-In Functions (Q-R) ReadNumberProperty

* * Note: The defined constants EXAMPLE_DIR and EXAMPLE_BIN must * be set to an existing directory and file on the target * system. * \*--------------------------------------------------------------*/ #define EXAMPLE_DIR "C:\\" #define EXAMPLE_BIN "Example.bin" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ReadBytes(HWND); function ExFn_ReadBytes(hMSI) STRING svString; NUMBER nvFileHandle; begin // Set the file mode to read/write. OpenFileMode (FILE_MODE_BINARY); // Open a binary file. if (OpenFile (nvFileHandle, EXAMPLE_DIR, EXAMPLE_BIN) < 0) then // Report an error; then abort. SprintfBox (SEVERE, "CopyBytes Example", "Could not open %s.", EXAMPLE_BIN); abort; endif; // Set the file pointer to the 16th byte in the file. SeekBytes (nvFileHandle, 15, FILE_BIN_START); // Read the next twenty-eight bytes into svString. if (ReadBytes (nvFileHandle, svString, 0, 28) < 0) then // Report an error. MessageBox ("ReadBytes failed.", SEVERE); else // Display the string. SprintfBox (INFORMATION, "ReadBytes Example", "Bytes read: %s", svString); endif; // Close the file. CloseFile (nvFileHandle); end;

ReadNumberProperty
Project: This information applies to InstallScript projects.

The ReadNumberProperty function is called in an object script to read the value of a specified property whose value is a number.

1076

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) ReadStringProperty

Syntax
ReadNumberProperty ( nPropertyBag, szPropertyName, nvPropertyValue );

Parameters
Table D-11: ReadNumberProperty Parameters Parameter nPropertyBag Description Specifies a reference to the object's property bag object, in which property values are stored. (The value of nPropertyBag is passed by the setup engine to the ReadProperties function block within which ReadBoolProperty is called. This value is placed in the object script when you use the Add New Property dialog in the InstallScript view.) Specifies the name of the property whose value you want to read. Returns the value of the specified property.

szPropertyName

nvPropertyValue

Return Values
Table D-12: ReadNumberProperty Return Values Return Value 0 Description This function always returns zero (0).

ReadStringProperty
Project: This information applies to InstallScript projects.

The ReadStringProperty function is called in an object script to read the value of a specified property whose value is a string.

Syntax
ReadStringProperty ( nPropertyBag, szPropertyName, svPropertyValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1077

Appendix D: Built-In Functions (Q-R) RebootDialog

Parameters
Table D-13: ReadStringProperty Parameters Parameter nPropertyBag Description Specifies a reference to the object's property bag object, in which property values are stored. (The value of nPropertyBag is passed by the setup engine to the ReadProperties function block within which ReadBoolProperty is called. This value is placed in the object script when you use the Add New Property dialog in the InstallScript view.) Specifies the name of the property whose value you want to read. Returns the value of the specified property.

szPropertyName

svPropertyValue

Return Values
Table D-14: ReadStringProperty Return Values Return Value 0 Description This function always returns zero (0).

RebootDialog
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The RebootDialog function displays a message box that enables end users to specify whether they want to restart the computer. The selected option is performed at the end of the installation. When you call a function with the SHAREDFILE or LOCKEDFILE option and locked .dll or .exe files are encountered, updated versions of the locked files are copied to the target system and the system variable BATCH_INSTALL is set to TRUE. RebootDialog automatically commits the locked files for update when the system is restarted, unless the user selects the No, I will restart my computer later option. The InstallScript engine makes every attempt not to restart the system when other instances of the installation are running. Because of this, you must make sure all other instances of the installation are shut down before calling RebootDialog. Your message to end users should request that they ensure all other applications are shut down before restarting the system.

1078

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RebootDialog

Note: An alternative to the RebootDialog function is SdFinishReboot, which has a better look and feel than the RebootDialog dialog.

Syntax
RebootDialog ( szTitle, szMsg, nDefChoice );

Parameters
Table D-15: RebootDialog Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title Restarting Windows, pass a null string ("") in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the default option button selection. Pass one of the following predefined constants in this parameter:

szMsg

nDefChoice

SYS_BOOTMACHINEThe option to reboot the computer (Yes, I want to restart my computer now) is the default option button selection. 0The option to not restart the computer (No, I will restart my computer later) is the default option button selection.

Return Values
Table D-16: RebootDialog Return Values Return Value WILL_REBOOT Description Indicates that the end user selected the Yes, I want to restart my computer now option button. Indicates that the end user selected the No, I will restart my computer later option button.

Additional Information
The message box that is displayed by the RebootDialog function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

RebootDialog Example
Project: This information applies to the following project types:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1079

Appendix D: Built-In Functions (Q-R) RegDBConnectRegistry

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RebootDialog function. * * This script calls RebootDialog to display a dialog that * asks the user whether or not to reboot the computer. The call * to RebootDialog passes a null string in parameter 2 to display * the default message and 0 in parameter 3 to make the default * selection "No, I will restart my computer later." * * Warning: If the end user selects Yes in this dialog, the * computer is rebooted. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "RebootDialog Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RebootDialog(HWND); function ExFn_RebootDialog(hMSI) NUMBER nvDefChoice; begin // Query to reboot computer. RebootDialog (TITLE_TEXT, "", 0); end;

RegDBConnectRegistry
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBConnectRegistry function creates a connection to a remote registry. After you have opened the connection, you can create, delete, or retrieve registry keys, value names, and value pairs on a remote registry much as you would on a local registry. This functionality is also supported on 64-bit systems with some limitations.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

1080

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBConnectRegistry

RegDBConnectRegistry allows you to edit only one registry root key each time the remote registry is opened, and you can edit only keys and values under either HKEY_LOCAL_MACHINE or HKEY_USERS. When you call RegDBConnectRegistry, you must specify which root key you want to be able to edit. If you want to edit the other root key or one its subkeys, you must close and re-open the connection.

Caution: Because you set the root key by calling RegDBConnectRegistry, you cannot call RegDBSetDefaultRoot after you have established a connection to a remote registry. When you call RegDBDisConnectRegistry, all calls to registry-related functions affect the local registry, and you can then call RegDBSetDefaultRoot to change the root key.

Note: If you are trying to open a registry on a remote Windows system, you must have administrator privileges. This function is intended for use by system administrators for network installations.

Syntax
RegDBConnectRegistry ( szRemoteSystem, nKeyType, nReserved );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1081

Appendix D: Built-In Functions (Q-R) RegDBConnectRegistry

Parameters
Table D-17: RegDBConnectRegistry Parameters Parameter szRemoteSystem Description Specifies the name of the system with which to connect, such as RemoteSys. If you pass a null string ("") in this parameter, the function creates a connection to the local registry. Specifies one of the following constants: HKEY_LOCAL_MACHINE or HKEY_USERS. Pass zero in this parameter. No other value is allowed.

nKeyType

nReserved

Return Values
Table D-18: RegDBConnectRegistry Return Values Return Value 0 Description Indicates this function successfully established a connection to the system registry. A connection to a remote registry already exists. It must be closed using RegDBDisConnectRegistry before you can call RegDBConnectRegistry again. Indicates that the remote registry is corrupted and cannot be accessed. Indicates that the registry services could not be initialized. Make sure Remote Administration is enabled and that you have appropriate privileges to be able to write to the registry. The key name provided for the remote registry is not allowed. Indicates that the system in szRemoteSystem could not be found. Check the name and try again. Other error.

REGDB_ERR_CONNECTIONEXISTS (-6)

REGDB_ERR_CORRUPTEDREGISTRY (-4) REGDB_ERR_INITIALIZATION (-2)

REGDB_ERR_INVALIDHANDLE (-5) REGDB_ERR_INVALIDNAME (-3)

-1

You can obtain the error message text associated with a large negative return valuefor example, 2147024891 (0x80070005)by calling FormatMessage.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

1082

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBConnectRegistry

RegDBConnectRegistry Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBConnectRegistry function and * RegDBDisConnectRegistry function. * * Note: In order for this script to run properly, you must set * the preprocessor constants to a valid remote computer * with remote administration enabled. Both computers * must also have the remote-registry service enabled. * \*--------------------------------------------------------------*/ #define REMOTE "IShield_NT1" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBConnectRegistry(HWND); function ExFn_RegDBConnectRegistry(hMSI) STRING szRemoteMachine, szKey, szTitle, szMsg; NUMBER nKeyType, nReturn; begin szTitle szRemoteMachine nKeyType szMsg = = = = "RegDBConnectRegistry & RegDBDisConnectRegistry"; REMOTE; HKEY_LOCAL_MACHINE; "Setup will now connect to %s.";

SprintfBox (INFORMATION, szTitle, szMsg, szRemoteMachine); // Connect to the remote computer's registry. All registry-related // function calls will now alter only the remote computer. nReturn = RegDBConnectRegistry (szRemoteMachine, nKeyType, 0); if (nReturn < 0) then szMsg = "RegDBConnectRegistry failed.\n\nCould not connect to remote " + "system."; MessageBox (szMsg, SEVERE); abort; else szMsg = "Successfully connected to %s."; SprintfBox (INFORMATION, szTitle, szMsg, szRemoteMachine); endif; // Create a key on the remote computer. szKey = "SOFTWARE\\InstallShield\\Test Key"; nReturn = RegDBCreateKeyEx(szKey, ""); if (nReturn < 0) then szMsg = "RegDBCreateKeyEx failed.\n\n\Could not create key on remote " +

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1083

Appendix D: Built-In Functions (Q-R) RegDBCopyKeys

"machine."; MessageBox (szMsg , SEVERE); else szMsg = "Successfully created %s on %s."; SprintfBox (INFORMATION, szTitle, szMsg, szKey, szRemoteMachine); // Verify that the key now exists in the remote registry. nReturn = RegDBKeyExist(szKey); if (nReturn < 0) then szMsg = "RegDBKeyExist failed.\n\nRemote key does not exist."; MessageBox (szMsg, SEVERE); else szMsg = "%s exists."; SprintfBox (INFORMATION, szTitle, szMsg, szKey); endif; endif; // Delete the key that was created on the remote computer. nReturn = RegDBDeleteKey(szKey); if (nReturn < 0) then MessageBox("RegDBDeleteKey failed.\n\nRemote key could not be deleted.", INFORMATION); else szMsg = "Successfully deleted %s on %s."; SprintfBox(INFORMATION, szTitle, szMsg, szKey, szRemoteMachine); endif; // Disconnect from the remote registry. All registry-related functions // will now alter only the local registry. nReturn = RegDBDisConnectRegistry(0); if (nReturn < 0) then MessageBox("RegDBDisConnectRegistry failed.\n\nRemote registry still " + "connected.", SEVERE); else MessageBox("RegDBDisConnectRegistry successful.\n\nRemote registry " + "disconnected.", INFORMATION); endif; end;

RegDBCopyKeys
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBCopyKeys function copies the registry keys and values under the key specified by szSourceKey to the key specified by szTargetKey.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.
1084 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBCopyKeys

Syntax
RegDBCopyKeys ( szSourceKey, szTargetKey, nRootKeySource, nRootKeyTarget );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1085

Appendix D: Built-In Functions (Q-R) RegDBCopyKeys

Parameters
Table D-19: RegDBCopyKeys Parameters Parameter szSourceKey Description Specifies the name of the key whose subkeys and values are to be copied. Separate different levels in the subkey with a double backslash (\\). Specifies the name of the key to be copied to. Separate different levels in the subkey with a double backslash (\\). If this key does not exist, RegDBCopyKeys creates it. If this key does exist, any existing values under the key that have the same names as values under szSourceKey are overwritten; this includes values under identically named subkeys. Specifies the root key of szSourceKey. Pass one of the following predefined constants in this parameter:

szTargetKey

nRootKeySource

nRootKeyTarget

HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG HKEY_DYN_DATA

Specifies the root key of szTargetKey. Pass one of the following predefined constants in this parameter:

HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG HKEY_DYN_DATA

Return Values
Table D-20: RegDBCopyKeys Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully copied the keys and values. Indicates that the function was unable to copy the keys and values. You can obtain the error message text associated with a large negative return valuefor example,-2147024891(0x80070005)by calling FormatMessage.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the
1086 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBCopyValues

REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBCopyValues
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBCopyValues function copies the registry values under the key specified by szSourceKey to the key specified by szTargetKey.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBCopyValues ( szSourceKey, szTargetKey, nRootKeySource, nRootKeyTarget );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1087

Appendix D: Built-In Functions (Q-R) RegDBCopyValues

Parameters
Table D-21: RegDBCopyValues Parameters Parameter szSourceKey Description Specifies the name of the key whose values are to be copied. Separate different levels in the subkey with a double backslash (\\). Specifies the name of the key to be copied to. Separate different levels in the subkey with a double backslash (\\). If this key does not exist, RegDBCopyKeys creates it. If this key does exist, any existing values under the key that have the same names as values under szSourceKey are overwritten. Specifies the root key of szSourceKey. Pass one of the following predefined constants in this parameter:

szTargetKey

nRootKeySource

nRootKeyTarget

HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG HKEY_DYN_DATA

Specifies the root key of szTargetKey. Pass one of the following predefined constants in this parameter:

HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG HKEY_DYN_DATA

Return Values
Table D-22: RegDBCopyValues Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully copied the values. Indicates that the function was unable to copy the values. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the
1088 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBCreateKeyEx

REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBCreateKeyEx
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBCreateKeyEx function creates a key in the registry. You can also associate a class object with the newly created key (advanced users only). The newly created key does not have a value associated with it. When logging is enabled, the InstallScript engine logs each key in the path that is passed through szKey to RegDBCreateKeyEx. For example, you might pass the following for szKey:
"Software" ^ IFX_COMPANY_NAME ^ IFX_PRODUCT_NAME

In this case, the InstallScript engine logs several keys:

Software The value of the IFX_COMPANY_NAME variable The value of the IFX_PRODUCT_NAME variable

The log flags a key as created if it did not already exist. In the aforementioned example, the Software key already exists on all target systems (HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER). The Software key is logged, but its created flag would be false, indicating that the key should not be removed during uninstallation. Any keys that are created and logged (because they did not already exist at the time the installation was running) are removed during uninstallation. When a key is uninstalled, all of its subkeys are also uninstalled. Therefore, if you use RegDBCreateKeyEx to create a key or keys under a key that is already logged for uninstallation, the keys that you create will be uninstalled when the higher-level key is uninstalled. This behavior occurs regardless of whether logging is enabled when the installation creates your keys and regardless of the order in which the installation creates the keys. Therefore, in the aforementioned example, if logging is also enabled for a second installation that likewise uses RegDBCreateKeyEx to create a key for a different product under the IFX_COMPANY_NAME key that the first installation created, and the then end user uninstalls the first product, the entire IFX_COMPANY_NAME key, with both of the product subkeys, are removed. This may make the second product behave unexpectedly. If you want to be able to share registry keys among multiple installations, it is recommended that you use the Registry view to configure the registry entries, instead of using the RegDBCreateKeyEx function. In the Registry view of an InstallScript project, you can mark a registry keys as shared (by right-clicking the key and then clicking Shared among several applications). During the uninstallation, the InstallScript engine removes a shared key only if no other logged installations that share the key still exist on the machine. To view all of the registry keys that were logged during an installation and find out how each of their created flags were set, use the InstallShield Cabinet and Log File Viewer. For more information about logging, see InstallScript Functions that Are Logged for Uninstallation.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1089

Appendix D: Built-In Functions (Q-R) RegDBCreateKeyEx

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBCreateKeyEx ( szKey, szClass );

Parameters
Table D-23: RegDBCreateKeyEx Parameters Parameter szKey Description Specify the name of the key to create. Separate different levels in the subkey with a double backslash (\\). If the root key is HKEY_CLASSES_ROOT, you do not need to specify the HKEY_CLASSES_ROOT in this parameter. Unless you specify otherwise, the InstallScript engine creates the key as a subkey of HKEY_CLASSES_ROOT. To specify a different root key, you can call RegDBSetDefaultRoot before calling RegDBCreateKeyEx. szClass Specify the class name to associate with this key.

Return Values
Table D-24: RegDBCreateKeyEx Return Values Return Value 0 <0 Description Indicates that the function successfully created the subkey. Indicates that the function was unable to create the subkey. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
RegDBCreateKeyEx is a general registry-related function, designed to work with all registry keys, including those handled by the special registry-related functions. For more information on special registry-related functions, see Special Registry-Related Functions.

Note: Windows does not allow the creation of a key directly under HKEY_LOCAL_MACHINE or HKEY_USERS.

By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS constant.

1090

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBCreateKeyEx

RegDBCreateKeyEx Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBCreateKeyEx and RegDBKeyExist functions. * * First, RegDBCreateKeyEx is called to create a subkey with no * class value in the HKEY_CLASSES_ROOT key. Then, RegDBKeyExist * is then called to check if the key was created. * * RegDBCreateKey is called again to create a multi-level subkey * with a class value associated with it under HKEY_CLASSES_ROOT. * Then RegDBKeyExist is called again to check for the existence * of the new key. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "RegDBCreateKeyEx & RegDBKeyExist" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBCreateKeyEx(HWND); function ExFn_RegDBCreateKeyEx(hMSI) STRING szKey, szClass, szKeyRoot, szMsg, svLogFile; NUMBER nResult1, nResult2; begin // Create a key with no class value. szKey = "CreateKeyExample"; szClass = ""; if (RegDBCreateKeyEx(szKey, szClass) < 0) then MessageBox ("First call to RegDBCreateKeyEx failed.", SEVERE); abort; else SprintfBox (INFORMATION, TITLE_TEXT, "Successfully created: %s", szKey); // Check to see if the key just created exists. if (RegDBKeyExist (szKey) < 0) then MessageBox ("First call to RegDBKeyExist failed.", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, "%s exists.", szKey); endif; endif; if (RegDBDeleteKey (szKey) < 0) then MessageBox ("RegDBDeleteKey failed.", SEVERE); endif; // Create a key with more than one sublevel and a class value. szKey = "ShareWare\\Games\\CoolChess";

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1091

Appendix D: Built-In Functions (Q-R) RegDBDeleteItem

szClass = "LastPlayed"; szKeyRoot = "ShareWare"; if (RegDBCreateKeyEx(szKey, szClass) < 0) then MessageBox ("Second call to RegDBCreateKeyEx failed.", SEVERE); abort; else SprintfBox (INFORMATION, TITLE_TEXT, "Successfully created: %s", szKey); // Check if the newly created multi-level key exists. if (RegDBKeyExist (szKeyRoot) < 0) then MessageBox ("Second call to RegDBKeyExist failed.", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, "%s exists.", szKey); endif; endif; if (RegDBDeleteKey (szKey) < 0) then MessageBox ("RegDBDeleteKey failed.", SEVERE); endif; end;

RegDBDeleteItem
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service. RegDBDeleteItem is a special registry-related function designed to work with certain predefined registry keys. The RegDBDeleteItem function deletes values under the per application paths key or the application uninstallation key, depending on the value of nItem. Calling RegDBDeleteItem with either the REGDB_APPPATH or the REGDB_APPPATH_DEFAULT option results in the deletion of the per application paths key.

Note: The InstallScript engine currently does not support writing or reading Add or Remove Programs information for a product in the 64-bit part of the registry. Therefore, using the REGDB_OPTION_WOW64_64KEY option with the REGDB_OPTIONS system variable is not supported for this registry function. Enabling the REGDB_OPTION_WOW64_64KEY option has no effect on where registry entries are created by this function.

Syntax
RegDBDeleteItem( nItem );

1092

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBDeleteItem

Parameters
Table D-25: RegDBDeleteItem Parameters Parameter nItem Description Specifies the item to delete. Pass one of the following predefined constants in this parameter:

REGDB_APPPATHThe data of the Path value under the per-application paths key. This key is deleted by the installation as a result of calling CreateInstallationInfo. You must call CreateInstallationInfo to create this key before calling RegDBDeleteItem. (In an event-based script, CreateInstallationInfo is called in the default OnMoveData event handler code.) REGDB_APPPATH_DEFAULTThe data of the DefaultPath value under the per-application paths key. This key is created by the installation as a result of calling CreateInstallationInfo. You must call CreateInstallationInfo to create this key before calling RegDBDeleteItem. (In an eventbased script, CreateInstallationInfo is called in the default OnMoveData event handler code.) REGDB_UNINSTALL_COMMENTSThe data of the Comments value under the uninstallation key. REGDB_UNINSTALL_CONTACTThe data of the Contact value under the uninstallation key. REGDB_UNINSTALL_DISPLAY_VERSIONThe data of the DisplayVersion value under the uninstallation key. REGDB_UNINSTALL_DISPLAYICONThe data of the DisplayIcon value under the uninstallation key. REGDB_UNINSTALL_HELPLINKThe data of the HelpLink value under the uninstallation key. REGDB_UNINSTALL_HELPTELEPHONEThe data of the HelpTelephone value under the uninstallation key. REGDB_UNINSTALL_INSTALLDATEThe data of the InstallDate value under the uninstallation key. REGDB_UNINSTALL_INSTALLLOCThe data of the InstallLocation value under the uninstallation key. REGDB_UNINSTALL_INSTALLSOURCEThe data of the InstallSource value under the uninstallation key. REGDB_UNINSTALL_LANGUAGEThe data of the Language value under the uninstallation key. REGDB_UNINSTALL_LOGFILEThe data of the LogFile value under the uninstallation key. REGDB_UNINSTALL_MAINT_OPTIONThe data of the LogMode value under the uninstallation key.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1093

Appendix D: Built-In Functions (Q-R) RegDBDeleteItem

Table D-25: RegDBDeleteItem Parameters (cont.) Parameter nItem (cont.) Description

REGDB_UNINSTALL_MAJOR_VERSIONThe data of the VersionMajor value under the uninstallation key. REGDB_UNINSTALL_MAJOR_VERSION_OLDThe data of the MajorVersion value under the uninstallation key. REGDB_UNINSTALL_MINOR_VERSIONThe data of the VersionMinor value under the uninstallation key. REGDB_UNINSTALL_MINOR_VERSION_OLDThe data of the MinorVersion value under the uninstallation key. REGDB_UNINSTALL_MODIFYPATHThe data of the ModifyPath value under the uninstallation key. REGDB_UNINSTALL_NAMEThe data of the DisplayName value under the uninstallation key. REGDB_UNINSTALL_NOMODIFYThe data of the NoModify value under the uninstallation key. REGDB_UNINSTALL_NOREMOVEThe data of the NoRemove value under the uninstallation key. REGDB_UNINSTALL_NOREPAIRThe data of the NoRepair value under the uninstallation key. REGDB_UNINSTALL_PRODUCTGUIDThe data of the ProductGuid value under the uninstallation key. REGDB_UNINSTALL_PRODUCTIDThe data of the ProductId value under the uninstallation key. REGDB_UNINSTALL_PUBLISHERThe data of the Publisher value under the uninstallation key. REGDB_UNINSTALL_READMEThe data of the Readme value under the uninstallation key. REGDB_UNINSTALL_REGCOMPANYThe data of the RegCompany value under the uninstallation key. REGDB_UNINSTALL_REGOWNERThe data of the RegOwner value under the uninstallation key. REGDB_UNINSTALL_STRINGThe data of the UninstallString value under the uninstallation key. The UninstallString value is created when the MaintenanceStart or DeinstallStart functions are called. REGDB_UNINSTALL_SYSTEMCOMPONENTThe data of the SystemComponent value under the uninstallation key. REGDB_UNINSTALL_URLINFOABOUTThe data of the URLInfoAbout value under the uninstallation key. REGDB_UNINSTALL_URLUPDATEINFOThe data of the URLUpdateInfo value under the uninstallation key. REGDB_UNINSTALL_VERSIONThe data of the Version value under the uninstallation key. When this constant is used, szValue specifies the installed products version number expressed as a string, for example, "16777216".

nItem (cont.)

Important: Do not use REGDB_WINCURRVER_REGOWNER or REGDB_WINCURRVER_REGORGANIZATION with this function. Windows sets these values, and they should not be deleted by an installation.

1094

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBDeleteKey

Return Values
Table D-26: RegDBDeleteItem Return Values Return Value 0 <0 Description Indicates that the function successfully set the value. Indicates that the function failed.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>" in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.
RegDBDeleteItem does not write anything to the uninstall log file; thus, calling this function does not have any effect how the application is uninstalled.

RegDBDeleteKey
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBDeleteKey function deletes a specific key and its associated value from the registry. All subkeys of the deleted key are also deleted, along with their associated values. InstallShield assumes the key specified in szSubKey is a subkey of HKEY_CLASSES_ROOT. You can use RegDBSetDefaultRoot to specify another root key. RegDBDeleteKey is a general registry-related function, designed to work with all registry keys, including those handled by the special registry-related functions. For more information on special registry-related functions, see Special Registry-Related Functions.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBDeleteKey ( szSubKey );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1095

Appendix D: Built-In Functions (Q-R) RegDBDeleteKey

Parameters
Table D-27: RegDBDeleteKey Parameters Parameter szSubKey Description Specifies the name of the key to delete. Separate different levels in the subkey with a double backslash (\\).

Return Values
Table D-28: RegDBDeleteKey Return Values Return Value 0 <0 Description Indicates that the function successfully deleted the key. Indicates that the function was unable to delete the key. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>" in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.
RegDBDeleteKey does not write anything to the uninstall log file; thus, calling this function does not

have any effect how the application is uninstalled.

RegDBDeleteKey Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBDeleteKey function. * * This example creates and then deletes a registry key. * Almost all of the examples provided with the registry functions * use this function to delete a key. Please refer to those * examples for more information. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "RegDBDeleteKey Example"
1096 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBDeleteValue

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBDeleteKey(HWND); function ExFn_RegDBDeleteKey(hMSI) STRING szKey, szClass, szKeyRoot, szMsg, svLogFile; NUMBER nResult1, nResult2; begin // Set up parameters for call to RegDBCreateKeyEx. szKey = "DeleteMeKey"; szClass = ""; // Create a key with no class value. if (RegDBCreateKeyEx (szKey, szClass) < 0) then MessageBox ("RegDBCreateKeyEx failed.", SEVERE); abort; else SprintfBox (INFORMATION, TITLE_TEXT, "%s successfully created.", szKey); endif; // Call RegDBDeleteKey to delete the key just created. if (RegDBDeleteKey (szKey) < 0) then MessageBox ("RegDBDeleteKey failed.", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, "%s successfully deleted.", szKey); endif; end;

RegDBDeleteValue
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBDeleteValue function deletes a value from a specific key in the registry. InstallShield assumes that the key specified in szSubKey is a subkey of HKEY_CLASSES_ROOT. You must use RegDBSetDefaultRoot to specify another root key. RegDBDeleteKey is a general registry-related function, designed to work with all registry keys, including those handled by the special registry-related functions. For more information on special registry-related functions, see Special Registry-Related Functions.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBDeleteValue ( szSubKey, szValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1097

Appendix D: Built-In Functions (Q-R) RegDBDeleteValue

Parameters
Table D-29: RegDBDeleteValue Parameters Parameter szSubKey Description Specifies the name of the registry key that contains the value name to delete. Separate different levels in the subkey with a double backslash (\\). Specifies the name of the value you want to delete.

szValue

Return Values
Table D-30: RegDBDeleteValue Return Values Return Value 0 <0 Description Indicates that the function successfully deleted the value. Indicates that the function was unable to delete the value.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>" in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.
RegDBDeleteValue does not write anything to the uninstall log file; thus, calling this function does not

have any effect how the application is uninstalled.

RegDBDeleteValue Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBDeleteValue function. * * RegDBDeleteValue is called to delete the value name "Cursive" * from the following registry key: * * "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Fonts". * * Note: Before running this script, set the preprocessor * constants so that they reference an existing subkey * and value on the target system.

1098

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBDisConnectRegistry

* \*--------------------------------------------------------------*/ #define SUBKEY "\\Software\\Microsoft\\Windows\\CurrentVersion\\Fonts" #define VALUE "Cursive" #define TITLE "RegDBDeleteValue Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBDeleteValue(HWND); function ExFn_RegDBDeleteValue(hMSI) STRING szSubKey, szValue, szTitle; NUMBER nReturn; begin // Set the root key. RegDBSetDefaultRoot (HKEY_LOCAL_MACHINE); // Set the name of the subkey. szSubKey = SUBKEY; szValue = VALUE; // Delete the subkey. nReturn = RegDBDeleteValue (szSubKey, szValue); // Report the results of the deletion. if (nReturn < 0) then MessageBox ("RegDBDeleteValue failed.", SEVERE); else SprintfBox (INFORMATION, TITLE, "%s successfully deleted.", szValue); endif; end;

RegDBDisConnectRegistry
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBDisConnectRegistry function closes a connection to a remote registry that you established by calling RegDBConnectRegistry. After calling RegDBDisConnectRegistry, all calls to the InstallScript registry-related functions affect the local systems registry. For more information on special registry-related functions, see Special RegistryRelated Functions.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1099

Appendix D: Built-In Functions (Q-R) RegDBDisConnectRegistry

Syntax
RegDBDisConnectRegistry ( nReserved );

Parameters
Table D-31: RegDBDisConnectRegistry Parameters Parameter nReserved Description Pass zero in this parameter. No other value is allowed.

Return Values
Table D-32: RegDBDisConnectRegistry Return Values Return Value 0 Description Indicates that this function successfully closed a connection to the registry on the remote system. Indicates that this function failed to close the registry connection.

<0

RegDBDisConnectRegistry Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBConnectRegistry function and * RegDBDisConnectRegistry function. * * Note: In order for this script to run properly, you must set * the preprocessor constants to a valid remote computer * with remote administration enabled. Both computers * must also have the remote-registry service enabled. * \*--------------------------------------------------------------*/ #define REMOTE "IShield_NT1" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBDisConnectRegistry(HWND); function ExFn_RegDBDisConnectRegistry(hMSI) STRING szRemoteMachine, szKey, szTitle, szMsg; NUMBER nKeyType, nReturn; begin

1100

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBDisConnectRegistry

szTitle szRemoteMachine nKeyType szMsg

= = = =

"RegDBConnectRegistry & RegDBDisConnectRegistry"; REMOTE; HKEY_LOCAL_MACHINE; "Setup will now connect to %s.";

SprintfBox (INFORMATION, szTitle, szMsg, szRemoteMachine); // Connect to the remote computer's registry. All registry-related // function calls will now alter only the remote computer. nReturn = RegDBConnectRegistry (szRemoteMachine, nKeyType, 0); if (nReturn < 0) then szMsg = "RegDBConnectRegistry failed.\n\nCould not connect to remote " + "system."; MessageBox (szMsg, SEVERE); abort; else szMsg = "Successfully connected to %s."; SprintfBox (INFORMATION, szTitle, szMsg, szRemoteMachine); endif; // Create a key on the remote computer. szKey = "SOFTWARE\\InstallShield\\Test Key"; nReturn = RegDBCreateKeyEx(szKey, ""); if (nReturn < 0) then szMsg = "RegDBCreateKeyEx failed.\n\n\Could not create key on remote " + "machine."; MessageBox (szMsg , SEVERE); else szMsg = "Successfully created %s on %s."; SprintfBox (INFORMATION, szTitle, szMsg, szKey, szRemoteMachine); // Verify that the key now exists in the remote registry. nReturn = RegDBKeyExist(szKey); if (nReturn < 0) then szMsg = "RegDBKeyExist failed.\n\nRemote key does not exist."; MessageBox (szMsg, SEVERE); else szMsg = "%s exists."; SprintfBox (INFORMATION, szTitle, szMsg, szKey); endif; endif; // Delete the key that was created on the remote computer. nReturn = RegDBDeleteKey(szKey); if (nReturn < 0) then MessageBox("RegDBDeleteKey failed.\n\nRemote key could not be deleted.", INFORMATION); else szMsg = "Successfully deleted %s on %s."; SprintfBox(INFORMATION, szTitle, szMsg, szKey, szRemoteMachine); endif; // Disconnect from the remote registry. All registry-related functions // will now alter only the local registry. nReturn = RegDBDisConnectRegistry(0); if (nReturn < 0) then
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1101

Appendix D: Built-In Functions (Q-R) RegDBGetAppInfo

MessageBox("RegDBDisConnectRegistry failed.\n\nRemote registry still " + "connected.", SEVERE); else MessageBox("RegDBDisConnectRegistry successful.\n\nRemote registry " + "disconnected.", INFORMATION); endif; end;

RegDBGetAppInfo
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBGetAppInfo function retrieves from the registry the value of a particular value name under the application information key of your main application. RegDBGetAppInfo is a special registry-related function, designed to work with certain predefined registry keys.

Note: The InstallScript engine currently does not support writing or reading Add or Remove Programs information for a product in the 64-bit part of the registry. Therefore, using the REGDB_OPTION_WOW64_64KEY option with the REGDB_OPTIONS system variable is not supported for this registry function. Enabling the REGDB_OPTION_WOW64_64KEY option has no effect on where registry entries are created by this function.

Syntax
RegDBGetAppInfo ( szName, nvType, svValue, nvSize );

1102

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBGetAppInfo

Parameters
Table D-33: RegDBGetAppInfo Parameters Parameter szName nvType Description Specifies the value name of the value to retrieve. Returns one of the following predefined constants, which identifies the type of data returned in svValue:

svValue nvSize

REGDB_STRINGString variable, no newline characters allowed. REGDB_STRING_EXPANDString variable holding an expandable environment variable expression, such as "%MYPATH%". REGDB_STRING_MULTIString variable, newline characters allowed. REGDB_NUMBERNumber expressed as a string and passed in a string variable. REGDB_BINARYBinary data stored in a string.

Returns the value of the value name specified in szName. Returns the sizein bytesof the return value.

Return Values
Table D-34: RegDBGetAppInfo Return Values Return Value 0 <0 Description Indicates that the function successfully retrieved the value. Indicates that the function was unable to retrieve the value.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBGetAppInfo Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBSetAppInfo and RegDBGetAppInfo functions. *
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1103

Appendix D: Built-In Functions (Q-R) RegDBGetAppInfo

* Before calling either of these functions, you must call * InstallationInfo to set the application information. * \*--------------------------------------------------------------*/ #define #define #define #define #define #define #define #define COMPANY_NAME PRODUCT_NAME PRODUCT_VERSION PRODUCT_KEY DEINSTALL_KEY UNINSTALL_NAME DEFAULT_LOG_PATH TITLE "Example_Company" "Example_App" "5.0" "EXAMPLE.EXE" "Example_DeinstKey" "Example_App_5.0" "EXAMPLE" "RegDBGetAppInfo"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBGetAppInfo(HWND); function ExFn_RegDBGetAppInfo(hMSI) STRING szStrName, szStrValue, svStrValue, szTitle, szMsg, svLogFile; NUMBER nvSize, nvType; begin // Set the root key. RegDBSetDefaultRoot (HKEY_LOCAL_MACHINE); // Set the name to be used with REGDB_STRING. szStrName = "ExampleStringValue"; szStrValue = "ExampleStringSetting"; // Set up the application information prior to using RegDBSetAppInfo // and RegDBGetAppInfo. InstallationInfo (COMPANY_NAME, PRODUCT_NAME, PRODUCT_VERSION, PRODUCT_KEY); DeinstallStart(DEFAULT_LOG_PATH, svLogFile, DEINSTALL_KEY, 0); // Set value of type REGDB_STRING if (RegDBSetAppInfo (szStrName, REGDB_STRING, szStrValue, -1) < 0) then MessageBox ("Failed to set key and value of REGDB_STRING type.", SEVERE); abort; endif; // RegDBGetAppInfo is called to return the values and compare all the setup // parameters. if (RegDBGetAppInfo (szStrName, nvType, svStrValue, nvSize) < 0) then MessageBox ("Failed to get application information value.", SEVERE); abort; else // Check to see if the value retrieved is the same as the value set. if (nvType != REGDB_STRING) then MessageBox ("Type comparison failed.", WARNING); endif; if (szStrValue != svStrValue) then MessageBox ("Sub key value comparison Failed.", WARNING); else szMsg = "Set values: %s = %s\n\nReturn values: %s = %s"; SprintfBox (INFORMATION, TITLE, szMsg, szStrName, szStrValue, szStrName, svStrValue); endif; if (nvSize != StrLength(szStrValue)) then
1104 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBGetDefaultRoot

MessageBox ("Size Comparison failed.", WARNING); else szMsg = "Size in bytes entered: %d\n\nSize in bytes returned: %d"; SprintfBox (INFORMATION, TITLE, szMsg, nvSize, StrLength(szStrValue) + 1); endif; endif; end;

RegDBGetDefaultRoot
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBGetDefaultRoot function returns the root key that is used by the general registry-related functions.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBGetDefaultRoot ( );

Parameters
None.

Return Values
HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG HKEY_DYN_DATA HKEY_USER_SELECTABLE

Note: The return value HKEY_USER_SELECTABLE indicates that a subsequent registry function call uses HKEY_LOCAL_MACHINE as the root key if the ALLUSERS system variable is non-zero when the function is called, or uses HKEY_CURRENT_USER as the root key if ALLUSERS is FALSE when the function is called.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1105

Appendix D: Built-In Functions (Q-R) RegDBGetItem

RegDBGetItem
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBGetItem function retrieves values under the per-application paths key or the application uninstallation key, depending on the value of nItem. RegDBGetItem is a special registry-related function, designed to work with certain predefined registry keys.

Note: The InstallScript engine currently does not support writing or reading Add or Remove Programs information for a product in the 64-bit part of the registry. Therefore, using the REGDB_OPTION_WOW64_64KEY option with the REGDB_OPTIONS system variable is not supported for this registry function. Enabling the REGDB_OPTION_WOW64_64KEY option has no effect on where registry entries are created by this function.

Syntax
RegDBGetItem ( nItem, svValue );

1106

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBGetItem

Parameters
Table D-35: RegDBGetItem Parameters Parameter nItem Description Specifies which item to retrieve. Pass one of the following predefined constants in this parameter:

REGDB_APPPATHThe data of the Path value under the per application paths key. REGDB_APPPATH_DEFAULTThe data of the DefaultPath value under the per application paths key. REGDB_UNINSTALL_COMMENTSThe data of the Comments value under the uninstallation key. REGDB_UNINSTALL_CONTACTThe data of the Contact value under the uninstallation key. REGDB_UNINSTALL_DISPLAY_VERSIONThe data of the DisplayVersion value under the uninstallation key. REGDB_UNINSTALL_DISPLAYICONThe data of the DisplayIcon value under the uninstallation key. REGDB_UNINSTALL_HELPLINKThe data of the HelpLink value under the uninstallation key. REGDB_UNINSTALL_HELPTELEPHONEThe data of the HelpTelephone value under the uninstallation key. REGDB_UNINSTALL_INSTALLDATEThe data of the InstallDate value under the uninstallation key. REGDB_UNINSTALL_INSTALLLOCThe data of the InstallLocation value under the uninstallation key. REGDB_UNINSTALL_INSTALLSOURCEThe data of the InstallSource value under the uninstallation key. REGDB_UNINSTALL_LANGUAGEThe data of the Language value under the uninstallation key. REGDB_UNINSTALL_LOGFILEThe data of the LogFile value under the uninstallation key. REGDB_UNINSTALL_MAINT_OPTIONThe data of the LogMode value under the uninstallation key.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1107

Appendix D: Built-In Functions (Q-R) RegDBGetItem

Table D-35: RegDBGetItem Parameters (cont.) Parameter nItem (cont.) Description

REGDB_UNINSTALL_MAJOR_VERSIONThe data of the VersionMajor value under the uninstallation key, if it is present. If it is not present, the function checks the data of the MajorVersion value under the uninstallation key. REGDB_UNINSTALL_MAJOR_VERSION_OLDThe data of the MajorVersion value under the uninstallation key. REGDB_UNINSTALL_MINOR_VERSIONThe data of the VersionMinor value under the uninstallation key, if it is present. If it is not present, the function checks the data of the MinorVersion value under the uninstallation key. REGDB_UNINSTALL_MINOR_VERSION_OLDThe data of the MinorVersion value under the uninstallation key. REGDB_UNINSTALL_MODIFYPATHThe data of the ModifyPath value under the uninstallation key. REGDB_UNINSTALL_NAMEThe data of the DisplayName value under the uninstallation key. When this constant is used, szValue specifies the application name shown in the list of uninstallable applications in the Control Panel. REGDB_UNINSTALL_NOMODIFYThe data of the NoModify value under the uninstallation key. REGDB_UNINSTALL_NOREMOVEThe data of the NoRemove value under the uninstallation key. REGDB_UNINSTALL_NOREPAIRThe data of the NoRepair value under the uninstallation key. REGDB_UNINSTALL_PRODUCTGUIDThe data of the ProductGuid value under the uninstallation key. REGDB_UNINSTALL_PRODUCTIDThe data of the ProductId value under the uninstallation key. REGDB_UNINSTALL_PUBLISHERThe data of the Publisher value under the uninstallation key. REGDB_UNINSTALL_READMEThe data of the Readme value under the uninstallation key. REGDB_UNINSTALL_REGCOMPANYThe data of the RegCompany value under the uninstallation key. REGDB_UNINSTALL_REGOWNERThe data of the RegOwner value under the uninstallation key.

1108

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBGetItem

Table D-35: RegDBGetItem Parameters (cont.) Parameter nItem (cont.) Description

REGDB_UNINSTALL_STRINGThe data of the UninstallString value under the uninstallation key. REGDB_UNINSTALL_SYSTEMCOMPONENTThe data of the SystemComponent value under the uninstallation key. REGDB_UNINSTALL_URLINFOABOUTThe data of the URLInfoAbout value under the uninstallation key. REGDB_UNINSTALL_URLUPDATEINFOThe data of the URLUpdateInfo value under the uninstallation key. REGDB_UNINSTALL_VERSIONThe data of the Version value under the uninstallation key. When this constant is used, svValue returns the installed products version number expressed as a string, for example, "16777216". REGDB_WINCURRVER_REGORGANIZATIONThe data of the RegisteredOrganization value under the current version key. REGDB_WINCURRVER_REGOWNERThe data of the RegisteredOwner value under the current version key.

svValue

Returns the value of the item.

Return Values
Table D-36: RegDBGetItem Return Values Return Value 0 <0 Description Indicates that the function successfully retrieved the value of the item. Indicates that the function was unable to retrieve the value of the item.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

Project: In an InstallScript installation, calling RegDBSetItem with REGDB_APPPATH or REGDB_APPPATH_DEFAULT before calling CreateInstallationInfo has no net effect. This is because CreateInstallationInfo overwrites registry information that is created by RegDBSetItem, thus nullifying the call. Calling RegDBSetItem with any other constant before calling MaintenanceStart has no net effect. This is because MaintenanceStart overwrites the registry data created by RegDBSetItem, thus nullifying the call. (In an event-based script, CreateInstallationInfo and MaintenanceStart are called in the default OnMoveData event handler code.) In an InstallScript MSI installation, the uninstallation information is created during file transfer by the Windows Installer. Therefore, if you call RegDBSetItem in an InstallScript MSI installation, you should call it only after file transfer.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1109

Appendix D: Built-In Functions (Q-R) RegDBGetItem

RegDBGetItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBSetItem and RegDBGetItem functions. * * This script sets several registry keys; then it gets those * keys and displays their current values. * \*--------------------------------------------------------------*/ #define #define #define #define #define #define #define #define #define #define COMPANY_NAME PRODUCT_NAME VERSION_NUMBER PRODUCT_KEY DEINST_KEY APP_DEF_LOG_PATH APP_PATH APP_DEF_PATH UNINSTALL_NAME TITLE "ExampleCompany" "ExampleProduct" "5.00.00" "EXAMPLE.EXE" "ExampleDeinstKey" "C:\\EXAMPLE\\TEMP" "C:\\EXAMPLE" "C:\\EXAMPLE\\TARGET" "ExampleUninstallName" "RegDBSetItem Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBGetItem(HWND); function ExFn_RegDBGetItem(hMSI) STRING svLogFile, svValue, szTitle; begin // Set the root key. RegDBSetDefaultRoot (HKEY_LOCAL_MACHINE); // Set installation and uninstallation information in // order to call RegDBSetItem and RegDBGetItem. InstallationInfo (COMPANY_NAME, PRODUCT_NAME, VERSION_NUMBER, PRODUCT_KEY); DeinstallStart (APP_DEF_LOG_PATH, svLogFile, DEINST_KEY, 0); // Set the value of the application path key in the // registry to the value of szAppPath. if (RegDBSetItem (REGDB_APPPATH, APP_PATH) < 0) then MessageBox ("Unable to set application path key.", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBSetItem set the application " + "path key to %s.", APP_PATH); endif; // Set the value of the application default path key in // the registry to the value of szAppDefPath. if (RegDBSetItem(REGDB_APPPATH_DEFAULT, APP_DEF_PATH) < 0) then MessageBox ("Unable to set application default path key.", SEVERE); else

1110

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBGetKeyValueEx

SprintfBox (INFORMATION, TITLE, "RegDBSetItem set the application " + "default path key to %s.", APP_DEF_PATH); endif; // Set the value of the uninstall name key in the // registry to the value of szUninstallName. if (RegDBSetItem (REGDB_UNINSTALL_NAME, UNINSTALL_NAME) < 0) then MessageBox ("Unable to set uninstall name key.", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBSetItem set the uninstall " + "name key to %s.", UNINSTALL_NAME); endif; // Set up title parameter for call to SprintfBox. szTitle = "RegDBGetItem"; // Get the value of the application path key from the registry. if (RegDBGetItem (REGDB_APPPATH, svValue) < 0) then MessageBox ("Unable to get value of application path key.", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBGetItem retrieved the value " + "of the application path key: %s.", svValue); endif; // Get the value of the application default path key in // the registry. if (RegDBGetItem (REGDB_APPPATH_DEFAULT, svValue) < 0) then MessageBox ("Unable to get application default path key", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBGetItem retrieved the value " + "of the application default path key: %s.", svValue); endif; // Get the value of the uninstall name key from the registry. if (RegDBGetItem (REGDB_UNINSTALL_NAME, svValue) < 0) then MessageBox ("Unable to get application uninstall name key.", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBGetItem retrieved the value " + "of the uninstallation name key: %s.", svValue); endif; end;

RegDBGetKeyValueEx
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBGetKeyValueEx function retrieves the value of a particular value name under a specified key in the registry. By default, InstallShield assumes this key is a subkey of HKEY_CLASSES_ROOT. You can use RegDBSetDefaultRoot to specify another root key.
RegDBGetKeyValueEx is a general registry-related function, designed to work with all registry keys,

including those handled by the special registry-related functions.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1111

Appendix D: Built-In Functions (Q-R) RegDBGetKeyValueEx

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBGetKeyValueEx ( szKey, szName, nvType, svValue, nvSize );

1112

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBGetKeyValueEx

Parameters
Table D-37: RegDBGetKeyValueEx Parameters Parameter szKey Description Specifies the name of the key whose value is to be retrieved. Separate different levels in the subkey with a double backslash (\\). Specifies the value name under szKey of the value to retrieve. To retrieve the default value of the key, pass a null string (""). Returns one of the following predefined constants, which identifies the type of data returned in svValue:

szName

nvType

REGDB_STRINGString variable, no newline characters allowed. REGDB_STRING_EXPANDString variable holding an expandable environment variable expression such as "%MYPATH%". REGDB_STRING_MULTIString variable, newline characters allowed. REGDB_NUMBERNumber expressed as a string and passed in a string variable. REGDB_BINARYBinary data stored in a string.

Note: When data type REGDB_STRING_MULTI is retrieved, use StrGetTokens with null string ("") to parse the multiple null terminated strings into a list of strings. That is, if svValue has the resulting multiple strings after a call to RegDBGetKeyValueEx, StrGetTokens( listID, svValue, "") can be used to parse the strings and put them in a string list (listID). svValue Returns the value that was specified by szKey and svName. Note that a number value is returned as a string. Returns the sizein bytesof the value returned in svValue.

nvSize

Return Values
Table D-38: RegDBGetKeyValueEx Return Values Return Value 0 <0 Description Indicates that the function successfully retrieved the value. Indicates that the function was unable to retrieve the value.

RegDBGetKeyValueEx Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1113

Appendix D: Built-In Functions (Q-R) RegDBGetKeyValueEx

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBSetKeyValueEx and RegDBGetKeyValueEx * functions. * * RegDBCreateKeyEx is called to create a test subkey in the * HKEY_CLASSES_ROOT key. The value of a key is set in integer * form using the REGDB_NUMBER option of the RegDBSetKeyValueEx * function. After this value is set, it is retrieved using * the RegDBGetKeyValueEx function and verified. * \*--------------------------------------------------------------*/ #define TITLE "RegDBSetKeyValueEx & RegDBGetKeyValueEx" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBGetKeyValueEx(HWND); function ExFn_RegDBGetKeyValueEx(hMSI) STRING szKey, szNumName, szNumValue, svNumValue, szTitle, szMsg; NUMBER nType, nSize, nvType, nvSize; begin // Create a key to test. szKey = "TestKey"; if (RegDBCreateKeyEx (szKey, "") < 0) then MessageBox ("RegDBCreateKeyEx failed.", SEVERE); abort; endif; // Set up parameters for call to RegDBSetKeyValueEx. szNumName = "TestValue"; szNumValue = "12345"; nType = REGDB_NUMBER; nSize = -1; // Set a key name and a value associated with it. if (RegDBSetKeyValueEx (szKey, szNumName, nType, szNumValue, nSize) < 0) then MessageBox ("RegDBSetKeyValueEx failed.", SEVERE); abort; else // Display what RegDBSetKeyValueEx has done. szMsg = "%s set to: %s"; SprintfBox (INFORMATION, TITLE, szMsg, szNumName, szNumValue); endif; // Retrieve key value information. if (RegDBGetKeyValueEx (szKey, szNumName, nvType, svNumValue, nvSize) < 0) then MessageBox ("RegDBGetKeyValueEx failed.", SEVERE); else // Check to see if the value returned is the same as the value set. if (nvType != REGDB_NUMBER) then MessageBox ("Type comparison failed.", SEVERE); endif;

1114

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBGetUninstCmdLine

if (svNumValue != szNumValue) then MessageBox ("Subkey value comparison failed.", SEVERE); endif; // Display what RegDBGetKeyValueEx retrieved. szMsg = "%s has value: %s\n\nThis data is %d bytes."; SprintfBox (INFORMATION, TITLE, szMsg, szNumName, svNumValue, nvSize); endif; // Delete the created test key. if (RegDBDeleteKey (szKey) < 0) then MessageBox ("RegDBDeleteKey failed.", SEVERE); endif; end;

RegDBGetUninstCmdLine
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBGetUninstCmdLine function gets the registered command line for the uninstallation that is specified by szUninstallKey and returns the command line in svUninstCmdLine.

Note: The InstallScript engine currently does not support writing or reading Add or Remove Programs information for a product in the 64-bit part of the registry. Therefore, using the REGDB_OPTION_WOW64_64KEY option with the REGDB_OPTIONS system variable is not supported for this registry function. Enabling the REGDB_OPTION_WOW64_64KEY option has no effect on where registry entries are created by this function.

Syntax
RegDBGetUninstCmdLine ( szUninstallKey, svUninstCmdLine );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1115

Appendix D: Built-In Functions (Q-R) RegDBKeyExist

Parameters
Table D-39: RegDBGetUninstCmdLine Parameters Parameter szUninstallKey Description Specifies the name of a subkey under the target registry's <root key>\Software\Microsoft\Windows\CurrentVersion\Uninstall key; the function first checks for the subkey under the root key HKEY_CURRENT_USER, and if it does not find the subkey there, it checks under HKEY_LOCAL_MACHINE. For setups created with InstallShield Professional 5.53 or earlier, this is typically the name of the application; for setups created with InstallShield Professional 6.0 or later, this is the application's product GUID including the surrounding braces ({}). Returns the uninstallation command line that is specified in szUninstallKey's UninstallString value's data.

svUninstCmdLine

Return Values
Table D-40: RegDBGetUninstCmdLine Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description The function successfully got the command line. The function failed to get the command line.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBKeyExist
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBKeyExist function checks for the existence of a specific key in the registry. By default, InstallShield assumes this key is a subkey of HKEY_CLASSES_ROOT. If you want to use a different main key, use RegDBSetDefaultRoot to specify another root key. RegDBKeyExist is a general registry-related function, designed to work with all registry keys, including those handled by the special registry-related functions. For more information on special registry-related functions, see Special Registry-Related Functions.

1116

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBKeyExist

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBKeyExist ( szSubKey );

Parameters
Table D-41: RegDBKeyExist Parameters Parameter szSubKey Description Specifies the name of the key to find. You do not have to include the HKEY_CLASSES_ROOT key (or another root key you specified) in this parameter. Separate different levels in the subkey with a double backslash (\\).

Return Values
Table D-42: RegDBKeyExist Return Values Return Value 1 Description Indicates that the function found the key name in the registry. Indicates that the function was unable to find the key name in the registry.

<0

This function never returns zero (0).

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBKeyExist Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1117

Appendix D: Built-In Functions (Q-R) RegDBKeyExist

* * Demonstrates the RegDBCreateKeyEx and RegDBKeyExist functions. * * First, RegDBCreateKeyEx is called to create a subkey with no * class value in the HKEY_CLASSES_ROOT key. Then, RegDBKeyExist * is then called to check if the key was created. * * RegDBCreateKey is called again to create a multi-level subkey * with a class value associated with it under HKEY_CLASSES_ROOT. * Then RegDBKeyExist is called again to check for the existence * of the new key. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "RegDBCreateKeyEx & RegDBKeyExist" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBKeyExist(HWND); function ExFn_RegDBKeyExist(hMSI) STRING szKey, szClass, szKeyRoot, szMsg, svLogFile; NUMBER nResult1, nResult2; begin // Create a key with no class value. szKey = "CreateKeyExample"; szClass = ""; if (RegDBCreateKeyEx(szKey, szClass) < 0) then MessageBox ("First call to RegDBCreateKeyEx failed.", SEVERE); abort; else SprintfBox (INFORMATION, TITLE_TEXT, "Successfully created: %s", szKey); // Check to see if the key just created exists. if (RegDBKeyExist (szKey) < 0) then MessageBox ("First call to RegDBKeyExist failed.", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, "%s exists.", szKey); endif; endif; if (RegDBDeleteKey (szKey) < 0) then MessageBox ("RegDBDeleteKey failed.", SEVERE); endif; // Create szKey szClass szKeyRoot a = = = key with more than one sublevel and a class value. "ShareWare\\Games\\CoolChess"; "LastPlayed"; "ShareWare";

if (RegDBCreateKeyEx(szKey, szClass) < 0) then MessageBox ("Second call to RegDBCreateKeyEx failed.", SEVERE); abort; else SprintfBox (INFORMATION, TITLE_TEXT, "Successfully created: %s", szKey); // Check if the newly created multi-level key exists. if (RegDBKeyExist (szKeyRoot) < 0) then MessageBox ("Second call to RegDBKeyExist failed.", SEVERE);
1118 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBQueryKey

else SprintfBox (INFORMATION, TITLE_TEXT, "%s exists.", szKey); endif; endif; if (RegDBDeleteKey (szKey) < 0) then MessageBox ("RegDBDeleteKey failed.", SEVERE); endif; end;

RegDBQueryKey
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBQueryKey function allows users to query a key for its subkeys and value names. The keys can be enumerated dynamically at run time using this function. RegDBQueryKey is a general registryrelated function, designed to work with all registry keys, including those handled by the special registryrelated functions.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBQueryKey ( szSubKey, nItem, listResults );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1119

Appendix D: Built-In Functions (Q-R) RegDBQueryKey

Parameters
Table D-43: RegDBQueryKey Parameters Parameter szSubKey Description Specifies subkeys under one of the root keys that were set by a previous call to RegDBSetDefaultRoot. Use backslashes to specify deeper levels of subkeys. To retrieve the root key, pass a null string (). Specifies which items should be placed in the list. Pass one of the following predefined constants in this parameter:

nItem

listResults

REGDB_KEYSThe string list returned in listResults will contain a list of all the subkeys under this key. REGDB_NAMESThe string list returned in listResults will contain the names of all named values for this key.

Returns the results of the query in a string list. The list identified by listResults must already have been initialized by a call to ListCreate.

Return Values
Table D-44: RegDBQueryKey Return Values Return Value 0 <0 Description Indicates function was successful. Indicates function failed.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBQueryKey Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBQueryKey function. * * First, RegDBQueryKey is called to query the subkeys under the * key KEY1. The list returned by RegDBQueryKey is displayed

1120

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBQueryKey

* in a dialog. * * Then RegDBQueryKey is called to query the subkeys under the * key KEY2. This list is also displayed in a dialog. * \*--------------------------------------------------------------*/ #define KEY1 "SOFTWARE" #define KEY2 "SOFTWARE\\Microsoft" #define TITLE "RegDBQueryKey Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBQueryKey(HWND); function ExFn_RegDBQueryKey(hMSI) STRING szMsg; NUMBER nReturn, nItem; LIST listSubKeys, listNames; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Create the lists to hold values returned by RegDBQueryKey. listSubKeys = ListCreate(STRINGLIST); listNames = ListCreate(STRINGLIST); if ((listNames = LIST_NULL) || (listSubKeys = LIST_NULL)) then MessageBox ("Unable to create necessary lists.", SEVERE); abort; endif; RegDBSetDefaultRoot(HKEY_LOCAL_MACHINE); // Get the list of subkeys. nReturn = RegDBQueryKey(KEY1, REGDB_KEYS, listSubKeys ); if (nReturn < 0) then MessageBox("First call to RegDBQueryKey failed.", SEVERE); else szMsg = "Subkeys under " + KEY1 + " key:"; SdShowInfoList(TITLE, szMsg, listSubKeys ); endif; // Get the list of subkeys. nReturn = RegDBQueryKey(KEY2, REGDB_NAMES, listNames); if (nReturn < 0) then MessageBox("Second call to RegDBQueryKey failed.", SEVERE); else szMsg = "Named values under " + KEY2 + " key"; SdShowInfoList(TITLE, szMsg, listNames); endif; // Remove the lists from memory. ListDestroy (listNames); ListDestroy (listSubKeys ); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1121

Appendix D: Built-In Functions (Q-R) RegDBQueryKeyCount

RegDBQueryKeyCount
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBQueryKeyCount function returns the number of subkeys or values under szKey. nItem specifies whether subkeys or values are counted.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBQueryKeyCount ( szKey, nItem );

1122

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBQueryStringMultiStringCount

Parameters
Table D-45: RegDBQueryKeyCount Parameters Parameter szKey Description Specifies a key under the root key that was set by a previous call to RegDBSetDefaultRoot. Use backslashes to specify deeper levels of subkeys. To specify the root key, pass a null string (""). Specifies which items should be counted. Pass one of the following predefined constants in this parameter:

nItem

REGDB_KEYSThe number of subkeys is returned. REGDB_NAMESThe number of values is returned.

Return Values
Table D-46: RegDBQueryKeyCount Return Values Return Value X < ISERR_SUCCESS Description The number of items of the specified type under the specified key. Indicates that the function could not determine the number of items. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
RegDBQueryKeyCount is a general registry-related function, designed to work with all registry keys, including those handled by the special registry-related functions. For more information on special registry-related functions, see Special Registry-Related Functions.

By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>" in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBQueryStringMultiStringCount
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBQueryStringMultiStringCount function returns the number of strings contained in the multistring value specified by szValue under the key specified by szKey.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1123

Appendix D: Built-In Functions (Q-R) RegDBQueryStringMultiStringCount

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBQueryStringMultiStringCount ( szKey, szValue );

Parameters
Table D-47: RegDBQueryStringMultiStringCount Parameters Parameter szKey Description Specifies a key under the root key that was set by a previous call to RegDBSetDefaultRoot. Use backslashes to specify deeper levels of subkeys. To specify the root key, pass a null string (""). Specifies the multistring value under szKey to check.

szValue

Return Values
Table D-48: RegDBQueryStringMultiStringCount Return Values Return Value X Description The number of substrings in the specified multistring value under the specified key. Indicates that the function could not determine the number of substrings. You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

< ISERR_SUCCESS

Additional Information
RegDBQueryStringMultiStringCount is a general registry-related function, designed to work with all registry keys, including those handled by the special registry-related functions. For more information on special registry-related functions, see Special Registry-Related Functions.

By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>" in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

1124

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBSetAppInfo

RegDBSetAppInfo
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBSetAppInfo function sets the value of a particular value name under the application information key in the registry. RegDBSetAppInfo is a special registry-related function, designed to work with certain predefined registry keys.

Note: The InstallScript engine currently does not support writing or reading Add or Remove Programs information for a product in the 64-bit part of the registry. Therefore, using the REGDB_OPTION_WOW64_64KEY option with the REGDB_OPTIONS system variable is not supported for this registry function. Enabling the REGDB_OPTION_WOW64_64KEY option has no effect on where registry entries are created by this function.

Syntax
RegDBSetAppInfo ( szName, nType, szValue, nSize );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1125

Appendix D: Built-In Functions (Q-R) RegDBSetAppInfo

Parameters
Table D-49: RegDBSetAppInfo Parameters Parameter szName nType Description Specifies the value name whose information is to be set. Specifies the type of data you are setting. Pass one of the following predefined constants in this parameter:

szValue nSize

REGDB_STRINGString variable, no newline characters allowed. REGDB_STRING_EXPANDString variable holding an expandable environment variable expression, such as "%MYPATH%". REGDB_STRING_MULTIString variable, newline characters allowed. REGDB_NUMBERNumber expressed as a string and passed in a string variable. REGDB_BINARYBinary data stored in a string.

Specifies the value to set for the value name. Specifies the size, in bytes, of the data passed to RegDBSetAppInfo. Pass -1 in this parameter to indicate that InstallShield should determine the size of the data.

Return Values
Table D-50: RegDBSetAppInfo Return Values Return Value 0 Description Indicates that the function successfully assigned the value to the value name. Indicates that the function was unable to assign the value.

<0

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBSetAppInfo Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

1126

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBSetAppInfo

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBSetAppInfo and RegDBGetAppInfo functions. * * Before calling either of these functions, you must call * InstallationInfo to set the application information. * \*--------------------------------------------------------------*/ #define #define #define #define #define #define #define #define COMPANY_NAME PRODUCT_NAME PRODUCT_VERSION PRODUCT_KEY DEINSTALL_KEY UNINSTALL_NAME DEFAULT_LOG_PATH TITLE "Example_Company" "Example_App" "5.0" "EXAMPLE.EXE" "Example_DeinstKey" "Example_App_5.0" "EXAMPLE" "RegDBGetAppInfo"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBSetAppInfo(HWND); function ExFn_RegDBSetAppInfo(hMSI) STRING szStrName, szStrValue, svStrValue, szTitle, szMsg, svLogFile; NUMBER nvSize, nvType; begin // Set the root key. RegDBSetDefaultRoot (HKEY_LOCAL_MACHINE); // Set the name to be used with REGDB_STRING. szStrName = "ExampleStringValue"; szStrValue = "ExampleStringSetting"; // Set up the application information prior to using RegDBSetAppInfo // and RegDBGetAppInfo. InstallationInfo (COMPANY_NAME, PRODUCT_NAME, PRODUCT_VERSION, PRODUCT_KEY); DeinstallStart(DEFAULT_LOG_PATH, svLogFile, DEINSTALL_KEY, 0); // Set value of type REGDB_STRING if (RegDBSetAppInfo (szStrName, REGDB_STRING, szStrValue, -1) < 0) then MessageBox ("Failed to set key and value of REGDB_STRING type.", SEVERE); abort; endif; // RegDBGetAppInfo is called to return the values and compare all the setup // parameters. if (RegDBGetAppInfo (szStrName, nvType, svStrValue, nvSize) < 0) then MessageBox ("Failed to get application information value.", SEVERE); abort; else // Check to see if the value retrieved is the same as the value set. if (nvType != REGDB_STRING) then MessageBox ("Type comparison failed.", WARNING); endif; if (szStrValue != svStrValue) then MessageBox ("Sub key value comparison Failed.", WARNING); else
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1127

Appendix D: Built-In Functions (Q-R) RegDBSetDefaultRoot

szMsg = "Set values: %s = %s\n\nReturn values: %s = %s"; SprintfBox (INFORMATION, TITLE, szMsg, szStrName, szStrValue, szStrName, svStrValue); endif; if (nvSize != StrLength(szStrValue)) then MessageBox ("Size Comparison failed.", WARNING); else szMsg = "Size in bytes entered: %d\n\nSize in bytes returned: %d"; SprintfBox (INFORMATION, TITLE, szMsg, nvSize, StrLength(szStrValue) + 1); endif; endif; end;

RegDBSetDefaultRoot
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBSetDefaultRoot function sets the root key that is used by the general registry-related functions. Most InstallScript registry functions work on the HKEY_CLASSES_ROOT as the default registry hive. Using this function, you can specify another key, such as HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, or HKEY_USERS, as the root key. You cannot use RegDBSetDefaultRoot to change the root key of keys created or handled using the special registry-related functions. For more information, see Special Registry-Related Functions.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBSetDefaultRoot ( nRootKey );

1128

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBSetDefaultRoot

Parameters
Table D-51: RegDBSetDefaultRoot Parameters Parameter nRootKey Description Specify one of the following constants for the root key:

HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE HKEY_USERS HKEY_CURRENT_CONFIG HKEY_DYN_DATA HKEY_USER_SELECTABLE

If you pass HKEY_USER_SELECTABLE as the argument, a subsequent registry function call uses HKEY_LOCAL_MACHINE as the root key if the ALLUSERS system variable is non-zero when the function is called, or uses HKEY_CURRENT_USER as the root key if ALLUSERS is FALSE when the function is called.

Note: Windows does not allow the creation of a key directly under HKEY_LOCAL_MACHINE or HKEY_USERS.

Return Values
Table D-52: RegDBSetDefaultRoot Return Values Return Value 0 <0 Description Indicates that the function successfully set the key. Indicates that the function was unable to set the key.

RegDBSetDefaultRoot Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBSetDefaultRoot function. * * RegDBSetDefaultRoot is called to set the default root key for * the RegDBCreateKeyEx function. *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1129

Appendix D: Built-In Functions (Q-R) RegDBSetDefaultRoot

* Note: Windows does not allow the creation of a key * directly under HKEY_LOCAL_MACHINE or HKEY_USERS. * \*--------------------------------------------------------------*/ #define TITLE "RegDBSetDefaultRoot Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBSetDefaultRoot(HWND); function ExFn_RegDBSetDefaultRoot(hMSI) STRING szKey, szClass, szMsg, szTitle; NUMBER nRootKey; begin // Create a subkey in the HKEY_CLASSES_ROOT key (default). szKey = "Test Key"; szClass = ""; if (RegDBCreateKeyEx (szKey, szClass) < 0) then MessageBox ("RegDBCreateKeyEx failed.", SEVERE); abort; else szMsg = "Successfully created %s in HKEY_CLASSES_ROOT."; SprintfBox (INFORMATION, TITLE, szMsg, szKey); endif; // Set the root key to HKEY_LOCAL_MACHINE. nRootKey = HKEY_LOCAL_MACHINE; if (RegDBSetDefaultRoot (nRootKey) < 0) then MessageBox ("First call to RegDBSetDefaultRoot failed.", SEVERE); else MessageBox ("Root key successfully set to HKEY_LOCAL_MACHINE.", INFORMATION); endif; // Create a subkey in the HKEY_LOCAL_MACHINE key. if (RegDBCreateKeyEx (szKey, szClass) < 0) then MessageBox ("RegDBCreateKeyEx failed.", SEVERE); abort; else szMsg = "Successfully created %s in HKEY_LOCAL_MACHINE"; SprintfBox (INFORMATION, TITLE, szMsg, szKey); endif; // Delete the example subkey in HKEY_LOCAL_MACHINE. if (RegDBDeleteKey (szKey) < 0) then MessageBox ("RegDBDeleteKey failed.", SEVERE); else szMsg = "Successfully deleted %s in HKEY_LOCAL_MACHINE"; SprintfBox (INFORMATION, TITLE, szMsg, szKey); endif; // Set the root key to HKEY_CLASSES_ROOT again. nRootKey = HKEY_CLASSES_ROOT; if (RegDBSetDefaultRoot (nRootKey) < 0) then MessageBox ("Second call to RegDBSetDefaultRoot failed.", SEVERE); else
1130 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBSetItem

MessageBox ("Root key successfully set to HKEY_CLASSES_ROOT.", INFORMATION); endif; if (RegDBDeleteKey (szKey) < 0) then MessageBox ("RegDBDeleteKey failed.", SEVERE); else szMsg = "Successfully deleted %s in HKEY_CLASSES_ROOT"; SprintfBox (INFORMATION, TITLE, szMsg, szKey); endif; end;

RegDBSetItem
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service. RegDBSetItem is a special registry-related function, designed to work with certain predefined registry keys. The RegDBSetItem function assigns values under the per application paths key or the application uninstallation key, depending on the value of nItem. Calling RegDBSetItem with either the

REGDB_APPPATH or the REGDB_APPPATH_DEFAULT option results in the creation of the per application paths key.

Note: The InstallScript engine currently does not support writing or reading Add or Remove Programs information for a product in the 64-bit part of the registry. Therefore, using the REGDB_OPTION_WOW64_64KEY option with the REGDB_OPTIONS system variable is not supported for this registry function. Enabling the REGDB_OPTION_WOW64_64KEY option has no effect on where registry entries are created by this function.

Syntax
RegDBSetItem ( nItem, szValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1131

Appendix D: Built-In Functions (Q-R) RegDBSetItem

Parameters
Table D-53: RegDBSetItem Parameters Parameter nItem Description Specifies the item to set. Pass one of the following predefined constants in this parameter:

REGDB_APPPATHThe data of the Path value under the per-application paths key. This key is created by the installation as a result of calling CreateInstallationInfo. You must call CreateInstallationInfo to create this key before calling RegDBSetItem. (In an event-based script, CreateInstallationInfo is called in the default OnMoveData event handler code.) REGDB_APPPATH_DEFAULTThe data of the DefaultPath value under the per-application paths key. This key is created by the installation as a result of calling CreateInstallationInfo. You must call CreateInstallationInfo to create this key before calling RegDBSetItem. (In an event-based script, CreateInstallationInfo is called in the default OnMoveData event handler code.) REGDB_UNINSTALL_COMMENTSThe data of the Comments value under the uninstallation key. REGDB_UNINSTALL_CONTACTThe data of the Contact value under the uninstallation key. REGDB_UNINSTALL_DISPLAY_VERSIONThe data of the DisplayVersion value under the uninstallation key. REGDB_UNINSTALL_DISPLAYICONThe data of the DisplayIcon value under the uninstallation key. REGDB_UNINSTALL_HELPLINKThe data of the HelpLink value under the uninstallation key. REGDB_UNINSTALL_HELPTELEPHONEThe data of the HelpTelephone value under the uninstallation key. REGDB_UNINSTALL_INSTALLDATEThe data of the InstallDate value under the uninstallation key. REGDB_UNINSTALL_INSTALLLOCThe data of the InstallLocation value under the uninstallation key. REGDB_UNINSTALL_INSTALLSOURCEThe data of the InstallSource value under the uninstallation key. REGDB_UNINSTALL_LANGUAGEThe data of the Language value under the uninstallation key. REGDB_UNINSTALL_LOGFILEThe data of the LogFile value under the uninstallation key. REGDB_UNINSTALL_MAINT_OPTIONThe data of the LogMode value under the uninstallation key.

1132

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBSetItem

Table D-53: RegDBSetItem Parameters (cont.) Parameter nItem (cont.) Description

REGDB_UNINSTALL_MAJOR_VERSIONThe data of the VersionMajor value under the uninstallation key. REGDB_UNINSTALL_MAJOR_VERSION_OLDThe data of the MajorVersion value under the uninstallation key. REGDB_UNINSTALL_MINOR_VERSIONThe data of the VersionMinor value under the uninstallation key. REGDB_UNINSTALL_MINOR_VERSION_OLDThe data of the MinorVersion value under the uninstallation key. REGDB_UNINSTALL_MODIFYPATHThe data of the ModifyPath value under the uninstallation key. REGDB_UNINSTALL_NAMEThe data of the DisplayName value under the uninstallation key. When this constant is used, szValue specifies the application name shown in the list of uninstallable applications in the Control Panel. In an InstallScript or InstallScript MSI project, an easier way to set this value is to set the system variable UNINSTALL_DISPLAYNAME directly.

REGDB_UNINSTALL_NOMODIFYThe data of the NoModify value under the uninstallation key. REGDB_UNINSTALL_NOREMOVEThe data of the NoRemove value under the uninstallation key. REGDB_UNINSTALL_NOREPAIRThe data of the NoRepair value under the uninstallation key. REGDB_UNINSTALL_PRODUCTGUIDThe data of the ProductGuid value under the uninstallation key. REGDB_UNINSTALL_PRODUCTIDThe data of the ProductId value under the uninstallation key. REGDB_UNINSTALL_PUBLISHERThe data of the Publisher value under the uninstallation key. REGDB_UNINSTALL_READMEThe data of the Readme value under the uninstallation key. REGDB_UNINSTALL_REGCOMPANYThe data of the RegCompany value under the uninstallation key. REGDB_UNINSTALL_REGOWNERThe data of the RegOwner value under the uninstallation key.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1133

Appendix D: Built-In Functions (Q-R) RegDBSetItem

Table D-53: RegDBSetItem Parameters (cont.) Parameter nItem (cont.) Description

REGDB_UNINSTALL_STRINGThe data of the UninstallString value under the uninstallation key. The UninstallString value is created when the MaintenanceStart or DeinstallStart functions are called. REGDB_UNINSTALL_SYSTEMCOMPONENTThe data of the SystemComponent value under the uninstallation key. REGDB_UNINSTALL_URLINFOABOUTThe data of the URLInfoAbout value under the uninstallation key. REGDB_UNINSTALL_URLUPDATEINFOThe data of the URLUpdateInfo value under the uninstallation key. REGDB_UNINSTALL_VERSIONThe data of the Version value under the uninstallation key. When this constant is used, szValue specifies the installed product's version number expressed as a string, for example, "16777216".

Important: Do not use REGDB_WINCURRVER_REGOWNER or REGDB_WINCURRVER_REGORGANIZATION with this function. Windows sets these values, and they should not be set by an installation. szValue Specifies the value to assign to the specified item.

Return Values
Table D-54: RegDBSetItem Return Values Return Value 0 <0 Description Indicates that the function successfully set the value. Indicates that the function failed.

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBSetItem Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ *

1134

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBSetItem

* InstallShield Example Script * * Demonstrates the RegDBSetItem and RegDBGetItem functions. * * This script sets several registry keys; then it gets those * keys and displays their current values. * \*--------------------------------------------------------------*/ #define COMPANY_NAME #define PRODUCT_NAME #define VERSION_NUMBER #define PRODUCT_KEY #define DEINST_KEY #define APP_DEF_LOG_PATH #define APP_PATH #define APP_DEF_PATH #define UNINSTALL_NAME #define TITLE "ExampleCompany" "ExampleProduct" "5.00.00" "EXAMPLE.EXE" "ExampleDeinstKey" "C:\\EXAMPLE\\TEMP" "C:\\EXAMPLE" "C:\\EXAMPLE\\TARGET" "ExampleUninstallName" "RegDBSetItem Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBSetItem(HWND); function ExFn_RegDBSetItem(hMSI) STRING svLogFile; STRING svValue, szTitle; begin // Set the root key. RegDBSetDefaultRoot (HKEY_LOCAL_MACHINE); // Set installation and uninstallation information in // order to call RegDBSetItem and RegDBGetItem. InstallationInfo (COMPANY_NAME, PRODUCT_NAME, VERSION_NUMBER, PRODUCT_KEY); DeinstallStart (APP_DEF_LOG_PATH, svLogFile, DEINST_KEY, 0); // Set the value of the application path key in the // registry to the value of szAppPath. if (RegDBSetItem (REGDB_APPPATH, APP_PATH) < 0) then MessageBox ("Unable to set application path key.", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBSetItem set the application " + "path key to %s.", APP_PATH); endif; // Set the value of the application default path key in // the registry to the value of szAppDefPath. if (RegDBSetItem(REGDB_APPPATH_DEFAULT, APP_DEF_PATH) < 0) then MessageBox ("Unable to set application default path key.", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBSetItem set the application " + "default path key to %s.", APP_DEF_PATH); endif; // Set the value of the uninstall name key in the // registry to the value of szUninstallName. if (RegDBSetItem (REGDB_UNINSTALL_NAME, UNINSTALL_NAME) < 0) then MessageBox ("Unable to set uninstall name key.", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBSetItem set the uninstall " +
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1135

Appendix D: Built-In Functions (Q-R) RegDBSetKeyValueEx

"name key to %s.", UNINSTALL_NAME); endif; // Set up title parameter for call to SprintfBox. szTitle = "RegDBGetItem"; // Get the value of the application path key from the registry. if (RegDBGetItem (REGDB_APPPATH, svValue) < 0) then MessageBox ("Unable to get value of application path key.", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBGetItem retrieved the value " + "of the application path key: %s.", svValue); endif; // Get the value of the application default path key in // the registry. if (RegDBGetItem (REGDB_APPPATH_DEFAULT, svValue) < 0) then MessageBox ("Unable to get application default path key", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBGetItem retrieved the value " + "of the application default path key: %s.", svValue); endif; // Get the value of the uninstall name key from the registry. if (RegDBGetItem (REGDB_UNINSTALL_NAME, svValue) < 0) then MessageBox ("Unable to get application uninstall name key.", SEVERE); else SprintfBox (INFORMATION, TITLE, "RegDBGetItem retrieved the value " + "of the uninstallation name key: %s.", svValue); endif; end;

RegDBSetKeyValueEx
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBSetKeyValueEx function sets the value of a particular value name under a specified key in the registry. If the value name does not already exist, RegDBSetKeyValueEx creates it. If the value data already exists, RegDBSetKeyValueEx overwrites it. If the key does not already exist, RegDBSetKeyValueEx calls RegDBCreateKeyEx, passing the key from the szKey parameter to create it.
RegDBSetKeyValueEx is a general registry-related function, designed to work with all registry keys, including those handled by the special registry-related functions.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

1136

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBSetKeyValueEx

Syntax
RegDBSetKeyValueEx ( szKey, szName, nType, szValue, nSize );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1137

Appendix D: Built-In Functions (Q-R) RegDBSetKeyValueEx

Parameters
Table D-55: RegDBSetKeyValueEx Parameters Parameter szKey Description Specifies the name of the key. Separate different levels in the subkey with a double backslash (\\). If the root key is HKEY_CLASSES_ROOT, you do not need to specify the HKEY_CLASSES_ROOT in this parameter. Unless you specify otherwise, the InstallScript engine assumes that the value that is being set is under the key HKEY_CLASSES_ROOT. To specify a different root key, you can call RegDBSetDefaultRoot before calling RegDBSetKeyValueEx. szName Specifies the value name for the value data to set be set. To set the default value of the key specified in szKey, pass a null string ("") in this parameter. Specifies the type of data to be set. Pass one of the following predefined constants in this parameter:

nType

REGDB_STRINGA string variable; no newline characters allowed. REGDB_STRING_EXPANDA string variable holding an expandable environment variable expression, such as "%MYPATH%". REGDB_STRING_MULTIA string variable; newline characters allowed. REGDB_NUMBERA number expressed as a string and passed in string variable. Creates data of type DWORD. When nType is REGDB_NUMBER, passing a decimal string in szValue results in a numeric value being stored in the registry. This numeric value is then displayed as a hexadecimal number followed by its decimal equivalent in parentheses. You cannot pass a hexadecimal number in the string in szValueit must be a decimal number. REGDB_BINARYBinary data stored in a string.

szValue

Specifies the value to associate with the value name. All values must be passed as string variables. Numbers must be expressed as strings. The InstallScript engine converts them to numbers internally. Specifies the sizein bytesof the data to be set. You can specify -1 in this parameter when nType is REGDB_STRING, REGDB_STRING_EXPAND, or REGDB_NUMBER, and the InstallScript engine will set the size. However, with REGDB_BINARY and REGDB_STRING_MULTI, you must always specify the number of bytes of binary data that you are storing.

nSize

Return Values
Table D-56: RegDBSetKeyValueEx Return Values Return Value 0 <0 Description Indicates that the function successfully set the key. Indicates that the function was unable to set the key.

1138

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegDBSetKeyValueEx

Additional Information
By default, any text that is surrounded by angle bracketsfor example, "<my registry entry text>"in this functions string arguments is interpreted as a text substitution and is processed accordingly. To disable text substitution processing for the string arguments of registry functions, call Disable with the REGISTRYFUNCTIONS_USETEXTSUBS argument.

RegDBSetKeyValueEx Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegDBSetKeyValueEx and RegDBGetKeyValueEx * functions. * * RegDBCreateKeyEx is called to create a test subkey in the * HKEY_CLASSES_ROOT key. The value of a key is set in integer * form using the REGDB_NUMBER option of the RegDBSetKeyValueEx * function. After this value is set, it is retrieved using * the RegDBGetKeyValueEx function and verified. * \*--------------------------------------------------------------*/ #define TITLE "RegDBSetKeyValueEx & RegDBGetKeyValueEx" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RegDBSetKeyValueEx(HWND); function ExFn_RegDBSetKeyValueEx(hMSI) STRING szKey, szNumName, szNumValue, svNumValue, szTitle, szMsg; NUMBER nType, nSize, nvType, nvSize; begin // Create a key to test. szKey = "TestKey"; if (RegDBCreateKeyEx (szKey, "") < 0) then MessageBox ("RegDBCreateKeyEx failed.", SEVERE); abort; endif; // Set up parameters for call to RegDBSetKeyValueEx. szNumName = "TestValue"; szNumValue = "12345"; nType = REGDB_NUMBER; nSize = -1; // Set a key name and a value associated with it. if (RegDBSetKeyValueEx (szKey, szNumName, nType, szNumValue, nSize) < 0) then MessageBox ("RegDBSetKeyValueEx failed.", SEVERE);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1139

Appendix D: Built-In Functions (Q-R) RegDBSetVersion

abort; else // Display what RegDBSetKeyValueEx has done. szMsg = "%s set to: %s"; SprintfBox (INFORMATION, TITLE, szMsg, szNumName, szNumValue); endif; // Retrieve key value information. if (RegDBGetKeyValueEx (szKey, szNumName, nvType, svNumValue, nvSize) < 0) then MessageBox ("RegDBGetKeyValueEx failed.", SEVERE); else // Check to see if the value returned is the same as the value set. if (nvType != REGDB_NUMBER) then MessageBox ("Type comparison failed.", SEVERE); endif; if (svNumValue != szNumValue) then MessageBox ("Subkey value comparison failed.", SEVERE); endif; // Display what RegDBGetKeyValueEx retrieved. szMsg = "%s has value: %s\n\nThis data is %d bytes."; SprintfBox (INFORMATION, TITLE, szMsg, szNumName, svNumValue, nvSize); endif; // Delete the created test key. if (RegDBDeleteKey (szKey) < 0) then MessageBox ("RegDBDeleteKey failed.", SEVERE); endif; end;

RegDBSetVersion
Project: For InstallScript MSI and Basic MSI projects, it is recommended that you use the Registry view in InstallShield instead of creating registry keys and values through InstallScript code. Handling all of your registry changes in this way allows for a clean uninstallation through the Windows Installer service.

The RegDBSetVersion function places the value of the system variable IFX_PRODUCT_VERSION as the data for the Version value under the application uninstallation registry key, creating the registry value if it does not already exist. If IFX_PRODUCT_VERSION is not in packed DWORD format, the function fails.

Note: This function supports the 64-bit parts of the registry by using the REGDB_OPTION_WOW64_64KEY option. For more information, see REGDB_OPTIONS.

Syntax
RegDBSetVersion ( );

1140

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegisterFontResource

Parameters
None.

Return Values
Table D-57: RegDBSetVersion Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description The function successfully placed the data in the registry value. The function failed to place data in the registry.

Additional Information
RegDBSetVersion is called by the default code for the OnMoveData event handler function.

RegisterFontResource
The RegisterFontResource function registers or unregisters the font resource specified by szFileName. This function is called by the default code for the OnInstalledFontFile and OnUninstallingFontFile event handler functions.

Syntax
RegisterFontResource ( szFileName, svFontTitle, bRegister, nOptions );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1141

Appendix D: Built-In Functions (Q-R) RegisterFontResource

Parameters
Table D-58: RegisterFontResource Parameters Parameter szFileName Description Specifies the fully qualified file name of the font file (.fnt, .fon, .fot, .mmm, .otf, .pfb, .pfm, .ttc, or .ttf file) to be registered or unregistered. Typically you would install a font file to FOLDER_FONTS. Only a font file that exists on the target system can be registered, and you must unregister a font file before you remove it from the system. This parameter must be a variable name and not a literal value. When RegisterFontResource is called, this parameter specifies the title for the font, if its value is not a null string (""); when RegisterFontResource returns, this parameter contains the title that was used when registering or unregistering the font file. If the font file being registered or unregistered is a TrueType font file, you can specify in this parameter a string variable whose value is a null string. In this case RegisterFontResource attempts to get the title by internally calling GetTrueTypeFontFileInfo; if this fails, the file name of the font file is used as the title. If the REGFONT_OPTION_DONTUPDATEREGISTRY option is specified in this function's fourth argument, svFontTitle is ignored. bRegister Specifies whether to register the font resource (TRUE) or unregister the font resource (FALSE).

svFontTitle

1142

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RegisterFontResource

Table D-58: RegisterFontResource Parameters (cont.) Parameter nOptions Description Specifies various options. Pass one of the following constants in this parameter, or combine these constants using the OR operator (|):

REGFONT_OPTION_DEFAULTSpecifies that the function has its default behavior. REGFONT_OPTION_DONTBROADCASTFONTCHANGEM SGSpecifies that the function does not send a message to top level windows indicating that font information has changed after registering or registering the font. You should specify this flag only if your installation sends this message manually after calling this function by calling the Windows API function PostMessage as in the following example:
WM_FONTCHANGE,

PostMessage( HWND_BROADCAST, 0, 0 );

You would typically use this flag if you are calling RegisterFontResource multiple times to update multiple fonts and then calling PostMessage.

REGFONT_OPTION_DONTUPDATEREGISTRY Specifies that the function does not add the font registration information to the registry or remove the font information from the registry. If you specify this option for font registration, the font is available only until the next time the system is rebooted. Note that if this option is specified svFontTitle is ignored.

Return Values
Table D-59: RegisterFontResource Return Values Return Value >= ISERR_SUCCESS Description Indicates that the function successfully registered or unregistered the font. Indicates that the function was unable to register or unregister the font.

< ISERR_SUCCESS

Additional Information
Font information is written to HKEY_LOCAL_MACHINE in all cases, so typically in order to install a font the end user must have administrator privileges on the system. The function calls PostMessage instead of SendMessage to send the WM_FONTCHANGE message. This is because SendMessage (when used with HWND_BROADCAST) waits for all open windows to respond to the message before returning, which could cause the installation to freeze if an open window on the system fails to respond to the message. Since the function calls PostMessage, the function could return before Windows has processed the message and released the font from the
ISP-1800-RG00 1143

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) ReleaseDialog

font cache; so when using this function to uninstall fonts, it is recommended that you wait a few seconds (by calling Delay) before removing the font file.

If you call this function in a feature event or a file install event (such as OnInstallingFile or OnInstalledFile) the font registration is associated with the corresponding feature and the font is automatically unregistered before the file or feature is uninstalled.

RegisterFontResource Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RegisterFontResource function. * \*--------------------------------------------------------------*/ function OnBegin() string szFileName, svFontTitle; begin szFileName = FOLDER_FONTS ^ "Estre.ttf"; svFontTitle = "Estrangelo Edessa"; RegisterFontResource ( szFileName, svFontTitle, TRUE, REGFONT_OPTION_DEFAULT ); // If you cut and paste this sample script into a project // and run it, the following line aborts execution of the script. abort; end;

ReleaseDialog
The ReleaseDialog function frees all memory associated with the custom dialog identified in szDialogName. Call this function after calling EndDialog. Call this function outside the messagehandling case statement.

Syntax
ReleaseDialog ( szDialogName );

1144

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) ReleaseDialog

Parameters
Table D-60: ReleaseDialog Parameters Parameter szDialogName Description Specifies the name of the dialog to destroy.

Return Values
Table D-61: ReleaseDialog Return Values Return Value 0 Description Indicates that the function successfully freed all memory associated with the custom dialog. Function failed. The dialog name may be invalid. ReleaseDialog was called before EndDialog. You must call EndDialog first to remove the dialog.

DLG_ERR (-1) DLG_ERR_ENDDLG (-2)

ReleaseDialog Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DefineDialog, EndDialog, and ReleaseDialog * functions. * * This script opens a simple custom dialog that displays * a bitmap. The dialog can be closed with any of three * buttons: Back, Next, or Cancel. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdBitmap. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * * In order to use this dialog as a custom dialog, the * script first defines it by calling DefineDialog. It then * displays the dialog by calling WaitOnDialog. When an event * ends dialog processing, EndDialog is called to close the * dialog. Then the dialog is released from memory by * a call to ReleaseDialog. * \*--------------------------------------------------------------*/

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1145

Appendix D: Built-In Functions (Q-R) ReleaseDialog

// Dialog and control IDs. #define RES_DIALOG_ID 12027 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12

// // // //

ID ID ID ID

of of of of

dialog itself Next button Cancel button Back button

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ReleaseDialog(HWND); function ExFn_ReleaseDialog(hMSI) STRING szDialogName, szDLLName, szDialog; NUMBER nDialog, nResult, nCmdValue; BOOL bDone; HWND hInstance, hwndParent; begin // Define the name of a dialog to pass as first // parameter to DefineDialog. szDialogName = "ExampleDialog"; // DefineDialog's second parameter will be 0 because the // .dll file is in _isres.dll. hInstance = 0; // DefineDialog's third parameter will be null; installation will // search for the dialog in _isuser.dll and _isres.dll. szDLLName = ""; // DefineDialog's fifth parameter will be null because the // dialog is identified by its ID in the fourth parameter. szDialog = ""; // This value is reserved and must be 0. hwndParent = 0; // Define the dialog. The installation's main window will own the // dialog (indicated by HWND_INSTALL in parameter 7). nResult = DefineDialog (szDialogName, hInstance, szDLLName, RES_DIALOG_ID, szDialog, hwndParent, HWND_INSTALL, DLG_MSG_STANDARD|DLG_CENTERED); // Check for an error. if (nResult < 0) then MessageBox ("An error occurred while defining the dialog.", SEVERE); bDone = TRUE; abort; endif; // Initialize the indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog(szDialogName); // Respond to the event. switch (nCmdValue)
1146 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RenameFile

case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory. ReleaseDialog (szDialogName); end;

RenameFile
The RenameFile function changes the name of a file or directory and/or moves a file or directory (and its subdirectories and files) from one parent directory to another.

Note: Note the following:

If szSource and szTarget reference the same directory orwhen using unqualified names, if SRCDIR and TARGETDIR reference the same directory for an InstallScript installation (or if SRCDIR and INSTALLDIR reference the same directory for a Basic MSI or InstallScript MSI installation)the file or directory that is specified by szSource is renamed, unless a file or directory with the name that is specified by szTarget already exists in that directory. If szSource and szTarget reference different directories orwhen using unqualified names, if SRCDIR and TARGETDIR reference different directories for an InstallScript installation (or if SRCDIR and INSTALLDIR reference different directory for a Basic MSI or InstallScript MSI installation)the file or directory that is specified by szSource is moved to the new directory and given the name that is specified by szTarget, unless a file or directory with that name already exists in that directory.

Syntax
RenameFile ( szSource, szTarget );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1147

Appendix D: Built-In Functions (Q-R) RenameFile

Parameters
Table D-62: RenameFile Parameters Parameter szSource Description Specifies the name of the file or directory to be renamed or moved. If szFileOld specifies a fully qualified file name or directory (it includes a path), RenameFile renames or moves the file or directory in the specified directory. If szSource contains an unqualified file name or directory name (without path information), RenameFile renames or moves the file or directory in the directory specified by the system variable SRCDIR.

Note: Wildcard characters are not permitted. Only one file or one directory (including its subdirectories and folders) can be renamed or moved with each call to RenameFile. szTarget Specifies a new name and/or location for the file or directory. If szFileNew specifies a fully qualified file name or directory (it includes a path), RenameFile renames the file or moves it to the specified directory. If szFileNew contains an unqualified file name or directory name (without path information), RenameFile either renames the file or directory, or moves the file or directory to the directory specified by the system variable TARGETDIR (for an InstallScript installation) or the system variable INSTALLDIR (for a Basic MSI or InstallScript MSI installation).

Return Values
Table D-63: RenameFile Return Values Return Value 0 Description Indicates that the function successfully changed the name of the file or directory or moved the file or directory. Indicates that the function was unable to change the name of the file or folder or move the file or folder.

<0

RenameFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RenameFile function. * * First, RenameFile is called to rename FILENAME1 to FILENAME2.

1148

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RenameFile

* It is then called again to move the FILENAME2 file to the * TARGET directory. * * This can also be done in one call to RenameFile. The third * call to RenameFile demonstrates this by renaming and moving * the FILENAME2 file from the TARGET directory to the SOURCE * directory, with the FILENAME1 file name. * * Note: Before running this script, set the preprocessor * constants so that they specify valid file names and * paths on the target system. * \*--------------------------------------------------------------*/ #define #define #define #define #define FILENAME1 FILENAME2 SOURCE_DIR TARGET_DIR TITLE "ISExampl.txt" "ISExampl.bak" "C:\\ISExampl\\Source" "C:\\ISExampl\\Target" "RenameFile Example"

#include "ifx.h" function OnBegin() begin // Set up system variables for rename operation. SRCDIR = SOURCE_DIR; TARGETDIR = SOURCE_DIR; // Rename FILENAME1 to FILENAME2. if (RenameFile (FILENAME1, FILENAME2) < 0) then MessageBox("First call to RenameFile failed.", SEVERE); abort; else szMsg = "%s successfully renamed to %s."; SprintfBox(INFORMATION, szTitle, szMsg, FILENAME1, FILENAME2); endif; // Set up system variables to move a file from one directory to another. SRCDIR = SOURCE_DIR; TARGETDIR = TARGET_DIR; // Move the file from the SOURCE to the TARGET directory. if (RenameFile(FILENAME2, FILENAME2) < 0) then MessageBox("Second call to RenameFile failed.", SEVERE); abort; else szMsg = "%s successfully moved to %s."; SprintfBox(INFORMATION, TITLE, szMsg, FILENAME2, TARGETDIR); endif; // Set up system variables to move the file back to its original location. SRCDIR = TARGET_DIR; TARGETDIR = SOURCE_DIR; // Rename the file and move it from the TARGET directory // to the SOURCE directory. if (RenameFile(FILENAME2, FILENAME1) < 0) then MessageBox("Third call to RenameFile failed.", SEVERE); abort; else
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1149

Appendix D: Built-In Functions (Q-R) ReplaceFolderIcon

szMsg = "%s successfully renamed %s and moved to the directory %s."; SprintfBox(INFORMATION, TITLE, szMsg, FILENAME2, FILENAME1, TARGETDIR); endif; end;

ReplaceFolderIcon
The ReplaceFolderIcon function replaces a shortcut in a specified folder. You must specify an existing folder, either one you have created with the CreateProgramFolder function or one that already exists on the user's system.

Syntax
ReplaceFolderIcon ( szProgramFolder, szItemName, szNewItem, szCmdLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag );

1150

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) ReplaceFolderIcon

Parameters
Table D-64: ReplaceFolderIcon Parameters Parameter szProgramFolder Description Specifies the name of the folder that contains the shortcut to replace. Specifies the name of the shortcut to replace. Specifies the name of the shortcut as it should appear after the replacement. Specifies one of the following:

szItemName szNewItem

szCmdLine

szWorkingDir

The fully qualified name of the executable associated with the icon, including any command-line parameters. The fully qualified path if szItemName is a subfolder.

Specifies the directory where the application's program files are located. (Not applicable if szItemName is a subfolder.) To make the directory that contains the program file the working directory, pass a null string () in this parameter. Specifies the name of an icon file or a valid Windows executable that contains the new icon. Specifies the icon ordinal if you specified a Window executable icon. Otherwise, pass 0 in this parameter. Specifies the string that contains the shortcut key sequence the user can press to start the program. For example, if you wanted the user to be able to open the application by depressing the Ctrl, the Alt, and then the 1 key, specify Ctrl + Alt + 1 in this parameter. Specifies one or more options. Pass the following predefined constants in this parameter. To specify more than one option, combine constants with the OR (|) operator.

szIconPath

nIcon

szShortCutKey

nFlag

NULLIndicates no options. REPLACEIndicates that the existing icon should be replaced with the new icon. RUN_MAXIMIZEDIndicates that the program should be maximized when launched. RUN_MINIMIZEDIndicates that the program should be minimized when launched.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1151

Appendix D: Built-In Functions (Q-R) ReplaceFolderIcon

Return Values
Table D-65: ReplaceFolderIcon Return Values Return Value 0 Description Indicates that the function successfully replaced the shortcut. Indicates that the function was unable to replace the icon. You can obtain the error message text associated with a large negative return valuefor example, 2147024891 (0x80070005)by calling FormatMessage.

<0

ReplaceFolderIcon Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ReplaceFolderIcon function. * * Note: In order for this script to run correctly, you must set * preprocessor constants to valid file names and a path * on the target system. To easily create this example * folder and icon, run the AddFolderIcon example #3. * \*--------------------------------------------------------------*/ #define FOLDER "C:\\Windows\\" #define NEW_PROGRAM "C:\\WINDOWS\\WRITE.EXE" #define NEW_PARAM "C:\\WINDOWS\\README.TXT" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ReplaceFolderIcon(HWND); function ExFn_ReplaceFolderIcon(hMSI) STRING szProgramFolder, szItemName, szNewItem, szCmdLine, szWorkingDir; STRING szShortCutKey, szIconPath, szProgram, szParam; NUMBER nIcon, nFlag; begin szProgramFolder = FOLDER ^ "Example folder"; szItemName = "Notepad Example"; szNewItem = "New Wordpad Example"; // Make sure the space is not seen as a delimiter.

1152

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) ReplaceProfString

szProgram = NEW_PROGRAM; LongPathToQuote (szProgram, TRUE); szParam = NEW_PARAM; LongPathToShortPath(szParam); szCmdLine szWorkingDir szIconPath nIcon szShortCutKey nFlag = = = = = = szProgram + " " + szParam; ""; ""; 0; ""; REPLACE|RUN_MAXIMIZED;

// Display the folder on the screen. ShowProgramFolder (szProgramFolder, SW_SHOW); // Replace the "Notepad Example" icon with "New Wordpad Example". if (ReplaceFolderIcon (szProgramFolder, szItemName, szNewItem, szCmdLine, szWorkingDir, szIconPath, nIcon, szShortCutKey, nFlag) < 0) then MessageBox ("ReplaceFolderIcon failed.", SEVERE); else MessageBox ("Icon successfully replaced.", INFORMATION); endif; end;

ReplaceProfString
In Windows Installer based projects, all .ini file changes should be created in the INI Files view of the IDE. Handling all of your .ini file changes in this way allows for a clean uninstallation through the Windows Installer service. The ReplaceProfString function replaces a profile string in an .ini file. This function can replace values of duplicate keys (non-unique keys) such as those found in the [386Enh] section of the System.ini file (device = ...). The function searches for a szKeyName = szOrigValue, and replaces the line. If it is not found, it adds the szKeyName = szReplaceValue line to the beginning of the szSectionName section. If you are adding unique keys (that is, keys that are all different for a given section), use the WriteProfString function. Use this function to replace only non-unique key names, such as the device= line in the System.ini file.

Syntax
ReplaceProfString ( szFileName, szSectionName, szKeyName, szOrigValue, szReplaceValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1153

Appendix D: Built-In Functions (Q-R) ReplaceProfString

Parameters
Table D-66: ReplaceProfString Parameters Parameter szFileName Description Specifies the name of the .ini file in which the profile string is to be replaced. If the file name is unqualified (that is, if a drive designation and path are not included), InstallShield searches for the file in the Windows folder. If the file does not exist, it is created in the specified folder; if a path is not included in file name, the file is created in the Windows folder. Note that if the file name is qualified with a path that does not exist, ReplaceProfString will fail. Specifies the name of the .ini file section to search for szKeyName. The section name should not be enclosed within delimiting brackets ( [ ] ). The search for this name is not case sensitive. Specifies the name of the key to replace. If the key does not exist, it is created. Specifies the current value of the key specified by szKeyName. Specifies the new value to assign to szKeyName. The value of this parameter will appear to the right of the equal sign in the profile string (szKeyName = szValue).

szSectionName

szKeyName

szOrigValue

szReplaceValue

Return Values
Table D-67: ReplaceProfString Return Values Return Value 0 Description Indicates that the function successfully replaced or added the profile string. Indicates that the function was unable to replace or add the profile string.

<0

Additional Information
Changes made to .ini files can be logged for uninstallation. However, there are some important restrictions to be aware of. For more information, see Uninstalling Initialization (.ini) File Entries.

1154

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) ReplaceProfString

ReplaceProfString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ReplaceProfString function. * * ReplaceProfString is called for the first time to replace * the szKeyName key value szOrigValue with the value * szReplaceValue. Then ReplaceProfString is called again to * replace the newly set value of szKeyName, szReplaceValue, * with szOrigValue. * * NOTE: In order for this script to run properly, you must set * the constant EXAMPLE_INI to reference an existing * initialization file on the target system. That file * should include the following lines: * * [Old Section] * Old Key=Old value * \*--------------------------------------------------------------*/ #define EXAMPLE_INI "C:\\ISExampl.ini" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ReplaceProfString(HWND); function ExFn_ReplaceProfString(hMSI) STRING szSectionName, szKeyName, szOrigValue, szReplaceValue; begin szSectionName szKeyName szOrigValue szReplaceValue = = = = "Old "Old "Old "New Section"; Key"; value"; value";

// Replace szOrigValue with szReplaceValue. if (ReplaceProfString (EXAMPLE_INI, szSectionName, szKeyName, szOrigValue, szReplaceValue) < 0) then MessageBox("ReplaceProfString failed.", SEVERE); abort; else SprintfBox (INFORMATION, "Replacement Successful", "Original: %s\nNew: %s", szOrigValue, szReplaceValue); endif; // Replace szReplaceValue with szOrigValue. if (ReplaceProfString(EXAMPLE_INI, szSectionName, szKeyName, szReplaceValue, szOrigValue) < 0) then; MessageBox("ReplaceProfString failed.", SEVERE); else

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1155

Appendix D: Built-In Functions (Q-R) Resize

SprintfBox (INFORMATION, "Replacement Successful", "Original: %s\nNew: %s", szReplaceValue, szOrigValue); endif; end;

Resize
The Resize operator resizes an InstallScript array.

Syntax
Resize ( Array , nNewSize );

Parameters
Table D-68: Resize Parameters Parameter Array nNewSize Description Specifies the name of the array variable. Specifies the new size to be given to the array.

Return values
This operator returns the new size of the array.

RGB
The RGB function creates a custom color value that can be used with SetColor and SetTitle.

Syntax
RGB ( constRed, constGreen, constBlue );

1156

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix D: Built-In Functions (Q-R) RGB

Parameters
Table D-69: RGB Parameters Parameter constRed Description Specifies a numeric constant, ranging in value from 0 to 255, that indicates the amount of red in the custom color. Specifies a numeric constant, ranging in value from 0 to 255, that indicates the amount of green in the custom color. Specifies a numeric constant, ranging in value from 0 to 255, that indicates the amount of green in the custom color.

constGreen

constBlue

Return Values
This function returns a number value for a custom color that can be used when calling SetColor and SetTitle.

RGB Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the RGB function. * * The first call to RGB returns the value of the background * color to Grey; the second call returns the background color * to red; the third call returns the background color to blue. * The values returned by the calls to RGB are passed to * SetColor to change the background color. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_RGB(HWND); function ExFn_RGB(hMSI) begin Enable ( BACKGROUND ); // Change the background color to light grey. SetColor (BACKGROUND, RGB(198,198,198));
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1157

Appendix D: Built-In Functions (Q-R) RGB

Delay (3); // Change the background color to red. SetColor (BACKGROUND, RGB(255,0,0)); Delay (3); // Change the background color to blue. SetColor (BACKGROUND, RGB(0, 0, 255)); Delay (3); end;

1158

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

E
Built-In Functions (S-T)
For a list of functions by category, see Built-In Functions by Category.

SdAskDestPath
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdAskDestPath function creates a dialog that allows the end user to select an alternate destination path. When the end user clicks Browse in this dialog, the SelectDir function is called to open a second dialog that enables the end user either to select an existing folder or to enter a new folder name.

Syntax
SdAskDestPath ( szTitle, szMsg, svDir, nReserved );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1159

Appendix E: Built-In Functions (S-T) SdAskDestPath

Parameters
Table E-1: SdAskDestPath Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Choose Folder), pass a null string () in this parameter. Specifies the text to display in the dialog. The text is considered a static control. Use the %P place holder in your message string to insert the product name (if any) that has been specified by a previous call to SdProductName. To display the default instructions for this dialog, pass a null string (""). Specifies the name of the directory to be selected by default. Returns the name of the directory selected by the end user. Pass zero in this parameter. No other value is allowed.

szMsg

svDir

nReserved

Return Values
Table E-2: SdAskDestPath Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. If the end user specifies an incomplete, invalid, or write-protected path in the second dialog, an error message is displayed. If you want the end user to be able to select folders that are not writable, call the AskPath function instead. Setups that run in silent mode should create the new folder if it does not exist before calling SdAskDestPath. This ensures that the confirmation dialog is not displayed. Without this step, two response files are required to handle the two possible conditions. In earlier versions of InstallShield Professional, when the end user selected in the Choose Folder dialog a folder that did not exist, a confirmation message box was displayed asking whether the folder should be created. This message box proved to be confusing to many end users, so it has been removed from InstallShield.

1160

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdAskDestPath2

SdAskDestPath Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdAskDestPath function. * * SdAskDestPath is called to prompt the user for a path. * Then the selected path is assigned to the system variable * INSTALLDIR, which is displayed in a message box. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "SdAskDestPath Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" function OnBegin() STRING svDir; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set default folder name for call to SdAskDestPath. svDir = "C:\\ISEXampl\\Target"; // Display the SdAskDestPath dialog. Pass a null string // in the second parameter to display the default message. if (SdAskDestPath (TITLE_TEXT, "", svDir, 0) = NEXT) then INSTALLDIR = svDir; endif; // Display the new target directory. SprintfBox (INFORMATION, "SdAskDestPath", "Successful.\n\nThe Target " + "directory is: " + INSTALLDIR); end;

SdAskDestPath2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1161

Appendix E: Built-In Functions (S-T) SdAskDestPath2

The SdAskDestPath function creates a dialog that allows the end user to select an alternate destination path. When you click the Change button in that dialog, the SelectDir function is called to open a second dialog that enables the end user either to select an existing folder or to enter a new folder name.

Syntax
SdAskDestPath2 ( szTitle, szMsg, svDir );

Parameters
Table E-3: SdAskDestPath2 Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title ("Choose Destination Location"), pass a null string ("") in this parameter. Specifies the text to display in the dialog. The text is considered a static control. Use the %P place holder in your message string to insert the product name (if any) that has been specified by a previous call to SdProductName. To display the default instructions for this dialog, pass a null string (""). Specifies the name of the directory to be selected by default. Returns the name of the directory selected by the end user.

szMsg

svDir

Return Values
Table E-4: SdAskDestPath2 Return Values Return Value NEXT BACK < ISERR_SUCCESS Description Indicates that the user selected the Next button. Indicates that the user selected the Back button. Indicates that the dialog could not be displayed.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. If the end user specifies an incomplete, invalid, or write-protected path in the second dialog, an error message is displayed. If you want the end user to be able to select folders that are not writable, call the AskPath function instead. Installations that run in silent mode should create the new folder if it does not exist before calling SdAskDestPath2. This ensures that the confirmation dialog is not displayed. Without this step, two response files are required to handle the two possible conditions.

1162

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdAskDestPath2

SdAskDestPath2 Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdAskDestPath2 function. * * SdProductName is called to set the product name so that it * can be displayed in place of the %P placeholder in the * SdAskDestPath2 dialog. Then, SdAskDestPath2 is called to * prompt the user for a path. Finally, the selected path * is assigned to the system variable TARGETDIR, which is * displayed in a message box. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "SdAskDestPath2 Example"

STRING svDir; #include "ifx.h" function OnBegin() begin // Set product name. SdProductName ("Example Product 5.2"); // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set default folder name for call to SdAskDestPath2. svDir = "C:\\ISEXampl\\Target"; // Display the SdAskDestPath2 dialog. Pass a null string // in the second parameter to display the default message. if (SdAskDestPath2 (TITLE_TEXT, "", svDir ) = NEXT) then TARGETDIR = svDir; endif; // Display the new target directory. SprintfBox (INFORMATION, "SdAskDestPath2", "Successful.\n\nThe Target " + "directory is: " + TARGETDIR); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1163

Appendix E: Built-In Functions (S-T) SdAskOptions

SdAskOptions
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdAskOptions function creates a dialog that offers installation options. You can use check boxes or option buttons as the selection mechanism. The information shown beside the button is retrieved from a group of options. The default number of options is four. You can add or subtract the number of options as necessary in the group.

Syntax
SdAskOptions ( szTitle, szMsg1, szMsg2, szId, szFeatures, nExclusiveFlag );

1164

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdAskOptions

Parameters
Table E-5: SdAskOptions Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Select Components), pass a null string () in this parameter. Specifies a message to display in the dialog. This static field has an ID of 801. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies a second message to display in the dialog. This static field has an ID of 802. Specifies an alternate numeric dialog ID. Use only numeric IDs expressed in string form (for example, ID 13001 as 13001). You can copy the SdAskOptions dialog resource, make limited changes to it, give it a unique numeric ID, and call that dialog by passing its ID as a string in szId. (See above.) To create the standard four-option SdAskOptions dialog, pass a null string () in this parameter. Specifies the name of the feature that contains the subfeatures to be displayed. The subfeatures are preceded by check boxes or option buttons. To display all top-level features, pass a null string () in this parameter. SdAskOptions searches for the requested features in the file media library or scriptcreated feature set specified by the system variable MEDIA. nExclusiveFlag Specifies the type of button you want to display in the dialog. Pass one of the following predefined constants in this parameter:

szMsg1

szMsg2

szId

szFeatures

EXCLUSIVESpecifies option buttons. NONEXCLUSIVESpecifies check boxes.

Return Values
Table E-6: SdAskOptions Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. If your setup includes required, visible components, do not call SdAskOptions to obtain installation options. Instead, call FeatureDialog, SdFeatureDialog, SdFeatureDialogAdv, SdFeatureMult, or SdAskOptionsList in nonexclusive mode.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1165

Appendix E: Built-In Functions (S-T) SdAskOptions

If your setup does not use a setup type dialog, you must call FeatureSetupTypeSet to specify a setup type that has been defined in the IDE's Setup Types view before calling SdAskOptions. SdAskOptions operates on the current media, which is specified by the system variable MEDIA. During setup initialization, the installation assigns to MEDIA a media name that is associated with your file media library (Data1.cab).

Task

To display script-created features: 1. 2. 3. 4.

Save the current value of MEDIA in a string variable, for example, szSaveMEDIAValue. Assign to MEDIA the name of the script-created component set. Call SdAskOptions to get end-user selections. Assign to MEDIA the value that you saved in step 1. You must do this before calling FeatureTransferData. You can create more than one dialog of the SdAskOptions type by copying the SdAskOptions dialog resource (located in _isres.dll) using a resource editor, making limited changes to the copy, and giving it a unique ID. You should save the copy to _isuser.dll. When you call SdAskOptions and pass the ID of the customized copy of the dialog in the parameter szId, the customized copy is displayed. Limit your changes to editing existing static text fields and adding static text fields. Adding controls that require handling is not recommended because it requires changing the SdAskOptions source script.

SdAskOptions Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdAskOptions function * * This script displays a dialog that offers installation * options. * * Note: To run this example script, create a project (or * insert into a project) with several features and/or * subfeatures. * \*--------------------------------------------------------------*/ // Specify your feature name here. These are the names you gave to your // features in the IDE. A NULL ("") string specifies base features. #define FEATURE "" #define SDASKOPTSTITLE "Component Selection" #define SDASKOPTSMSG1 "Select components to install."
1166 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdAskOptionsList

#define SDASKOPTSMSG2 #define APPBASE_PATH

"Your selections will be used to effect file transfer." "Your Company Name\\Your Product Name"

// Include Ifx.h for built-in InstallScript function prototypes. #include "ifx.h" function OnFirstUIBefore() begin // Set a default destination path. INSTALLDIR = PROGRAMFILES ^ APPBASE_PATH; // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Get installation options. SdAskOptions (SDASKOPTSTITLE, SDASKOPTSMSG1, SDASKOPTSMSG2, "", FEATURE, NONEXCLUSIVE); end;

SdAskOptionsList
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdAskOptionsList function creates a dialog that displays a list of features for a custom installation.

Syntax
SdAskOptionsList ( szTitle, szMsg, szFeatures, nStyle );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1167

Appendix E: Built-In Functions (S-T) SdAskOptionsList

Parameters
Table E-7: SdAskOptionsList Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Select Components), pass a null string () in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies the name of the feature that contains the subfeatures to be displayed. The subfeatures are preceded by check boxes or option buttons. To display all top-level features, pass a null string () in this parameter. SdAskOptionsList searches for the requested feature(s) in the file media library or script-created feature set specified by the system variable MEDIA. nStyle Specifies whether the end user's selection is limited. Pass one of the following predefined constants in this parameter:

szMsg

szFeatures

EXCLUSIVEAllows the end user to select only one item from the list. Do not use EXCLUSIVE mode if any of szFeatures' subfeatures are required features. NONEXCLUSIVEAllows the end user to select more than one item from the list, including multiple non-contiguous selections. Also displays two buttons Select All and Clear Allwhich allow selection of all options or clearing of all selections.

Return Values
Table E-8: SdAskOptionsList Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. If your setup does not use a setup type dialog, you must call FeatureSetupTypeSet to specify a setup type that has been defined in the IDE's Setup Types view before calling SdAskOptionsList. SdAskOptionsList operates on the current media, which is specified by the system variable MEDIA. During setup initialization, the installation assigns to MEDIA a media name that is associated with your file media library (Data1.cab).

1168

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdAskOptionsList

Task

To display script-created features: 1. 2. 3. 4.

Save the current value of MEDIA in a string variable, for example, szSaveMEDIAValue. Assign to MEDIA the name of the script-created component set. Call SdAskOptionsList to get end-user selections. Assign to MEDIA the value that you saved in step 1. You must do this before calling FeatureTransferData.

SdAskOptionsList Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdAskOptionsList function with the * NONEXCLUSIVE and EXCLUSIVE options. * \*--------------------------------------------------------------*/ // Define strings. In a real setup you would define these in your string // tables and precede each constant with @ to use them in your script. #define COMP_SELECT_TITLE "Select Components" #define COMP_SELECT_MSG "Select components to install." #define MY_FEATURE_NAME"DefaultFeature" #include "ifx.h" function OnFirstUIBefore() begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Let user select from top-level components, nonexclusively. SdAskOptionsList(COMP_SELECT_TITLE, COMP_SELECT_MSG + " NONEXCLUSIVE", "", NONEXCLUSIVE); // Let user select from subcomponents of MY_FEATURE_NAME, exclusively. SdAskOptionsList(COMP_SELECT_TITLE, COMP_SELECT_MSG + " EXCLUSIVE", MY_FEATURE_NAME, EXCLUSIVE); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1169

Appendix E: Built-In Functions (S-T) SdBitmap

SdBitmap
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdBitmap function displays a bitmap on a dialog. The maximum allowable size of the bitmap is 440 pixels wide by 275 pixels high. You can also display a message in the SdBitmap dialog, but only if you use a resource editor to modify the SdBitmap dialog resource so that the control that displays the message is made visible.

Syntax
SdBitmap ( szTitle, szMsg, szBitmap );

1170

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdBitmap

Parameters
Table E-9: SdBitmap Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Welcome), pass a null string () in this parameter. Pass a null string () in this parameter unless you use a resource editor to modify the SdBitmap dialog to display a message. See the Additional Information section, below. Specifies the file name of the bitmap to display and, optionally, a set of bitmap attributes. If bitmap attributes are included, the string passed in this parameter should be formatted as follows:
"bitmap file name;transparent flag;3-D flag;Background color"

szMsg

szBitmap

bitmap file nameSpecifies the name of the bitmap file. If the file name is unqualified (that is, if it does not include a drive designation and path), InstallShield searches for the bitmap in SUPPORTDIR. transparent flagIndicates whether to display the bitmap transparently. When this flag is 1 (true), all portions of the bitmap that are magenta (RGB Value: 255,0,255) will be displayed transparently. The default for this parameter is 0 (non-transparent). 3-D flagIndicates whether to add a 3-D border around the edges of the static field that contains the bitmap. The default for this parameter is 0 (no 3D border). background colorIndicates the color to use for the background of the static text field. Note that this color will be visible only if the bitmap is smaller than the static text field in which it appears or if the transparent flag is set to 1 and the bitmap has transparent areas. The background color must be expressed as an RGB value, that is, as three numeric values separated by commas. The following example displays the bitmap from the file MyBitmap.bmp, which is located in the SUPPORTDIR folder. The bitmap is displayed on a black background and has a three-dimensional border. Any parts of the bitmap that are magenta are displayed in the background color of black.
"MyBitmap.bmp;1;1;0,0,0"

Return Values
Table E-10: SdBitmap Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
You can use a resource editor to modify the SdBitmap dialog resource so that a message string passed as the parameter szMsg is displayed in the SdBitmap dialog.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1171

Appendix E: Built-In Functions (S-T) SdBitmap

The SdBitmap dialog resource is contained in _isres.dll. The resource contains a static text control that receives the string passed as the parameter szMsg. However, by default this static text control is out of view in the SdBitmap dialog (below the dialog). SdBitmap also uses a static text control to display the bitmap image. You can resize the bitmap image static text control and move the message static text control into view in the dialog. The message in szMsg will then be visible when SdBitmap is called. Be aware that changing the size of the bitmap image static text control may affect the display of your bitmap image. The bitmap image must be small enough to avoid being clipped when SdBitmap centers it in the bitmap image static text control. This function does not support transparent bitmaps. If you use a transparent bitmap with this function, the transparent portions are displayed normally. Metafiles are not supported by SdBitmap.

SdBitmap Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdBitmap function. * * Note: Before running this script, set the defined constant * BITMAP_FILE so that it references a bitmap file * included in the Support Files/Billboards view. * \*--------------------------------------------------------------*/ // The bitmap to display. #define BITMAP_FILE SUPPORTDIR ^ "MyBitmap.bmp" // The title to use for the SdBitmap dialog. #define TITLE_TEXT "SdBitmap Example" #include "Ifx.h" function OnBegin() begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Display the specified bitmap in a dialog. Pass a // null string in the second parameter because the dialog // has not been customized to display a message, SdBitmap (TITLE_TEXT, "", BITMAP_FILE); end;

1172

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdConfirmNewDir

SdConfirmNewDir
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdConfirmNewDir function creates a dialog that displays a folder name and prompts for confirmation. If the end user clicks the Yes button, this function creates the new folder automatically.

Syntax
SdConfirmNewDir ( szTitle, szDir, nReserved );

Parameters
Table E-11: SdConfirmNewDir Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Confirm New Folder), pass a null string () in this parameter. Specifies the name of the directory to confirm. (Obtain this information by calling SdAskDestPath.) Pass zero in this parameter. No other value is allowed.

szDir

nReserved

Return Values
Table E-12: SdConfirmNewDir Return Values Return Value YES (1) Description Indicates that the Yes button was clicked. The directory has been confirmed and will be created. Indicates that the No button was clicked. The specified directory will not be created. Indicates that the Yes button was clicked but the function was unable to create the new directory.

NO (0) <0

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. The dialog that is displayed by this function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1173

Appendix E: Built-In Functions (S-T) SdConfirmNewDir

SdConfirmNewDir Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdConfirmNewDir function. * * This example script first calls SdAskDestPath to get the * destination folder from the user. If the folder does not * exist, SdConfirmNewDir is then called to ask if the user * wants to create the folder. * * Note: This script creates directories on the local hard disk. * \*--------------------------------------------------------------*/ #define DEFAULT_TARGET_FOLDER "C:\\NONEXIST\\DIR"; #define TITLE_TEXT "SdConfirmNewDir Example" #include "ifx.h" function OnBegin() NUMBER nResult; STRING szMsg, svDir; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); start: // Set up parameters for call to SdAskDestPath. szMsg = "Select destination folder:"; svDir = DEFAULT_TARGET_FOLDER // Retrieve destination folder from user. nResult = SdAskDestPath (TITLE_TEXT, szMsg, svDir, 0); // Check if the selected folder exists. if (ExistsDir (svDir) = EXISTS) then // Inform user that the specified folder already exists. szMsg = "folder '%s' already exists.\n\nIn order for this example to " + "run properly, please specify a nonexisting folder."; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svDir); // Start over. goto start; else // The specified folder does not exist. Request user // confirmation to create it. nResult = SdConfirmNewDir (TITLE_TEXT, svDir, 0); if (nResult = NO) then

1174

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdConfirmRegistration

// The user did not want it created select. MessageBox ("Selected folder was not created.", INFORMATION); // Start over. goto start; elseif (nResult = YES) then // The user wants to create the folder. SprintfBox (INFORMATION, TITLE_TEXT, "%s created.", svDir); elseif (nResult < 0) then // Report the error; then terminate. MessageBox ("SdConfirmNewDir failed.", SEVERE); abort; endif; endif; end;

SdConfirmRegistration
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdConfirmRegistration function creates a message box that displays the User Name, Company Name, and Serial Number. If a null string () is entered in any field in the dialog, the displayed field will be empty.

Syntax
SdConfirmRegistration ( szTitle, szName, szCompany, szSerial, nReserved );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1175

Appendix E: Built-In Functions (S-T) SdConfirmRegistration

Parameters
Table E-13: SdConfirmRegistration Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Registration Confirmation), pass a null string () in this parameter. Specifies the end user's name. Specifies the company name. Specifies the serial number. If this parameter contains a null string (), the serial number field is not displayed in the dialog. Pass zero in this parameter. No other value is allowed.

szName szCompany szSerial

nReserved

Return Values
Table E-14: SdConfirmRegistration Return Values Return Value YES (1) NO (0) Description Indicates that the Yes button was clicked. Indicates that the No button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. The dialog that is displayed by this function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin. To obtain the serial number and end users name and company, call SdRegisterUserEx. To obtain only the end users name and company, call SdRegisterUser.

SdConfirmRegistration Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script *

1176

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdCustomerInformation

* Demonstrates the SdRegisterUser and SdConfirmRegistration * functions. * * SdRegisterUser is called to prompt for the user's name * and company name. These entries are then confirmed when * SdConfirmRegistration is called. * \*--------------------------------------------------------------*/ #define REG_TITLE #define REG_MSG #define CONFIRM_TITLE #include "Ifx.h" function OnBegin() STRING svName, svCompany; NUMBER nResult; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); repeat // Get the user's name and company name. SdRegisterUser (REG_TITLE, REG_MSG, svName, svCompany); // Confirm that the information is correct. Pass a null string in // parameter four since SdRegisterUser does not get a serial number. nResult = SdConfirmRegistration (CONFIRM_TITLE, svName, svCompany, "", 0); until nResult = YES; end; "SdRegisterUser Example" "Please register your product now." "SdConfirmRegistration Example"

SdCustomerInformation
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdCustomerInformation function displays a dialog that enables the end user to specify the user name and company name for the product being installed. The dialog may also include radio buttons that let the end user specify whether the product should be installed for all users or only the current user. You can specify default values for these fields by specifying the appropriate parameters. If you specify a null string (""), the function uses the appropriate script variable. The Next button becomes enabled only when data exists in both edit fields. The end user cannot leave any field blank.

Syntax
SdCustomerInformation ( szTitle, svName, svCompany, bvAllUsers );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1177

Appendix E: Built-In Functions (S-T) SdCustomerInformation

Parameters
Table E-15: SdCustomerInformation Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Customer Information), pass a null string ("") in this parameter. Specifies the default value for the Name edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDOWNER variable. For an InstallScript project, this variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. For an InstallScript MSI project, the default value of the variable is always read from the Windows Installer property USERNAME. The function returns the value that the end user specified in this parameter. In an InstallScript installation, the function also sets the value of IFX_PRODUCT_REGISTEREDOWNER to the value that the end user specified. In an InstallScript MSI installation, the function automatically updates the Windows Installer property USERNAME. svCompany Specifies the default value for the Company edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDCOMPANY variable. For an InstallScript project, this variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. For an InstallScript MSI project, the default value of the variable is always read from the Windows Installer property COMPANYNAME. The function returns the value that the end user specified in this parameter. In an InstallScript installation, the function also sets the value of IFX_PRODUCT_REGISTEREDCOMPANY to the value that the end user specified. In an InstallScript MSI installation, the function automatically updates the Windows Installer property COMPANYNAME.

svName

1178

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdCustomerInformation

Table E-15: SdCustomerInformation Parameters (cont.) Parameter bvAllUsers Description Returns which option the end user selected. After the function returns, bvAllUsers is set to one of the following values:

TRUEThe Anyone who uses this computer [all users] option is selected. If the end user selects this option in an InstallScript installation, the function sets the system variable ALLUSERS to a non-zero value. If the end user selects this option in an InstallScript MSI installation, the function sets the ALLUSERS property to a value of 2.

FALSEThe Only for me [user name] option is selected. If the end user selects this option in an InstallScript installation, the function sets the ALLUSERS variable to FALSE.

The default option is not based on the current value of the bvAllUsers parameter, but on the ALLUSERS Windows Installer property in an InstallScript MSI installation, or on the ALLUSERS system variable in an InstallScript installation:

If the ALLUSERS property is 2 or the ALLUSERS system variable is non-zero, the all-users option is selected by default. If the ALLUSERS property is 1 or the ALLUSERS system variable is FALSE, the per-user option is selected by default.

One or both of the radio buttons can be disabled or hidden by updating script variables as follows:

DISABLE_PERUSERBTNIndicates that the per-user option should be disabled (or hidden if HIDE_DISABLED_BTNS is TRUE) in cases where it would normally be enabled. The default value of this variable is FALSE. Note that the per-user option is always hidden on Windows 9x platforms, regardless of the value of this variable. DISABLE_ALLUSERBTNIndicates that the all-users option should be disabled (or hidden) in cases where it would normally be enabled. The default value of this variable is FALSE. Note that the all-users option is always hidden if the installation is being run without administrator or power-user privileges, regardless of the value of this variable. HIDE_DISABLED_BTNSIndicates that both options should be hidden instead of being disabled. The default value of this variable is TRUE. Note that when this variable is set to TRUE, both options are hidden if either option is determined to be disabled.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1179

Appendix E: Built-In Functions (S-T) SdCustomerInformation

Return Values
Table E-16: SdCustomerInformation Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdCustomerInformation Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdCustomerInformation function. * SdCustomerInformation prompts the end user to enter a user * name and company name, and to specify whether the installation is * for anyone who uses the target system or for the current user only. * \*--------------------------------------------------------------*/ #include "ifx.h" function OnFirstUIBefore( ) // ...other variable declarations... STRING svName, svCompany, szMsg; NUMBER nvUser, nReturn; begin // ...show other dialogs... // get the end user's name and company name SdCustomerInformation("", svName, svCompany, nvUser); if (nvUser = 0) then szMsg = "per-user installation"; else szMsg = "all-users installation"; endif; MessageBox("You entered:\n\n" +

1180

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdCustomerInformationEx

"Name: " + svName + "\n" + "Company: " + svCompany + "\n" + "Type: " + szMsg, INFORMATION); // ...other dialogs... end;

SdCustomerInformationEx
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdCustomerInformationEx function displays a dialog that enables the end user to specify the user name, company name, and serial number for the product being installed. The dialog may also include radio buttons that let the end user specify whether the product should be installed for all users or only the current user. You can specify default values for these fields by specifying the appropriate parameters. If you specify a null string (""), the function uses the appropriate script variable. The Next button becomes enabled only when data exists in all three edit fields. The end user cannot leave any field blank.

Note: The SdCustomerInformationEx function does not verify the serial number. To learn how to add code that verifies the serial number, see the sample serial number validation project. This sample project is in one of the Samples subfolders within the InstallShield Program Files folder. The default installation location is C:\Program Files\InstallShield\2012\Samples\InstallScript\Serial Number Validation Sample Project.

Syntax
SdCustomerInformationEx ( szTitle, svName, svCompany, svSerial, bvAllUsers );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1181

Appendix E: Built-In Functions (S-T) SdCustomerInformationEx

Parameters
Table E-17: SdCustomerInformationEx Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Customer Information), pass a null string ("") in this parameter. Specifies the default value for the Name edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDOWNER variable. For an InstallScript project, this variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. For an InstallScript MSI project, the default value of the variable is always read from the Windows Installer property USERNAME. The function returns the value that the end user specified in this parameter. In an InstallScript installation, the function also sets the value of IFX_PRODUCT_REGISTEREDOWNER to the value that the end user specified. In an InstallScript MSI installation, the function automatically updates the Windows Installer property USERNAME. svCompany Specifies the default value for the Company edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDCOMPANY variable. For an InstallScript project, this variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. For an InstallScript MSI project, the default value of the variable is always read from the Windows Installer property COMPANYNAME. The function returns the value that the end user specified in this parameter. In an InstallScript installation, the function also sets the value of IFX_PRODUCT_REGISTEREDCOMPANY to the value that the end user specified. In an InstallScript MSI installation, the function automatically updates the Windows Installer property COMPANYNAME. svSerial Specifies the default value for the Serial Number edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDSERIALNUM variable. This variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. The function returns the value that the end user specified in this parameter. The function also sets the value of IFX_PRODUCT_REGISTEREDSERIALNUM to the value that the end user specified.

svName

1182

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdCustomerInformationEx

Table E-17: SdCustomerInformationEx Parameters (cont.) Parameter bvAllUsers Description Returns which option the end user selected. After the function returns, bvAllUsers is set to one of the following values:

TRUEThe Anyone who uses this computer [all users] option is selected. If the end user selects this option in an InstallScript installation, the function sets the system variable ALLUSERS to a non-zero value. If the end user selects this option in an InstallScript MSI installation, the function sets the ALLUSERS property to a value of 2.

FALSEThe Only for me [user name] option is selected. If the end user selects this option in an InstallScript installation, the function sets the ALLUSERS variable to FALSE.

The default option is not based on the current value of the bvAllUsers parameter, but on the ALLUSERS Windows Installer property in an InstallScript MSI installation, or on the ALLUSERS system variable in an InstallScript installation:

If the ALLUSERS property is 2 or the ALLUSERS system variable is non-zero, the all-users option is selected by default. If the ALLUSERS property is 1 or the ALLUSERS system variable is FALSE, the per-user option is selected by default.

One or both of the radio buttons can be disabled or hidden by updating script variables as follows:

DISABLE_PERUSERBTNIndicates that the per-user option should be disabled (or hidden if HIDE_DISABLED_BTNS is TRUE) in cases where it would normally be enabled. The default value of this variable is FALSE. Note that the per-user option is always hidden on Windows 9x platforms, regardless of the value of this variable. DISABLE_ALLUSERBTNIndicates that the all-users option should be disabled (or hidden) in cases where it would normally be enabled. The default value of this variable is FALSE. Note that the all-users option is always hidden if the installation is being run without administrator or power-user privileges, regardless of the value of this variable. HIDE_DISABLED_BTNSIndicates that both options should be hidden instead of being disabled. The default value of this variable is TRUE. Note that when this variable is set to TRUE, both options are hidden if either option is determined to be disabled.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1183

Appendix E: Built-In Functions (S-T) SdCustomerInformationEx

Return Values
Table E-18: SdCustomerInformationEx Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdCustomerInformationEx Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdCustomerInformationEx function. * SdCustomerInformationEx prompts the end user to enter a user * name, company name, and serial number, and to specify whether * the installation is for anyone who uses the target system * or for the current user only. * \*--------------------------------------------------------------*/ #include "ifx.h" function OnFirstUIBefore( ) // ...other variable declarations... STRING svName, svCompany, svSerial, szMsg; NUMBER nvUser, nReturn; begin // ...show other dialogs... // get the end user's name and company name SdCustomerInformationEx("", svName, svCompany, svSerial, nvUser); if (nvUser = 0) then szMsg = "per-user installation"; else szMsg = "all-users installation"; endif;

1184

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdDiskSpace2

MessageBox("You entered:\n\n" + "Name: " + svName + "\n" + "Company: " + svCompany + "\n" + "Serial number: " + svSerial + "\n" + "Type: " + szMsg, INFORMATION); // ...other dialogs... end;

SdDiskSpace2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdDiskSpace2 function displays a dialog that shows either of the following:

A list view of volumes, required space, available space, and the difference between available space and required space. A warning message indicating that the target system does not have enough available space for the installation to take place. The dialog also displays a list view of volumes, required space, available space, and the difference between available space and required space.

The SdDiskSpace2 function supersedes the SdDiskSpaceRequirements and SdOutOfDiskSpace functions.

Syntax
SdDiskSpace2 (szTitle, szMsg, bUseOutOfSpaceDialog);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1185

Appendix E: Built-In Functions (S-T) SdDiskSpace2

Parameters
Table E-19: SdDiskSpace2 Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Disk Space Requirements or Out of Disk Space), pass a null string ("") in this parameter. Specifies the message to display in the dialog. This text is considered a static control. To display the default instructions for this dialog, pass a null string ("") in this parameter. Indicates whether to show the dialog that warns that the installation is out of space or the dialog that shows the disk space requirements. Pass one of the following predefined constants in this parameter:

szMsg

bUseOutOfSpaceDialog

TRUEShow the dialog that displays a warning message indicating that the target system does not have enough available space for the installation to take place. The dialog also displays a list view of volumes, required space, available space, and the difference between available space and required space. FALSEShow the dialog that displays a list view of volumes, required space, available space, and the difference between available space and required space.

Return Values
Table E-20: SdDiskSpace2 Return Values Return Value NEXT (1) Description Indicates that the end user clicked the OK button.

Additional Information

Project: In InstallScript MSI installations, the OnOutOfDiskSpace event handler responds to the Out Of Disk Space event. The default implementation of OnOutOfDiskSpace displays the SdDiskSpace2 dialog, and then aborts the installation.

To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdDiskSpace2 Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

1186

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdDiskSpaceRequirements

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdDiskSpace2 function. * SdDiskSpace2 displays a list view of volumes, * required space, available space, and the difference between * available and required space. * \*--------------------------------------------------------------*/ #include "ifx.h" function OnFirstUIBefore( ) begin // ... show other dialogs ... // display the disk space requirements SdDiskSpace2 ("", "Review the available and required disk space " + "to determine where to install the application.", FALSE); // ... other dialogs ... end;

SdDiskSpaceRequirements
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdDiskSpace2 function displays a list view of volumes, required space, available space, and the difference between available space and required space. The SdDiskSpace2 function supersedes the SdDiskSpaceRequirements function.

Syntax
SdDiskSpaceRequirements (szTitle, szMsg);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1187

Appendix E: Built-In Functions (S-T) SdDisplayTopics

Parameters
Table E-21: SdDiskSpaceRequirements Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Disk Space Requirements), pass a null string ("") in this parameter. Specifies the message to display in the dialog. This text is considered a static control. To display the default instructions for this dialog, pass a null string ("") in this parameter.

szMsg

Return Values
Table E-22: SdDiskSpaceRequirements Return Values Return Value NEXT (1) Description Indicates that the end user clicked the OK button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdDisplayTopics
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdDisplayTopics function creates a dialog that displays information based on topic data. The dialog provides a heading and then topics of titles and descriptions. You can use this dialog to display Help topics, examples, and so on.

Syntax
SdDisplayTopics ( szTitle, szMsg, listTopics, listDetails, nReserved );

1188

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdDisplayTopics

Parameters
Table E-23: SdDisplayTopics Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Custom Installation Help), pass a null string () in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies the string list that contains the topics to display. Specifies the string list that contains a description of each topic. Pass 0 (zero) in this parameter. No other value is allowed.

szMsg

listTopics listDetails nReserved

Return Values
Table E-24: SdDisplayTopics Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. In an InstallScript MSI installation, when the end user clicks Next the USERNAME and COMPANYNAME properties are set using the information contained in the svName and svCompany fields, respectively. You can modify the font style of description text to distinguish it from title (topic) text. The message and topic titles are always displayed in bold type. The message static field must have an ID of 801. The topic identifiers must have numbers in the range of 802 - 849. Description fields have an ID range of 851 - 899. The spacing of the static description fields is fixed by the size of the dialog. You cannot dynamically change the spacing in the listDetails list. If the number of topics and descriptions is less than the number of static fields, nothing appears in the white space, but the size of the dialog is not changed.

SdDisplayTopics Example
Project: This information applies to the following project types:
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1189

Appendix E: Built-In Functions (S-T) SdDisplayTopics

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdDisplayTopics function. * * This example script creates two lists: one for topic titles, * one for topic descriptions. It then calls SdDisplayTopics to * display the topics and descriptions. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "SdDisplayTopics Example" #define MSG_TEXT "Custom setup options let you choose which parts of YourApp to install." #define TOPIC1 "YourApp Program:" #define TOPIC2 "YourApp Help:" #define TOPIC3 "YourApp Examples:" #define DESC1 #define DESC2 #define DESC3 "Includes all the files to run and write YourApp." "A computer-based tutorial demonstrating how to create programs using YourApp." "Several examples applications created using YourApp."

#include "Ifx.h" function OnBegin() LIST listDescriptions, listTopics; begin // Create a list for topics. listTopics = ListCreate (STRINGLIST); // Create a list for topic descriptions. listDescriptions = ListCreate (STRINGLIST); if (listTopics = LIST_NULL) || (listDescriptions = LIST_NULL) then // Report the error; then terminate. MessageBox("Unable to create lists.", INFORMATION); abort; endif; // Build the list of topics. ListAddString (listTopics, TOPIC1, AFTER); ListAddString (listTopics, TOPIC2, AFTER); ListAddString (listTopics, TOPIC3, AFTER); // Build the list of topic descriptions. ListAddString (listDescriptions, DESC1, AFTER); ListAddString (listDescriptions, DESC2, AFTER); ListAddString (listDescriptions, DESC3, AFTER); // Display the topics and descriptions. SdDisplayTopics (TITLE_TEXT, MSG_TEXT, listTopics, listDescriptions, 0); // Remove the lists from memory. ListDestroy (listTopics); ListDestroy (listDescriptions);

1190

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdExceptions

end;

SdExceptions
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdExceptions function displays a message box that informs the end user that a shared, locked (in use), or read-only file has been encountered, and it offers appropriate options.

Syntax
SdExceptions (nExceptionType, szFilename);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1191

Appendix E: Built-In Functions (S-T) SdExceptions

Parameters
Table E-25: SdExceptions Parameters Parameter nExceptionType Description Specifies which type of file problem has been encountered. Pass one of the following predefined constants in this parameter:

szFilename

SHAREDA shared files reference count has been reduced to zero. READONLYA read-only file has been encountered. LOCKEDA locked file has been encountered.

Specifies the name of the file that caused the problem.

Return Values
Table E-26: SdExceptions Return Values Return Value ERR_RETRY (4) ERR_IGNORE (5) ERR_YES (6) ERR_NO (7) ERR_PERFORM_AFTER_REBOOT (100) <0 Description Indicates that the Retry button was selected. Indicates that the Ignore button was selected. Indicates that the Yes button was selected. Indicates that the No button was selected. Indicates that the Reboot button was selected. Indicates that the dialog could not be displayed.

Additional Information
The dialog that is displayed by this function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

SdExceptions Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * The SdExceptions function displays a dialog informing the * end user that a shared, locked (in use), or read-only file has

1192

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFeatureDialog

* been encountered and offering appropriate options. * * The SdExcpetions function is used in the default code * for the following Miscellaneous event handlers: * * OnFileLocked * OnFileReadOnly * OnRemovingSharedFile * * The sample script below uses the OnFileReadOnly event. To get * the SdExceptions prompt, the setup must attempt to overwrite or * uninstall a read-only file. * \*--------------------------------------------------------------*/ #include "Ifx.h" //--------------------------------------------------------------------------// OnFileReadOnly // // The OnFileReadOnly event is called when a read-only file needs to be // installed or uninstalled. // // szFile will contain the full path of the file that is read-only when the // event is called. // // The event should return one of the following values: // // ERR_YES - Indicates that the file should be installed or uninstalled, // // ERR_NO - Indicates that the file should not be installed or uninstalled. //--------------------------------------------------------------------------function OnFileReadOnly(szFile) begin // TODO: Enable this code if you want to return ERR_YES and simply // install or uninstall the read-only file w/o confirmation. // return ERR_YES; return SdExceptions(READONLY, szFile); end;

SdFeatureDialog
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFeatureDialog function creates a dialog that displays a list of features in the setup that the user can install and the amount of disk space that each feature occupies. This function is identical to SdFeatureDialogAdv. The end user can change the destination folder by clicking the Browse button and can check the available disk space on other drives by clicking the Disk Space button.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1193

Appendix E: Built-In Functions (S-T) SdFeatureDialog

Syntax
SdFeatureDialog ( szTitle, szMsg, svDir, szFeatures );

Parameters
Table E-27: SdFeatureDialog Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Select Features), pass a null string ("") in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the name of the folder to be selected by default and returns the name of the folder selected by the end user. The destination folder specified by svDir is not assigned automatically to INSTALLDIR, TARGETDIR, or any other system variable. To apply the value of svDir to the installation, you must assign it to INSTALLDIR (in an InstallScript MSI installation), TARGETDIR (in an InstallScript installation), or to a scriptdefined variable, if one is in use. If the default folder specified by svDir does not already exist on the end user's system, it is not created unless the end user clicks the Browse button and follows the steps to create it from the Choose Folder dialog. Therefore, whenever you specify a default folder, you must call ExistsDir when FeatureDialog returns in order to determine whether that folder exists. If it does not exist, call CreateDir to create it on the end users system. szFeatures Specifies the name of the feature whose subfeatures are to be displayed. To display all top-level features, pass a null string ("") in this parameter. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls. SdFeatureDialog searches for the requested features in the script-created feature set specified by the system variable MEDIA; see the Additional Information section.

szMsg

svDir

Return Values
Table E-28: SdFeatureDialog Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

1194

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFeatureDialog

A feature's size is displayed as 0 until it is selected. Once it has been selected, its actual size is displayed. The required disk space that is displayed by the dialog includes the size of the files that must be installed to enable maintenance and uninstallation. If all application components are deselected, the size of these files is still displayed. If your installation does not use a setup type dialog, you must call FeatureSetupTypeSet to specify a setup type that has been defined in the Setup Types view before calling SdFeatureDialog.
SdFeatureDialog operates on the current media, which is specified by the system variable MEDIA.

During setup initialization, the installation assigns to MEDIA a media name that is associated with your file media library (Data1.cab).

Task

To display script-created features: 1. 2. 3. 4.

Save the current value of MEDIA in a string variable, for example, szSaveMEDIAValue. Assign to MEDIA the name of the script-created component set. Call SdFeatureDialog to get end-user selections. Assign to MEDIA the value that you saved in step 1. You must do this before calling FeatureTransferData. If necessary, feature names are truncated to allow the display of the largest possible feature size. The space required to display the size depends on the maximum feature size (2 GB), the feature size options currently in use, and the font used to display feature information in the dialog. Feature size options are set with the DialogSetInfo function. When the space required to display the maximum possible size has been determined, all feature names are truncated automatically, if necessary, to fit the remaining space. The name of a feature that requires less space to display its size (or that is not selected) may still be truncated under this method. To maximize performance and ensure that feature names appear complete, make feature names or display names smaller than the space available in the dialog.

The Available Disk Space dialog cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin. The Disk Space button has an ID of 101. This button automatically displays the available disk space dialog. You can remove this button/option if you prefer. The Directory static field requires an ID of 851. The list box ID has a multiple selection style. In installations that were created with early versions of InstallShield Professional, when the end user selected in the Choose Folder dialog a folder that did not exist, a confirmation message box was displayed asking whether the folder should be created. This message box proved to be confusing to many end users, so it has been removed from InstallShield.

SdFeatureDialog Example
Project: This information applies to the following project types:
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1195

Appendix E: Built-In Functions (S-T) SdFeatureDialog2

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdFeatureDialog function. * * This example script displays a dialog that displays a list * of features in the setup that the end user can install and the * amount of space that each feature occupies. * * Comments: To run this example script, create a project (or * insert into a project) with several features * and/or subfeatures with components containing * files. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svDir; begin svDir = TARGETDIR; szTitle = "Select Features"; szMsg = "Select the features you want to install on your computer."; // Display all top-level features available. SdFeatureDialog (szTitle, szMsg, svDir, ""); end;

SdFeatureDialog2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFeatureDialog2 function creates a dialog that displays the following:

A list of features that the end user can install. The space required for the selected features and the space that is available in the destination location. A features size is displayed as the number 0 until it is selected. When the feature is selected, its actual size is displayed. A description of the selected featurethe value of the features Description setting.

If a particular feature has subfeatures, the Change button becomes active when the end user clicks the feature. Clicking the Change button launches the Select Subfeatures dialog, where the end user can make further selections.

1196

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFeatureDialog2

Syntax
SdFeatureDialog2 ( szTitle, szMsg, szDir, szFeatures );

Parameters
Table E-29: SdFeatureDialog2 Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Select Features), pass a null string ("") in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the name of the folder to be selected by default and returns the name of the folder selected by the end user. The destination folder specified by szDir is not assigned automatically to INSTALLDIR, TARGETDIR, or any other system variable. To apply the value of szDir to the installation, you must assign it to INSTALLDIR (in an InstallScript MSI installation), TARGETDIR (in an InstallScript installation), or to a script-defined variable, if one is in use. If the default folder specified by szDir does not already exist on the end users system, it is not created unless the end user clicks the Browse button and follows the steps to create it from the Choose Folder dialog. Therefore, whenever you specify a default folder, you must call ExistsDir when FeatureDialog returns in order to determine whether that folder exists. If it does not exist, call CreateDir to create it on the end users system. szFeatures Specifies the name of the feature whose subfeatures are displayed. To display all toplevel features, pass a null string ("") in this parameter. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls. SdFeatureDialog2 searches for the requested features in the script-created feature set specified by the system variable MEDIA; see the Additional Information section.

szMsg

szDir

Return Values
Table E-30: SdFeatureDialog2 Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1197

Appendix E: Built-In Functions (S-T) SdFeatureDialog2

Default selection settings are cleared when the end user selects a feature or subfeature displayed in the dialog. If the end user clears a feature selection, all of its subfeatures are cleared. Conversely, if the end user clears all of a features subfeature selections, the features selection is cleared. When a feature is not selected by default, its subfeatures are not selected by default. If all subfeatures of a feature are not selected by default, the parent feature should not be selected by default. For information on default feature and subfeature selection settings, see FeatureAddItem.

A features size is displayed as the number 0 until it is selected. Once it has been selected, its actual size is displayed. The required disk space displayed by the dialog includes the size of the files that must be installed to enable maintenance setups and uninstallation. Even if all application components are deselected, the size of these files is still displayed. If your installation does not use a setup type dialog, you must call FeatureSetupTypeSet to specify a setup type that has been defined in the Setup Types view before calling SdFeatureDialog2.
SdFeatureDialog2 operates on the current media, which is specified by the system variable MEDIA.

During setup initialization, the installation assigns to MEDIA a media name that is associated with your file media library (Data1.cab).

Task

To display script-created features: 1. 2. 3. 4.

Save the current value of MEDIA in a string variable, for example, szSaveMEDIAValue. Assign to MEDIA the name of the script-created component set. Call SdFeatureDialog2 to get end-user selections. Assign to MEDIA the value that you saved in step 1. You must do this before calling FeatureTransferData. If necessary, feature names are truncated to allow the display of the largest possible feature size. The space required to display the size depends on the maximum feature size (2 GB), the feature size options currently in use, and the font used to display feature information in the dialog. Feature size options are set with the DialogSetInfo function. When the space required to display the maximum possible size has been determined, all feature names are truncated automatically, if necessary, to fit the remaining space. The name of a feature that requires less space to display its size (or that is not selected) may still be truncated under this method. To maximize performance and ensure that feature names appear complete, make feature names or display names smaller than the space available in the dialog.

The Select Subfeatures dialog cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

SdFeatureDialog2 Example
Project: This information applies to the following project types:

1198

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFeatureDialogAdv

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdFeatureDialog2 function. * * This example script displays a dialog that displays a list * of features in the setup that the end user can install and the * amount of space that each feature occupies. * * Comments: To run this example script, create a project (or * insert into a project) with several features * and/or subfeatures with components containing * files. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svDir; begin svDir = TARGETDIR; szTitle = "Select Features"; szMsg = "Select the features you want to install on your computer."; // Display all top-level features available. SdFeatureDialog2 (szTitle, szMsg, svDir, ""); end;

SdFeatureDialogAdv
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFeatureDialogAdv function creates a dialog that displays a list of features in the setup that the end user can install and the amount of disk space that each feature occupies. This function is identical to SdFeatureDialog. The end user can change the destination folder by clicking the Browse button and can check the available disk space on other drives by clicking the Disk Space button.

Syntax
SdFeatureDialogAdv ( szTitle, szMsg, svDir, szFeatures );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1199

Appendix E: Built-In Functions (S-T) SdFeatureDialogAdv

Parameters
Table E-31: SdFeatureDialogAdv Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Select Features), pass a null string ("") in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the name of the folder to be selected by default and returns the name of the folder selected by the end user. The destination folder specified by svDir is not assigned automatically to INSTALLDIR, TARGETDIR, or any other system variable. To apply the value of svDir to the setup, you must assign it to INSTALLDIR (in an InstallScript MSI installation), TARGETDIR (in an InstallScript installation), or to a scriptdefined variable, if one is in use. If the default folder specified by svDir does not already exist on the end user's system, it is not created unless the end user clicks the Browse button and follows the steps to create it from the Choose Folder dialog. Therefore, whenever you specify a default folder, you must call ExistsDir when FeatureDialog returns in order to determine whether that folder exists. If it does not exist, call CreateDir to create it on the end user's system. szFeatures Specifies the name of the feature whose subfeatures are to be displayed. To display all top-level features, pass a null string ("") in this parameter. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls. SdCFeatureDialogAdv searches for the requested features in the script-created feature set specified by the system variable MEDIA; see the Additional Information section.

szMsg

svDir

Return Values
Table E-32: SdFeatureDialogAdv Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. A feature's size is displayed as 0 until it is selected. Once it has been selected, its actual size is displayed.

1200

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFeatureDialogAdv

The required disk space displayed by the dialog includes the size of the files that must be installed to enable maintenance setups and uninstallation. Even if all application components are deselected, the size of these files is still displayed. If your setup does not use a setup type dialog, you must call FeatureSetupTypeSet to specify a setup type that has been defined in the IDE's Setup Types view before calling SdFeatureDialogAdv. SdFeatureDialogAdv operates on the current media, which is specified by the system variable MEDIA. During setup initialization, the installation assigns to MEDIA a media name that is associated with your file media library (Data1.cab).

Task

To display script-created features: 1. 2. 3. 4.

Save the current value of MEDIA in a string variable, for example, szSaveMEDIAValue. Assign to MEDIA the name of the script-created component set. Call SdFeatureDialogAdv to get end-user selections. Assign to MEDIA the value that you saved in step 1. You must do this before calling FeatureTransferData. If necessary, feature names are truncated to allow the display of the largest possible feature size. The space required to display the size depends on the maximum feature size (2 GB), the feature size options currently in use, and the font used to display feature information in the dialog. Feature size options are set with the DialogSetInfo function. When the space required to display the maximum possible size has been determined, all feature names are truncated automatically, if necessary, to fit the remaining space. The name of a feature that requires less space to display its size (or that is not selected) may still be truncated under this method. To maximize performance and ensure that feature names appear complete, make feature names or display names smaller than the space available in the dialog.

The Available Disk Space dialog cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin. The Disk Space... button has an ID of 101. This button automatically displays the available disk space dialog. You can remove this button/option if you prefer. The Directory static field requires an ID of 851. The list box ID has a multiple selection style. In earlier versions of InstallShield Professional, when the end user selected in the Choose Folder dialog a folder that did not exist, a confirmation message box was displayed asking whether the folder should be created. This message box proved to be confusing to many end users, so it has been removed from InstallShield.

SdFeatureDialogAdv Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1201

Appendix E: Built-In Functions (S-T) SdFeatureMult

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdFeatureDialogAdv function. * * This example script displays a dialog that displays a list * of features in the setup that the end user can install and the * amount of space that each feature occupies. * * Comments: To run this example script, create a project (or * insert into a project) with several features * and/or subfeatures with components containing * files. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svDir; begin svDir = TARGETDIR; szTitle = "Select Features"; szMsg = "Select the features you want to install on your computer."; // Display all top-level features available. SdFeatureDialogAdv (szTitle, szMsg, svDir, ""); end;

SdFeatureMult
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFeatureMult function creates a dialog that displays the following:

A list of features and subfeatures that the end user can select for installation. The dialog has two feature lists. If the feature selected in the first list has subfeatures, the subfeatures are displayed in the second list. The disk space required for the selected features and the space available in the destination location. A feature's size is displayed as 0 until it is selected. When the end user selects a feature, its actual size is displayed. The description of a feature or subfeature. The end user can view the description by clicking on the feature or subfeature.

Syntax
SdFeatureMult ( szTitle, szMsg, svDir, szFeatures );

1202

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFeatureMult

Parameters
Table E-33: SdFeatureMult Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Select Features), pass a null string ("") in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the name of the folder to be selected by default and returns the name of the folder selected by the end user. The destination folder specified by svDir is not assigned automatically to INSTALLDIR, TARGETDIR, or any other system variable. To apply the value of svDir to the setup, you must assign it to INSTALLDIR (in an InstallScript MSI installation), TARGETDIR (in an InstallScript installation), or to a scriptdefined variable, if one is in use. If the default folder specified by svDir does not already exist on the end user's system, it is not created unless the end user clicks the Browse button and follows the steps to create it from the Choose Folder dialog. Therefore, whenever you specify a default folder, you must call ExistsDir when FeatureDialog returns in order to determine whether that folder exists. If it does not exist, call CreateDir to create it on the end user's system. szFeatures Specifies the name of the feature whose subfeatures are displayed. To display all toplevel features, pass a null string ("") in this parameter. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls. SdFeatureMult searches for the requested features in the script-created feature set specified by the system variable MEDIA; see the Additional Information section.

szMsg

svDir

Return Values
Table E-34: SdFeatureMult Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. Default selection settings are cleared when the end user selects a feature or subfeature displayed in the dialog. If the end user clears a feature selection, all of its subfeatures are cleared. Conversely, if the end user clears all of a feature's subfeature selections, the feature's selection is cleared.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1203

Appendix E: Built-In Functions (S-T) SdFeatureMult

When a feature is not selected by default, its subfeatures are not selected by default. If all subfeatures of a feature are not selected by default, the parent feature should not be selected by default. See FeatureAddItem for information on default feature and subfeature selection settings.

A feature's size is displayed as 0 until it is selected. Once it has been selected, its actual size is displayed. The required disk space displayed by the dialog includes the size of the files that must be installed to enable maintenance setups and uninstallation. Even if all application components are deselected, the size of these files is still displayed. If your setup does not use a setup type dialog, you must call FeatureSetupTypeSet to specify a setup type that has been defined in the IDE's Setup Types view before calling SdFeatureMult. SdFeatureMult operates on the current media, which is specified by the system variable MEDIA. During setup initialization, the installation assigns to MEDIA a media name that is associated with your file media library (Data1.cab).

Task

To display script-created features: 1. 2. 3. 4.

Save the current value of MEDIA in a string variable, for example, szSaveMEDIAValue. Assign to MEDIA the name of the script-created component set. Call SdFeatureMult to get end-user selections. Assign to MEDIA the value that you saved in step 1. You must do this before calling FeatureTransferData. If necessary, feature names are truncated to allow the display of the largest possible feature size. The space required to display the size depends on the maximum feature size (2 GB), the feature size options currently in use, and the font used to display feature information in the dialog. Feature size options are set with the DialogSetInfo function. When the space required to display the maximum possible size has been determined, all feature names are truncated automatically, if necessary, to fit the remaining space. The name of a feature that requires less space to display its size (or that is not selected) may still be truncated under this method. To maximize performance and ensure that feature names appear complete, make feature names or display names smaller than the space available in the dialog.

The Select Subfeatures dialog cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

SdFeatureMult Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ *
1204 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFeatureTree

* InstallShield Example Script * * Demonstrates the SdFeatureMult function. * * This example script displays a dialog that lets the user * select features and subfeatures, view feature descriptions, * and see the amount of space required for the selected features * and the space available on the destination folder. * * Comments: To run this example script, create a project (or * insert into a project) with several features * and/or subfeatures with components containing * files. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svDir; begin svDir = TARGETDIR; szTitle = "Select Features"; szMsg = "Select the features you want to install on your computer."; // Display all top-level features available. SdFeatureMult (szTitle, szMsg, svDir, ""); end;

SdFeatureTree
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFeatureTree function displays a dialog that contains the following:

A tree control in which end users can select the features they want on their system and clear the features they do not want on their system. A description of the selected featurethe text in the features Description property. The drive space required to perform the file operations selected in the tree control, and the space available on the drive of the path specified by szDir. The calculation of required drive space takes into account the cluster size on the szDir drive.

Syntax
SdFeatureTree ( szTitle, szMsg, szDir, szFeatures, nLevel );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1205

Appendix E: Built-In Functions (S-T) SdFeatureTree

Parameters
Table E-35: SdFeatureTree Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title ("Select Features"), pass a null string ("") in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the path that is used in calculating required and available drive space. The script variable TARGETDIR should always be specified for this parameter. Specifies the name of the feature whose subfeatures are displayed. To display all toplevel features, pass a null string ("") in this parameter. To learn how to refer to top-level features and subfeatures, see Specifying Features and Subfeatures in Function Calls. Specifies how many levels of features and subfeatures are open in the tree control when the dialog is first displayed. (For example, an nLevel of 2 causes third- and lower-level subfeatures to be closed in the tree control when the dialog is first displayed.)

szMsg

szDir

szFeatures

nLevel

Return Values
Table E-36: SdFeatureTree Return Values Return Value NEXT (1) BACK (12) Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. The required disk space displayed by the dialog includes the size of the files that must be installed to enable maintenance installations and uninstallation. Even if all application features are deselected, the size of these files is still displayed.
SdFeatureTree operates on the current media, which is specified by the system variable MEDIA. During setup initialization, the installation assigns to MEDIA a media name that is associated with your file media library (Data1.cab).

1206

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFeatureTree

Task

To display script-created features: 1. 2. 3. 4.

Save the current value of MEDIA in a string variable, for example, szSaveMEDIAValue. Assign to MEDIA the name of the script-created component set. Call SdFeatureTree to get end-user selections. Assign to MEDIA the value that you saved in step 1. You must do this before calling FeatureTransferData.

SdFeatureTree Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdFeatureTree function. * * This example script displays a dialog that lets the user * select features and subfeatures, view feature descriptions, * and see the amount of space required for the selected features * and the space available on the destination folder. * * Comments: To run this example script, create a project (or * insert into a project) with several features * and/or subfeatures with components containing * files. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svDir; begin svDir = TARGETDIR; szTitle = "Select Features"; szMsg = "Select the features you want to install on your computer."; // Display all top-level features available, with third- and // lower-level subfeatures to be closed in the tree control // when the dialog is first displayed. SdFeatureTree (szTitle, szMsg, svDir, "", 2); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1207

Appendix E: Built-In Functions (S-T) SdFilesInUse

SdFilesInUse
Project: The InstallScript MSI project type support the SdFilesInUse function. The SdFilesInUse dialog can also be called manually in InstallScript projects, in InstallScript MSI projects, and Basic MSI projects that have InstallScript custom actions; however, the installation must provide the list of applications that are locking files through the nvlistApps parameter, and it must handle the return value appropriately.

The SdFilesInUse function displays a dialog that includes a list box containing a list of the applications that are open and are locking files. Typically, the OnFilesInUse event handler displays this dialog in an InstallScript MSI installation as a response to an INSTALLMESSAGE_FILESINUSE message sent by the Windows Installer. When this occurs, the Windows Installer provides to the installation the list of applications that are locking files. The list of applications are passed through the szMessage parameter to the OnFilesInUse event. The event passes this information to the SdFilesInUse function through the szMessage parameter. The event then passes the return value from the function as the return value of the event, which causes the Windows Installer to act appropriately.

Syntax
SdFilesInUse ( byval string szTitle, byval string szMsg, byval string szFilesInUse, byref LIST nvlistApps );

1208

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFilesInUse

Parameters
Table E-37: SdFilesInUse Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Files in Use), pass a null string () in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. When SdFilesInUse is called by the OnFilesInUse event handler in an InstallScript MSI installation, this parameter specifies the list of applications that the Windows Installer found to be locking files. The function parses this string in order to display the list of applications in the dialog's list box. If you manually call SdFilesInUse, pass an empty string ("") in this parameter. Note that if nvlistApps is a valid string list, this parameter is ignored. nvlistApps When SdFilesInUse is called by the OnFilesInUse event handler in an InstallScript MSI installation, this parameter is specified as an uninitialized list variablethat is, a variable with a value of 0. If you manually call SdFilesInUse, specify a string list of applications that are locking files and that should be displayed in the dialog. Each string in the list indicates one application. (Use the ListCreate function and associated list functions to create and initialize the string list.)

szMsg

szFilesInUse

Note: You must provide a variable for this parameter; you cannot specify a literal value.

Return Values
Table E-38: SdFilesInUse Return Values Return Value IDRETRY (4) Description Indicates that the end user clicked the Retry button. If you manually call SdFilesInUse, you should handle this return value by rechecking locked files and redisplaying the dialog as needed. When SdFilesInUse is called by the OnFilesInUse event handler, this value is returned by the event handler, and this is handled by the Windows Installer. IDIGNORE (5) Indicates that the end user clicked the Ignore button.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1209

Appendix E: Built-In Functions (S-T) SdFilesInUse

Table E-38: SdFilesInUse Return Values (cont.) Return Value IDCANCEL Description Indicates that the end user clicked the Exit button.

Note: Note that unlike other script dialogs, this dialog does not call the OnCanceling event handler when the user clicks the Exit button. Therefore, if you are calling this function manually, you must handle this return value manually in order to display the Cancel Setup dialog.

SdFilesInUse Example
Project: The InstallScript MSI project type support the SdFilesInUse function.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdFilesInUse function. SdFilesInUse displays * a list box dialog that lists applications that are locking * files. * * Keep displaying SdFilesInUse if Notepad.exe is running * and user clicks Retry. * \*--------------------------------------------------------------*/ #include "ifx.h"

function OnFirstUIBefore( ) // ...other variables... LIST listID; NUMBER nReturn; begin // ...display other dialogs... // display file-locked dialog only if Notepad.exe running if (Is(FILE_LOCKED, WINDIR ^ "Notepad.exe")) then // create a string list listID = ListCreate(STRINGLIST); // if an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox("Unable to create list.", SEVERE); abort; endif; ListAddString(listID, "Notepad.exe", AFTER); AskAgain:

1210

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFinish

// display the Files in Use dialog. nReturn = SdFilesInUse("", "The following applications are currently locking files.", "", listID); // if user clicks RETRY, show locked-file dialog again; // otherwise, let the file-transfer process handle it, which might require a reboot if (nReturn = IDRETRY) then if (Is(FILE_LOCKED, WINDIR ^ "Notepad.exe")) then goto AskAgain; endif; endif; // remove the list from memory ListDestroy(listID); endif; end;

SdFinish
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFinish function displays a dialog to inform the end user that the installation is complete and to provide information or options. The SdFinish dialog displays up to two messages and two check box selection options. For example, you could offer the end user the option of either viewing a README file or launching the application. To insert the product name into the messages and check box descriptions, use the place holder %P in the strings passed in szMsg1, szMsg2, szOpt1, and szOpt2.

Note: SdFinish has no option to terminate the setup and reboot the end user's computer. When SdFinish returns, the setup continues to execute. To provide the end user with the option to reboot, call SdFinishReboot instead.

Syntax
SdFinish ( szTitle, szMsg1, szMsg2, szOpt1, szOpt2, bvOpt1, bvOpt2 );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1211

Appendix E: Built-In Functions (S-T) SdFinish

Parameters
Table E-39: SdFinish Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Setup Complete), pass a null string () in this parameter. Specifies the message to display at the top of the dialog. To display the default instructions, which inform the user that the installation is complete, pass a null string () in this parameter. Specifies the message to display at the bottom of the dialog. To display the default instructions (Click Finish to complete Setup), pass a null string () in this parameter. Specifies the text to display beside the first check box. Pass a null string () in this parameter to hide the check box. Specifies the text to display beside the second check box. Pass a null string () in this parameter to hide the check box. Returns the selection state (TRUE or FALSE) of the first check box. Returns the selection state (TRUE or FALSE) of the second check box.

szMsg1

szMsg2

szOpt1

szOpt2

bvOpt1 bvOpt2

Return Values
Table E-40: SdFinish Return Values Return Value NEXT (1) Description Indicates that the Finish button was clicked.

Note: Because SdFinish announces the end of the installation, the Back button is disabled.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdFinish Example
Project: This information applies to the following project types:

1212

InstallScript InstallScript MSI

ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFinish

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the function SdFinish. * * Note: Before running this script, set the preprocessor * constants so that they reference the fully-qualified * names of the Windows Notepad executable and a valid * text file in the Support Files/Billboards view. * \*--------------------------------------------------------------*/ //Assign the name of a text file to READMEFILE #define NOTEPAD WINDIR ^ "Notepad.exe" #define READMEFILE SUPPORTDIR ^ "ReadMe.txt" #include "Ifx.h" function OnBegin() STRING szProductName, szTitle; STRING szMsg1, szMsg2, szOpt1, szOpt2; BOOL bvOpt1, bvOpt2; NUMBER nReturn; begin // Set the product name to substitute for the %P place holder. szProductName = "My Application"; SdProductName (szProductName); // Setup parameters that will be passed to SdFinish. szTitle = "SdFinish Example"; szMsg1 = "%P Setup is almost complete.\n" + "Choose the options you want below."; szMsg2 = "Click Finish to complete %P Setup."; szOpt1 = "I would like to view the README file."; szOpt2 = "I would like to launch %P."; // Display the SdFinish dialog. SdFinish (szTitle, szMsg1, szMsg2, szOpt1, szOpt2, bvOpt1, bvOpt2); if (bvOpt1) then // Display the read me file. LaunchAppAndWait (NOTEPAD, READMEFILE, WAIT); endif; if (bvOpt2) then // Because this example does not actually install an // application, a message box is displayed in place of // the call to LaunchApp that would normally be made here, // for example: // LaunchApp (TARGETDIR ^ "MyApp.exe",""); SprintfBox (INFORMATION, szTitle, "Launch %s here.", szProductName); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1213

Appendix E: Built-In Functions (S-T) SdFinishEx

SdFinishEx
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFinishEx function calls either SdFinish or SdFinishReboot to display a dialog that informs the end user that the installation is complete and provides information or options. If the system variable BATCH_INSTALL is equal to FALSE (indicating that no locked files were encountered during the setup), SdFinishEx calls SdFinish to display the dialog. If BATCH_INSTALL is equal to a non-zero value, SdFinishEx calls SdFinishReboot to display the dialog. To insert the product name into the messages and check box descriptions, use the place holder %P in the strings passed in szMsg1, szMsg2, szOpt1, and szOpt2.

Syntax
SdFinishEx (szTitle, szMsg1, szMsg2, szOpt1, szOpt2, bvOpt1, bvOpt2);

Parameters
The parameters are the same as those of SdFinish. If BATCH_INSTALL is equal to TRUE, these parameters are ignored and SdFinishReboot("", "", SYS_BOOTMACHINE, "", 0) is called.

Return Values
Table E-41: SdFinishEx Return Values Return Value 0 NEXT (1) Description Indicates that SdFinish was called. Indicates that SdFinishReboot was called and the user chose not to reboot the computer. Indicates that SdFinishReboot was called and the user chose to reboot the computer, but the reboot failed.

<0

Additional Information
To display non-default text in the SdFinishReboot dialog, do not call SdFinishEx. Instead, use code like the following:
if (!BATCH_INSTALL) then SdFinish( szTitle, szMsg1, szMsg2, szOption1, szOption2, bOpt1, bOpt2 ); else SdFinishReboot( szRebootTitle, szRebootMsg1, SYS_BOOTMACHINE, szRebootMsg2, 0 ); endif;

1214

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFinishReboot

SdFinishEx Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the function SdFinishEx. * * The SdFinishEx function calls either SdFinish or SdFinishReboot * to display a dialog informing the end user that the * installation is complete and giving the user information or * options. If the system variable BATCH_INSTALL is equal to * FALSE (0), indicating that no locked files were encountered * during the setup, SdFinishEx calls SdFinish to display the * dialog. If BATCH_INSTALL is equal to a non-zero value, * SdFinishEx calls SdFinishReboot to display the dialog. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg1, szMsg2, szOption1, szOption2; NUMBER bOpt1, bOpt2; begin bOpt1 = FALSE; bOpt2 = FALSE; szMsg1 = SdLoadString(IFX_SDFINISH_MSG1); SdFinishEx(szTitle, szMsg1, szMsg2, szOption1, szOption2, bOpt1, bOpt2); end;

SdFinishReboot
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFinishReboot function at the end of your installation announces that the installation is complete and gives the end user the option to restart the system. Restarting the system allows changes to Autoexec.bat, Config.sys, and some .ini files to take effect. The SdFinishReboot dialog displays up to two messages in static text fields. Set the value of these fields with the parameters szMsg1 and szMsg2. To insert the product name into the messages, use the place holder %P in the strings passed in szMsg1 and szMsg2.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1215

Appendix E: Built-In Functions (S-T) SdFinishReboot

Syntax
SdFinishReboot ( szTitle, szMsg1, nDefOption, szMsg2, nReserved );

Parameters
Table E-42: SdFinishReboot Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Setup Complete), pass a null string () in this parameter. Specifies the text to display at the top of the dialog, informing the user about the end of the installation. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies a default radio button option selection. Pass one of the following predefined constants in this parameter:

szMsg1

nDefOption

szMsg2

SYS_BOOTMACHINEReboot the computer when the setup is finished. 0Do not reboot the computer.

Specifies the text to display at the bottom of the dialog, giving the user information about what to do. To display the default instructions, pass a null string (). Pass zero in this parameter. No other value is allowed.

nReserved

Return Values
Table E-43: SdFinishReboot Return Values Return Value WILL_REBOOT NEXT (1) <0 Description Indicates that the user chose to reboot the system. Indicates that the user chose not to reboot the system or restart Windows. Indicates that the user chose to either reboot the system or restart Windows, but the reboot or restart failed.

Note: Because SdFinishReboot announces the end of the installation, the Back button is disabled.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. The installation makes every attempt not to reboot the computer when other instances of the installation are running. Because of this, you must ensure that all other instances of the installation are shut down before allowing SdFinishReboot to restart Windows or the system. Additionally, your
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

1216

Appendix E: Built-In Functions (S-T) SdFinishReboot

message to the end user should request that if they plan to restart the system later, they should ensure that all other applications are shut down first.

The installation automatically ensures that locked .dll and .exe files are updated the next time that the system starts.

SdFinishReboot Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdFinishReboot dialog. * * Warning: If you select the reboot option, your computer will * reboot. Be sure you do not have any unsaved files * open when you select this option. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg1, szMsg2; NUMBER nDefOption, nReserved; begin // Set up variables to pass as parameters to SdFinishReboot. szTitle = "SdFinishReboot Example"; szMsg1 = "Setup has completed installing %P."; // nDefOption - Specifies a default radio button option selection. // SYS_BOOTMACHINE - Reboot the computer when the setup is finished. // 0 - Do not reboot the computer. nDefOption = 0; szMsg2 = "Click Finish to exit %P setup."; nReserved = 0; // if // // Display the SdFinishReboot dialog. (SdFinishReboot (szTitle, szMsg1, nOption, szMsg2, nReserved) < 0) then Indicates that the user chose to either reboot the system or restart Windows, but the reboot or restart failed. MessageBox ("SdFinishReboot failed.", SEVERE); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1217

Appendix E: Built-In Functions (S-T) SdFinishUpdate

SdFinishUpdate
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFinishUpdateEx function supersedes the SdFinishUpdate function. SdFinishUpdate calls the following:
SdFinishUpdateEx( szTitle, szMsg1, szMsg2, "", "", bDefOption );

The SdFinishUpdate function at the end of your installation displays a dialog that indicates that the installation is complete. The dialog includes the option to check for application updates.

Note: SdFinishUpdate does not check for updates; to check for updates, add FlexNet Connect API calls in your InstallScript code. For more information, see the FlexNet Connect SDK documentation.

Syntax
SdFinishUpdate ( szTitle, szMsg1, szMsg2, bDefOption );

SdFinishUpdateEx
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFinishUpdateEx function at the end of your installation displays a dialog that indicates that the installation is complete. The dialog includes the option to check for application updates.

Note: SdFinishUpdateEx does not check for updates; to check for updates, add FlexNet Connect API calls in your InstallScript code. For more information, see the FlexNet Connect SDK documentation.

Syntax
SdFinishUpdateEx ( szTitle, szMsg1, szMsg2, szOpt1, szOpt2, bDefOption );

1218

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFinishUpdateEx

Parameters
Table E-44: SdFinishUpdateEx Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Setup Complete), pass a null string ("") in this parameter. Specifies the text to display at the top of the dialog, informing the user about the end of the installation. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the text to display at the bottom of the dialog, providing information to the end user about what to do next. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the text to display beside the first radio button. To display the default instructions ("Yes, check for program updates. (Recommended)\nPlease ensure that you're connected to the Internet before you proceed."), pass a null string ("") in this parameter. Specifies the text to display beside the second radio button. To display the default instructions ("No, skip this step."), pass a null string ("") in this parameter. Specifies the option button that is selected by default. Pass one of the following predefined constants in this parameter:

szMsg1

szMsg2

szOpt1

szOpt2

bDefOption

TRUESpecifies the first option button as the default selection. FALSESpecifies the second option button as the default selection.

Return Values
Table E-45: SdFinishUpdateEx Return Values Return Value TRUE FALSE Description Indicates that the Check for program updates option button is selected. Indicates that the Skip this step option is selected.

Note: Because SdFinishUpdateEx announces the end of the installation, the Back button is disabled.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1219

Appendix E: Built-In Functions (S-T) SdFinishUpdateReboot

SdFinishUpdateReboot
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdFinishUpdateReboot function at the end of your installation displays a dialog that indicates that the installation is complete. The dialog gives the end user the option to restart the system and to check for application updates. Restarting the system enables changes to Autoexec.bat, Config.sys, and some .ini files to take effect.

Note: SdFinishUpdateReboot does not check for updates; to check for updates, add FlexNet Connect API calls in your InstallScript code. For more information, see the FlexNet Connect SDK documentation.

Syntax
SdFinishUpdateReboot ( szTitle, szMsg1, nDefOption, szMsg2, nChkUpdate, nReserved );

1220

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdFinishUpdateReboot

Parameters
Table E-46: SdFinishUpdateReboot Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Setup Complete), pass a null string () in this parameter. Specifies the text to display at the top of the dialog, informing the end user about the end of the installation. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies a default radio button selection. Pass one of the following predefined constants in this parameter:

szMsg1

nDefOption

szMsg2

SYS_BOOTMACHINEReboot the computer when the setup is finished. 0Do not reboot the computer.

Specifies the text to display at the bottom of the dialog, giving the end user information about what to do. To display the default instructions, pass a null string (). Returns the state of the FlexNet Connect check box:

nvChkUpdate

nReserved

0Check box is not selected. Do not check for application updates. Other than 0Check box is selected. Check for application updates.

Pass zero in this parameter. No other value is allowed.

Return Values
Table E-47: SdFinishUpdateReboot Return Values Return Value WILL_REBOOT NEXT (1) <0 Description Indicates that the end user chose to reboot the system. Indicates that the end user chose not to reboot the system or restart Windows. Indicates that the end user chose to either reboot the system or restart Windows, but the reboot or restart failed.

Note: Because SdFinishUpdateReboot announces the end of the installation, the Back button is disabled.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1221

Appendix E: Built-In Functions (S-T) SdGeneralInit

SdFinishUpdateReboot Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdFinishUpdateReboot dialog. * * This dialog is used at the end of an installation to announce * that the installation is complete and gives the user the option * to restart the system and to check for application updates. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes #include "ifx.h" export prototype ExFn_SdFinishUpdateReboot(HWND); function ExFn_SdFinishUpdateReboot(hMSI) STRING szTitle, szMsg1, szMsg2; NUMBER nDefOption, nChkUpdate, nReserved; begin szTitle = "SdFinishUpdateReboot Example"; szMsg1 = ""; szMsg2 = ""; // nDefOption - Specifies the option button selected by default. // 1 - Yes, check for program updates // 0 - No, skip this step nDefOption = 1; // nChkUpdate - Specifies the default state of the FlexNet Connect check box. // nChkUpdate - Returns the state of the FlexNet Connect check box. // 0 - Check box is not selected. Do not check for application updates. // Other than 0 - Check box is selected. Check for application updates. nChkUpdate = 1; nReserved = 0; SdFinishUpdateReboot ( szTitle, szMsg1, nDefOption, szMsg2, nChkUpdate, nReserved ); end;

SdGeneralInit
The SdGeneralInit function provides standard dialog initialization, including setting the enable or disable state of the Next, Back, and Cancel buttons. This function also replaces all %P, %VS, and %VI instances with IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and IFX_INSTALLED_DISPLAY_VERSION on static controls with control IDs 700 through 724, and 202.

1222

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdGeneralInit

Syntax
SdGeneralInit (szDialog, hwndDialg, nUnused, szUnused);

Parameters
Table E-48: SdGeneralInit Parameters Parameter szDialog hwndDialog nUnused szUnused Description Name of the dialog created with EzDefineDialog or DefineDialog. Handle to the current dialog. This is obtained by calling CmdGetHwndDlg. Unused parameter; pass 0. Unused parameter; pass an empty string ("").

Return Values
None.

SdGeneralInit Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdGeneralInit, which is used to initialize * a dialog that is created with the EzDefineDialog function. * * This script opens a simple custom dialog that displays * a bitmap. The dialog can be closed with any of three * buttons: Back, Next, or Cancel. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdBitmap. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * * In order to use this custom dialog, the script first defines * it by calling EzDefineDialog. It then displays the dialog * and gets dialog events by calling WaitOnDialog. When an * event ends dialog processing, EndDialog is called to close * the dialog. Then the dialog is released from memory by * a call to ReleaseDialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12027 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12

// // // //

ID ID ID ID

of of of of

dialog itself Next button Cancel button Back button

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1223

Appendix E: Built-In Functions (S-T) SdGeneralInit

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_EzDefineDialog(HWND); function ExFn_EzDefineDialog(hMSI) STRING szDialogName, szDLLName, szDialog; NUMBER nDialog, nResult, nCmdValue; BOOL bDone; HWND hInstance, hwndParent; begin // Specify a name to identify the custom dialog in this installation. szDialogName = "CustomDialog"; // Define // to get // string // by its nResult = the dialog. Pass a null string in the second parameter the dialog from _isuser.dll or _isres.dll. Pass a null in the third parameter because the dialog is identified ID in the fourth parameter. EzDefineDialog (szDialogName, "", "", RES_DIALOG_ID);

if (nResult < 0) then // Report an error; then terminate. MessageBox ("Error in defining dialog", SEVERE); abort; endif; // Initialize the indicator used to control the while loop. bDone = FALSE; // Loop until done. repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog(szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; if (SdIsStdButton( nCmdValue ) && SdDoStdButton( nCmdValue )) then bDone = TRUE; endif; endswitch;
1224 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdInit

until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory. ReleaseDialog (szDialogName); end;

SdInit
The SdInit function prepares an installation for Sd dialog function calls by loading required resource strings, restoring the installations window if it is minimized, and specifying Windows 95-style check boxes in Sd dialogs.

Note: This function is called automatically by each Sd function. It is unnecessary to call SdInit explicitly unless your script calls DialogSetInfo before calling any of the Sd dialog functions. In that case, your script must call SdInit before it calls DialogSetInfootherwise the call to DialogSetInfo has no effect.

Syntax
SdInit ( );

Parameters
This function takes no parameters.

Return Values
Table E-49: SdInit Return Values Return Value 0 1 Description Indicates that the setup was initialized for Sd dialog function calls. Indicates that the setup has already been initialized for Sd dialog function calls.

SdInit Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdInit function. * * Note that SdInit is called automatically by each Sd function. * It is unnecessary to call SdInit explicitly unless your script * calls DialogSetInfo before calling any of the Sd dialog functions. * In that case, your script must call SdInit before it calls * DialogSetInfootherwise the call to DialogSetInfo has no effect.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1225

Appendix E: Built-In Functions (S-T) SdLicense

* \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szInfoString; begin // Initialize setup for calls to Sd dialog functions. SdInit (); // Set check box style for feature selection. DialogSetInfo ( DLG_INFO_CHECKSELECTION, szInfoString, CHECKBOX ); // Get feature selections. SdFeatureDialog2 ( "", "", TARGETDIR, "" ); end;

SdLicense
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdLicenseEx function supersedes the SdLicense function. The SdLicense function displays a dialog that contains a license agreement in a multi-line edit field. The license agreement is stored in a text file identified in the parameter szLicenseFile. The end user can scroll up and down to read the agreement. The end user must choose either the Yes, No, orif enabledBack button. Because this is usually the first dialog that you would display, you might want to disable the Back button. If the user selects Yes, the installation continues. If the user selects No, the installation displays the ExitSetup dialog.

Syntax
SdLicense ( szTitle, szMsg, szQuestion, szLicenseFile );

1226

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLicense

Parameters
Table E-50: SdLicense Parameters Parameter szTitle Description Specify the title of the dialog. To display the default title (Software License Agreement), pass a null string () in this parameter. Specify the message to display in the static text field above the multi-line edit field. To display the default instructions, pass a null string () in this parameter. Specify the text to display in the static text field below the multi-line edit field. You would likely place a question here, to which the user should respond by selecting either Yes and No. To display the default instructions, pass a null string () in this parameter. Specify the name of the ANSI text file that contains the license agreement. This file must be added to the appropriate language folder in the Support Files/Billboards view. You can also specify szLicenseFile by entering the fully qualified name, in quotation marks, or a UNC path.

szMsg

szQuestion

szLicenseFile

Note: This file must be a text file (.txt).

Return Values
Table E-51: SdLicense Return Values Return Value YES (1) BACK (12) Description The end user selected the Yes button. Indicates that the user selected the Back button.

Note: This function cannot return NO because if the end user clicks the No button, the ExitSetup dialog is displayed.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdLicense Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

ISP-1800-RG00 1227

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLicense2

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdLicense function. * * This script calls SdLicense to display a license agreement * and prompt the user to accept or reject that agreement. * * Note: The license agreement is read from a text file that * is stored at the location specified by the constant * LICENSE_PATH. Before running this script, set that * constant so that it references an existing text file * in the Support Files/Billboards view. * \*--------------------------------------------------------------*/ #define LICENSE_PATH SUPPORTDIR ^ "License.txt" #define TITLE "SdLicense Example" #include "Ifx.h" function OnBegin() STRING szMsg, szQuestion; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up the variables to pass as parameters to SdLicense. szMsg = "Please read the following license agreement. Use " + "the scroll bar to view\nthe rest of this agreement."; szQuestion = "Select Yes to accept the agreement.\n" + "Select No to cancel the setup."; // Display the SdLicense dialog. if (SdLicense (TITLE, szMsg, szQuestion, LICENSE_PATH) = YES) then MessageBox ("Continue with the installation.", INFORMATION); endif; end;

SdLicense2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdLicense2Ex function supersedes the SdLicense2 function. The SdLicense2 function displays a dialog that contains a license agreement in a multi-line edit field. The license agreement is stored in a text file identified in the parameter szLicenseFile.

1228

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLicense2

The end user can scroll up and down to read the agreement. The end user must select the upper option button for the Next button to become enabled, which allows the installation to continue. Because this is usually the first dialog that you would display, you might want to disable the Back button.

Syntax
SdLicense2 ( szTitle, szOpt1, szOpt2, szLicenseFile, bLicenseAccepted );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1229

Appendix E: Built-In Functions (S-T) SdLicense2

Parameters
Table E-52: SdLicense2 Parameters Parameter szTitle Description Specify the title of the dialog. To display the default title ("License Agreement"), pass a null string ("") in this parameter. Specify the text to display in the static text field next to the upper option button. To display the default text ("I accept the terms of the license agreement"), pass a null string ("") in this parameter. Specify the text to display in the static text field next to the lower option button. To display the default text ("I do not accept the terms of the license agreement"), pass a null string ("") in this parameter. Specify the name of the ANSI text file that contains the license agreement. This file must be added to the appropriate language folder in the Support Files/Billboards view. You can also specify szLicenseFile by entering the fully qualified name, in quotation marks, or a UNC path.

szOpt1

szOpt2

szLicenseFile

Note: This file must be a text file (.txt). bLicenseAccepted Specify the option button that is selected by default. Pass one of the following predefined constants in this parameter:

TRUESpecifies the upper option button as the default selection. FALSESpecifies the lower option button as the default selection.

Return Values
Table E-53: SdLicense2 Return Values Return Value NEXT BACK < ISERR_SUCCESS Description The end user selected the upper option button and the Next button. The end user selected the Back button. The dialog could not be displayed.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

1230

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLicense2Ex

SdLicense2 Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdLicense2 function. * * This script calls SdLicense2 to display a license agreement * and prompt the user to accept or reject that agreement. * * Note: The license agreement is read from a text file that * is stored at the location specified by the constant * LICENSE_PATH. Before running this script, set that * constant so that it references an existing text file * on the target system. * \*--------------------------------------------------------------*/

#define LICENSE_PATH "License.txt" #define TITLE "SdLicense2 Example" #include "ifx.h" function OnBegin() begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON);

// Display the SdLicense2 dialog. if (SdLicense2 (TITLE, "", "", LICENSE_PATH, FALSE) = NEXT) then MessageBox ("Continue with the installation.", INFORMATION); endif; end;

SdLicense2Ex
Project: This information applies to the following project types:

InstallScript InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1231

Appendix E: Built-In Functions (S-T) SdLicense2Ex

The SdLicense2Ex function displays a dialog that contains a license agreement in a multi-line edit field. The license agreement is stored in a text file (.txt) or a rich text format file (.rtf) identified in the parameter szLicenseFile. The end user can scroll up and down to read the agreement. The end user must select the upper option button for the Next button to become enabled, which allows the installation to continue. Because this is usually the first dialog that you would display, you might want to disable the Back button.

Syntax
SdLicense2Ex (byval string szTitle, byval string szOpt1, byval string szOpt2, byval string szLicenseFile, byval bool bLicenseAccepted, byval bool bRtf);

1232

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLicense2Ex

Parameters
Table E-54: SdLicense2Ex Parameters Parameter szTitle Description Specify the title of the dialog. To display the default title ("License Agreement"), pass a null string ("") in this parameter. Specify the text to display in the static text field next to the upper option button. To display the default text ("I accept the terms of the license agreement"), pass a null string ("") in this parameter. Specify the text to display in the static text field next to the lower option button. To display the default text ("I do not accept the terms of the license agreement"), pass a null string ("") in this parameter. Specify the name of the ANSI text file or .rtf file that contains the license agreement. This file must be added to the appropriate language folder in the Support Files/Billboards view. You can also specify szLicenseFile by entering the fully qualified name, in quotation marks, or a UNC path.

szOpt1

szOpt2

szLicenseFile

Note: If you are using an .rtf file, the file size limit is 16 MB. bLicenseAccepted Specify the option button that is selected by default. Pass one of the following predefined constants in this parameter:

bRtf

TRUESpecifies the upper option button as the default selection. FALSESpecifies the lower option button as the default selection.

Indicate whether to use the dialog with the rich text edit control. Available options are:

TRUEUse the rich text edit control. If you select this option, the file that you specify for szLicenseFile must be an .rtf file. FALSEUse the standard edit control. If you select this option, the file that you specify for szLicenseFile must be a .txt file.

Return Values
Table E-55: SdLicense2Ex Return Values Return Value NEXT BACK < ISERR_SUCCESS Description The end user selected the upper option button and the Next button. The end user selected the Back button. The dialog could not be displayed.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1233

Appendix E: Built-In Functions (S-T) SdLicense2Rtf

InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdLicense2Rtf
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdLicense2Ex function supersedes the SdLicense2Rtf function. The SdLicense2Rtf function displays a dialog that contains a license agreement in a multi-line edit field. The license agreement is stored in a text file or rich text format file (.rtf) file identified in the parameter szLicenseFile. The user can scroll up and down to read the agreement, then must select the upper option button for the Next button to become enabled, which allows the setup to continue. Because this is usually the first dialog you would display, you might want to disable the Back button.

Syntax
SdLicense2Rtf ( szTitle, szOpt1, szOpt2, szLicenseFile, bLicenseAccepted );

1234

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLicense2Rtf

Parameters
Table E-56: SdLicense2Rtf Parameters Parameter szTitle Description Specify the title of the dialog. To display the default title ("License Agreement"), pass a null string ("") in this parameter. Specify the text to display in the static text field next to the upper option button. To display the default text ("I accept the terms of the license agreement"), pass a null string ("") in this parameter. Specify the text to display in the static text field next to the lower option button. To display the default text ("I do not accept the terms of the license agreement"), pass a null string ("") in this parameter. Specify the name of the .rtf file or ANSI text file that contains the license agreement. This file must be added to the appropriate language folder in the Support Files/Billboards view. You can also specify szLicenseFile by entering the fully qualified name, in quotation marks, or a UNC path.

szOpt1

szOpt2

szLicenseFile

Note: If you are using an .rtf file, the file size limit is 16 MB. bLicenseAccepted Specifies the option button that is selected by default. Pass one of the following predefined constants in this parameter:

TRUESpecifies the upper option button as the default selection. FALSESpecifies the lower option button as the default selection.

Return Values
Table E-57: SdLicense2Rtf Return Values Return Value NEXT BACK < ISERR_SUCCESS Description The end user selected the upper option button and the Next button. The end user selected the Back button. The dialog could not be displayed.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1235

Appendix E: Built-In Functions (S-T) SdLicenseEx

SdLicense2Rtf Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdLicense2Rtf function. * * This script calls SdLicense2Rtf to display a license agreement * and prompt the user to accept or reject that agreement. * * Note: The license agreement is read from an RTF file that * is stored at the location specified by the constant * LICENSE_PATH. Before running this script, set that * constant so that it references an existing RTF file * on the target system. * \*--------------------------------------------------------------*/

#define LICENSE_PATH "License.rtf" #define TITLE "SdLicense2Rtf Example" #include "ifx.h" function OnBegin() begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON);

// Display the SdLicense2Rtf dialog. if (SdLicense2Rtf (TITLE, "", "", LICENSE_PATH, FALSE) = NEXT) then MessageBox ("Continue with the installation.", INFORMATION); endif; end;

SdLicenseEx
Project: This information applies to the following project types:

InstallScript InstallScript MSI

1236

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLicenseEx

The SdLicenseEx function displays a dialog that contains a license agreement in a multi-line edit field. The license agreement is stored in a text file (.txt) or a rich text format file (.rtf). The end user can scroll up and down to read the agreement. The end user must choose either the Yes, No, orif enabledBack button. Because this is usually the first dialog that you would display, you might want to disable the Back button. If the user selects Yes, the installation continues. If the user selects No, the installation displays the ExitSetup dialog.

Syntax
SdLicenseEx (byval string szTitle, byval string szMsg, byval string szQuestion, byval string szLicenseFile, byval bool bRtf);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1237

Appendix E: Built-In Functions (S-T) SdLicenseEx

Parameters
Table E-58: SdLicenseEx Parameters Parameter szTitle Description Specify the title of the dialog. To display the default title (Software License Agreement), pass a null string () in this parameter. Specify the message to display in the static text field above the multi-line edit field. To display the default instructions, pass a null string () in this parameter. Specify the text to display in the static text field below the multi-line edit field. You would likely place a question here, to which the user should respond by selecting either Yes and No. To display the default instructions, pass a null string () in this parameter. Specify the name of the ANSI text file or .rtf file that contains the license agreement. This file must be added to the appropriate language folder in the Support Files/Billboards view. You can also specify szLicenseFile by entering the fully qualified name, in quotation marks, or a UNC path.

szMsg

szQuestion

szLicenseFile

Note: If you are using an .rtf file, the file size limit is 16 MB. bRtf Indicate whether to use the dialog with the rich text edit control. Available options are:

TRUEUse the rich text edit control. If you select this option, the file that you specify for szLicenseFile must be an .rtf file. FALSEUse the standard edit control. If you select this option, the file that you specify for szLicenseFile must be a .txt file.

Return Values
Table E-59: SdLicenseEx Return Values Return Value YES (1) BACK (12) Description The end user selected the Yes button. The end user selected the Back button.

Note: This function cannot return NO because if the end user clicks the No button, the ExitSetup dialog is displayed.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

1238

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLicenseRtf

SdLicenseRtf
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdLicenseEx function supersedes the SdLicenseRtf function. The SdLicenseRtf function displays a dialog that contains a license agreement in a multi-line edit field. The license agreement is stored in a text file or rich text format file (.rtf) file identified in the parameter szLicenseFile. The user can scroll up and down to read the agreement, then must choose either the Yes, No, orif enabledthe Back button. Because this is usually the first dialog you would display, you might want to disable the Back button. If the user selects Yes, the installation continues. If the user selects No, the installation displays the ExitSetup dialog.

Syntax
SdLicenseRtf ( szTitle, szMsg, szQuestion, szLicenseFile );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1239

Appendix E: Built-In Functions (S-T) SdLicenseRtf

Parameters
Table E-60: SdLicenseRtf Parameters Parameter szTitle Description Specify the title of the dialog. To display the default title (Software License Agreement), pass a null string () in this parameter. Specify the message to display in the static text field above the multi-line edit field. To display the default instructions, pass a null string () in this parameter. Specify the text to display in the static text field below the multi-line edit field. You would likely place a question here, to which the user should respond by selecting either Yes and No. To display the default instructions, pass a null string () in this parameter. Specify the name of the .rtf file or ANSI text file that contains the license agreement. This file must be added to the appropriate language folder in the Support Files/Billboards view. You can also specify szLicenseFile by entering the fully qualified name, in quotation marks, or a UNC path.

szMsg

szQuestion

szLicenseFile

Note: If you are using an .rtf file, the file size limit is 16 MB.

Return Values
Table E-61: SdLicenseRtf Return Values Return Value YES (1) BACK (12) Description The end user selected the Yes button. The end user selected the Back button.

Note: This function cannot return NO because if the end user clicks the No button, the ExitSetup dialog is displayed.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdLicenseRtf Example
Project: This information applies to the following project types:

1240

InstallScript

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLoadString

InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdLicenseRtf function. * * This script calls SdLicenseRtf to display a license agreement * and prompt the user to accept or reject that agreement. * * Note: The license agreement is read from an RTF file that * is stored at the location specified by the constant * LICENSE_PATH. Before running this script, set that * constant so that it references an existing RTF file * in the Support Files/Billboards view. * \*--------------------------------------------------------------*/ #define LICENSE_PATH SUPPORTDIR ^ "License.rtf" #define TITLE "SdLicenseRtf Example" #include "Ifx.h" function OnBegin() STRING szMsg, szQuestion; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up the variables to pass as parameters to SdLicense. szMsg = "Please read the following license agreement. Use " + "the scroll bar to view\nthe rest of this agreement."; szQuestion = "Select Yes to accept the agreement.\n" + "Select No to cancel the setup."; // Display the SdLicenseRtf dialog. if (SdLicenseRtf (TITLE, szMsg, szQuestion, LICENSE_PATH) = YES) then MessageBox ("Continue with the installation.", INFORMATION); endif; end;

SdLoadString
The SdLoadString function returns the string value associated with the specified resource ID. The InstallScript engine first looks for the resource in _isuser.dll, if that file exists. If the resource is not found, the InstallScript engine looks in _isres.dll.

Syntax
SdLoadString (nID);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1241

Appendix E: Built-In Functions (S-T) SdLoadString

Parameters
Table E-62: SdLoadString Parameters Parameter nID Description Specifies the identifier of a string resource in _isuser.dll or _isres.dll. Some valid values of nID can be found in the InstallShield Program Files Folder\Script\Ifx\Include subfolder's Ifx.h file. The default OnMaintUIBefore event handler function code uses the following identifiers with their corresponding string values:

IFX_MAINTUI_MSGDo you want to completely remove the selected application and all of its components? IFX_ONMAINTUI_CAPTIONConfirm Uninstall

Return Values
Table E-63: SdLoadString Return Values Return Value non-null string value null string value ("") Description The string value successfully retrieved by SdLoadString. Indicates that SdLoadString failed.

SdLoadString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdLoadString function. * * This script calls SdLoadString to get the string resource * that is stored in _isres.dll with the ID IFX_MAINTUI_MSG. * That string resource is then displayed in a message box. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING svResource; begin // Get the string resource. svResource = SdLoadString (IFX_MAINTUI_MSG); if (svResource = "") then
1242 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLogonUserBrowse

// Report the error. MessageBox ("SdLoadString failed.", WARNING); else // Display the string resource. SprintfBox ( INFORMATION , "SdLoadString" , "Value of string resource %ld:\n%s" , IFX_MAINTUI_MSG, svResource ); endif; end;

SdLogonUserBrowse
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdLogonUserBrowse function displays a dialog that allows the end user to select a domain or server and a user name. This dialog is displayed when an end user clicks the Browse button on the SdLogonUserInformation dialog.

Syntax
SdLogonUserBrowse();

SdLogonUserCreateUser
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdLogonUserCreateUser function displays a dialog that allows the end user to enter new user information after the end user clicks the New User Information button on the SdLogonUserInformation dialog.

Syntax
SdLogonUserCreateUser();

SdLogonUserInformation
Project: This information applies to the following project types:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1243

Appendix E: Built-In Functions (S-T) SdLogonUserListGroups

InstallScript InstallScript MSI

The SdLogonUserInformation function displays a dialog that prompts the end user for existing user account information or new user information if an account is to be created during the installation. If the end user clicks the Browse button next to the User box, the SdLogonUserBrowse dialog is displayed.

Syntax
SdLogonUserInformation (byval string szTitle, byval string szMsg, byref string szAssociatedAccountName, byref string szAssociatePassword);

Parameters
Table E-64: SdLogonUserInformation Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title, pass a null string ("") in this parameter. Specifies the message in the dialog. To display the default title, pass a null string ("") in this parameter. Specifies the BYREF value that is the account name. Example: INSTALLSHIELD\John Smith Specifies the BYREF value that is the password.

szMsg

szAssociatedAccountName

szAssociatePassword

Return Values
Table E-65: SdLogonUserInformation Return Values Return Value NEXT BACK < ISERR_SUCCESS Description Indicates that the user selected the Next button Indicates that the user selected the Back button. Indicates that the dialog could not be displayed.

SdLogonUserListGroups
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdLogonUserListGroups function displays a dialog that allows the end user to select a group from a specified server or domain and populate the Group field in the SdLogonUserCreateUser dialog.
1244 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdLogonUserListServers

Syntax
SdLogonUserListGroups();

SdLogonUserListServers
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdLogonUserListServers function displays a dialog that allows the end user to browse for the domain or server with which the user account is associated.

Syntax
SdLogonUserListServers();

SdLogonUserListUsers
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdLogonUserListUsers function displays a dialog that allows the end user to browse and select an existing user for a specified domain or server.

Syntax
SdLogonUserListUsers();

SdMakeName
The SdMakeName function creates a section name for a custom dialog. This section name is used in writing to and reading from an .iss file, which is used when running an InstallScript-based installation project's Setup.exe in silent mode.

Syntax
SdMakeName ( svSection, szDlg, szUnused, nvDlgName );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1245

Appendix E: Built-In Functions (S-T) SdMakeName

Parameters
Table E-66: SdMakeName Parameters Parameter svSection Description Specifies the section name (for example, "MyDlg-0"). InstallShield places a value into this variable using the variables szDlg and nvDlgName. This value is used by SilentReadData and SilentWriteData. Specifies the name of the custom dialog (for example, "MyDlg") for which to create a section name. This parameter is not used; pass a null string ("") in this parameter. Specifies the counter that records the number of times SdMakeName is called for the dialog named in szDlg. InstallShield automatically increments this counter. For sections to be properly named, you must use a unique variable name in this parameter for each different custom dialog. A simple way to do this is to use the dialog name in szDlg to name the variable. For example, when szDlg is "MyDlgOne," name the variable in this parameter nvMyDlgOne, and when szDlg is "MyDlgTwo," name the variable nvMyDlgTwo.

szDlg

szUnused nvDlgName

Return Values
None.

SdMakeName Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions SdMakeName, SilentReadData, and * SilentWriteData. * * This example script shows how to handle a custom dialog * in a silent installation. The resource .dll for the example * custom dialog shown below should be stored in a compressed * form under the Support Files/Billboards view of InstallShield. * * The example dialog was built from the custom dialog * template provided with InstallShield. * * Dialog control IDs and other information are included in * the Resource.h file (not shown). This file, which is included * in the first line of the example, must be inserted in the * InstallScript view of InstallShield. * * The example creates a text file called Cominit.txt. If the

1246

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdMakeName

* installation runs in silent mode, SilentReadData is called * and the custom dialog control selections are read from * the .iss file. The selections are then saved in the file * Cominit.txt as a means of demonstrating that they were * successfully read from the .iss file. If the installation * runs in normal mode, the custom dialog is displayed * and the selections are recorded in the .iss file and * displayed in message boxes. The initial .ISS file text is * shown after the example script. * \*--------------------------------------------------------------*/ #include "Resource.h" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SdMakeName(HWND); function ExFn_SdMakeName(hMSI) BOOL bDone; STRING svSection, svComPort, svPulse, svTone, svDial9, svVal; NUMBER nvCommDialog, nCmdValue, nPulseState, nToneState; NUMBER nDial9State, nResult, nvHandle; LIST listID; begin // Open the text file COMINIT.TXT so custom dialog selections // from the .ISS file can be stored in it. OpenFileMode (FILE_MODE_APPEND); OpenFile (nvHandle, "c:\\rul", "cominit.txt"); // If operating in silent mode, then read from the .ISS file. if (MODE=SILENTMODE) then SdMakeName (svSection, "COMM_DIALOG", "", nvCommDialog); SilentReadData (svSection, "Result", DATA_NUMBER, svVal, nResult); if (nResult = 1) then // Read the data from the .ISS file. For purposes of // writing the results to a text file, read the // data as strings. SilentReadData (svSection, "nPulseState", DATA_STRING, svPulse, nResult); SilentReadData (svSection, "nToneState", DATA_STRING, svTone, nResult); SilentReadData (svSection, "nDial9State", DATA_STRING, svDial9, nResult); // Store the custom dialog selections in // the text file COMINIT.TXT. svVal = "Pulse box is: " ^ svPulse; WriteLine(nvHandle, svVal); svVal = "Tone box is: " ^ svTone; WriteLine(nvHandle, svVal); svVal = "Dial9 box is: " ^ svDial9; WriteLine(nvHandle, svVal);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1247

Appendix E: Built-In Functions (S-T) SdMakeName

endif; // If not in silent mode, then call and handle the custom dialog // as you normally would. else listID = ListCreate (STRINGLIST); ListAddString (listID, "COMM1:", AFTER); ListAddString (listID, "COMM2:", AFTER); ListAddString (listID, "COMM3:", AFTER); ListAddString (listID, "COMM4:", AFTER); EzDefineDialog ("MYCOMDIALOG", SUPPORTDIR^"RESOURCE.DLL", "COMM_DIALOG",0); bDone = FALSE; while (bDone=FALSE) nCmdValue = WaitOnDialog ("MYCOMDIALOG"); switch (nCmdValue) case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 // and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_CHECKED); CtrlSetList ("MYCOMDIALOG", ID_COMPORT, listID); CtrlSetState ("MYCOMDIALOG", ID_DIAL9, BUTTON_CHECKED); case OK: CtrlGetCurSel ("MYCOMDIALOG", ID_COMPORT, svComPort); nPulseState = CtrlGetState ("MYCOMDIALOG", ID_PULSE); nToneState = CtrlGetState ("MYCOMDIALOG", ID_TONE); nDial9State = CtrlGetState ("MYCOMDIALOG", ID_DIAL9); nResult = NEXT; bDone = TRUE; case BACK: nResult = BACK; bDone = TRUE; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case DLG_CLOSE: // The user clicked the window's close button. Do (EXIT); case ID_PULSE: nPulseState = CtrlGetState ("MYCOMDIALOG", ID_PULSE); if (nPulseState = BUTTON_CHECKED) then CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_UNCHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_CHECKED); else CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_CHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_UNCHECKED); endif; case ID_TONE: nToneState = CtrlGetState ("MYCOMDIALOG", ID_TONE); if (nPulseState = BUTTON_CHECKED) then CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_CHECKED);
1248 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdMakeName

CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_UNCHECKED); else CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_UNCHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_CHECKED); endif; case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; endswitch; endwhile; EndDialog ("MYCOMDIALOG"); ReleaseDialog ("MYCOMDIALOG"); SdMakeName (svSection, "COMM_DIALOG", "", nvCommDialog); SilentWriteData (svSection, "nPulseState", DATA_NUMBER, svPulse, nPulseState); SilentWriteData (svSection, "nToneState", DATA_NUMBER, svTone, nToneState); SilentWriteData (svSection, "nDial9State", DATA_NUMBER, svDial9, nDial9State); if (nPulseState = BUTTON_CHECKED) then MessageBox ("The Pulse button was checked.", INFORMATION); else MessageBox ("The Pulse button was unchecked.", INFORMATION); endif; if (nToneState = BUTTON_CHECKED) then MessageBox ("The Tone button was checked.", INFORMATION); else MessageBox ("The Tone button was unchecked.", INFORMATION); endif; if (nDial9State = BUTTON_CHECKED) then MessageBox ("The Dial9 button was checked.", INFORMATION); else MessageBox ("The Dial9 button was unchecked.", INFORMATION); endif; endif; // Close the text file COMINIT.TXT CloseFile (nvHandle); end;

/*The following is the initial .iss file text for the above example, where <PRODUCT_GUID> represents your project's GUID, including the surrounding braces. Note that -1001 is the numeric value of BUTTON_CHECKED and -1002 is the numeric value of BUTTON_UNCHECKED. [InstallShield Silent] Version=v9.00 File=Response File [Application] Name=MyDialog Version=4.0
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1249

Appendix E: Built-In Functions (S-T) SdOptionsButtons

Company=My Software Company [<PRODUCT_GUID>-DlgOrder] Dlg0=<PRODUCT_GUID>-COMM_DIALOG-0 Count=1 [<PRODUCT_GUID>-COMM_DIALOG-0] nPulseState=-1001 nToneState=-1002 nDial9State=-1001 Result=1 */

SdOptionsButtons
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdOptionsButtons function displays a dialog that contains from one to four push button controls that have bitmap images. A short text description is displayed next to each control.

Important: Do not change the control identifiers of the push button controls on the SdOptionsButtons dialog, or set one of the push button controls as the default control. If you change the control identifiers or set one of the these controls as the default control of the dialog, the SdOptionsButtons dialog will not work as expected.

Note: Although SdOptionsButtons can be used as a setup type dialog, the SdSetupTypeEx dialog is the recommended dialog for allowing the end user to select a setup type because it does not require any customization. If you call SdOptionsButtons to get the end users setup type selection, you must then call FeatureSetupTypeSet to establish the selected setup type for your setup.

Syntax
SdOptionsButtons (szTitle, szMsg, listButton, listDescription);

1250

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdOptionsButtons

Parameters
Table E-67: SdOptionsButtons Parameters Parameter szTitle Description Specifies the dialog title. To display the default title (Select Features), pass a null string ("") in this parameter. Specifies the message to display on the dialog. To display the default instructions for this dialog (Please select the features that you want to install.), pass a null string ("") in this parameter. Specifies a string list that contains from one to four elements. Each element is a formatted string that specifies a bitmap to be displayed on a button. One button is displayed for each string element in the list. The string list elements should have the following format:
"@<bitmap ID>;<bitmap icon flag>;<transparent color>"

szMsg

listButton

The @ symbol begins the string and is followed by the bitmap ID. The <bitmap icon flag> field is either 1 (true) or 0 (false), indicating whether the color that is specified in the <transparent color> field will be transparent when the bitmap is displayed. The <transparent color> field specifies an RGB value that is a transparent color for the bitmap. Use semicolons to delimit the bitmap ID from the icon flag and the icon flag from the transparent color. InstallShield provides four default bitmaps in _isres.dll that can be used by this function. These bitmaps have IDs of 12001 through 12004 and correspond to the Typical, Portable, Compact, and Custom setup types in the example script. If you are using this dialog for another purpose or if you want to use setup types other than the types provided in _isres.dll, you must to add your own custom buttons to the _isuser.dll dialog template and then include the customized _isuser.dll with your installation.

Tip: To determine the bitmap IDs of bitmap controls created in the Dialog Editor, you need to build your project and open the .rc file to locate the bitmap IDs. The .rc file is located in your builds folder (by default, C:\InstallShield 2012\Your Project Name.ism). Adding additional bitmap controls may change the bitmap IDs. Because of this, you need to rebuild your project and open the .rc file again to find the updated bitmap IDs. listDescription Specifies a string list that contains from one to four string elements, each corresponding to a string in the parameter listButton. Each string is a text description to be displayed with its corresponding button.

Return Values
Table E-68: SdOptionsButtons Return Values Return Value NEXT (1) Description Indicates that the Next button was clicked.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1251

Appendix E: Built-In Functions (S-T) SdOptionsButtons

Table E-68: SdOptionsButtons Return Values (cont.) Return Value BACK (12) 101 Description Indicates that the Back button was clicked. Indicates that the button corresponding to the first string element in listButton was selected. Indicates that the button corresponding to the second string element in listButton was selected. Indicates that the button corresponding to the third string element in listButton was selected. Indicates that the button corresponding to the fourth string element in listButton was selected.

102

103

104

Note: To prevent the user from exiting the dialog without clicking a particular button, call the Disable function to disable the Next button before you call SdOptionsButtons.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdOptionsButtons Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdOptionsButtons function. * * This script allows the user to select a setup type. First, * two lists are created, one for the setup type button icons, * another for the setup type descriptions. Then the buttons * and descriptions are added to the lists. Next, the dialog * is presented. When the user clicks a setup type button, the * dialog closes and the user's selection is displayed in a * message box. * \*--------------------------------------------------------------*/ #include "Ifx.h"

1252

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdOptionsButtons

function OnBegin() STRING szTitle, szMsg; LIST listButton, listDesc; NUMBER nResult; begin // Disable the Back and Next buttons in setup dialogs. Disable (BACKBUTTON); Disable (NEXTBUTTON); // Create the lists for buttons and descriptions. listButton = ListCreate (STRINGLIST); listDesc = ListCreate (STRINGLIST); if (listButton = LIST_NULL) || (listDesc = LIST_NULL) then // Report the error; then terminate. MessageBox ("Unable to create lists.", INFORMATION); abort; endif; // Add the bitmap buttons to listButton. ListAddString (listButton, "@12001;1;255,0,255", ListAddString (listButton, "@12002;1;255,0,255", ListAddString (listButton, "@12003;1;255,0,255", ListAddString (listButton, "@12004;1;255,0,255",

AFTER); AFTER); AFTER); AFTER);

// Add the descriptions to listDesc. ListAddString (listDesc, "Typical\n" + "Recommended for most computers.", AFTER); ListAddString (listDesc, "Portable\n" + "The application will be set up with " + "options that are useful for portable " + "computers.", AFTER); ListAddString (listDesc, "Compact\n" + "To save disk space, none of the " + "optional features will be " + "installed.", AFTER); ListAddString (listDesc, "Custom\n" + "For advanced users and system " + "administrators only. You can " + "customize all available Setup " + "options.", AFTER); // Display the dialog. nResult = SdOptionsButtons (szTitle, szMsg, listButton, listDesc); // Display a message showing which button was selected. switch (nResult) case 101: MessageBox ("Typical installation selected.", INFORMATION); case 102: MessageBox ("Portable installation selected.", INFORMATION); case 103: MessageBox ("Compact installation selected.", INFORMATION); case 104: MessageBox("Custom installation selected.", INFORMATION); default: MessageBox ("SdOptionsButtons:\n\n An error occurred.", SEVERE); endswitch; Enable(NEXTBUTTON);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1253

Appendix E: Built-In Functions (S-T) SdOutOfDiskSpace

// Destroy the lists. ListDestroy (listButton); ListDestroy (listDesc); end;

SdOutOfDiskSpace
Project: This information applies to InstallScript MSI projects.

The SdOutOfDiskSpace function displays a dialog warning the end user that the target system does not have enough available space for the application installation to take place. It also displays a list view of volumes, required space, available space, and the difference between available space and required space. In an InstallScript MSI installation, this function is triggered when an INSTALLMESSAGE_OUTOFDISKSPACE message is detected. This message comes from the MSI engine. The SdDiskSpace2 function supersedes the SdOutOfDiskSpace function.

Syntax
SdOutOfDiskSpace ( szTitle, szMsg );

Parameters
Table E-69: SdOutOfDiskSpace Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Out of Disk Space), pass a null string () in this parameter. Specifies the message to display in the dialog. This text is considered a static control. To display the default instructions for this dialog, pass a null string () in this parameter.

szMsg

Return Values
Table E-70: SdOutOfDiskSpace Return Values Return Value NEXT (1) Description Indicates that the end user clicked the OK button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.
1254 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdPatchWelcome

SdPatchWelcome
Project: This information applies to InstallScript MSI projects.

The SdPatchWelcome function creates a dialog that displays a welcome message to the end user during a patch installation.

Syntax
SdPatchWelcome ( szTitle, szMsg );

Parameters
Table E-71: SdPatchWelcome Parameters Parameter szTitle Description Specifies the text to display in the title of the dialog. To display the default title (Welcome), pass a null string ("") in this parameter. Specifies the message to display in the Welcome dialog. To include in this message the product name set by a previous call to SdProductName, insert the place holder %P anywhere in the message string. When the message is displayed, %P is replaced by the product name. To display the default welcome message, pass a null string ("") in this parameter.

szMsg

Return Values
Table E-72: SdPatchWelcome Return Values Return Value NEXT (1) Description Indicates that the Next button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. If you call SdPatchWelcome but SD_NDLG_PATCHWELCOMEits dialog resource (12059) cannot be found in the _isres.dll file of the installation, SdWelcome is called automatically instead of SdPatchWelcome to display a dialog that is similar to the SdPatchWelcome dialog. In this case, the values for szTitle and szMsg are passed to the SdWelcome function, or custom strings are used if szTitle and szMsg are blank. This occurs only if you are patching a product whose installation was created with InstallShield Developer 7, or the dialog template has been removed manually. Note that when this occurs, the dialog uses the same template as SdWelcome; thus, any changes to the SdWelcome dialog template affect the SdPatchWelcome dialog as well. Note that in this scenario, silent mode is not supported, and it does not work correctly.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1255

Appendix E: Built-In Functions (S-T) SdProductName

SdPatchWelcome Example
Project: This information applies to InstallScript MSI projects.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdPatchWelcome function. * * This function displays a welcome message to the end user during * a patch installation. This function is called in the default * script for the OnPatchUIBefore event, which can be found in the * Miscellaneous event category for InstallScript MSI projects. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg; begin // Display SdPatchWelcome with default title and message szTitle = ""; szMsg = ""; SdPatchWelcome(szTitle, szMsg); end;

SdProductName
The SdProductName function sets the value of the system variable IFX_PRODUCT_DISPLAY_NAME, which makes your product name available to all instances of the %P place holder. The %P place holder is found in static text fields in some Sd dialogs. In addition, some Sd dialog functions, such as SdFinish, allow you to include %P in strings passed as parameters to functions.

Syntax
SdProductName ( szProductName );

1256

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdProductName

Parameters
Table E-73: SdProductName Parameters Parameter szProductName Description Specifies the name of the product that is being installed. This name replaces the product name placeholder (%P) wherever it appears in appropriate static fields in Sd dialogs.

Caution: If you want to include an ampersand (&) in your product name, you must use two ampersands (&&) to display the name properly in end user dialogs. For example, to display New & Improved Product, you should enter the product name as New && Improved Product.

Return Values
This function does not return a value.

Additional Information
Rather than call SdProductName, for example,
SdProductName( "My Product Name" );

you can simply assign the desired value to IFX_PRODUCT_DISPLAY_NAME, for example,
IFX_PRODUCT_DISPLAY_NAME = "My Product Name";

SdProductName Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions SdProductName. * * The function SdProductName is called to set the product name to * substitute for the %P place holder, which is embedded in the * message strings passed to Sd dialogs. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szProductName, szTitle; begin // Set the product name to substitute for the %P place holder.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1257

Appendix E: Built-In Functions (S-T) SdRegisterUser

szProductName = "My Application"; SdProductName (szProductName); // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Display the SdWelcome dialog. The null string in parameter // two specifies the default message, which uses the %P place holder. szTitle = "SdProductName Example"; SdWelcome (szTitle, ""); end;

SdRegisterUser
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdRegisterUser function displays a dialog that enables the end user to specify the user name and company name for the product being installed. You can specify default values for these fields by specifying the appropriate parameters. If you specify a null string (""), the function uses the appropriate script variable. The Next button becomes enabled only when data exists in both edit fields. The end user cannot leave any field blank.

Syntax
SdRegisterUser ( szTitle, szMsg, svName, svCompany );

1258

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdRegisterUser

Parameters
Table E-74: SdRegisterUser Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (User Information), pass a null string () in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies the default value for the Name edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDOWNER variable. For an InstallScript project, this variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. For an InstallScript MSI project, the default value of the variable is always read from the Windows Installer property USERNAME. The function returns the value that the end user specified in this parameter. In an InstallScript installation, the function also sets the value of IFX_PRODUCT_REGISTEREDOWNER to the value that the end user specified. In an InstallScript MSI installation, the function automatically updates the Windows Installer property USERNAME. svCompany Specifies the default value for the Company edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDCOMPANY variable. For an InstallScript project, this variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. For an InstallScript MSI project, the default value of the variable is always read from the Windows Installer property COMPANYNAME. The function returns the value that the end user specified in this parameter. In an InstallScript installation, the function also sets the value of IFX_PRODUCT_REGISTEREDCOMPANY to the value that the end user specified. In an InstallScript MSI installation, the function automatically updates the Windows Installer property COMPANYNAME.

szMsg

svName

Return Values
Table E-75: SdRegisterUser Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1259

Appendix E: Built-In Functions (S-T) SdRegisterUserEx

SdRegisterUser Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdRegisterUser and SdConfirmRegistration * functions. * * SdRegisterUser is called to prompt for the user's name * and company name. These entries are then confirmed when * SdConfirmRegistration is called. * \*--------------------------------------------------------------*/ #define REG_TITLE #define REG_MSG #define CONFIRM_TITLE #include "Ifx.h" function OnBegin() STRING svName, svCompany; NUMBER nResult; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); repeat // Get the user's name and company name. SdRegisterUser (REG_TITLE, REG_MSG, svName, svCompany); // Confirm that the information is correct. Pass a null string in // parameter four since SdRegisterUser does not get a serial number. nResult = SdConfirmRegistration (CONFIRM_TITLE, svName, svCompany, "", 0); until nResult = YES; end; "SdRegisterUser Example" "Please register your product now." "SdConfirmRegistration Example"

SdRegisterUserEx
Project: This information applies to the following project types:

InstallScript InstallScript MSI

1260

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdRegisterUserEx

The SdRegisterUserEx function displays a dialog that enables the end user to specify the user name, company name, and serial number for the product being installed. You can specify default values for these fields by specifying the appropriate parameters. If you specify a null string (""), the function uses the appropriate script variable. The Next button becomes enabled only when data exists in all three edit fields. The end user cannot leave any field blank.

Note: The SdRegisterUserEx function does not verify the serial number. To learn how to add code that verifies the serial number, see the sample serial number validation project. This sample project is in one of the Samples subfolders within the InstallShield Program Files folder. The default installation location is C:\Program Files\InstallShield\2012\Samples\InstallScript\Serial Number Validation Sample Project.

Syntax
SdRegisterUserEx ( szTitle, szMsg, svName, svCompany, svSerial );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1261

Appendix E: Built-In Functions (S-T) SdRegisterUserEx

Parameters
Table E-76: SdRegisterUserEx Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (User Information), pass a null string () in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies the default value for the Name edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDOWNER variable. For an InstallScript project, this variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. For an InstallScript MSI project, the default value of the variable is always read from the Windows Installer property USERNAME. The function returns the value that the end user specified in this parameter. In an InstallScript installation, the function also sets the value of IFX_PRODUCT_REGISTEREDOWNER to the value that the end user specified. In an InstallScript MSI installation, the function automatically updates the Windows Installer property USERNAME. svCompany Specifies the default value for the Company edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDCOMPANY variable. For an InstallScript project, this variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. For an InstallScript MSI project, the default value of the variable is always read from the Windows Installer property COMPANYNAME. The function returns the value that the end user specified in this parameter. In an InstallScript installation, the function also sets the value of IFX_PRODUCT_REGISTEREDCOMPANY to the value that the end user specified. In an InstallScript MSI installation, the function automatically updates the Windows Installer property COMPANYNAME. svSerial Specifies the default value for the Serial Number edit field when the function is called. If a null string ("") is specified, the default value is the current value of the IFX_PRODUCT_REGISTEREDSERIALNUM variable. This variable is read from the registry in a first-time installation or the corresponding text substitution in maintenance mode. The function returns the value that the end user specified in this parameter. The function also sets the value of IFX_PRODUCT_REGISTEREDSERIALNUM to the value that the end user specified.

szMsg

svName

Return Values
Table E-77: SdRegisterUserEx Return Values Return Value NEXT (1) Description Indicates that the Next button was clicked.

1262

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdRegisterUserEx

Table E-77: SdRegisterUserEx Return Values (cont.) Return Value BACK (12) Description Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdRegisterUserEx Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the function SdRegisterUserEx. * * SdRegisterUserEx is called to collect installation information * from the user. The information is stored in a list and * displayed in SdShowInfoList. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svName, svCompany, svSerial; LIST listData; begin // Create the list. listData = ListCreate (STRINGLIST); // Set up parameters for call to SdRegisterUserEx. szTitle = "SdRegisterUserEx Example"; szMsg = "Please enter your name, company, and serial number."; // Retrieve registration information. SdRegisterUserEx (szTitle, szMsg, svName, svCompany, svSerial); // Add the information to the list. ListAddString (listData, "User Information: ", AFTER); ListAddString (listData, " " + svName, AFTER); ListAddString (listData, " " + svCompany, AFTER); ListAddString (listData, " " + svSerial, AFTER); ListAddString (listData, "", AFTER);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1263

Appendix E: Built-In Functions (S-T) SdRMFilesInUse

// Display user selections from list in SdShowInfoList. szMsg = "The user name, company name, and serial number " + "entered in SdRegisterUserEx."; SdShowInfoList(szTitle, szMsg, listData); end;

SdRMFilesInUse
Project: The InstallScript MSI project type support the SdFilesInUse function.

The SdRMFilesInUse function displays a dialog that includes a list box containing a list of the applications that are open and are locking files. The dialog also includes two radio buttons that allow end users to specify whether the installation should attempt to use the Restart Manager to shut down the applications that are locking files or overwrite the locked files (which most likely results in the need for a reboot to complete the installation). Typically, the OnRMFilesInUse event handler displays this dialog in an InstallScript MSI installation as a response to an INSTALLMESSAGE_FILESINUSE message sent by the Windows Installer. When this occurs, the Windows Installer provides to the installation the list of applications that are locking files. The list of applications are passed through the szMessage parameter to the OnRMFilesInUse event. The event passes this information to the SdRMFilesInUse function through the szMessage parameter. The event then passes the return value from the function as the return value of the event, which causes the Windows Installer to act appropriately.

Project: The SdRMFilesInUse dialog can also be called manually in InstallScript projects and in InstallScript MSI projects; however, the installation must provide the list of applications that are locking files through the nvlistApps parameter, and it must handle the return value appropriately. It must also interact with the Restart Manager to attempt to shut down applications that are locking files if the end user selects the corresponding option on the SdRMFilesInUse dialog.

Syntax
SdRMFilesInUse ( byval string szTitle, byval string szMsg, byval string szFilesInUse, byref LIST nvlistApps, byref BOOL bvCloseRestart );

1264

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdRMFilesInUse

Parameters
Table E-78: SdRMFilesInUse Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Files in Use), pass a null string () in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. When SdRMFilesInUse is called by the OnRMFilesInUse event handler in an InstallScript MSI installation, this parameter specifies the list of applications that the Windows Installer found to be locking files. The function parses this string in order to display the list of applications in the dialog's list box. If you manually call SdFilesInUse, pass an empty string ("") in this parameter. Note that if nvlistApps is a valid string list, this parameter is ignored. nvlistApps When SdRMFilesInUse is called by the OnRMFilesInUse event handler in an InstallScript MSI installation, this parameter is specified as an uninitialized list variablethat is, a variable with a value of 0. If you manually call SdRMFilesInUse, specify a string list of applications that are locking files and that should be displayed in the dialog. Each string in the list indicates one application. (Use the ListCreate function and associated list functions to create and initialize the string list.)

szMsg

szFilesInUse

Note: You must provide a variable for this parameter; you cannot specify a literal value. bvCloseRestart Indicates the default for the aforementioned radio buttons. TRUE indicates that the close-andrestart-applications radio button is the default. FALSE indicates that the ignore-and-reboot-later radio button should be the default.

Project: In InstallScript MSI projects, the OnRMFilesInUse event sets the value of bvCloseRestart based on the current value of the Windows Installer property called MSIRESTARTMANAGERCONTROL Property. When the SdRMFilesInUse function returns, this value indicates which radio button the end user selectedTRUE for the close-and-restart-applications option or FALSE for the ignore-andreboot-later option. Note that the function also returns the same information in the return value of the function.

Return Values
Table E-79: SdRMFilesInUse Return Values Return Value IDOK Description Indicates that the end user selected the close-and-restart-applications option and then clicked the OK button.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1265

Appendix E: Built-In Functions (S-T) SdSelectFolder

Table E-79: SdRMFilesInUse Return Values (cont.) Return Value IDIGNORE (5) Description Indicates that the end user selected the ignore-and-reboot-later option and then clicked the OK button. Note that this value can be returned even though the dialog does not include an Ignore button. Indicates that the end user clicked the Exit button.

IDCANCEL

Note: Note that unlike other script dialogs, this dialog does not call the OnCanceling event handler when the user clicks the Exit button. Therefore, if you are calling this function manually, you must handle this return value manually in order to display the Cancel Setup dialog.

SdSelectFolder
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdSelectFolder function displays folders for selection. SdSelectFolder enables you to offer a default selection. The end user can also enter a new folder name. SdSelectFolder returns only the selected or entered folder name. It cannot create the folder.

Syntax
SdSelectFolder ( szTitle, szMsg, svDefGroup );

1266

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdSelectFolder

Parameters
Table E-80: SdSelectFolder Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Select Program Folder), pass a null string () in this parameter. Specifies the message to display in the dialog. This text is considered a static control. To display the default instructions for this dialog, pass a null string () in this parameter. Returns the name of the selected folder.

szMsg

svDefGroup

Return Values
Table E-81: SdSelectFolder Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. If ProgDefGroupType is called before calling SdSelectFolder, the program folders displayed by SdSelectFolder (Common or Personal) depend on the parameter that was passed to ProgDefGroupType.

SdSelectFolder Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdSelectFolder function. * * SdSelectFolder is called to prompt the user to select a * folder. *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1267

Appendix E: Built-In Functions (S-T) SdSetupCompleteError

* Note: Before running this script, verify that the constant * DEF_FOLDER references an existing folder on the * target computer. * \*--------------------------------------------------------------*/ #define DEF_FOLDER "Startup" #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svDefGroup; begin // Set up parameters for call to SdSelectFolder. szTitle = "SdSelectFolder Example"; szMsg = ""; svDefGroup = DEF_FOLDER; // Get user's folder selection. SdSelectFolder (szTitle, szMsg, svDefGroup); end;

SdSetupCompleteError
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdSetupCompleteError function displays a dialog to inform the end user that the installation was interrupted before it could be completed. It also informs the end user that the product has not been installed and that the target system was not modified.

Syntax
SdSetupCompleteError ( szTitle, szMsg1, szMsg2 );

1268

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdSetupCompleteError

Parameters
Table E-82: SdSetupCompleteError Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (InstallShield Wizard Completed), pass a null string ("") in this parameter. Specifies the message to display at the top of the dialog. To display the default instructions, which inform the end user that the installation has been interrupted and the product has not been installed, pass a null string ("") in this parameter. Specifies the message to display at the bottom of the dialog. To display the default instructions (Click Finish to exit the wizard), pass a null string ("") in this parameter.

szMsg1

szMsg2

Return Values
Table E-83: SdSetupCompleteError Return Values Return Value NEXT (1) Description Indicates that the Finish button was clicked.

Additional Information
If you write your own procedural script, that is, a program/endprogram block, you can use the SdSetupCompleteError function to display a dialog if the end user cancels the installation. If you are using the default script event model, you do not need to call this function. Because SdSetupCompleteError indicates that the installation was interrupted and cannot be completed, the Back button is disabled. The SdSetupCompleteError dialog is a variation of the SdFinish dialog. In a silent response file (.iss), the SdSetupCompleteError dialog is referred to as SdFinish.

SdSetupCompleteError Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdSetupCompleteError function. * * SdSetupCompleteError function displays a dialog to inform * the end user that the installation was interrupted before it
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1269

Appendix E: Built-In Functions (S-T) SdSetupType

* could be completed. It also informs the end user that the * application has not been installed and that the target system * was not modified. This function is only available for MSI * based projects. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg1, szMsg2; begin // Set up parameters for call to SdSetupCompleteError. szTitle = "SdSetupCompleteError Example"; szMsg1 = ""; szMsg2 = ""; SdSetupCompleteError ( szTitle, szMsg1, szMsg2 ); end;

SdSetupType
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdSetupType function displays a dialog that enables the end user to select one of the three standard setup types: Typical, Compact, or Custom. These setup options are displayed with standard description text. If you want to add other setup types or change the displayed setup type names or descriptions, call SdSetupTypeEx instead. The dialog also displays a default destination path. A browse button launches a dialog that allows the end user to change the destination path, either by entering a new folder name or by selecting an existing folder from a list. If the end user enters the name of a folder that does not exist, this function automatically creates the specified folder. The fully qualified path of the specified folder is returned in svDir.

Caution: If the end user returns to the SdSetupType dialog after using a feature dialog to select and deselect features associated with the selected setup type, those choices are lost. This occurs because the SdSetupType function automatically resets the default feature selections for the selected setup type each time it is called.

Syntax
SdSetupType ( szTitle, szMsg, svDir, nReserved );

1270

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdSetupType

Parameters
Table E-84: SdSetupType Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Setup Type), pass a null string () in this parameter. Specifies a message to display in the dialog. This text is considered a static control. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies a default folder name. Returns the name of the folder selected by the end user. Reserved for future use. Pass 0 (zero) in this parameter.

szMsg

svDir

nReserved

Return Values
Table E-85: SdSetupType Return Values Return Value TYPICAL (301) COMPACT (302) CUSTOM (303) BACK (12) Description Indicates that the user selected Typical Setup. Indicates that the user selected Compact Setup. Indicates that the user selected Custom Setup. Indicates that the Back button was clicked.

Additional Information
In an InstallScript project, if you do not display a setup type dialog, your script must do one of the following:

Select a setup type. Call a feature selection dialog function such as SdFeatureTree. Directly select features.

To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdSetupType Example
Project: This information applies to the following project types:

InstallScript
ISP-1800-RG00 1271

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdSetupType2

InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions SdSetupType. * * This function displays a dialog that enables the end user * to select one of the three standard setup types: Typical, * Compact, or Custom. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svDir; NUMBER nReserved, nResult; begin // Display the SdSetupType dialog. szTitle = "SdSetupType Example"; szMsg = ""; // Default destination folder displayed in dialog. svDir = "C:\\Example"; nReserved = 0; nResult = SdSetupType (szTitle, szMsg, svDir, nReserved); // Set TARGETDIR to the user selected destination folder. TARGETDIR = svDir; // Retrieve user selected setup type. switch(nResult) case CUSTOM: MessageBox("Custom setup type selected", 0); case TYPICAL: MessageBox("Typical setup type selected", 0); case COMPACT: MessageBox("Compact setup type selected", 0); endswitch; end;

SdSetupType2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdSetupType2 function displays a dialog that enables the end user to select one of the two standard setup types: Typical or Custom. These setup options are displayed with standard description text. If you want to add other setup types or change the displayed setup type names or descriptions, call SdSetupTypeEx instead.
1272 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdSetupType2

The dialog also displays a default destination path. A browse button launches a dialog that allows the end user to change the destination path, either by entering a new folder name or by selecting an existing folder from a list. If the end user enters the name of a folder that does not exist, this function automatically creates the specified folder. The fully qualified path of the specified folder is returned in svDir.

Caution: If the end user returns to the SdSetupType2 dialog after using a feature dialog to select and deselect features associated with the selected setup type, those choices are lost. This occurs because the SdSetupType2 function automatically resets the default feature selections for the selected setup type each time it is called.

Syntax
SdSetupType2 ( szTitle, szMsg, svDir, nReserved );

Parameters
Table E-86: SdSetupType2 Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Setup Type), pass a null string () in this parameter. Specifies a message to display in the dialog. This text is considered a static control. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies a default folder name. Returns the name of the folder selected by the end user. Reserved for future use. Pass 0 (zero) in this parameter.

szMsg

svDir

nReserved

Return Values
Table E-87: SdSetupType2 Return Values Return Value COMPLETE (304) TYPICAL (301) CUSTOM (303) BACK (12) Description Indicates that the user selected the Complete setup type. Indicates that the user selected the Typical setup type. Indicates that the user selected the Custom setup type. Indicates that the user clicked the Back button.

Additional Information
In an InstallScript project, if you do not display a setup type dialog, your script must do one of the following:

Select a setup type.

ISP-1800-RG00 1273

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdSetupType2

Call a feature selection dialog function such as SdFeatureTree. Directly select features.

To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdSetupType2 Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the function SdSetupType2. * * SdSetupType2 is called to collect installation information * from the user. * \*--------------------------------------------------------------*/ #include "ifx.h" function OnBegin() STRING szTitle, szMsg, svDir; STRING svSetupType; NUMBER nResult; begin // Disable Back button Disable(BACKBUTTON); // Set up parameters for call to SdSetupType2. szTitle = "SdSetupType2 Example"; szMsg = "Choose the type of installation by clicking one of the buttons."; // Retrieve setup type and directory information. svDir = TARGETDIR; nResult = SdSetupType2 (szTitle , szMsg, svDir, 0); TARGETDIR = svDir; // Create a string that describes the selected setup type. switch (nResult) case COMPLETE: svSetupType = "COMPLETE: Application will be installed " + "with all options."; case CUSTOM: svSetupType = "CUSTOM: You select the options that you " + "want installed."; default: MessageBox ("Invalid setup type selection!", SEVERE); abort;
1274 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdSetupTypeEx

endswitch; MessageBox("Setup Type: " + svSetupType, 0); end;

SdSetupTypeEx
Project: This information applies to InstallScript MSI projects.

The SdSetupTypeEx function displays a dialog that enables the end user to select the setup type when you specify setup types beyond Complete and Custom. The dialog displays the names of the setup types as you specified them in the Setup Types view.

Syntax
SdSetupTypeEx ( szTitle, szMsg, szReserved, svSetupType, nReserved );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1275

Appendix E: Built-In Functions (S-T) SdSetupTypeEx

Parameters
Table E-88: SdSetupTypeEx Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Setup Type), pass a null string () in this parameter. Specifies the message to be displayed in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. Pass a null string () in this parameter. No other value is allowed. Specifies a default setup type and returns the setup type selected by the end user. The string returned in this parameter will match the name of the setup type as you specified it in the IDE. Pass zero in this parameter. No other value is allowed.

szMsg

szReserved svSetupType

nReserved

Return Values
Table E-89: SdSetupTypeEx Return Values Return Value 0 BACK (12) Description Indicates that SdSetupTypeEx was successful. Indicates that the Back button was clicked.

Additional Information
In an InstallScript project, if you do not display a setup type dialog, your script must do one of the following:

Select a setup type Call a feature selection dialog function such as SdFeatureTree. Directly select features.

To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdSetupTypeEx Example
Project: This information applies to InstallScript MSI projects.
/*--------------------------------------------------------------*\ * * InstallShield Example Script

1276

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdShowAnyDialog

* * Demonstrates the SdSetupTypeEx function. * * The SdSetupTypeEx function displays a dialog that enables * the end user to select the setup type when you specify setup * types beyond Complete and Custom. The dialog * displays the names of the setup types you create in the IDE's * Setup Types view. * * This sample sets the default setup type in the SdSetupTypeEx * dialog to "Complete". * \*--------------------------------------------------------------*/ #include "ifx.h" function OnBegin() STRING szTitle, szMsg, szReserved, svSetupType; NUMBER nReserved; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up the variables to pass as parameters to SdSetupTypeEx. szTitle= "SdSetupTypeEx Sample"; szMsg= ""; szReserved = ""; // Specifies a default setup type (as specified in the Setup Type // view) and returns the setup type selected by the end user svSetupType = "Complete"; nReserved = 0; // Display the SdSetupTypeEx dialog. SdSetupTypeEx(szTitle, szMsg, szReserved, svSetupType, nReserved); // Display a MessageBox with the setup type selected by the end user MessageBox("Setup Type selected: " + svSetupType, 0); end;

SdShowAnyDialog
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdShowAnyDialog function displays a custom or modified dialog. This function is recommended for advanced users only.

Syntax
SdShowAnyDialog ( szTitle, szID, nID, nReserved );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1277

Appendix E: Built-In Functions (S-T) SdShowAnyDialog

Parameters
Table E-90: SdShowAnyDialog Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Welcome), pass a null string () in this parameter. Specifies the string identifier that identifies the dialog. If this parameter contains a null string (), SdShowAnyDialog uses the value in nID. Specifies the numeric value that identifies the dialog. If you entered a value in szID, this parameter is ignored. Pass zero in this parameter. No other value is allowed.

szID

nID

nReserved

Return Values
Table E-91: SdShowAnyDialog Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler. In order to use the SdShowAnyDialog function, you must know the ID of either the modified dialog in _isres.dll or the custom dialog in _isuser.dll that you want to display. If the dialog has only static controls, you do not need to modify the SdShowAnyDialog script file. However, if your dialog has any other controls, you must modify the Sdsadlg.rul filelocated in the Script\Isrt\Src folder of your InstallShield program files folderin order to process the feedback from the user.

SdShowAnyDialog Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script

1278

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdShowDlgEdit1

* * Demonstrates the SdShowAnyDialog function. * * SdShowAnyDialog is called twice, first with the ID of the * Welcome dialog, then with the ID of the Finish dialog * box. * \*--------------------------------------------------------------*/ #define TITLE "SdShowAnyDialog Example" #include "Ifx.h" function OnBegin() begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up the product name so that it can be displayed // in place of the %P placeholder in Sd dialogs. SdProductName ("ExampApp"); // Display the SdWelcome dialog. SdShowAnyDialog (TITLE, "", SD_NDLG_WELCOME, 0); // Display the SdFinish dialog. SdShowAnyDialog (TITLE, "", SD_NDLG_FINISH, 0); end;

SdShowDlgEdit1
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdShowDlgEdit1 function creates a general dialog that displays a message and one single-line edit field. You can specify a title for the dialog.

Syntax
SdShowDlgEdit1 ( szTitle, szMsg, szField1, svEdit1 );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1279

Appendix E: Built-In Functions (S-T) SdShowDlgEdit1

Parameters
Table E-92: SdShowDlgEdit1 Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Edit Data), pass a null string () in this parameter. Specifies the message to display in the dialog. To include in this message the product name set by a previous call to SdProductName, insert the place holder %P anywhere in the message string. When the message is displayed, %P is replaced by the product name. Specifies a field name to be displayed to the left of the edit field. The default field name is Field 1:. To display the default name, pass a null string () in this parameter. The maximum number of characters that can be displayed is approximately 10. The actual maximum depends on the combined width of each character in the field name. If the field name exceeds the available space, it will be truncated on the right when the dialog is displayed. Specifies an initial value for the edit field; returns the value of the edit field when the dialog is closed.

szMsg

szField1

svEdit1

Return Values
Table E-93: SdShowDlgEdit1 Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdShowDlgEdit1 Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------* * * InstallShield Example Script *

1280

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdShowDlgEdit2

* Demonstrates the SdShowDlgEdit1 function. * * This example script calls SdShowDlgEdit1 to obtain the name * of a folder, which is then displayed in a message box. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, szField1, svEdit1; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up parameters for call to SdShowDlgEdit1. szTitle = "SdShowDlgEdit1 Example"; szMsg = "Please choose a folder for YourApp:"; szField1 = "Target:"; svEdit1 = "C:\\Example\\Target\\YourApp"; // Get a target folder name from the user. if (SdShowDlgEdit1 (szTitle, szMsg, szField1, svEdit1) < 0) then // Report an error. MessageBox ("SdShowDlgEdit1 failed.", SEVERE); else // Display svEdit1 string variable. SprintfBox (INFORMATION, szTitle, "You selected %s", svEdit1); endif; end;

SdShowDlgEdit2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdShowDlgEdit2 function creates a general dialog that displays a message and two single-line edit fields. You can specify a title for the dialog.

Syntax
SdShowDlgEdit2 ( szTitle, szMsg, szField1, szField2, svEdit1, svEdit2 );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1281

Appendix E: Built-In Functions (S-T) SdShowDlgEdit2

Parameters
Table E-94: SdShowDlgEdit2 Parameters Parameter szTitle Description Specifies the title of the dialog. If you pass a null string () in this parameter, the default title (Edit Data) is displayed. Specifies the message to display in the dialog. To include in this message the product name set by a previous call to SdProductName, insert the place holder %P anywhere in the message string. When the message is displayed, %P is replaced by the product name. Specifies a field name to be displayed to the left of the first edit field. The default field name is Field 1: ; to display the default name, pass a null string () in this parameter. The maximum number of characters that can be displayed is approximately 10. The actual maximum depends on the combined width of each character in the field name. If the field name exceeds the available space, it will be truncated on the right when the dialog is displayed. Specifies a field name for the second edit field. Field 2: is the default. Specifies an initial value for the first edit field; returns the value of the first edit field when the dialog is closed. Specifies an initial value for the second edit field; returns the value of the second edit field when the dialog is closed.

szMsg

szField1

szField2 svEdit1

svEdit2

Return Values
Table E-95: SdShowDlgEdit2 Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdShowDlgEdit2 Example
Project: This information applies to the following project types:

InstallScript

1282

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdShowDlgEdit3

InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdShowDlgEdit2 function. * * This script displays a dialog that prompts the user to * specify a source folder and a target folder. It then displays * the user's selections in a message box. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, szField1, szField2, svEdit1, svEdit2; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up parameters for call to SdShowDlgEdit2. szTitle = "SdShowDlgEdit2 Example"; szMsg = "All files within the Source directory will be copied into " + "the Target directory."; szField1 = "Source:"; szField2 = "Target:"; svEdit1 = "C:\\Example\\Source"; svEdit2 = "C:\\Example\\Target"; // Get source and target folder names. if (SdShowDlgEdit2 (szTitle, szMsg, szField1, szField2, svEdit1, svEdit2) < 0) then // Report an error. MessageBox ("SdShowDlgEdit2 failed.", SEVERE); else // Display the user's selections. SprintfBox (INFORMATION, szTitle, "svEdit1: %s\n\nsvEdit2: %s", svEdit1, svEdit2); endif; end;

SdShowDlgEdit3
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdShowDlgEdit3 function creates a general dialog that displays a message and three single-line edit fields. You can specify a title for the dialog in szTitle.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1283

Appendix E: Built-In Functions (S-T) SdShowDlgEdit3

Syntax
SdShowDlgEdit3 ( szTitle, szMsg, szField1, szField2, szField3, svEdit1, svEdit2, svEdit3 );

Parameters
Table E-96: SdShowDlgEdit3 Parameters Parameter szTitle Description Specifies the title of the dialog. If you pass a null string () in this parameter, the default title (Edit Data) is displayed. Specifies the message to display in the dialog. To include in this message the product name set by a previous call to SdProductName, insert the place holder %P anywhere in the message string. When the message is displayed, %P is replaced by the product name. Specifies a field name to be displayed to the left of the first edit field. The default field name is Field 1:. To display the default name, pass a null string () in this parameter. The maximum number of characters that can be displayed is approximately 10. The actual maximum depends on the combined width of the characters in the field name. If the field name is too large for the available space, it will be truncated on the right when the dialog is displayed. Specifies a field name for the second edit field. Field 2: is the default. Specifies a field name for the third edit field. Field 3: is the default. Specifies an initial value for the first edit field; returns the value of the first edit field when the dialog is closed. Specifies an initial value for the second edit field; returns the value of the second edit field when the dialog is closed. Specifies an initial value for the third edit field; returns the value of the third edit field when the dialog is closed.

szMsg

szField1

szField2 szField3 svEdit1

svEdit2

svEdit3

Return Values
Table E-97: SdShowDlgEdit3 Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

1284

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdShowDlgEdit3

SdShowDlgEdit3 Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdShowDlgEdit3 function. * * This script calls SdShowDlgEdit3 to get three folder names * from the user. These are then displayed in a message box. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, szField1, szField2, szField3, svEdit1, svEdit2; STRING svEdit3; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up parameters for call to SdShowDlgEdit3. szTitle = "SdShowDlgEdit3 Example"; szMsg = "Please choose up to two valid directories in Backup: or " + "Alternate: to back up the source directory.\n\n"; szField1 = "Directory"; szField2 = "Backup"; szField3 = "Alternate"; svEdit1 = "C:\\YourApp"; svEdit2 = "C:\\Backup1"; svEdit3 = "C:\\Backup2"; // Get three folder names from the user. if (SdShowDlgEdit3 (szTitle, szMsg, szField1, szField2, szField3, svEdit1, svEdit2, svEdit3) < 0) then // Report an error. MessageBox ("SdShowDlgEdit3 failed.", SEVERE); else // Display the folder names specified by the user. szMsg = "svEdit1: %s\n\nsvEdit2: %s\n\nsvEdit3: %s"; SprintfBox (INFORMATION, szTitle, szMsg, svEdit1, svEdit2, svEdit3); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1285

Appendix E: Built-In Functions (S-T) SdShowFileMods

SdShowFileMods
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdShowFileMods function creates a dialog that displays changes you want to make to a file. These choices are available:

Make changes to the target file. Make changes to the alternate file, which is a copy of the target file, but incorporates changes. Do not make any changes. SdShowFileMods does not make changes to a file. You must write those changes into your script using the appropriate file functions.

Syntax
SdShowFileMods ( szTitle, szMsg, szTargetFile, szAltFile, listChanges, nvSelection );

1286

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdShowFileMods

Parameters
Table E-98: SdShowFileMods Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Modifying File), pass a null string () in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies the name of the file to modify. This will be displayed with the first radio button. Specifies an alternate name to give the file if the end user decides to make the changes. This will be displayed with the second radio button. To use the name of file specified in szTargetFile with the extension .bak, pass a null string () in this parameter. Specifies the name of a string list that contains the list of changes to make to the file. This list is placed in a multi-line edit field that allows the end user to select the changes to be implemented. Returns the ID of the button selected by the end user:

szMsg

szTargetFile

szAltFile

listChanges

nvSelection

101Let Setup modify the <szTargetFile> file. 102Save the required changes to <szAltFile> file. 103Do not make any changes.

Return Values
Table E-99: SdShowFileMods Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdShowFileMods Example
Project: This information applies to the following project types:

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1287

Appendix E: Built-In Functions (S-T) SdShowFileMods

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdShowFileMods function. * * This script displays a list of changes to make to a specified * file. The user may elect to make those changes, to save the * changes to a new file, or not to make or save the changes. * * Note: SdShowFileMods does not itself modify or create files. * It simply obtains the user's choice. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, szTargetFile, szAltFile; NUMBER nvSelection; LIST listID; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up variables for call to SdShowFileMods. szTitle = "SdShowFileMods Example"; szMsg = "Choose what option to take"; szTargetFile = "Example.txt"; szAltFile = "Example.new"; // Create a list to hold file modification details. listID = ListCreate (STRINGLIST); // Add file modification details to the list. ListAddString (listID, "PATH = C:\\Example", AFTER); ListAddString (listID, "FILES = 40", AFTER); // Present options and get the user's choice. SdShowFileMods (szTitle, szMsg, szTargetFile, szAltFile, listID, nvSelection); // Handle the user's selection. switch(nvSelection) case 101: SprintfBox (INFORMATION, szTitle, "Setup modified the %s file.", szTargetFile); case 102: SprintfBox (INFORMATION, szTitle, "The required changes were saved " + "to the %s file.", szAltFile); case 103: SprintfBox (INFORMATION, szTitle, "No changes were made.");

1288

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdShowInfoList

endswitch; end;

SdShowInfoList
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdShowInfoList function creates a dialog that displays a list of scrollable messages. SdShowInfoList can display lists of up to approximately 57,200 characters.

Syntax
SdShowInfoList ( szTitle, szMsg, listID );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1289

Appendix E: Built-In Functions (S-T) SdShowInfoList

Parameters
Table E-100: SdShowInfoList Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Information), pass a null string () in this parameter. Specifies the message to display on one line above the information box. If the message is too long to fit on one line, it is truncated on the right. If the message includes a newline escape sequence (\n), the text following that escape sequence is not displayed. To display the default message (Text), pass a null string () in this parameter. Specifies the list of messages to display in the dialog. All messages that appear in the dialog are read only.

szMsg

listID

Return Values
Table E-101: SdShowInfoList Return Values Return Value NEXT (1) BACK (12) Description Indicates that the Next button was clicked. Indicates that the Back button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdShowInfoList Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdShowInfoList function. * * This script calls GetSystemInfo to retrieve information about * the user's system. The ListAdd function is used to add the * information to a string list, which is displayed by * calling SdShowInfoList function. *
1290 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdShowMsg

\*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svReturn, szInfo; NUMBER nvReturn; LIST listInfo; begin // Create a list to hold system information. listInfo = ListCreate (STRINGLIST); // Check if the system has a CD-ROM drive. GetSystemInfo (CDROM, nvReturn, svReturn); if (nvReturn = TRUE) then szInfo = "Your machine has a CD-ROM Drive."; else szInfo = "Your machine does not have a CD-ROM drive."; endif; // Add the CD-ROM info to the list. ListAddString (listInfo, szInfo, AFTER); // Check the time on the system. GetSystemInfo (TIME, nvReturn, svReturn); Sprintf (szInfo, "The time now is %s.", svReturn); // Add the time to the list. ListAddString (listInfo, szInfo, AFTER); // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set up title and message parameters for call to SdShowInfoList. szTitle = "SdShowInfoList Example"; szMsg = "Following is some information related to your system:"; // Display the information. SdShowInfoList (szTitle, szMsg, listInfo); end;

SdShowMsg
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdShowMsg function provides a simple way to display an informative message that remains on screen while script processing continues.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1291

Appendix E: Built-In Functions (S-T) SdShowMsg

The SdShowMsg function opens or closes a small modeless window that displays the message specified by szMsg. When bShow is TRUE, the window is opened, the message is displayed in the window, and processing continues with the next statement in the script. Note that the SdShowMsg window is positioned at the center of the setup window. When bShow is FALSE, szMsg is ignored and the SdShowMsg window is closed.

Note: When the SdShowMsg window is open, subsequent calls to SdShowMsg with TRUE in the second parameter are ignored. To change the message, you must first close the window by calling SdShowMsg with FALSE in the second parameter and then call SdShowMsg again with the new message in szMsg and TRUE in the second parameter.

Syntax
SdShowMsg ( szMsg, bShow );

Parameters
Table E-102: SdShowMsg Parameters Parameter szMsg Description Specifies the message to display in the window. To display the default message (Setup is searching for installed features), pass a null string () in this parameter. This parameter is ignored when bShow is FALSE. SdShowMsg is designed to display a message on a single line. Do not embed newline characters (\n) in szMsg.

Note: The SdShowMsg window is sized horizontally to display the value of szMsg on a single line. If the length of the message exceeds the maximum width of the window, the message is truncated to fit the window. bShow Specifies whether to open or close the window. Pass one of the following predefined constants in this parameter:

TRUEOpens the window if it is not already open. FALSECloses the window if it is open.

Return Values
This function always returns 0.

Additional Information
The dialog that is displayed by the SdShowMsg function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin. The Dialog Editor does not support dialogs, such as SdShowMsg, that do not have a title bar. Therefore, this dialog is not displayed in the Dialogs view as one of the dialogs that you can edit. To customize this dialog, use the SdShowMsg call.

1292

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdStartCopy

SdShowMsg Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SdShowMsg dialog. * * SdShowMsg is called to display a message for three seconds. * It's then called again to remove the message from the screen. * A final call to SdShowMsg displays another message. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szMsg; begin // Display a message on the screen. szMsg = "This message will appear for three seconds."; SdShowMsg (szMsg, TRUE); // Delay for 3 seconds. Delay (3); // Remove message from screen. SdShowMsg (szMsg, FALSE); // Display another message on the screen. szMsg = "This is another message which will " + "appear for a mere three seconds."; SdShowMsg (szMsg, TRUE); Delay(3); // Remove message from screen. SdShowMsg (szMsg, FALSE); end; // Source file:Is5fn157.rul

SdStartCopy
Project: This information applies to the following project types:

InstallScript

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1293

Appendix E: Built-In Functions (S-T) SdStartCopy

InstallScript MSI

The SdStartCopy function creates a multi-line edit field displaying the settings and selections made during the installation. The end user can click the Back button on the dialog to return to previous dialogs in order to change settings as required. Call SdStartCopy after retrieving the selections from the user, but before beginning the file transfer process. Use a string list to collect the information obtained during the installation. You then pass the string list to SdStartCopy in the parameter listData. SdStartCopy displays the list and allows the user to verify that the information is correct before continuing with the file transfer process.

Syntax
SdStartCopy (szTitle, szMsg, listData);

Parameters
Table E-103: SdStartCopy Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title (Start Copying Files), pass a null string () in this parameter. Specifies the message to display in the static text field above the multi-line edit field. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies a string list of information retrieved from the end user. SdStartCopy automatically places each element into the multi-line edit field. If listData has not been initialized by a call to ListCreate, the multi-line edit field is hidden and only the static text field is visible.

szMsg

listData

Return Values
Table E-104: SdStartCopy Return Values Return Value NEXT (1) BACK (12) Description Indicates that the user selected the Next button. Indicates that the user selected the Back button.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

1294

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdStartCopy

SdStartCopy Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the function SdStartCopy, with the use of * SdRegisterUserEx and SdSetupType. * * SdRegisterUserEx and SdSetupType are called to collect * installation information from the user. The information is * stored in a list and displayed by SdStartCopy. * \*--------------------------------------------------------------*/ #include "Ifx.h" function OnBegin() STRING szTitle, szMsg, svName, svCompany, svSerial, svDir, svSetupType; LIST listData; NUMBER nResult; begin start: // Create the list. listData = ListCreate (STRINGLIST); // Set up message parameter for call to SdRegisterUserEx. szMsg = "Please enter your name, company, and serial no."; // Retrieve registration information. SdRegisterUserEx ("Registration", szMsg, svName, svCompany, svSerial); // Add the information to the list. ListAddString (listData, "User Information: ", AFTER); ListAddString (listData, " " + svName, AFTER); ListAddString (listData, " " + svCompany, AFTER); ListAddString (listData, " " + svSerial, AFTER); ListAddString (listData, "", AFTER); SetupTypeLabel: // Set up parameters for call to SdSetupType. szMsg = "Choose the type of installation by clicking one of the buttons."; svDir = TARGETDIR; // Retrieve setup type and directory information. nResult = SdSetupType("Select Setup Type", szMsg, svDir, 0); // Create a string that describes the selected setup type. switch (nResult) case TYPICAL: svSetupType = "TYPICAL: Application will be installed " + "with the most common options.";

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1295

Appendix E: Built-In Functions (S-T) SdStartCopy2

case COMPACT: svSetupType = "COMPACT: Application will be installed " + "with the minimum required options."; case CUSTOM: svSetupType = "CUSTOM: You select the options that you " + "want installed."; case BACK: goto start; default: MessageBox ("Invalid setup type selection!", SEVERE); abort; endswitch; // Add the setup type information to the list. ListAddString(listData, "Setup Type:", AFTER); ListAddString(listData, " " + svSetupType, AFTER); ListAddString(listData, "", AFTER); ListAddString(listData, "Destination Directory:", AFTER); ListAddString(listData, " " + svDir, AFTER); // Set up title and message parameters for call to SdStartCopy. szTitle = "SdStartCopy Example"; szMsg = "Setup has enough information to begin the file-transfer\n" + "operation. If you want to review or change any of the\n" + "settings, click Back. If you are satisfied with the\n" + "settings, click Next to begin copying files."; // Call SdStartCopy to display user selections. nResult = SdStartCopy (szTitle, szMsg, listData); // Handle the user's exit from the SdStartCopy dialog. switch(nResult) case NEXT: MessageBox ("SdStartCopy successful.",INFORMATION); case BACK: goto SetupTypeLabel; default: MessageBox ("SdStartCopy failed.", SEVERE); endswitch; end;

SdStartCopy2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdStartCopy2 function informs the user that the file transfer process is about to begin. The user can click the Back button to return to previous dialogs in order to change settings as required. Call SdStartCopy2 after retrieving the selections from the user, but before beginning the file transfer process.

Syntax
SdStartCopy2 ( szTitle, szMsg );
1296 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdStartCopy2

Parameters
Table E-105: SdStartCopy2 Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title ("Ready to Install the Program"), pass a null string ("") in this parameter. Specifies the message to display in the static text field. To display the default instructions for this dialog, pass a null string ("") in this parameter.

szMsg

Return Values
Table E-106: SdStartCopy2 Return Values Return Value NEXT BACK < ISERR_SUCCESS Description Indicates that the user selected the Install button. Indicates that the user selected the Back button. Indicates that the dialog could not be displayed.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdStartCopy2 Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions SdProductName, SdWelcome, * SdStartCopy2, and SdFinish. * * First, SdProductName is called to set the product name to * substitute for the %P place holder, which is embedded in the * message strings passed to SdWelcome and SdFinish. * * Next, SdWelcome is called to display a welcome message and * then SdStartCopy2 is called. Finally, a call to SdFinish * completes the setup process by giving the user final options. *
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1297

Appendix E: Built-In Functions (S-T) SdStartCopy2

* Note: Before running this script, set the preprocessor * constants so that they reference the fully-qualified * names of the Windows Notepad executable and a valid * text file on the target system. * \*--------------------------------------------------------------*/

//Assign the name of a text file to READMEFILE #define NOTEPAD "C:\\Windows\\Notepad.exe" #define READMEFILE "" STRING STRING BOOL NUMBER szProductName, szTitle, szMsg, szFeatures; szMsg1, szMsg2, szOpt1, szOpt2; bvOpt1, bvOpt2; nReturn;

#include "ifx.h" function OnBegin() begin // Set the product name to substitute for the %P place holder. szProductName = "My Application"; SdProductName (szProductName); SdWelcomeLabel: szTitle = "SdWelcome Example"; // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Display the SdWelcome dialog. The null string in parameter // two specifies the default message, which uses the %P place holder. SdWelcome (szTitle, ""); // Enable the Back button in setup dialogs. Enable (BACKBUTTON); SdStartCopy2Label: szTitle = "SdStartCopy2 Example"; // Display the SdStartCopy2 dialog. if (SdStartCopy2 (szTitle, szMsg) = BACK) then goto SdWelcomeLabel; endif; // The %P place holder is embedded in several of the string // parameters that will be passed to SdFinish. szTitle = "SdFinish Example"; szMsg1 = "%P Setup is almost complete.\n" + "Choose the options you want below."; szMsg2 = "Click Finish to complete %P Setup."; szOpt1 = "I would like to view the README file."; szOpt2 = "I would like to launch %P."; // Display the SdFinish dialog. SdFinish (szTitle, szMsg1, szMsg2, szOpt1, szOpt2, bvOpt1, bvOpt2); if (bvOpt1) then // Display the read me file.
1298 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdSubstituteProductInfo

LaunchAppAndWait (NOTEPAD, READMEFILE, LAAW_OPTION_WAIT); endif; if (bvOpt2) then // Because this example does not actually install an // application, a message box is displayed in place of // the call to LaunchApp that would normally be made here, // for example: // LaunchApp (TARGETDIR^PROGRAMEXECUTABLE,""); SprintfBox (INFORMATION, szTitle, "Launch %s here.", szProductName); endif; end;

SdSubstituteProductInfo
The SdSubstituteProductInfo function replaces any occurrences of the %P, %VS, and %VI placeholders in svString with the values of the system variables IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and IFX_INSTALLED_DISPLAY_VERSION. You can use this function before calling a function, such as MessageBox, that does not automatically perform this replacement before displaying strings.

Syntax
SdSubstituteProductInfo ( svString );

Parameters
Table E-107: SdSubstituteProductInfo Parameters Parameter svString Description Specifies the string containing placeholders; returns the string with the placeholders replaced.

Return Values
This function does not return a value.

SdWelcome
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdWelcome function creates a dialog that displays a welcome message to the end user.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1299

Appendix E: Built-In Functions (S-T) SdWelcome

Syntax
SdWelcome ( szTitle, szMsg );

Parameters
Table E-108: SdWelcome Parameters Parameter szTitle Description Specifies the text to display in the title of the dialog. To display the default title (Welcome), pass a null string () in this parameter. Specifies the message to display in the Welcome dialog. To include in this message the product name set by a previous call to SdProductName, insert the place holder %P anywhere in the message string. When the message is displayed, %P is replaced by the product name. To display the default welcome message (Welcome to the %P Setup program. This program will install %P on your computer), pass a null string () in this parameter.

szMsg

Return Values
Table E-109: SdWelcome Return Values Return Value NEXT (1) Description Indicates that the Next button was clicked.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdWelcome Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the function SdWelcome. * * The SdWelcome function displays a dialog that welcomes * the end user. * \*--------------------------------------------------------------*/

1300

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SdWelcomeMaint

#include "ifx.h" function OnBegin() STRING szTitle, szProductName; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set the product name to substitute for the %P place holder. szProductName = "My Application"; SdProductName (szProductName); szTitle = "SdWelcome Example"; // Display the SdWelcome dialog. The null string in parameter // two specifies the default message, which uses the %P place holder. SdWelcome (szTitle, ""); end;

SdWelcomeMaint
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SdWelcomeMaint function displays a dialog that is intended for use at the beginning of a maintenance setup (that is, the re-running of a setup that has already been run). The dialog contains Modify, Repair, and Remove option buttons.

Syntax
SdWelcomeMaint (szTitle, szMsg, nType);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1301

Appendix E: Built-In Functions (S-T) SdWelcomeMaint

Parameters
Table E-110: SdWelcomeMaint Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title ("Welcome"), pass a null string ("") in this parameter. Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies which option button is the default selection. Pass one of the following predefined constants in this parameter:

szMsg

nType

MODIFYThe Modify button is the default selection. REPAIRThe Repair button is the default selection. REMOVEALLThe Remove button is the default selection.

Return Values
Table E-111: SdWelcomeMaint Return Values Return Value MODIFY (301) Description Indicates that the Modify button was selected when the end user clicked the Next button. Indicates that the Repair button was selected when the end user clicked the Next button. Indicates that the Remove button was selected when the end user clicked the Next button.

REPAIR (302)

REMOVEALL (303)

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SdWelcomeMaint Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script *

1302 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SeekBytes

* Demonstrates the function SdWelcomeMaint. * * The SdWelcomeMaint function displays a dialog that is intended * for use at the beginning of a maintenance setup (the re-running * of a setup that has already been run). The dialog contains * Modify, Repair, and Remove option buttons. * \*--------------------------------------------------------------*/ #include "ifx.h" function OnBegin() STRING szTitle, szProductName; NUMBER nType, nReturn; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Set the product name to substitute for the %P place holder. szProductName = "My Application"; SdProductName (szProductName); szTitle = "SdWelcomeMaint Example"; //Specifies which option button is the default selection. nType = REMOVEALL; // Display the SdWelcomeMaint dialog. The null string in // parameter two specifies the default message, which uses // the %P place holder. nReturn = SdWelcomeMaint (szTitle, "", nType); switch(nReturn) case MODIFY: MessageBox("SdWelcomeMaint selection: Modify", 0); case REPAIR: MessageBox("SdWelcomeMaint selection: Repair", 0); case REMOVEALL: MessageBox("SdWelcomeMaint selection: Remove", 0); endswitch; end;

SeekBytes
The SeekBytes function repositions the file pointer within an open binary file. You can move the file pointer a specific number of bytes relative to its current position or relative to the beginning or end of the file.

Note: Before calling SeekBytes, you must open the file (which can be a file on the Internet) in binary mode by calling OpenFileMode and OpenFile. When you are finished writing bytes to the file, call CloseFile to close the file.

Syntax
SeekBytes ( nFileHandle, nBytes, nPosition );
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1303

Appendix E: Built-In Functions (S-T) SeekBytes

Parameters
Table E-112: SeekBytes Parameters Parameter nFileHandle Description Specifies the file handle of a file that has been opened in binary mode. Specifies the number of bytes to move the file pointer relative to the position specified by nPosition. If nBytes is a positive number, the file pointer is moved toward the end of the file. If nBytes is a negative number, the file pointer is moved toward the beginning of the file. Specifies the location in the file from which to move the pointer nBytes. Pass one of the following predefined constants in this parameter:

nBytes

nPosition

FILE_BIN_CURMoves the pointer nBytes from its current position. FILE_BIN_ENDMoves the pointer nBytes from the end of the file. FILE_BIN_STARTMoves the pointer nBytes from the beginning of the file.

Return Values
Table E-113: SeekBytes Return Values Return Value 0 Description Indicates that the function successfully repositioned the pointer. Indicates that the function was unable to reposition the pointer.

<0

SeekBytes Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ReadBytes and SeekBytes functions. * * SeekBytes is called to position a file pointer to a

1304

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SeekBytes

* specific location in a file that has been opened in binary * mode. ReadBytes then reads a specific number of bytes, * starting at this location. The bytes are read into a string, * which is then displayed in a message box. * * Note: The defined constants EXAMPLE_DIR and EXAMPLE_BIN must * be set to an existing directory and file on the target * system. * \*--------------------------------------------------------------*/ #define EXAMPLE_DIR "C:\\" #define EXAMPLE_BIN "Example.bin" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SeekBytes(HWND); function ExFn_SeekBytes(hMSI) STRING svString; NUMBER nvFileHandle; begin // Set the file mode to read/write. OpenFileMode (FILE_MODE_BINARY); // Open a binary file. if (OpenFile (nvFileHandle, EXAMPLE_DIR, EXAMPLE_BIN) < 0) then // Report an error; then abort. SprintfBox (SEVERE, "CopyBytes Example", "Could not open %s.", EXAMPLE_BIN); abort; endif; // Set the file pointer to the 16th byte in the file. SeekBytes (nvFileHandle, 15, FILE_BIN_START); // Read the next twenty-eight bytes into svString. if (ReadBytes (nvFileHandle, svString, 0, 28) < 0) then // Report an error. MessageBox ("ReadBytes failed.", SEVERE); else // Display the string. SprintfBox (INFORMATION, "ReadBytes Example", "Bytes read: %s", svString); endif; // Close the file. CloseFile (nvFileHandle); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1305

Appendix E: Built-In Functions (S-T) SelectDir

SelectDir
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SelectDir function has been superseded by the SelectDirEx function. You should use the SelectDirEx function when writing new installation programs. You can call the SelectDirEx function with nFlags set to BIF_RETURNONLYFSDIRS | BIF_EDITBOX to achieve the same result as calling the SelectDir function with bCreate set to FALSE. The SelectDir function displays a dialog that allows the end user to specify the folder into which the application will be installed. The end user can enter a fully qualified folder name or select an existing folder from a list. If the end user enters an invalid folder name or an unqualified folder name, a message box is displayed to prompt the end user to enter a valid name. The fully qualified name of the selected folder is returned in svDir. If the specified folder does not exist and the parameter bCreate is TRUE, SelectDir automatically creates the specified folder. If the parameter bCreate is set to FALSE and a non-existent folder is selected, the end user is not informed, and SelectDir does not create it. In this case, it is up to you to handle the selection contained in svDir.

Note: SelectDir is called automatically when the end user clicks the Browse button in the dialogs presented by AskDestPath, SdAskDestPath, and other InstallScript functions that obtain a folder name.

Syntax
SelectDir ( szTitle, szMsg, svDir, bCreate );

1306

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SelectDir

Parameters
Table E-114: SelectDir Parameters Parameter szTitle Description Specifies the title of this dialog. To display the default title ("Choose Folder"), pass a null string ("") in this parameter. Specifies the message you want to display in this dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Specifies the name of a folder that will appear as the default selection. Returns the fully qualified name of the folder selected by the end user. Specifies whether or not you want InstallShield to create the specified folder if it does not already exist. Pass one of the following predefined constants in this parameter:

szMsg

svDir

bCreate

TRUEIndicates that the folder should be created if it does not exist. FALSEIndicates that the folder should not be created if it does not exist.

Return Values
If bCreate is FALSE, this function returns one of the following values:
Table E-115: SelectDir Return Values when bCreate is FALSE Return Value IDOK (1) IDCANCEL (2) <0 Description Indicates that the OK button was selected. Indicates that the CANCEL button was selected. Indicates that the function was unable to display the dialog.

If bCreate is TRUE, this function returns one of the following values:

Table E-116: SelectDir Return Values when bCreate is TRUE Return Value IDCANCEL (2) 0 Description Indicates that the CANCEL button was selected. Indicates that the OK button was selected and the function was able to create the folder specified, if necessary. Indicates that the function failed to display the dialog and/or create the specified folder.

<0

Additional Information
The dialog that is displayed by this function cannot be displayed with a skin; it appears the same, regardless of whether you have specified a skin.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1307

Appendix E: Built-In Functions (S-T) SelectDir

In early versions of InstallShield Professional, when bCreate was set to TRUE and the end user selected a folder that did not exist, a confirmation message box was displayed asking whether the folder should be created. This message box proved to be confusing to many end users, so it has been removed from InstallShield.

SelectDir Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SelectDir function. * * This script calls SelectDir to display a dialog that * allows the user to specify a folder. If the specified folder * does not exist, it is not created. Instead, an error message * is displayed and the SelectDir dialog is displayed again. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "SelectDir Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SelectDir(HWND); function ExFn_SelectDir(hMSI) STRING szTitle, szMsg, svDir; BOOL bCreate, bFolderExists; NUMBER nResult; begin // Loop until user cancels or selects an existing folder. repeat // Set a default folder for the SelectDir dialog. svDir = INSTALLDIR; // Set the message to display in the SelectDir dialog. szMsg = "Please choose an existing folder."; // Get an existing folder name from the user. The fourth // parameter indicates that a non-existing folder should // not be created. nResult = (SelectDir (TITLE_TEXT, szMsg, svDir, FALSE) < 0) ; if nResult = 0 then // Determine whether the folder exists. bFolderExists = ExistsDir (svDir);

1308

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SelectDirEx

if bFolderExists = NOTEXISTS then // The folder does not exist. Ask user to select again. szMsg = "%s does not exist.\nPlease choose an existing folder."; SprintfBox (WARNING, szTitle, szMsg, svDir); endif; endif; until (nResult = CANCEL) || (bFolderExists = EXISTS); if (bFolderExists = EXISTS) then // Display the name of the selected folder. SprintfBox (INFORMATION, szTitle, "You selected %s.", svDir); endif; end;

SelectDirEx
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SelectDirEx function displays a dialog that enables the end user to select a folder into which the application will be installed. An edit box can also be displayed to enable the end user to specify a new folder. This function calls the Windows API function SHBrowseForFolder to display the dialog. For more information on SHBrowseForFolder, see the Windows API documentation.

Syntax
SelectDirEx ( szTitle, szMsg, szEditBoxStatusText, szTreeControlStatusText, nFlags, svDir );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1309

Appendix E: Built-In Functions (S-T) SelectDirEx

Parameters
Table E-117: SelectDirEx Parameters Parameter szTitle Description Specifies the title of this dialog. To display the default title Choose Folder, pass a null string ("") in this parameter. Specifies the message you want to display in this dialog. To display the default instructions for this dialog (Please choose the installation folder), pass a null string ("") in this parameter. Specifies the static text that accompanies the edit box when nFlags specifies BIF_EDITBOX. If nFlags does not specify BIF_EDITBOX, this parameter is ignored. Specifies the static text to accompany the dialog's tree control when nFlags specifies BIF_STATUSTEXT. If nFlags does not specify BIF_STATUSTEXT, this parameter is ignored. Specifies the appearance and functionality of the dialog that is displayed by the function by specifying the same flags that are used for the Windows structure BROWSEINFO. Note that if you pass BIF_BROWSEFORCOMPUTER or BIF_BROWSEFORPRINTER, no edit box is displayed. Pass any of the following constants:

szMsg

szEditBoxStatusText

szTreeControlStatusText

nFlags

BIF_BROWSEFORCOMPUTEREnables the end user to select a computer on the network. The Network Neighborhood is preselected in the tree control and the OK button is enabled only if a valid computer name is selected in the tree control. No edit box is displayed, even if BIF_EDITBOX is specified. BIF_BROWSEFORPRINTEREnables the end user to select a printer. The My Computer folder is preselected in the tree control. Only computers that include at least one printer are displayed under the Network Neighborhood folder. The OK button is enabled only if a valid printer is selected in the tree control. No edit box is displayed, even if BIF_EDITBOX is specified. BIF_DONTGOBELOWDOMAINNetwork folders below the domain level are not displayed in the tree control. BIF_RETURNFSANCESTORSShows folders above svDir. BIF_RETURNONLYFSDIRSBrowses file system folders.

The following constants specify other aspects of the dialog: BIF_STATUSTEXTDisplays status text in the dialog. BIF_EDITBOXAdds an edit field to the Browse dialog. The end user can type a folder name in the edit box. The text specified in the SzEditBoxStaticText parameter appears above the edit box, unless BIF_BROWSEFORCOMPUTER or BIF_BROWSEFORPRINTER is specified. When the end user clicks OK, SelectDirEx checks whether a valid folder name is entered. If not, an error message appears and the dialog is not closed.

svDir

Specifies the name of a folder that will appear as the default selection. Returns the fully qualified name of the folder selected by the end user. If a valid folder name that exists on the target system is specified in this parameter, the specified folder is preselected in the tree control.

1310

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SelectDirEx

Return Values
Table E-118: SelectDirEx Return Values Return Value IDOK (1) IDCANCEL (2) <0 Description Indicates that the end user clicked the OK button. Indicates that the end user clicked the Cancel button. Indicates that the function was unable to display the dialog.

Additional Information
The dialog that is displayed by this function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

SelectDirEx Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SelectDirEx function. * * This sample script calls SelectDirEx to display a dialog * that allows the user to specify a folder. If the specified * folder does not exist, it is not created; instead, an error * message is displayed and the SelectDirEx dialog is displayed * again. * \*--------------------------------------------------------------*/ #include "ifx.h" function OnBegin() STRING szTitle, szMsg, svDir; BOOL bCreate, bFolderExists; NUMBER nResult; begin // Loop until user cancels or selects an existing folder. repeat // Set a default folder for the SelectDirEx dialog. svDir = TARGETDIR; // Set the title to display in the SelectDirEx dialog. szTitle = "SelectDirEx Example"; // Set the message to display in the SelectDirEx dialog. szMsg = "Please choose an existing folder.";
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1311

Appendix E: Built-In Functions (S-T) SelectFolder

// Get an existing folder name from the user. nResult = (SelectDirEx (szTitle, szMsg, "", "", BIF_RETURNONLYFSDIRS | BIF_EDITBOX, svDir ) < 0) ; if nResult = 0 then // Determine whether the folder exists. bFolderExists = ExistsDir (svDir); if bFolderExists = NOTEXISTS then // The folder does not exist. Ask user to select again. szMsg = "%s does not exist.\nPlease choose an existing folder."; SprintfBox (WARNING, szTitle, szMsg, svDir); endif; endif; until (nResult = CANCEL) || (bFolderExists = EXISTS); if (bFolderExists = EXISTS) then // Display the name of the selected folder. SprintfBox (INFORMATION, szTitle, "You selected %s.", svDir); endif; end;

SelectFolder
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SelectFolder function displays a dialog that enables the end user to enter the name of a program folder in an edit field or select a program folder from a list. The function automatically displays all program folders on the system. A default folder name passed in svDefFolder is displayed in the edit field. The selected folder name is returned in svResultFolder.

Caution: If the specified folder does not exist, you must call CreateProgramFolder to create it; SelectFolder will not create the folder.

Syntax
SelectFolder ( szTitle, szDefFolder, svResultFolder );

1312

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SelectFolder

Parameters
Table E-119: SelectFolder Parameters Parameter szTitle Description Specifies the title of the dialog. To display the default title, Select Program Folder, pass a null string ("") in this parameter. Specifies the name of the folder to display as the default folder. Returns the name of the folder selected or specified by the end user.

szDefFolder svResultFolder

Return Values
Table E-120: SelectFolder Return Values Return Value NEXT (1) BACK (12) <0 Description Indicates that the end user clicked the Next button. Indicates that the end user clicked the Back button. Indicates that the function was unsuccessful.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

SelectFolder Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SelectFolder function. * * First, SelectFolder is called to get a folder selection from * the user. Then the name of the selected folder is displayed. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "SelectFolder Example" // Include Ifx.h for built-in InstallScript function prototypes.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1313

Appendix E: Built-In Functions (S-T) SendMessage

#include "Ifx.h" export prototype ExFn_SelectFolder(HWND); function ExFn_SelectFolder(hMSI) STRING svResultFolder; NUMBER nReturn; begin // Get folder selection from user. Make "Startup" the // default selection nReturn = SelectFolder (TITLE_TEXT, "Startup", svResultFolder); if (nReturn < 0) then // Report an error. MessageBox ("SelectFolder failed.", SEVERE); else // Display the name of the selected folder. SprintfBox (INFORMATION, TITLE_TEXT, "Selected folder: %s", svResultFolder); endif; end;

SendMessage
The SendMessage function sends a message to one or more windows. SendMessage does not return control to the setup script until the message has been processed. The SendMessage function is a direct pass-through to the Windows API SendMessage. Consult the Windows programming documentation for detailed information.

Note: To send a message using the parameter nMsg or to handle return values, you must define constants in your script that are equivalent to the constants defined in Windows.h. You cannot use #include to include Windows.h in your script.

Syntax
SendMessage ( nHwnd, nMsg, nwParam, nlParam );

1314

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SendMessage

Parameters
Table E-121: SendMessage Parameters Parameter nHwnd nMsg nwParam nlParam Description Specifies the handle that identifies the window to receive the message. Specifies the message to send to the window(s). Specifies additional message information. Specifies additional message information.

Return Values
SendMessage returns the value it receives from calling the Windows API of the same name. The return value depends on the message received by the Windows API SendMessage. Consult Windows programming documentation for detailed information on messages returned by the Windows API SendMessage.

Additional Information

Task

To pass string data in the fourth parameter of SendMessage, do the following: 1.

For projects converted from InstallShield Professional, include the required function declaration by doing one of the following:

Remove the preprocessor constant ISINCLUDE_NO_WINAPI_H from the Preprocessor Defines box, which is available on the Compile/Link tab on the Settings dialog box. (To access this dialog box, click Settings on the Build menu.) Place the following code in your script:
prototype USER.SendMessageA(HWND, NUMBER, NUMBER, BYREF STRING);

(For projects created with InstallShield, ISRTWindows.h is included by default in Ifx.h, which in turn is included by default in the script.)
2.

Call the function as in the following example:

USER.SendMessageA( hWnd, LB_GETTEXT, nResult, sResult);

SendMessage Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1315

Appendix E: Built-In Functions (S-T) SendMessage

* * Demonstrates the FindWindow and SendMessage functions. * * This script launches Windows Notepad and then calls * FindWindow to locate the Notepad window. Next, it calls * SendMessage to maximize the window; after a three-second * delay, it calls SendMessage again to minimize the * window. When the script ends, Windows NotePad remains * open but minimized. Note that the parameters passed to * SendMessage are Windows system messages whose values * are defined as constants in this script. * * Note: Before running this script, set the preprocessor * constant NOTEPAD so that it references the fully* qualified name of the Windows Notepad executable. * \*--------------------------------------------------------------*/ #define NOTEPAD "C:\\Windows\\Notepad.exe" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SendMessage(HWND); function ExFn_SendMessage(hMSI) NUMBER nMsg, nwParam, nlParam; HWND nHwnd; begin // Do not display the setup's background window. Disable (BACKGROUND); // Open the Windows Notepad. if (LaunchApp (NOTEPAD, "") < 0 ) then MessageBox ("Unable to launch Notepad.", SEVERE); abort; endif; // Wait three seconds so we can view the window before // it's maximized. Delay (3); // Retrieve the handle of the Notepad window. The first // parameter is the window class. A null string in the // second parameter specifies the topmost Notepad window. nHwnd = FindWindow ("NotePAD", ""); if (nHwnd = NULL) then MessageBox ("Unable to find the Notepad window.", SEVERE); else // Send system command to maximize the window. SendMessage (nHwnd, WM_SYSCOMMAND, SC_MAXIMIZE, 0); // Wait three seconds so we can view the window // before it's minimized. Delay (3); // Send system command to minimize the window. SendMessage (nHwnd, WM_SYSCOMMAND, SC_MINIMIZE, nlParam); endif;

1316

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) ServiceAddService

end;

ServiceAddService
The ServiceAddService function adds the service specified by szServiceName to the list of services registered on the system. You can customize the SERVICE_IS_PARAMS structure to control additional service creation elements. ServiceAddService does not install any files; you must install the service file yourself during the installation. If the service specified by szServiceName already exists, ServiceAddService reconfigures it to the parameters specified in the function call. If the existing service is running when ServiceAddService is called, the installation attempts to stop the service before attempting to reconfigure the service. If the service cannot be stopped, ServiceAddService reconfigures the service and sets BATCH_INSTALL to non-zero so that Windows can complete the service reconfiguration after reboot.

Syntax
ServiceAddService ( szServiceName, szServiceDisplayName, szServiceDescription, szServicePathFile, bStartService, szStartServiceArgs );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1317

Appendix E: Built-In Functions (S-T) ServiceExistsService

Parameters
Table E-122: ServiceAddService Parameters Parameter szServiceName szServiceDisplayName szServiceDescription szServicePathFile Description Specifies the name of the service. Specifies the display name of the service. Specifies the service description. Specifies the path to the service executable file and, optionally, command line parameters that are passed to the service whenever it is started. Specifies whether to start the service after adding it. Specifies command line arguments that are passed to the service only when it is started by the installation.

bStartService szStartServiceArgs

Return Values
Table E-123: ServiceAddService Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function successfully added or reconfigured the service. Indicates that the function was unable to add or reconfigure the service. If this function fails, additional error information may be available by calling GetExtendedErrInfo and checking the value of its third argument. (This value typically indicates the result of internally calling the Windows API function GetLastError after a call to a Windows API function failed.) You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
If logging is enabled when ServiceAddService is called, the service is logged for uninstallation whether or not the service existed already and is removed when the application is uninstalled. If you are adding a service that should not be uninstalled, disable logging before calling this function. Note that the publicly defined structuresSERVICE_IS_PARAMS and SERVICE_IS_STATUSare not used when the service is uninstalled automatically. If you want to specify non-default settings when uninstalling the service, disable logging when adding the service and then remove the service manually during uninstallation by calling ServiceRemoveService directly from the script.

ServiceExistsService
The ServiceExistsService function determines whether the service specified by szServiceName is registered on the system.
1318 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) ServiceGetServiceState

Syntax
ServiceExistsService ( szServiceName );

Parameters
Table E-124: ServiceExistsService Parameters Parameter szServiceName Description Specifies the name of the service.

Return Values
Table E-125: ServiceExistsService Return Values Return Value TRUE FALSE Description Indicates that the service is registered on the system. Indicates that the service is not registered on the system, or that the setup could not determine whether the service is registered on the system.

ServiceGetServiceState
The ServiceGetServiceState function returns in nvServiceState the state of the service that is specified by szServiceName.

Syntax
ServiceGetServiceState ( szServiceName, nvServiceState );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1319

Appendix E: Built-In Functions (S-T) ServiceInitParams

Parameters
Table E-126: ServiceGetServiceState Parameters Parameter szServiceName nvServiceState Description Specifies the name of the service. Returns one of the following Windows-defined constants specifying the state of the service:

SERVICE_STOPPED SERVICE_START_PENDING SERVICE_STOP_PENDING SERVICE_RUNNING SERVICE_CONTINUE_PENDING SERVICE_PAUSE_PENDING SERVICE_PAUSED

Return Values
Table E-127: ServiceGetServiceState Return Values Return Value >= ISERR_SUCCESS Description Indicates that the function retrieved the state of the service. Additional status information is available in the SERVICE_IS_STATUS system variable. Indicates that the function was unable to retrieve the state of the service. If this function fails, additional error information may be available by calling GetExtendedErrInfo and checking the value of its third argument. (This value typically indicates the result of internally calling the Windows API function GetLastError after a call to a Windows API function failed.) You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

< ISERR_SUCCESS

ServiceInitParams
The ServiceInitParams function initializes the SERVICE_IS_PARAMS system variables members to the following default values. This function is called automatically during setup initialization.

Syntax
ServiceInitParams ( );

1320

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) ServiceRemoveService

System Variable Members

Table E-128: ServiceInitParams System Variable Members Parameter SERVICE_IS_PARAMS.lpMachineName SERVICE_IS_PARAMS.lpDatabaseName SERVICE_IS_PARAMS.dwDesiredAccess SERVICE_IS_PARAMS.dwServiceType SERVICE_IS_PARAMS.dwStartType SERVICE_IS_PARAMS.dwErrorControl SERVICE_IS_PARAMS.lpLoadOrderGroup SERVICE_IS_PARAMS.lpdwTagId SERVICE_IS_PARAMS.lpDependencies SERVICE_IS_PARAMS.lpServiceStartName SERVICE_IS_PARAMS.lpPassword SERVICE_IS_PARAMS.nStartServiceWaitCount SERVICE_IS_PARAMS.nStopServiceWaitCount Default Value NULL NULL SERVICE_ALL_ACCESS SERVICE _WIN32_OWN_PROCESS SERVICE_AUTO_START SERVICE_ERROR_IGNORE NULL NULL NULL NULL NULL INFINITE INFINITE

Parameters
None.

Return Values
Table E-129: ServiceInitParams Return Values Return Value ISERR_SUCCESS Description This function always returns ISERR_SUCCESS.

ServiceRemoveService
The ServiceRemoveService function removes the service that is specified by szServiceName from the service control manager database. If the service is running when the function is called, the installation stops the service before removing the service.

Syntax
ServiceRemoveService ( szServiceName );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1321

Appendix E: Built-In Functions (S-T) ServiceStartService

Parameters
Table E-130: ServiceRemoveService Parameters Parameter szServiceName Description Specifies the name of the service.

Return Values
Table E-131: ServiceRemoveService Return Values Return Value >= ISERR_SUCCESS Description Indicates that the function removed the service from the service control manager database. Indicates that the function was unable to remove the service. If this function fails, additional error information may be available by calling GetExtendedErrInfo and checking the value of its third argument. (This value typically indicates the result of internally calling the Windows API function GetLastError after a call to a Windows API function failed.) You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

< ISERR_SUCCESS

ServiceStartService
The ServiceStartService function starts the service that is specified by szServiceName. If the service is running when the function is called, the installation stops it and then restarts it. This function waits for the service to reach its running state before returning; it waits indefinitely as long as the service is updating the dwCheckPoint member of the SERVICE_IS_STATUS structure at least every dwWaitHint milliseconds. To force the function to return after a specific time interval, regardless of whether the service has started, you can change the nStartServiceWaitCount member of the structured variable SERVICE_IS_PARAMS to the appropriate time in seconds.

Syntax
ServiceStartService ( szServiceName, szStartServiceArgs );

1322

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) ServiceStopService

Parameters
Table E-132: ServiceStartService Parameters Parameter szServiceName szStartServiceArgs Description Specifies the name of the service. Specifies a comma-delimited string of arguments to the service.

Return Values
Table E-133: ServiceStartService Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function started the service. Indicates that the function was unable to start the service. If this function fails, additional error information may be available by calling GetExtendedErrInfo and checking the value of its third argument. (This value typically indicates the result of internally calling the Windows API function GetLastError after a call to a Windows API function failed.) You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

ServiceStopService
The ServiceStopService function stops the service that is specified by szServiceName. This function waits for the service to stop before returning; it waits indefinitely as long as the service is updating the dwCheckPoint member of the SERVICE_IS_STATUS structure at least every dwWaitHint milliseconds. To force the function to return after a specific time interval, regardless of whether the service has stopped, you can change the nStopServiceWaitCount member of the structured variable SERVICE_IS_PARAMS to the appropriate time in seconds.

Syntax
ServiceStopService ( szServiceName );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1323

Appendix E: Built-In Functions (S-T) SetColor

Parameters
Table E-134: ServiceStopService Parameters Parameter szServiceName Description Specifies the name of the service.

Return Values
Table E-135: ServiceStopService Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function stopped the service. Indicates that the function was unable to stop the service. If this function fails, additional error information may be available by calling GetExtendedErrInfo and checking the value of its third argument. (This value typically indicates the result of internally calling the Windows API function GetLastError after a call to a Windows API function failed.) You can obtain the error message text associated with a large negative return valuefor example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information

SetColor
The SetColor function sets the color of the setup background.

Note: This function is not supported for use in Basic MSI setup projects.

Syntax
SetColor ( nObject, nColor );

1324

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetColor

Parameters
Table E-136: SetColor Parameters Parameter nObject Description Specifies the user interface object to change. Pass the following predefined constant in this parameter:

nColor

BACKGROUNDIndicates the background of the setup window. The default color is solid teal: RGB (0,128,128).

Specifies a color for the background. For a gradient background color, pass one of the following constants:

BK_BLUE BK_GREEN BK_MAGENTA BK_ORANGE BK_PINK BK_RED BK_YELLOW

For a solid background color, pass one of the following constants or call the RGB function to indicate a particular color (using the values provided in the parentheses):

BK_SOLIDBLACK (0, 0, 0) BK_SOLIDBLUE (0, 0, 255) BK_SOLIDGREEN (0, 255, 0) BK_SOLIDMAGENTA (255, 0, 127) BK_SOLIDORANGE (255, 127, 0) BK_SOLIDPINK (255, 0, 255) BK_SOLIDRED (255, 0, 0) BK_SOLIDWHITE (255, 255, 255) BK_SOLIDYELLOW (255, 255, 0)

For a custom color, pass the function RGB in this parameter.

Note: When using an RGB value, you can apply the same method as described in the programming manuals for Microsoft Windows. You specify the mixture of RED, GREEN, and BLUE colors to mix the color. Use a number from 0 to 255 to represent the amount of color to use. You must use literal numbers in the parameters of the RGB macro. You can also use a long value that represents the RGB color instead of the RGB statement. To achieve a smoothing effect (gradient) when the background is painted with a custom color, bitwise OR the color with the predefined constant BK_SMOOTH. Note that the smoothing effect is better with 256 colors enabled.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1325

Appendix E: Built-In Functions (S-T) SetColor

Return Values
Table E-137: SetColor Return Values Return Value 0 <0 Description Indicates that the function successfully set the color of the object. Indicates that the function was unable to set the color of the user interface object.

SetColor Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetColor function. * * The first call to SetColor sets the background color to solid * blue. The second call sets the background color to gradient * red. The last call sets the background color to an RGB value. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SetColor(HWND); function ExFn_SetColor(hMSI) begin // Change the background color to solid blue. if (SetColor (BACKGROUND, BK_SOLIDBLUE) < 0) then MessageBox ("SetColor failed.", SEVERE); endif; // Delay for three seconds. Delay (3); // Change the background color to gradient red. if (SetColor (BACKGROUND, BK_RED) < 0) then MessageBox ("SetColor failed.", SEVERE); endif; // Delay for three seconds. Delay (3); // Change the background color to custom magenta. if (SetColor (BACKGROUND, RGB(100, 50, 150)) < 0) then MessageBox ("SetColor failed.", SEVERE); endif;

1326

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetDialogTitle

Delay (3); end;

SetDialogTitle
The SetDialogTitle function changes the titles that appear in the title bars of some common built-in dialogs. Specify the dialog using the parameter nDialogId. If you do not use SetDialogTitle, the default title appears. When you set the title for a particular dialog, InstallShield uses that title for every instance of that type of dialog until you use SetDialogTitle to change the title again. You must call SetDialogTitle separately for each type of dialog whose title you wish to change.

Note: InstallShield creates message boxes using standard Windows message box functions. Windows determines the OK and Cancel button text for these message boxes. InstallShield cannot control the text used in the buttons inside Windows message boxes.

Syntax
SetDialogTitle ( nDialogId, szTitle );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1327

Appendix E: Built-In Functions (S-T) SetDialogTitle

Parameters
Table E-138: SetDialogTitle Parameters Parameter nDialogId Description Identifies the built-in dialog whose title is to be changed change. Pass one of the following predefined constants in this parameter:

szTitle

DLG_ASK_OPTIONSChanges the title of the AskOptions dialog. DLG_ASK_PATHChanges the title of the AskPath dialog. DLG_ASK_TEXTChanges the title of the AskText dialog. DLG_ASK_YESNOChanges the title of the AskYesNo dialog. DLG_ENTER_DISKChanges the title of the EnterDisk dialog. DLG_MSG_INFORMATIONChanges the title of the Information-style MessageBox. DLG_MSG_SEVEREChanges the title of the Severe-style MessageBox. DLG_STATUSChanges the title of the dialog-style progress indicator. You must reenable the dialog-style progress indicator by calling Enable(STATUSDLG) after calling SetDialogTitle with the DLG_STATUS option in order for the title change to take effect. DLG_MSG_WARNINGChanges the title of the Warning-style MessageBox. DLG_USER_CAPTIONChanges the MessageBox caption when you use the userdefined message box styles.

Specifies the new title.

Return Values
Table E-139: SetDialogTitle Return Values Return Value 0 <0 Description Indicates that the function successfully changed the title of the dialog. Indicates that the function was unable to change the title of the dialog.

SetDialogTitle Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetDialogTitle function. * * SetDialogTitle is called to change the title of the * AskYesNo dialog. *
1328 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetDisplayEffect

\*--------------------------------------------------------------*/ #define TITLE_TEXT "SetDialogTitle Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SetDialogTitle(HWND); function ExFn_SetDialogTitle(hMSI) NUMBER nCheck1, nCheck2; begin // Set the title for the AskYesNo dialog. if (SetDialogTitle (DLG_ASK_YESNO, TITLE_TEXT) < 0) then // Report an error. MessageBox ("SetDialogTitle failed.", SEVERE); else // Display the AskYesNo dialog with its new title. AskYesNo ("Did SetDialogTitle change this title?", YES); endif; end;

SetDisplayEffect
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SetDisplayEffect function specifies the display effect to be used when displaying bitmaps or metafiles with the PlaceBitmap function or when displaying billboards. Once the display effect has been set, all bitmaps subsequently displayed by PlaceBitmap, or billboards, are displayed with this effect until a new effect is set by another call to SetDisplayEffect. Display effects occur only when placing bitmaps or billboards. No display effects are used when removing bitmaps or billboards.

Note: A bitmap that is displayed by PlaceBitmap with the option BITMAPICON, FULLSCREEN, FULLSCREENSIZE, or TILED is not displayed with display effects. Instead it is displayed normally. For more information, see PlaceBitmap.

Syntax
SetDisplayEffect ( nEffect );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1329

Appendix E: Built-In Functions (S-T) SetDisplayEffect

Parameters
Table E-140: SetDisplayEffect Parameters Parameter nEffect Description Specifies a display effect. Pass one of the following predefined constants in this parameter. Note that these constants are exclusive; you cannot use the bitwise OR operator and specify more than one. Moreover, this parameter has no effect when BITMAPICON, FULLSCREEN, FULLSCREENSIZE, or TILED is specified when displaying a bitmap with PlaceBitmap.

EFF_FADEThe bitmap or billboard slowly fades in and out. EFF_REVEALThe bitmap or billboard gradually fills in from the center toward all sides. EFF_HORZREVEALThe bitmap or billboard gradually scrolls out horizontally from its center. EFF_HORZSTRIPEA section of the bitmap or billboard fills in horizontally from the outside in; then the remainder fills in from the center out. EFF_VERTSTRIPEA section of the bitmap or billboard fills in vertically from the outside in; then the remainder fills in from the center out. EFF_BOXSTRIPEA section of the bitmap or billboard fills in from all sides; then the remainder fills in toward all sides. EFF_NONEThis option is the default setting. Use it to clear the display effects after calling one of the other options.

Note: Only EFF_REVEAL and EFF_HORZREVEAL work with metafiles.

Return Values
Table E-141: SetDisplayEffect Return Values Return Value 0 <0 Description Indicates that the function successfully set the display effect. Indicates that the function was unable to set the display effect.

SetDisplayEffect Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetDisplayEffect function. * * This script displays the same bitmap seven times, with a * different effect each time. * * Note: In order for this script to run correctly, you must * set the constant BITMAP_FILE so that it references an * existing bitmap file on the target system. The

1330

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetDisplayEffect

* constant BITMAP_ID can be any integer in this example * since the bitmap is not loaded from a DLL and there * are no other bitmaps on the screen. * \*--------------------------------------------------------------*/ #define BITMAP_FILE "C:\\Windows\\Forest.BMP" // ID to use for the bitmap. #define BITMAP_ID 1 // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SetDisplayEffect(HWND); function ExFn_SetDisplayEffect(hMSI) begin // Open a background window so the effect's name can // be shown in the title bar each time the bitmap // is displayed. Enable (FULLWINDOWMODE); Enable (BACKGROUND); // 1. Display bitmap using the box stripe effect. SetDisplayEffect (EFF_FADE); SetTitle ("Fade effect", 0, BACKGROUNDCAPTION); PlaceBitmap (BITMAP_FILE, BITMAP_ID, 0, 0, CENTERED); Delay (3); PlaceBitmap ("", BITMAP_ID, 0, 0, REMOVE); // 2. Display bitmap using the reveal effect. SetDisplayEffect (EFF_REVEAL); SetTitle("Reveal effect", 0, BACKGROUNDCAPTION); PlaceBitmap (BITMAP_FILE, BITMAP_ID, 0, 0, CENTERED); Delay (3); PlaceBitmap ("", BITMAP_ID, 0, 0, REMOVE); // 3. Display bitmap using the horizontal reveal effect. SetDisplayEffect (EFF_HORZREVEAL); SetTitle ("Horizontal reveal effect", 0, BACKGROUNDCAPTION); PlaceBitmap (BITMAP_FILE, BITMAP_ID, 0, 0, CENTERED); Delay (3); PlaceBitmap ("", BITMAP_ID, 0, 0, REMOVE); // 4. Display bitmap using the horizontal stripe effect. SetDisplayEffect (EFF_HORZSTRIPE); SetTitle ("Horizontal stripe effect", 0, BACKGROUNDCAPTION); PlaceBitmap (BITMAP_FILE, BITMAP_ID, 0, 0, CENTERED); Delay (3); PlaceBitmap ("", BITMAP_ID, 0, 0, REMOVE); // 5. Display bitmap using the vertical stripe effect. SetDisplayEffect (EFF_VERTSTRIPE); SetTitle ("Vertical stripe effect", 0, BACKGROUNDCAPTION); PlaceBitmap (BITMAP_FILE, BITMAP_ID, 0, 0, CENTERED);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1331

Appendix E: Built-In Functions (S-T) SetErrorMsg

Delay (3); PlaceBitmap ("", BITMAP_ID, 0, 0, REMOVE); // 6. Display bitmap using the box stripe effect. SetDisplayEffect (EFF_BOXSTRIPE); SetTitle ("Box stripe effect", 0, BACKGROUNDCAPTION); PlaceBitmap (BITMAP_FILE, BITMAP_ID, 0, 0, CENTERED); Delay (3); PlaceBitmap ("", BITMAP_ID, 0, 0, REMOVE); Delay (1); // 7. Clear all effects. SetDisplayEffect (EFF_NONE); SetTitle ("No effect", 0, BACKGROUNDCAPTION); PlaceBitmap (BITMAP_FILE, BITMAP_ID, 0, 0, CENTERED); Delay (3); PlaceBitmap ("", BITMAP_ID, 0, 0, REMOVE); Delay (1); end;

SetErrorMsg
When a disk error occurs, the SetErrorMsg function sets the corresponding error message that is displayed by the EnterDiskError function.

Syntax
SetErrorMsg (nErrorID, szText);

1332

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetErrorMsg

Parameters
Table E-142: SetErrorMsg Parameters Parameter nErrorID Description Specifies which error message to customize. Pass one of the following predefined constants in this parameter:

szText

ERR_BOX_BADPATHThis message appears when EnterDiskError detects a bad path entered by the user. ERR_BOX_BADTAGFILEThis message appears when EnterDiskError detects the specified tag file does not exist on the disk. ERR_BOX_DISKIDThis message appears when EnterDiskError detects the drive specified by the user does not exist.

Specifies the error message to display in the message box.

Return Values
Table E-143: SetErrorMsg Return Values Return Value 0 <0 Description Indicates that the function successfully changed the error message. Indicates that the function was unable to change the error message.

SetErrorMsg Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetErrorMsg function. * * This script customizes the error messages displayed after a * call to EnterDisk if the next disk in a set of setup disks * is not ready in the specified drive. * \*--------------------------------------------------------------*/ // Define the text messages #define MSG_DRIVE_DOOR "The #define MSG_BAD_PATH "The #define MSG_BAD_TAG "Bad #define MSG_BAD_DRIVE "The for EnterDisk errors. drive door is open." path does not exist." tag file." specified drive does not exist."

// Include Ifx.h for built-in InstallScript function prototypes.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1333

Appendix E: Built-In Functions (S-T) SetErrorTitle

#include "Ifx.h" export prototype ExFn_SetErrorMsg(HWND); function ExFn_SetErrorMsg(hMSI) begin // Set the messages for the error boxes of the EnterDisk function. SetErrorMsg (ERR_BOX_DRIVEOPEN, MSG_DRIVE_DOOR); SetErrorMsg (ERR_BOX_BADPATH, MSG_BAD_PATH ); SetErrorMsg (ERR_BOX_BADTAGFILE, MSG_BAD_TAG); SetErrorMsg (ERR_BOX_DISKID, MSG_BAD_DRIVE); // Prompt the user to specify a disk. EnterDisk ("Please enter the 'Examples' disk:", "Example.exe"); end;

SetErrorTitle
When a disk error occurs, the SetErrorTitle function sets the title bar for the error message that is displayed by the EnterDiskError function.

Syntax
SetErrorTitle (nErrorID, szText);

1334

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetErrorTitle

Parameters
Table E-144: SetErrorTitle Parameters Parameter nErrorID Description Specifies the error message box whose title you want to customize. Pass one of the following predefined constants in this parameter:

szText

ERR_BOX_BADPATHThis message appears when EnterDiskError detects a bad path. ERR_BOX_BADTAGFILEThis message box appears when EnterDiskError detects that the specified tag file does not exist on the disk. ERR_BOX_DISKIDThis message box appears when EnterDiskError detects that the specified drive does not exist.

Specifies the title to display in the error message box.

Return Values
Table E-145: SetErrorTitle Return Values Return Value 0 <0 Description Indicates that the function successfully changes the text in the title bar. Indicates that the function was unable to change the text in the title bar.

SetErrorTitle Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetErrorTitle function. * * This script customizes the title text for the message box * displayed after a call to EnterDisk if the next disk in set * of setup disks is not ready in the specified drive. * \*--------------------------------------------------------------*/ // Define the message box title text for EnterDisk errors. #define MSG_DRIVE_DOOR "Drive door is open." #define MSG_BAD_PATH "Path not found." #define MSG_BAD_TAG "Bad tag file." #define MSG_BAD_DRIVE "Drive not found." // Include Ifx.h for built-in InstallScript function prototypes.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1335

Appendix E: Built-In Functions (S-T) SetExtendedErrInfo

#include "Ifx.h" export prototype ExFn_SetErrorTitle(HWND); function ExFn_SetErrorTitle(hMSI) STRING szText; NUMBER nErrorID; begin // Set the message box title for each error that can // occur after a call to EnterDisk. SetErrorTitle (ERR_BOX_DRIVEOPEN, MSG_DRIVE_DOOR); SetErrorTitle (ERR_BOX_DISKID, MSG_BAD_DRIVE); SetErrorTitle (ERR_BOX_BADTAGFILE, MSG_BAD_TAG); SetErrorTitle (ERR_BOX_BADPATH, MSG_BAD_PATH); // Make drive A: the default. // Prompt the user to specify a disk. EnterDisk ("Please enter the 'Examples' disk:", "Example.exe"); end;

SetExtendedErrInfo
Project: This information applies to InstallScript projects.

The SetExtendedErrInfo function sets error information, which can be retrieved by GetExtendedErrInfo.

Syntax
SetExtendedErrInfo ( szScriptFile, nLineNumber, nError );

1336

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetFileInfo

Parameters
Table E-146: SetExtendedErrInfo Parameters Parameter szScriptFile Description Specifies the script file in which the error occurred. To specify the current script file (that is, the script file that contains the call to SetExtendedErrInfo), pass the reserved identifier __FILE__. Specifies the line number in which the error occurred. To specify the current line number (that is, the line number of the call to SetExtendedErrInfo), pass the reserved identifier __LINE__. Specifies the error code for the error.

nLineNumber

nError

Return Values
Table E-147: SetExtendedErrInfo Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description The function successfully set the error information. The function failed to set the error information.

SetFileInfo
The SetFileInfo function sets the date or time stamp of an existing file or changes the file's attributes. To change both a file's date and time you must call SetFileInfo twice, once to change the date and once to change the time. However, you can set multiple file attributes with a single call to SetFileInfo by combining constants in nAttribute with the OR ( | ) operator.

Note: You can also use this function to change a folder's attribute. For example, you can use this function to create a hidden folder.

Syntax
SetFileInfo ( szPathFile, nType, nAttribute, szValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1337

Appendix E: Built-In Functions (S-T) SetFileInfo

Parameters
Table E-148: SetFileInfo Parameters Parameter szPathFile Description Specifies the fully qualified name of the file or folder whose date, time, or attributes you want to change. Specifies the file characteristic to change. Pass one of the following predefined constants in this parameter:

nType

nAttribute

FILE_ATTRIBUTEIndicates that one or more of the file's attributes will be changed. FILE_DATEIndicates that the file's date stamp will be changed. FILE_TIMEIndicates the file's time stamp will be changed.

Specifies the file attribute when nType is FILE_ATTRIBUTE. (When nType is FILE_DATE or FILE_TIME, pass 0 in this parameter.) To specify more than one file attribute, combine one or more of the following predefined constants with the OR (|) operator:

FILE_ATTR_ARCHIVEDSets the archive attribute. FILE_ATTR_HIDDENSets the hidden attribute. FILE_ATTR_READONLYSets the read-only attribute. FILE_ATTR_SYSTEMSets the system attribute. FILE_ATTR_NORMALWhen this constant is specified alone, all file attributes are cleared. When the OR operator is used to combine this constant with other file attribute constants, those attributes not included in the OR expression are cleared.

szValue

Specifies one of the following, depending on the value you passed in nType:

FILE_DATESpecifies a date in the format YYYY/MM/DD or YYYY\MM\DD. That date must not be earlier than "1980/01/01". When using backslashes as delimiters, remember that a backslash is inserted into a string as an escape sequence, for example, "1980\\01\\01". FILE_TIMESpecifies a time in the format HH:MM:SS, using a 24-hour clock format; note that the seconds must be a multiple of 2. FILE_ATTRIBUTEPass a null string ("") in this parameter.

Return Values
Table E-149: SetFileInfo Return Values Return Value 0 Description Indicates that the function successfully set the file's date stamp, time stamp, or attributes. Indicates that the function was unable to set the file's date stamp, time stamp, or attributes.

<0

1338

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetFileInfo

SetFileInfo Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetFileInfo function. * * SetFileInfo is called to set a file's date, time, and * attributes. * * Note: Before running this script, create a file called * ISExampl.txt in the root of drive C. * \*--------------------------------------------------------------*/ #define EXAMPLE_FILE "C:\\ISExampl.txt" #define TITLE_TEXT "SetFileInfo Example"

#define NEW_FILE_DATE "2003/09/12" #define NEW_FILE_TIME "18:30:00" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SetFileInfo(HWND); function ExFn_SetFileInfo(hMSI) LIST listID; begin // Create a list to hold messages. listID = ListCreate (STRINGLIST); // If an error occurred, report it; then terminate. if (listID = LIST_NULL) then MessageBox ("Unable to create list required for this example.", SEVERE); abort; endif; // Set the file's date. if (SetFileInfo (EXAMPLE_FILE, FILE_DATE, 0, NEW_FILE_DATE) < 0) then ListAddString (listID, "Unable to change the file\'s date.", AFTER); else ListAddString (listID, "File\'s date changed to" + NEW_FILE_DATE + ".", AFTER); endif; // Set the file's time. if (SetFileInfo (EXAMPLE_FILE, FILE_TIME, 0, NEW_FILE_TIME) < 0) then ListAddString (listID, "Unable to change the file\'s time.", AFTER);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1339

Appendix E: Built-In Functions (S-T) SetFont

else ListAddString (listID, "File\'s date changed to" + NEW_FILE_TIME + ".", AFTER); endif; // Clear the file's attributes. if (SetFileInfo (EXAMPLE_FILE, FILE_ATTRIBUTE, FILE_ATTR_NORMAL, "") < 0) then ListAddString (listID, "Unable to clear file attributes.", AFTER); else ListAddString (listID, "File attributes cleared.", AFTER); endif; // Report the results. SdShowInfoList (TITLE_TEXT, "Changes to " + EXAMPLE_FILE, listID); // Remove the list from memory. ListDestroy (listID); end;

SetFont
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SetFont function sets the font and style when displaying text strings. You can use standard Windows fonts with this function.

Syntax
SetFont ( nItemID, nFontStyle, szFontName );

1340

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetFont

Parameters
Table E-150: SetFont Parameters Parameter nItemID Description Specifies the item whose font and font style is to be set. Pass the following predefined constant in this parameter:

nFontStyle

FONT_TITLESpecifies the main title of the setup procedure, which is displayed in the top left corner of the setup window.

Specifies font styles. Pass one or more of the following predefined constants in this parameter. All but STYLE_NORMAL can be bitwise ORed to specify multiple styles.

szFontName

STYLE_NORMALNo bold, italic, or shadow (cannot be ORed) STYLE_BOLDBold text. STYLE_ITALICItalic text. STYLE_SHADOWText with shadow drawn. STYLE_UNDERLINEUnderlined text.

Specifies the name of an available Windows font. Valid font names include Courier, Helv, Helvetica, Modern, Roman, Script, Terminal, Times, and TmsRmn. If the specified font is not found with the styles specified, Arial is used.

Return Values
Table E-151: SetFont Return Values Return Value 0 <0 Description Indicates that the function successfully set the font. Indicates that the function was unable to set the font.

SetFont Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetFont function. * * In this script, three different titles are displayed in * the setup's main window; each title remains on the * screen for three seconds. The titles are displayed by * calls to SetTitle, which also sets the type size and * color. To control the font and font style of the titles, * the script calls SetFont before each call to SetTitle. * * Font Size Style Color *
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1341

Appendix E: Built-In Functions (S-T) SetInstallationInfo

* Title 1 Times New Roman 36 Normal Red * Title 2 Courier New 48 Italic Yellow * Title 3 Arial 60 Bold, Shadow Blue * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SetFont(HWND); function ExFn_SetFont(hMSI) begin Enable ( BACKGROUND ); // Title 1: Times Roman, 36pt, Normal, Red. if (SetFont (FONT_TITLE, STYLE_NORMAL, "Times New Roman") < 0) then MessageBox ("SetFont failed.", SEVERE); endif; SetTitle ("SetFont Example 1", 36, RGB(255, 0, 0)); Delay (3); // Title 2: Courier New, 48pt, Italic, Yellow. if (SetFont (FONT_TITLE, STYLE_ITALIC, "Courier New") < 0) then MessageBox ("SetFont failed.", SEVERE); endif; SetTitle ("SetFont Example 2", 48, RGB(255, 255, 0)); Delay (3); // Title 3: Arial, 60pt, Bold, Shadow, Blue. if (SetFont (FONT_TITLE, STYLE_BOLD | STYLE_SHADOW, "Arial") < 0) then MessageBox ("SetFont failed.", SEVERE); endif; SetTitle ("SetFont Example 3", 60, RGB(0, 0, 255)); Delay (3); end;

SetInstallationInfo
The SetInstallationInfo function sets the values of the system variables IFX_COMPANY_NAME, IFX_PRODUCT_NAME, IFX_PRODUCT_VERSION, and IFX_PRODUCT_KEY. SetInstallationInfo specifies this information for use by CreateInstallationInfo, which in an event-based script is called in the default OnShowUI event handler code to create an application information key and a per application paths key for the program you are installing. SetInstallationInfo is a special registry-related function, designed to work with certain predefined registry keys. For more information on special registry-related functions, see Special Registry-Related Functions.

Syntax
SetInstallationInfo ( szCompany, szProduct, szVersion, szProductKey );

1342

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetObjectPermissions

Parameters
Table E-152: SetInstallationInfo Parameters Parameter szCompany Description Specifies the company name. CreateInstallationInfo uses szCompany to create a \<company> key under the HKEY_LOCAL_MACHINE\Software key in the registry. Specifies the name of the product to be installed. CreateInstallationInfo uses szProduct to create a \<product> key under the HKEY_LOCAL_MACHINE\Software\<company> key in the registry. The value in szProduct is also inserted into the first paragraph of message text in the Welcome dialog. Specifies the version number of the product. CreateInstallationInfo uses szVersion to create a \<version> key under the HKEY_LOCAL_MACHINE\Software\<company>\<product> key in the registry. Together, the \<company> key (szCompany), the \<product> key (szProduct), and the \<version> key (szVersion) are referred to as the application information key. The application information key is created immediately upon calling CreateInstallationInfo. Specifies the name of the application's main executable file. If your product uses several executables, specify the executable that best represents the product. CreateInstallationInfo uses szProductKey to create a per application paths key under the key HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersio n\App Paths. The per application paths key is not actually created in the registry until you call RegDBSetItem to create a value name and value pair under the key.

szProduct

szVersion

szProductKey

Return Values
This function always returns 0.

SetObjectPermissions
The SetObjectPermissions function is used to set permissions for a file, a folder, or a registry key. The file, folder, or registry key can be installed as part of your installation, or it can be already present on the target system.

Syntax
SetObjectPermissions (byval string szObject, byval number nType, byval string szDomain, byval string szUser, byval number nPermissions, byval number nOptions);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1343

Appendix E: Built-In Functions (S-T) SetObjectPermissions

Parameters
Table E-153: SetObjectPermissions Parameters Parameter szObject Description Specify the object (file, folder, or registry key) for which you want to set permissions. For files and folders, specify the full path. For registry keys, use one of the following in the path:

CLASSES_ROOTThis indicates the HKEY_CLASSES_ROOT hive. CURRENT_USERThis indicates the HKEY_CURRENT_USER hive. MACHINEThis indicates the HKEY_LOCAL_MACHINE hive. USERSThis indicates the HKEY_USERS hive.

The following example set permissions for a key in HKEY_LOCAL_MACHINE:

SetObjectPermissions("MACHINE\\Software\\MyProduct\\Example", IS_PERMISSIONS_TYPE_REGISTRY, "", "Users", KEY_CREATE_SUB_KEY, IS_PERMISSIONS_OPTION_DENY_ACCESS);

nType

Indicate the type of object that is being passed through the szObject parameter. Valid options are:

szDomain

IS_PERMISSIONS_TYPE_FILEszObject is a file. IS_PERMISSIONS_TYPE_FOLDERszObject is a folder. IS_PERMISSIONS_TYPE_REGISTRYszObject is a registry key.

Specify the domain name of the user for which permissions are being set. To use the local machine as the domain, pass an empty string ("") for this parameter.

szUser

Specify the name of the user for which permissions are being set. Available options are:

Administrators Authenticated Users Creator Owner Everyone Guests Interactive IUSR Local Service Local System Network Service Power Users Remote Desktop Users Users

The user can be one that is being created during the installation, or one that already exists on the target system at run time.

1344

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetObjectPermissions

Table E-153: SetObjectPermissions Parameters (cont.) Parameter nPermissions Description To specify the permissions that are to be applied to the object for the specified user, pass one of the following predefined constants in this parameter. You can combine these constants by using the bitwise OR operator ( | ). Available options are:

DELETE GENERIC_ALL GENERIC_EXECUTE GENERIC_WRITE GENERIC_READ READ_CONTROL STANDARD_RIGHTS_ALL STANDARD_RIGHTS_EXECUTE STANDARD_RIGHTS_READ STANDARD_RIGHTS_REQUIRED STANDARD_RIGHTS_WRITE SYNCHRONIZE WRITE_DAC WRITE_OWNER

The following options are applicable to files and folders: FILE_LIST_DIRECTORY (for folders) FILE_READ_DATA (for files) FILE_WRITE_DATA (for files) FILE_ADD_FILE (for folders) FILE_APPEND_DATA (for files) FILE_ADD_SUBDIRECTORY (for folders) FILE_READ_EA (for files and folders) FILE_WRITE_EA (for files and folders) FILE_EXECUTE (for files) FILE_TRAVERSE (for folders) FILE_DELETE_CHILD (for folders) FILE_READ_ATTRIBUTES (for files and folders) FILE_WRITE_ATTRIBUTES (for files and folders) FILE_ALL_ACCESS

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1345

Appendix E: Built-In Functions (S-T) SetObjectPermissions

Table E-153: SetObjectPermissions Parameters (cont.) Parameter nPermissions (cont.) Description The following options are applicable to registry keys:

KEY_QUERY_VALUE KEY_SET_VALUE KEY_CREATE_SUB_KEY KEY_ENUMERATE_SUB_KEYS KEY_NOTIFY KEY_CREATE_LINK

For information on each value, see Registry Key Security and Access Rights, File Security and Access Rights, and Registry Key Security and Access Rights in the MSDN Library. nOptions Pass one or more of the following predefined constants in this parameter.

IS_PERMISSIONS_OPTION_DENY_ACCESSThe set of permissions that are specified in nPermissions should be denied. IS_PERMISSIONS_OPTION_NO_APPLYDOWNThe permissions should be applied to only the specified object; they should not be propagated to any child objects. IS_PERMISSIONS_OPTION_ALLOW_ACCESSThe set of permissions that are specified in nPermissions should allow access.

You can combine more than one constant by using the bitwise OR operator ( | ). The IS_PERMISSIONS_OPTION_DENY_ACCESS and IS_PERMISSIONS_OPTION_ALLOW_ACCESS constants should not be combined because they are mutually exclusive; if you specify both of these options for nOptions, permissions are denied.

Return Values
Table E-154: SetObjectPermissions Return Values Return Value ISERR_SUCCESS != ISERR_SUCCESS Description The function successfully set the permissions. The function could not set the permissions. The return value is a Win32 error. For documentation on Win32 errors, see the MSDN Library.

SetObjectPermissions Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
//--------------------------------------------------------------------------//
1346 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetStatus

// InstallScript Example Script // // Demonstrates the SetObjectPermissions function. // // This sample shows how to prevent the local administrator // from changing a file or any of its attributes. // //--------------------------------------------------------------------------function OnFirstUIAfter() STRING szTitle, szMsg1, szMsg2, szOpt1, szOpt2; NUMBER bvOpt1, bvOpt2; begin SetObjectPermissions (TARGETDIR+"MyFile.exe",IS_PERMISSIONS_TYPE_FILE, "", "administrator", FILE_WRITE_DATA|FILE_APPEND_DATA|FILE_WRITE_EA|FILE_WRITE_ATTRIBUTES, IS_PERMISSIONS_OPTION_DENY_ACCESS); end;

SetStatus
Project: This information applies to InstallScript projects.

The SetStatus function is called in an object script to set the object's Status.Number and Status.Description properties. To set the object's other status properties, call SetStatusEx.

Syntax
SetStatus ( nNumber, szDescription );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1347

Appendix E: Built-In Functions (S-T) SetStatusEx

Parameters
Table E-155: SetStatus Parameters Parameter nNumber szDescription Description Specifies the value of Status.Number. Specifies the value of Status.Description.

Return Values
Table E-156: SetStatus Return Values Return Value >= ISERR_SUCCESS Description The function successfully set the status properties. The function failed to set the status properties.

< ISERR_SUCCESS

SetStatusEx
Project: This information applies to InstallScript projects.

The SetStatusEx function is called in an object script to set the object's status properties.

Syntax
SetStatusEx ( nNumber, szDescription, szSource, szScriptFile, nScriptLine, nScriptError );

1348

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetStatusExStaticText

Parameters
Table E-157: SetStatusEx Parameters Parameter nNumber szDescription szSource szScriptFile Description Specifies the value of Status.Number. Specifies the value of Status.Description. Specifies the value of Status.szSource. Specifies the value of Status.szScriptFile. To specify the current script file (that is, the script file that contains the call to SetStatusEx), pass the reserved identifier __FILE__. Specifies the value of Status.nScriptLine. To specify the current line number (that is, the line number of the call to SetStatusEx), pass the reserved identifier __LINE__. Specifies the value of Status.nScriptError.

nScriptLine

nScriptError

Return Values
Table E-158: SetStatusEx Return Values Return Value >= ISERR_SUCCESS Description The function successfully set the status properties. The function failed to set the status properties.

< ISERR_SUCCESS

SetStatusExStaticText
The SetStatusExStaticText function sets the static text displayed in the STATUSEX dialog above the status text. The events OnFirstUIBefore, OnMaintUIBefore, and OnUpdateUIBefore automatically call this function to set the status text appropriately.

Syntax
SetStatusExStaticText ( szString);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1349

Appendix E: Built-In Functions (S-T) SetStatusWindow

Parameters
Table E-159: SetStatusExStaticText Parameters Parameter szString Description The text to be set as the static text. The following standard strings are available using the SdLoadString function:

IDS_IFX_STATUSEX_STATICTEXT_FIRSTUIThe InstallShield Wizard is installing %P. IDS_IFX_STATUSEX_STATICTEXT_MAINTUI_MODIFYThe InstallShield Wizard is modifying %P. IDS_IFX_STATUSEX_STATICTEXT_MAINTUI_REPAIRThe InstallShield Wizard is repairing %P. IDS_IFX_STATUSEX_STATICTEXT_MAINTUI_REMOVEALLThe InstallShield Wizard is removing %P. IDS_IFX_STATUSEX_STATICTEXT_UPDATEUIThe InstallShield Wizard is updated %VI of %P to version %VS.

Note: The status dialog supports the text substitution, %P, but does not support any other text substitutions such as %VI or %VS. If you are setting the static text to a string with any other text substitution than %P, you must call the SdSubstituteProductInfo function to update these text substitutions to the correct value before calling SetStatusExStaticText.

Return Values
Table E-160: SetStatusExStaticText Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function was successful. Indicates that the function was not successful.

SetStatusWindow
The SetStatusWindow function sets an initial or current value for the percentage complete indicator of the progress indicator (status bar) and specifies the current message to display on the top line of the progress indicator. Setups that install files using the FeatureMoveData function must call SetStatusWindow before calling FeatureMoveData in order to set the percentage complete indicator to 0% and clear the top line of the indicator. No additional calls to SetStatusWindow are required. The 'Status Text' string for each feature is displayed on the top line of the status bar automatically while the files of the feature are being installed.

1350

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetStatusWindow

Before calling FeatureMoveData, your setup should also call the StatusUpdate function to enable automatic updating of the percentage complete indicator during file transfer. To enable the display of the name and path of the file being installed on the second line of the status bar, call Enable with the INDVFILESTATUS parameter before calling FeatureMoveData. After these calls, the percentage complete indicator is updated smoothly during file transfer and the names of individual files are displayed as they are transferred when the FeatureMoveData function is called. Setups that install files using the CopyFile or XCopyFile functions may need to make multiple calls to SetStatusWindow in order to change the message on the top line of the indicator between successive calls to CopyFile or XCopyFile. StatusUpdate and Enable (with the parameter INDVFILESTATUS) work normally with CopyFile and XCopyFile. It is not necessary to call SetStatusWindow to change the percentage complete indicator between successive calls to CopyFile or XCopyFile if you have called StatusUpdate to enable automatic updating.

Syntax
SetStatusWindow ( nPercent, szString );

Parameters
Table E-161: SetStatusWindow Parameters Parameter nPercent Description Specifies a value between 0 and 100 that represents the percentage to be displayed by the percentage complete indicator. To reset the indicator before calling FeatureMoveData, specify 0. To change the message displayed on the top line of the status bar without changing the percentage complete indicator, specify -1 in this parameter. Specifies a string to display on the top line of the status bar. Note that if a 'DisplayText' parameter has been specified for this feature (in the IDE), that string automatically overwrites any text specified in this parameter when FeatureMoveData is called.

szString

Return Values
This function does not return a value.

SetStatusWindow Example
This function cannot be used in a Basic MSI installation.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetStatusWindow function. * * SetStatusWindow is called to set the progress bar and

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1351

Appendix E: Built-In Functions (S-T) SetTitle

* to display text in the progress indicator. * * Note: Before running this script, create the directories * and file referenced by the preprocessor constants. * \*--------------------------------------------------------------*/ #define #define #define SOURCE_DIR "C:\\Source" TARGET_DIR "C:\\Target" TARGET_FILE "ISExampl.txt"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SetStatusWindow(HWND); function ExFn_SetStatusWindow(hMSI) begin // Enable progress indicator. Enable (STATUS); // Set the progress bar to 33% and display a message. SetStatusWindow (33, "Now copying file..."); // Delay for two seconds to ensure the window is displayed correctly. Delay (2); // Copy the file in the source directory to the target directory CopyFile (SOURCE_DIR ^ TARGET_FILE, TARGET_DIR ^ TARGET_FILE); // Set the progress bar to 66% and display a message. SetStatusWindow (66, "Now deleting file..."); Delay (2); // Delete copied file in the Target directory. DeleteFile (TARGET_FILE); // Set the percent indicator to 100% and display a message. SetStatusWindow (100, "SetStatusWindow example completed."); Delay (2); end;

SetTitle
Project: This information does not apply to Basic MSI projects.

The SetTitle function displays a title either in the main window's title bar or inside the main window, depending on the value of nColor.

To set the background color of your setup, call SetColor. To set the font and font style of the title displayed inside the background window, call SetFont.

1352

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetTitle

Syntax
SetTitle ( szTitle, nPointSize, nColor );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1353

Appendix E: Built-In Functions (S-T) SetTitle

Parameters
Table E-162: SetTitle Parameters Parameter szTitle Description Specifies a title to appear either in the main window's title bar or inside the main window. If the title is to appear in the window's title bar, you must specify the predefined constant BACKGROUNDCAPTION in the third parameter. A title bar title that does not fit the available space will be displayed truncated on the right and terminated with ellipses. The default title bar title is Setup.

Note: The BACKGROUNDCAPTION option is supported for backward compatibility only. The recommended method for setting the main window's title bar is to set the value of the system variable IFX_SETUP_TITLE. When a color value is passed in the third parameter, the title is displayed left aligned at the top of the main window. Titles that are too wide for the main window will be displayed truncated on the right. To create a title that occupies more than one line, embed newline characters where you want the line to break. nPointSize Specifies the size, in points, of a title to be displayed in the main window. The suggested size is 24 points. Note that this parameter is ignored when the third parameter is BACKGROUNDCAPTION.

1354

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetTitle

Table E-162: SetTitle Parameters (cont.) Parameter nColor Description Specifies either a color or the predefined constant BACKGROUNDCAPTION.

Note: Calling SetTitle with the nColor set to BACKGROUNDCAPTION has no effect on setups that do not run in window mode. To run your setup in a standard window, you must first call Enable with the parameter DEFWINDOWMODE or FULLWINDOWMODE and then display the window by calling Enable with the parameter BACKGROUND.

To indicate that the value of szTitle should be displayed in the title bar of the main window, pass the predefined constant BACKGROUNDCAPTION in this parameter. When you specify BACKGROUNDCAPTION, nPointSize is ignored; the color and size of the title bar title are determined by the end user's system settings. Note that this option has no effect on setups that do not run in window mode. To indicate that the value of szTitle should be displayed inside the setup window, specify a color for that title by passing one of the following constants (whose corresponding RGB values are given in parentheses) or calling the RGB function to indicate a particular custom color. BLACK(0, 0, 0) BLUE(0, 0, 255) GREEN(0, 255, 0) MAGENTA(255, 0, 127) RED(255, 0, 0) WHITE(255, 255, 255) YELLOW(255, 255, 0)

Note: Magenta is not part of the standard Windows 16-color palette.

Return Values
Table E-163: SetTitle Return Values Return Value 0 <0 Description Indicates that the function successfully set the title of the setup. Indicates that the function was unable to set the title of the setup.

SetTitle Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1355

Appendix E: Built-In Functions (S-T) SetUpdateStatus

* Demonstrates the SetTitle function. * * This script displays a title in yellow, 24-point type. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SetTitle(HWND); function ExFn_SetTitle(hMSI) begin // Make the background window a standard maximized window. Enable (FULLWINDOWMODE); // Set the background color to blue. SetColor (BACKGROUND, BK_BLUE); // Display a title in the window. The newline character // in the title string forces "Example" to the next line. SetTitle ("SetTitle\nExample", 24, YELLOW); // Display the background window Enable (BACKGROUND); // Leave the window open for 3 seconds. Delay (3); end;

SetUpdateStatus
The SetUpdateStatus function is obsolete. If this function is called, it returns ISERR_NOT_IMPL.

Syntax
void SetUpdateStatus( BOOL );

SetUpdateStatusReboot
The SetUpdateStatusReboot function is obsolete. If this function is called, it returns ISERR_NOT_IMPL.

Syntax
void SetUpdateStatusReboot( BOOL );

SetupType
Project: This information applies to the following project types:
1356 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetupType

InstallScript InstallScript MSI

The SetupType function displays a dialog that enables the end user to select one of the three standard setup types: Typical, Compact, or Custom. These setup options are displayed with standard description text. If you want to add other setup types or change the displayed setup type names or descriptions, call SdSetupTypeEx instead.

Caution: If an end user returns to the Setup Type dialog after using a feature dialog to select and deselect features associated with the selected setup type, those choices are lost. This occurs because the SetupType function automatically resets the default feature selections for the selected setup type each time it is called.

Syntax
SetupType ( szTitle, szMsg, szReserved, nType, nReserved );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1357

Appendix E: Built-In Functions (S-T) SetupType

Parameters
Table E-164: SetupType Parameters Parameter szTitle Description Specifies the title of this dialog. To display the default title Setup Type, pass a null string ("") in this parameter. Specifies the message you want to display at the top of the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Pass a null string ("") in this parameterno other value is allowed. Specifies the default setup type when the dialog is opened. Pass one of the following predefined constants in this parameter:

szMsg

szReserved nType

nReserved

TYPICALDefines the default setup type as Typical. COMPACTDefines the default setup type as Compact. CUSTOMDefines the default setup type as Custom.

Pass zero in this parameter. No other value is allowed.

Return Values
Table E-165: SetupType Return Values Return Value TYPICAL (301) COMPACT (302) CUSTOM (303) BACK (12) Description Indicates that the end user selected the Typical setup type. Indicates that the end user selected the Compact setup type. Indicates that the end user selected the Custom setup type. Indicates that the end user clicked the Back button.

Additional Information
In an InstallScript project, if you do not display a setup type dialog, your script must do one of the following:

Select a setup type. Call a feature selection dialog function such as SdFeatureTree. Directly select features.

To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

1358

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetupType

SetupType Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetupType function. * * Comments: To run this example script, create a project (or * insert into a project) with several features and * subfeatures with components containing files. * This example includes setup of uninstallation * functionality. * \*--------------------------------------------------------------*/ // Specify your feature name here. These are the names you gave to your // features in the IDE. A NULL ("") string specifies base features. #define ASKDESTTITLE "Choose Destination Location" #define ASKDESTMSG "Choose a destination location for the application." #define SETUPTYPETITLE "Choose Setup Type" #define SETUPTYPEMSG "Select a setup type." #define FEATURE "" #define SDFEATDLGTITLE "Feature Selection" #define SDFEATDLGMSG "Select features to install and destination location." #define APPBASE_PATH "Your Company\\Word Processor" #define COMPANY_NAME "Your Company" #define PRODUCT_NAME "Word Processor" #define PRODUCT_VERSION "1.0" #define PRODUCT_KEY "Word Processor" #define DEINSTALL_KEY "Word Processor" #define UNINSTALL_NAME "Word Processor" prototype HandleFeatureError (NUMBER);

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SetupType(HWND); function ExFn_SetupType(hMSI) STRING svLogFile; NUMBER nvDisk, nResult; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Get the destination location. INSTALLDIR = PROGRAMFILES ^ APPBASE_PATH; AskDestPath (ASKDESTTITLE, ASKDESTMSG, INSTALLDIR , 0);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1359

Appendix E: Built-In Functions (S-T) SetupType

// Get setup type and target location with SdSetupType. INSTALLDIR = PROGRAMFILES ^ APPBASE_PATH; nResult = SetupType (SETUPTYPETITLE, SETUPTYPEMSG, "", TYPICAL, 0); // If Custom setup type is selected, let user select features // and change location if desired. if (nResult = CUSTOM) then SdFeatureDialogAdv (SDFEATDLGTITLE, SDFEATDLGMSG, INSTALLDIR, FEATURE); endif; // Set up uninstallation. InstallationInfo (COMPANY_NAME, PRODUCT_NAME, PRODUCT_VERSION, PRODUCT_KEY); svLogFile = "Uninst.isu"; DeinstallStart (INSTALLDIR, svLogFile, DEINSTALL_KEY, 0); RegDBSetItem (REGDB_UNINSTALL_NAME, UNINSTALL_NAME); // Transfer files based on feature selection. Handle errors. Enable (STATUSDLG); Enable (INDVFILESTATUS); StatusUpdate (ON, 100); nResult = FeatureMoveData (MEDIA, nvDisk, 0); HandleFeatureError (nResult); Disable (INDVFILESTATUS); Disable (STATUSDLG); end; /*--------------------------------------------------------------------------*\ * * Function: HandleFeatureError * * Purpose: This function evaluates the value returned by a feature * function and if the value is less than zero, displays the error * number and aborts the setup. * \*--------------------------------------------------------------------------*/ function HandleFeatureError (nResult) NUMBER nvError; STRING svFeatureSource, svFeature, svComponent, svFile; begin if (nResult < 0) then ComponentError (svFeatureSource, svFeature, svComponent, svFile, nvError); SprintfBox (INFORMATION, "Data Transfer Error Information", "FeatureError returned the " + "following data transfer error.\n" + "Setup will now abort.\n\n" + "Media Name: %s\nFeature: %s\nComponent: %s\n" + "File: %s\nError Number: %ld", svFeatureSource, svFeature, svComponent, svFile, nvError); abort; endif; end;

1360

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetupType2

SetupType2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SetupType2 function displays a dialog that enables the end user to select one of the two standard setup types: Complete or Custom. These setup options are displayed with standard description text. If you want to add other setup types or change the displayed setup type names or descriptions, call SdSetupTypeEx instead.

Caution: If an end user returns to the Setup Type dialog after using a feature dialog to select and deselect features associated with the selected setup type, those choices are lost. This occurs because the SetupType2 function automatically resets the default feature selections for the selected setup type each time it is called.

Syntax
SetupType2 ( szTitle, szMsg, szReserved, nType, nReserved );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1361

Appendix E: Built-In Functions (S-T) SetupType2

Parameters
Table E-166: SetupType2 Parameters Parameter szTitle Description Specifies the title of this dialog. To display the default title Setup Type2, pass a null string ("") in this parameter. Specifies the message you want to display at the top of the dialog. To display the default instructions for this dialog, pass a null string ("") in this parameter. Pass a null string ("") in this parameter. No other value is allowed. Specifies the default setup type when the dialog is opened. Pass one of the following predefined constants in this parameter:

szMsg

szReserved nType

nReserved

COMPLETEDefines the default setup type as Complete. CUSTOMDefines the default setup type as Custom.

Pass zero in this parameter. No other value is allowed.

Return Values
Table E-167: SetupType2 Return Values Return Value COMPLETE (304) CUSTOM (303) BACK (12) < ISERR_SUCCESS Description Indicates that the Complete setup type was selected. Indicates that the end user selected the Custom setup type. Indicates that the end user clicked the Back button. Indicates that the dialog could not be displayed.

Additional Information
In an InstallScript project, if you do not display a setup type dialog, your script must do one of the following:

Select a setup type. Call a feature selection dialog function such as SdFeatureTree. Directly select features.

To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

1362

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SetupType2

SetupType2 Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SetupType2 function. * * Comments: To run this example script, create a project (or * insert into a project) with several features and * subfeatures with components containing files. * This example includes setup of uninstallation * functionality. * \*--------------------------------------------------------------*/ // Specify your feature name here. These are the names you gave to // your features in InstallShield. A NULL ("") string // specifies base features. #define ASKDESTTITLE "Choose Destination Location" #define ASKDESTMSG "Choose a destination location for the application." #define SETUPTYPETITLE "Choose Setup Type" #define SETUPTYPEMSG "Select a setup type." #define FEATURE "" #define SDFEATDLGTITLE "Feature Selection" #define SDFEATDLGMSG "Select features to install and destination location." #define APPBASE_PATH "Your Company\\Word Processor" #define COMPANY_NAME "Your Company" #define PRODUCT_NAME "Word Processor" #define PRODUCT_VERSION "1.0" #define PRODUCT_KEY "Word Processor" #define DEINSTALL_KEY "Word Processor" #define UNINSTALL_NAME "Word Processor" prototype HandleFeatureError (NUMBER);

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SetupType2(HWND); function ExFn_SetupType2(hMSI) STRING svLogFile; NUMBER nvDisk, nResult; begin // Disable the Back button in setup dialogs. Disable (BACKBUTTON); // Get the destination location. INSTALLDIR = PROGRAMFILES ^ APPBASE_PATH; AskDestPath (ASKDESTTITLE, ASKDESTMSG, INSTALLDIR , 0);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1363

Appendix E: Built-In Functions (S-T) SetupType2

// Get setup type and target location with SdSetupType2. INSTALLDIR = PROGRAMFILES ^ APPBASE_PATH; nResult = SetupType2 (SETUPTYPETITLE, SETUPTYPEMSG, "", COMPLETE, 0); // If Custom setup type is selected, let user select features // and change location if desired. if (nResult = CUSTOM) then SdFeatureDialogAdv (SDFEATDLGTITLE, SDFEATDLGMSG, INSTALLDIR, FEATURE); endif; // Set up uninstallation. InstallationInfo (COMPANY_NAME, PRODUCT_NAME, PRODUCT_VERSION, PRODUCT_KEY); svLogFile = "Uninst.isu"; DeinstallStart (INSTALLDIR, svLogFile, DEINSTALL_KEY, 0); RegDBSetItem (REGDB_UNINSTALL_NAME, UNINSTALL_NAME); // Transfer files based on feature selection. Handle errors. Enable (STATUSDLG); Enable (INDVFILESTATUS); StatusUpdate (ON, 100); nResult = FeatureMoveData (MEDIA, nvDisk, 0); HandleFeatureError (nResult); Disable (INDVFILESTATUS); Disable (STATUSDLG); end; /*--------------------------------------------------------------------------*\ * * Function: HandleFeatureError * * Purpose: This function evaluates the value returned by a feature * function and if the value is less than zero, displays the error * number and aborts the installation. * \*--------------------------------------------------------------------------*/ function HandleFeatureError (nResult) NUMBER nvError; STRING svFeatureSource, svFeature, svComponent, svFile; begin if (nResult < 0) then ComponentError (svFeatureSource, svFeature, svComponent, svFile, nvError); SprintfBox (INFORMATION, "Data Transfer Error Information", "FeatureError returned the " + "following data transfer error.\n" + "Setup will now abort.\n\n" + "Media Name: %s\nFeature: %s\nComponent: %s\n" + "File: %s\nError Number: %ld", svFeatureSource, svFeature, svComponent, svFile, nvError); abort; endif; end;

1364

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) ShowObjWizardPages

ShowObjWizardPages
Project: This information applies to InstallScript projects.

The ShowObjWizardPages function is called in a projects UI event handler to execute each included objects corresponding UI event handler. For example, calling ShowObjWizardPages in a projects OnFirstUIBefore event handler executes each included objects OnFirstUIBefore code.

Syntax
ShowObjWizardPages ( nDirection );

Parameters
Table E-168: ShowObjWizardPages Parameters Parameter nDirection Description Pass one of the following predefined constants to indicate the measurement unit:

NEXTSpecifies the following: The first UI event handler called is that of the object listed first in the project's Components pane, then that of the object listed second, and so on. The WizardDirection function, when called in an object's UI event handler, returns the value NEXT.

BACKSpecifies the following: The first UI event handler called is that of the object listed last in the project's Components pane, then that of the object listed next to last, and so on. The WizardDirection function, when called in an object's UI event handler, returns the value BACK.

Return Values
The value returned by the most recently executed object UI event handler.

Additional Information
The objects dialogs are displayed in one of two possible orders, depending on the value of nDirection. For greater control over the order in which the objects dialogs are displayed, call the objects ShowxxxxxUIyyyyy methods. For more information on object UI event handlers, see Creating the Object's Run-Time User Interface.

ShowProgramFolder
The ShowProgramFolder function displays a program folder.

Syntax
ShowProgramFolder ( szFolder, nCommand );
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1365

Appendix E: Built-In Functions (S-T) ShowProgramFolder

Parameters
Table E-169: ShowProgramFolder Parameters Parameter szFolder nCommand Description Specifies the name of the folder to display. Specifies the state of the folder. Pass one of the following predefined constants in this parameter:

SW_SHOWShow folder in normal state. SW_MAXIMIZEMaximize the folder. SW_MINIMIZEMinimize the folder. SW_RESTORERestore the folder to original size.

Return Values
This function does not return a value.

ShowProgramFolder Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the ShowProgramFolder function. * * ShowProgramFolder displays a folder, then changes the state * of the folder. * * Note: This script will not run properly if the program folder * "Startup" does not exist. Either create a program * folder called "Startup" or set the constant FOLDER so * that it references an existing program folder. In * addition, the specified folder should be closed or * minimized when you run this script. * \*--------------------------------------------------------------*/ #define FOLDER "Startup"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_ShowProgramFolder(HWND); function ExFn_ShowProgramFolder(hMSI) begin

1366

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) ShowWindow

// Display the specified folder. ShowProgramFolder (FOLDER, SW_SHOW); Delay (3); // Maximize the folder. ShowProgramFolder (FOLDER, SW_MAXIMIZE); Delay (3); // Restore the folder to its previous state. ShowProgramFolder (FOLDER, SW_RESTORE); Delay (3); // Minimize the folder. ShowProgramFolder (FOLDER, SW_MINIMIZE); Delay (3); // Restore the folder to its previous state. ShowProgramFolder (FOLDER, SW_RESTORE); Delay (3); end;

ShowWindow
The ShowWindow function sets the specified window's show state.

Syntax
BOOL ShowWindow( HWND hWnd, // handle to window int nCmdShow // show state );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1367

Appendix E: Built-In Functions (S-T) ShowWindow

Parameters
Table E-170: ShowWindow Parameters Parameter hWnd nCmdShow Description Specifies the handle to the window. Specifies the show state of the window. If the program that launched the application includes a STARTUPINFO structure, this parameter is ignored the first time the application calls ShowWindow. Otherwise, the first time ShowWindow is called, the value should be the value obtained by the WinMain function in its nCmdShow parameter. In subsequent calls, this parameter can be one of the following values.

SW_FORCEMINIMIZEWindows 2000/XP: Minimizes a window, even if the thread that owns the window is not responding. This value should only be used when minimizing windows from a different thread. SW_HIDEHides the window and activates another window. SW_MAXIMIZEMaximizes the specified window. SW_MINIMIZEMinimizes the specified window and activates the next top-level window in the Z order. The Z order is the position of a window in a stack of overlapping windows on the z axis, which indicates depth. SW_RESTOREActivates and displays the window. If the window is minimized or maximized, the system restores it to its original size and position. An application should specify this value when restoring a minimized window. SW_SHOWActivates the window and displays it in its current size and position. SW_SHOWDEFAULTSets the show state based on the SW_ value specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application. SW_SHOWMAXIMIZEDActivates the window and displays it as a maximized window. SW_SHOWMINIMIZEDActivates the window and displays it as a minimized window. SW_SHOWMINNOACTIVEDisplays the window as a minimized window. The active window remains active. SW_SHOWNADisplays the window in its current size and position. The active window remains active. SW_SHOWNOACTIVATEDisplays a window in its most recent size and position. The active window remains active. SW_SHOWNORMALActivates and displays a window. If the window is minimized or maximized, it is restored it to its original size and position. An application should specify this value when displaying the window for the first time.

1368

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SilentReadData

Return Values
Table E-171: ShowWindow Return Values Return Value Nonzero Description The return value is nonzero if the window was visible. The return value is 0 if the window was hidden.

Additional Information
This information was adapted from the MSDN topic ShowWindow Function.

SilentReadData
The SilentReadData function instructs InstallShield Silent on how to read the .iss file dialog data for a custom dialog when an installation runs in silent mode (when using the -s switch with Setup.exe). Note that you can create an .iss file by calling SilentWriteData. To use SilentReadData in your script, construct the logic so that it first checks to make sure that the installation is running in silent mode. Place the SilentReadData function call inside an if-else statement, based on a test of the system variable MODE, as shown below:
if (MODE=SILENTMODE) then // Call SilentReadData here else // Make a normal, non-silent function call here endif;

Custom dialogs can be resources that you call and handle in your installation script using functions like EzDefineDialog and WaitOnDialog, or they can be completely external, executed as calls to functions in DLLs. In either case, you must use SilentReadData to retrieve from the .iss file the dialog buttons return value (Next, Back, Cancel, and so on) and any values set or returned in variables.

Syntax
SilentReadData (szSection, szValName, nValType, svVal, nvVal);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1369

Appendix E: Built-In Functions (S-T) SilentReadData

Parameters
Table E-172: SilentReadData Parameters Parameter szSection Description Specifies the name of the dialog data section in the .iss file. Do not include the square brackets ( [ ] ). The parameter szSection takes the form <functionname>-<number>, where <functionname> is the name of the dialog function as it is used in the script, and <number> is the number of the occurrence of that dialog in the script, beginning with 0 (zero). For example, the first occurrence of the MyDialog function dialog would have a value of "MyDialog-0" in szSection, the second occurrence "MyDialog-1," the third "MyDialog-2," and so on. Specifies the value name that appears in the dialog data section of the .iss file. Every dialog has at least one value for szValName"Result"which identifies the value returned by the dialog button controls (BACK, NEXT, OK, or CANCEL). Other value names are used to identify values and data associated with the other dialog controls. Identifies the data type of the value assigned to the value name in szValName. The value itself is stored in either svVal or nvVal, depending upon the value of nValType. Pass one of the following predefined constants in this parameter:

szValName

nValType

svVal

DATA_STRINGThe value assigned to the value name in szValName is of type STRING. Its value will be stored in svVal. DATA_NUMBERThe value assigned to the value name in szValName is of type NUMBER. Its value will be stored in nvVal. DATA_COMPONENTThe value assigned to the value name in szValName is the name of a component It will be stored in svVal. DATA_LISTThe value assigned to the value name in szValName is the list ID for an InstallScript list. It will be stored in nvVal.

Specifies the value assigned to the value name in szValName when nValType is DATA_STRING or DATA_COMPONENT. Specifies the value assigned to the value name in szValName when nValType is DATA_NUMBER or DATA_LIST.

nvVal

Return Values
Table E-173: SilentReadData Return Values Return Value 0 Description SilentReadData successfully instructed InstallShield Silent on how to read the dialog data for the custom dialog. SilentReadData was called in an installation that is not running silently.

<0

Note: If SilentReadData cannot read the custom dialog data in the response file, the installation is aborted.

1370

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SilentReadData

SilentReadData Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions SdMakeName, SilentReadData, and * SilentWriteData. * * This example script shows how to handle a custom dialog * in a silent installation. The resource .dll for the example * custom dialog shown below should be stored in a compressed * form under the Support Files/Billboards view of InstallShield. * * The example dialog was built from the custom dialog * template provided with InstallShield. * * Dialog control IDs and other information are included in * the RESOURCE.H file (not shown). This file, which is included * in the first line of the example, must be inserted in the * InstallScript view of InstallShield. * * The example creates a text file called Cominit.txt. If the * installation runs in silent mode, SilentReadData is called * and the custom dialog control selections are read from * the .ISS file. The selections are then saved in the file * Cominit.txt as a means of demonstrating that they were * successfully read from the .iss file. If the installation * runs in normal mode, the custom dialog is displayed * and the selections are recorded in the .iss file and * displayed in message boxes. The initial .ISS file text is * shown after the example script. * \*--------------------------------------------------------------*/ #include "Resource.h" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SilentReadData(HWND); function ExFn_SilentReadData(hMSI) BOOL bDone; STRING svSection, svComPort, svPulse, svTone, svDial9, svVal; NUMBER nvCommDialog, nCmdValue, nPulseState, nToneState; NUMBER nDial9State, nResult, nvHandle; LIST listID; begin // Open the text file COMINIT.TXT so custom dialog selections // from the .ISS file can be stored in it. OpenFileMode (FILE_MODE_APPEND); OpenFile (nvHandle, "c:\\rul", "cominit.txt");

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1371

Appendix E: Built-In Functions (S-T) SilentReadData

// If operating in silent mode, then read from the .ISS file. if (MODE=SILENTMODE) then SdMakeName (svSection, "COMM_DIALOG", "", nvCommDialog); SilentReadData (svSection, "Result", DATA_NUMBER, svVal, nResult); if (nResult = 1) then // Read the data from the .ISS file. For purposes of // writing the results to a text file, read the // data as strings. SilentReadData (svSection, "nPulseState", DATA_STRING, svPulse, nResult); SilentReadData (svSection, "nToneState", DATA_STRING, svTone, nResult); SilentReadData (svSection, "nDial9State", DATA_STRING, svDial9, nResult); // Store the custom dialog selections in // the text file COMINIT.TXT. svVal = "Pulse box is: " ^ svPulse; WriteLine(nvHandle, svVal); svVal = "Tone box is: " ^ svTone; WriteLine(nvHandle, svVal); svVal = "Dial9 box is: " ^ svDial9; WriteLine(nvHandle, svVal); endif; // If not in silent mode, then call and handle the custom dialog // as you normally would. else listID = ListCreate (STRINGLIST); ListAddString (listID, "COMM1:", AFTER); ListAddString (listID, "COMM2:", AFTER); ListAddString (listID, "COMM3:", AFTER); ListAddString (listID, "COMM4:", AFTER); EzDefineDialog ("MYCOMDIALOG", SUPPORTDIR^"RESOURCE.DLL", "COMM_DIALOG",0); bDone = FALSE; while (bDone=FALSE) nCmdValue = WaitOnDialog ("MYCOMDIALOG"); switch (nCmdValue) case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 // and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_CHECKED); CtrlSetList ("MYCOMDIALOG", ID_COMPORT, listID); CtrlSetState ("MYCOMDIALOG", ID_DIAL9, BUTTON_CHECKED); case OK: CtrlGetCurSel ("MYCOMDIALOG", ID_COMPORT, svComPort);
1372 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SilentReadData

nPulseState = CtrlGetState ("MYCOMDIALOG", ID_PULSE); nToneState = CtrlGetState ("MYCOMDIALOG", ID_TONE); nDial9State = CtrlGetState ("MYCOMDIALOG", ID_DIAL9); nResult = NEXT; bDone = TRUE; case BACK: nResult = BACK; bDone = TRUE; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case DLG_CLOSE: // The user clicked the window's close button. Do (EXIT); case ID_PULSE: nPulseState = CtrlGetState ("MYCOMDIALOG", ID_PULSE); if (nPulseState = BUTTON_CHECKED) then CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_UNCHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_CHECKED); else CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_CHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_UNCHECKED); endif; case ID_TONE: nToneState = CtrlGetState ("MYCOMDIALOG", ID_TONE); if (nPulseState = BUTTON_CHECKED) then CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_CHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_UNCHECKED); else CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_UNCHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_CHECKED); endif; case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; endswitch; endwhile; EndDialog ("MYCOMDIALOG"); ReleaseDialog ("MYCOMDIALOG"); SdMakeName (svSection, "COMM_DIALOG", "", nvCommDialog); SilentWriteData (svSection, "nPulseState", DATA_NUMBER, svPulse, nPulseState); SilentWriteData (svSection, "nToneState", DATA_NUMBER, svTone, nToneState); SilentWriteData (svSection, "nDial9State", DATA_NUMBER, svDial9, nDial9State); if (nPulseState = BUTTON_CHECKED) then MessageBox ("The Pulse button was checked.", INFORMATION); else MessageBox ("The Pulse button was unchecked.", INFORMATION); endif; if (nToneState = BUTTON_CHECKED) then MessageBox ("The Tone button was checked.", INFORMATION);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1373

Appendix E: Built-In Functions (S-T) SilentWriteData

else MessageBox ("The Tone button was unchecked.", INFORMATION); endif; if (nDial9State = BUTTON_CHECKED) then MessageBox ("The Dial9 button was checked.", INFORMATION); else MessageBox ("The Dial9 button was unchecked.", INFORMATION); endif; endif; // Close the text file COMINIT.TXT CloseFile (nvHandle); end;

/*The following is the initial .iss file text for the above example, where <PRODUCT_GUID> represents your project's GUID, including the surrounding braces. Note that -1001 is the numeric value of BUTTON_CHECKED and -1002 is the numeric value of BUTTON_UNCHECKED. [InstallShield Silent] Version=v9.00 File=Response File [Application] Name=MyDialog Version=4.0 Company=My Software Company [<PRODUCT_GUID>-DlgOrder] Dlg0=<PRODUCT_GUID>-COMM_DIALOG-0 Count=1 [<PRODUCT_GUID>-COMM_DIALOG-0] nPulseState=-1001 nToneState=-1002 nDial9State=-1001 Result=1 */

SilentWriteData
The SilentWriteData function records selections made in custom dialogs during the installation. This selection data is written to an .iss file for use by InstallShield Silent. To write to an .iss file during an installation, run the installation using the -r switch with Setup.exe. Custom dialogs can be resources that you call and handle in your installation script using functions like EzDefineDialog and WaitOnDialog, or they can be completely external, executed as calls to functions in DLLs. In either case, you must use SilentWriteData to record the dialog's button return value (Next, Back, Cancel, and so on) and any values set or returned in variables.

Syntax
SilentWriteData ( szSection, szValName, nValType, szVal, nVal );

1374

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SilentWriteData

Parameters
Table E-174: SilentWriteData Parameters Parameter szSection Description Specifies the name of the dialog data section in the .iss file. Do not include the square brackets ( [ ] ). The parameter szSection takes the form <functionname>-<number>, where <functionname> is the name of the dialog function as it is used in the script, and <number> is the number of the occurrence of that dialog in the script, beginning with 0 (zero). For example, the first occurrence of the MyDialog function dialog would have a value of "MyDialog-0" for szSection, the second occurrence "MyDialog-1," the third "MyDialog2," and so on. Specifies the value name that appears in the dialog data section of the .iss file. Every dialog has at least one value for szValName "Result"which identifies the value returned by the dialog button controls (BACK, NEXT, OK, or CANCEL). Other value names are used to identify values and data associated with the other dialog controls. Identifies the data type of the value assigned to the value name in szValName. The value itself is stored in either szVal or nVal, depending upon the value of nValType. Pass one of the following predefined constants in this parameter:

szValName

nValType

DATA_STRINGThe value assigned to the value name in szValName is of type STRING. Its value will be stored in szVal. DATA_NUMBERThe value assigned to the value name in szValName is of type NUMBER. Its value will be stored in nVal. DATA_COMPONENTThe value assigned to the value name in szValName is the name of a component. It will be stored in szVal. DATA_LISTThe value assigned to the value name in szValName is the list ID for an InstallShield list. It is stored in nVal.

szVal

Specifies the value assigned to the value name in szValName when nValType is DATA_STRING or DATA_COMPONENT. Specifies the value assigned to the value name in szValName when nValType is DATA_NUMBER or DATA_LIST.

nVal

Return Values
Table E-175: SilentWriteData Return Values Return Value 0 Description SilentWriteData successfully wrote the dialog data for the custom dialog to Setup.iss.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1375

Appendix E: Built-In Functions (S-T) SilentWriteData

Table E-175: SilentWriteData Return Values (cont.) Return Value <0 Description SilentWriteData was unable to write the dialog data for the custom dialog to Setup.iss.

SilentWriteData Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the functions SdMakeName, SilentReadData, and * SilentWriteData. * * This example script shows how to handle a custom dialog * in a silent installation. The resource .dll for the example * custom dialog shown below should be stored in a compressed * form under the Support Files/Billboards view of InstallShield. * * The example dialog was built from the custom dialog * template provided with InstallShield. * * Dialog control IDs and other information are included in * the RESOURCE.H file (not shown). This file, which is included * in the first line of the example, must be inserted in the * InstallScript view of InstallShield. * * The example creates a text file called Cominit.txt. If the * installation runs in silent mode, SilentReadData is called * and the custom dialog control selections are read from * the .ISS file. The selections are then saved in the file * Cominit.txt as a means of demonstrating that they were * successfully read from the .iss file. If the installation * runs in normal mode, the custom dialog is displayed * and the selections are recorded in the .iss file and * displayed in message boxes. The initial .ISS file text is * shown after the example script. * \*--------------------------------------------------------------*/ #include "Resource.h" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SilentWriteData(HWND); function ExFn_SilentWriteData(hMSI) BOOL bDone; STRING svSection, svComPort, svPulse, svTone, svDial9, svVal; NUMBER nvCommDialog, nCmdValue, nPulseState, nToneState;

1376

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SilentWriteData

NUMBER nDial9State, nResult, nvHandle; LIST listID; begin // Open the text file COMINIT.TXT so custom dialog selections // from the .ISS file can be stored in it. OpenFileMode (FILE_MODE_APPEND); OpenFile (nvHandle, "c:\\rul", "cominit.txt"); // If operating in silent mode, then read from the .ISS file. if (MODE=SILENTMODE) then SdMakeName (svSection, "COMM_DIALOG", "", nvCommDialog); SilentReadData (svSection, "Result", DATA_NUMBER, svVal, nResult); if (nResult = 1) then // Read the data from the .ISS file. For purposes of // writing the results to a text file, read the // data as strings. SilentReadData (svSection, "nPulseState", DATA_STRING, svPulse, nResult); SilentReadData (svSection, "nToneState", DATA_STRING, svTone, nResult); SilentReadData (svSection, "nDial9State", DATA_STRING, svDial9, nResult); // Store the custom dialog selections in // the text file COMINIT.TXT. svVal = "Pulse box is: " ^ svPulse; WriteLine(nvHandle, svVal); svVal = "Tone box is: " ^ svTone; WriteLine(nvHandle, svVal); svVal = "Dial9 box is: " ^ svDial9; WriteLine(nvHandle, svVal); endif; // If not in silent mode, then call and handle the custom dialog // as you normally would. else listID = ListCreate (STRINGLIST); ListAddString (listID, "COMM1:", AFTER); ListAddString (listID, "COMM2:", AFTER); ListAddString (listID, "COMM3:", AFTER); ListAddString (listID, "COMM4:", AFTER); EzDefineDialog ("MYCOMDIALOG", SUPPORTDIR^"RESOURCE.DLL", "COMM_DIALOG",0); bDone = FALSE; while (bDone=FALSE) nCmdValue = WaitOnDialog ("MYCOMDIALOG"); switch (nCmdValue) case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1377

Appendix E: Built-In Functions (S-T) SilentWriteData

// IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 // and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_CHECKED); CtrlSetList ("MYCOMDIALOG", ID_COMPORT, listID); CtrlSetState ("MYCOMDIALOG", ID_DIAL9, BUTTON_CHECKED); case OK: CtrlGetCurSel ("MYCOMDIALOG", ID_COMPORT, svComPort); nPulseState = CtrlGetState ("MYCOMDIALOG", ID_PULSE); nToneState = CtrlGetState ("MYCOMDIALOG", ID_TONE); nDial9State = CtrlGetState ("MYCOMDIALOG", ID_DIAL9); nResult = NEXT; bDone = TRUE; case BACK: nResult = BACK; bDone = TRUE; case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case DLG_CLOSE: // The user clicked the window's close button. Do (EXIT); case ID_PULSE: nPulseState = CtrlGetState ("MYCOMDIALOG", ID_PULSE); if (nPulseState = BUTTON_CHECKED) then CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_UNCHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_CHECKED); else CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_CHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_UNCHECKED); endif; case ID_TONE: nToneState = CtrlGetState ("MYCOMDIALOG", ID_TONE); if (nPulseState = BUTTON_CHECKED) then CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_CHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_UNCHECKED); else CtrlSetState ("MYCOMDIALOG", ID_TONE, BUTTON_UNCHECKED); CtrlSetState ("MYCOMDIALOG", ID_PULSE, BUTTON_CHECKED); endif; case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; endswitch; endwhile; EndDialog ("MYCOMDIALOG"); ReleaseDialog ("MYCOMDIALOG"); SdMakeName (svSection, "COMM_DIALOG", "", nvCommDialog); SilentWriteData (svSection, "nPulseState", DATA_NUMBER, svPulse, nPulseState); SilentWriteData (svSection, "nToneState", DATA_NUMBER, svTone, nToneState); SilentWriteData (svSection, "nDial9State", DATA_NUMBER,
1378 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SizeOf

svDial9, nDial9State); if (nPulseState = BUTTON_CHECKED) then MessageBox ("The Pulse button was checked.", INFORMATION); else MessageBox ("The Pulse button was unchecked.", INFORMATION); endif; if (nToneState = BUTTON_CHECKED) then MessageBox ("The Tone button was checked.", INFORMATION); else MessageBox ("The Tone button was unchecked.", INFORMATION); endif; if (nDial9State = BUTTON_CHECKED) then MessageBox ("The Dial9 button was checked.", INFORMATION); else MessageBox ("The Dial9 button was unchecked.", INFORMATION); endif; endif; // Close the text file COMINIT.TXT CloseFile (nvHandle); end;

/*The following is the initial .iss file text for the above example, where <PRODUCT_GUID> represents your project's GUID, including the surrounding braces. Note that -1001 is the numeric value of BUTTON_CHECKED and -1002 is the numeric value of BUTTON_UNCHECKED. [InstallShield Silent] Version=v9.00 File=Response File [Application] Name=MyDialog Version=4.0 Company=My Software Company [<PRODUCT_GUID>-DlgOrder] Dlg0=<PRODUCT_GUID>-COMM_DIALOG-0 Count=1 [<PRODUCT_GUID>-COMM_DIALOG-0] nPulseState=-1001 nToneState=-1002 nDial9State=-1001 Result=1 */

SizeOf
The SizeOf operator retrieves the number of elements in an InstallScript array, or the size of a variable passed as an argument.

Syntax
SizeOf ( Item );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1379

Appendix E: Built-In Functions (S-T) SizeWindow

Parameters
Table E-176: SizeOf Parameters Parameter Item Description Specifies the name of the variable.

Return Values
Returns the number of elements in an array, or the size of a variable passed as an argument.

Note: To determine the number of characters in the value of a string variable, use StrLengthChars instead of SizeOf.

SizeWindow
Use the SizeWindow function to change the size of a specific user interface element. Specify the new size in pixels. The installation may run under many different screen resolutions. To account for this, you need to use the GetExtents function to determine the overall size of the screen; then use ratios in the parameters of your SizeWindow function call to specify the size of your user interface object.

Note: This function is recommended for advanced developers only.

Syntax
SizeWindow (nObject, nDx, nDy);

1380

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SizeWindow

Parameters
Table E-177: SizeWindow Parameters Parameter nObject Description Specifies the object to resize. Pass one of the following predefined constants in this parameter:

BACKGROUNDIndicates the main background window. METAFILEIndicates a billboard used during the file transfer process. SizeWindow does not support bitmap (.bmp) files.

Note: This parameter does not have any effect on metafiles that are displayed with SdBitmap function. SdBitmap automatically resizes metafiles when they are displayed. In addition, this parameter does not have any effect on the type of billboard that is displayed on a progress dialog when Enable(BBRD) is called.

nDx nDy

MMEDIA_AVISets the window size for next AVI file to be played. All the AVI videos are displayed with a default size. Changing the size may change the resolution and crispness of the video. MMEDIA_SWFSets the window size for the Adobe Flash application file (.swf) to be played.

Specifies the horizontal size of the object in pixels. Specifies the vertical size of the object in pixels.

Return Values
Table E-178: SizeWindow Return Values Return Value 0 <0 Description The function successfully changed the size of the window. The function was unable to change the size of the window.

Additional Information
Use the PlayMMedia function if you want your installation to play an Adobe Flash application file (.swf) or an AVI file.

SizeWindow Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1381

Appendix E: Built-In Functions (S-T) Sprintf

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SizeWindow function. * * GetExtents is called to retrieve the extents of the screen. * SizeWindow is then called to resize the background to half * the original size. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SizeWindow(HWND); function ExFn_SizeWindow(hMSI) NUMBER nDx, nDy, nObject; begin // Enable the background. Enable (BACKGROUND); MessageBox ("Background at original size.", INFORMATION); // Get the extents of the screen. GetExtents (nDx, nDy); // Set the object to be resized. nObject = BACKGROUND; // Resize the background window to half of its original size. if (SizeWindow (nObject, (nDx / 2), (nDy / 2)) < 0) then MessageBox ("SizeWindow failed.", SEVERE); endif; MessageBox ("Background after call to SizeWindow.", INFORMATION); end;

Sprintf
The Sprintf function creates a string from variable data using format specifier and matching variables. Sprintf works like the Microsoft Windows API wsprintf.

Syntax
Sprintf ( svResult, szFormat [,arg] [,...] );

1382

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) Sprintf

Parameters
Table E-179: Sprintf Parameters Parameter svResult Description Returns a string created from the arguments passed in the third and subsequent parameters and formatted according the specifications in the second parameter, szFormat. Specifies a string than can include literal text and must include one format specifier for each argument to be embedded in the string returned by svResult. You may specify up to nine arguments to be included in the message. You must have one argument for each format specifier in the message; the type of each argument must match the type of its respective format specifier. Sprintf generates a compiler error or fail at run time under the following conditions:

szFormat

arg

More than nine format specifiers and arguments are specified. This results in a compiler error. The number of arguments does not match the number of format specifiers. When a specifier does not have a corresponding argument, the resulting string contains unpredictable characters in the specifier's position. When there are more arguments than specifiers, the excess arguments are not inserted into the resulting string. A variable does not match the type of its respective format specifier. The resulting string contains unpredictable characters in the specifier's position.

Return Values
If the Sprintf function is successful, the return value is the lengththe number of charactersin the string stored in the variable svResult, not including the terminating null character.

Sprintf Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the Sprintf function. * * This script gets the capacity of drive C: and then calls * Sprintf to create a formatted message. That message * includes the drive letter and disk size, which are stored * in variables. The message is then displayed. *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1383

Appendix E: Built-In Functions (S-T) SprintfBox

\*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_Sprintf(HWND); function ExFn_Sprintf(hMSI) STRING svResult, svMssg; NUMBER nvResult; begin // Set up the string parameter for the call to GetSystemInfo. svResult = "C:"; // Get the capacity of drive C. GetSystemInfo (DISK_TOTALSPACE, nvResult, svResult); // Build a message that incorporates the values // returned by GetSystemInfo. Sprintf (svMssg, "Total disk space on drive %s is %ld bytes.", svResult, nvResult); // Display the message. MessageBox (svMssg, INFORMATION); end;

SprintfBox
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

The SprintfBox function presents a message box containing one of three icons, a title, and a formatted message. The message can contain variables that are formatted according to commands that you enter.
SprintfBox is similar to MessageBox, but SprintfBox permits much more flexible control over displayed

items.

Caution: Multiple null-delimited strings should not be used, except for passing to external functionality.

The SprintfBox function uses the Microsoft Windows API MessageBox to create the message box. The operating environment, not InstallShield, determines the size and location of the message box. The operating environment also generates the text for the OK button in the local language (the language that the operating system is running under). You cannot change the text in this button. For more information regarding the use of Windows MessageBox types, consult the description of the MessageBox Windows API function in the appropriate Windows SDK. Note the following when using Windows message box constants:

1384

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SprintfBox

Some Windows MessageBox type constants are predefined in the ISRTWindows.h file that is provided in the InstallShield Program Files Folder\Script\Isrt\Include folder. This file is automatically included in your installation when you include Ifx.h in your script. You do not need to redefine any constants that are defined in ISRTWindows.h; doing so will result in a compiler warning. To determine which constants are predefined, refer to the ISRTWindows.h file. To use constants that are not defined in ISRTWindows.h, you must define them (using #define) in the declaration block of your installation script. You cannot simply include the Windows.h file that is usually part of a C++ program. The values that you need to assign to the undefined constants can generally be found in an include file that is provided with the appropriate Windows SDK or development tool. (For Microsoft Visual C++, most constants can be found in the Winuser.h file, which is located in the InstallShield Program Files Folder\Script\Resource folder.) Windows and InstallShield message box constants cannot be used together in an installation. If an InstallShield message box constant is combined with a Windows message box constant using the OR operator (|), the Windows message box constant is ignored. Some Windows message box styles are not supported on some Windows platforms. To determine whether a particular style is supported on the operating systems targeted by the installation, consult the appropriate Windows SDK.

Syntax
SprintfBox ( nType, szTitle, szFormat [,arg] [,...] );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1385

Appendix E: Built-In Functions (S-T) SprintfBox

Parameters
Table E-180: SprintfBox Parameters Parameter nType Description Specifies the type of icon to display in the message box. Pass one of the following predefined constants in this parameter:

INFORMATION WARNING SEVERE

Advanced developers familiar with the Windows APIs can specify any style of message box by using the native message box style constants in the parameter nType. See the description for the MessageBox or WinMessageBox API in the programming manual for your operating environment. If you are using any of the native message box styles, the InstallShield SprintfBox function returns the return value from the Windows API. Therefore, you must use the Windows API return values in your script. For example, if you pass YES|NO|CANCEL as the first parameter, the SprintfBox message box has Yes, No, and Cancel buttons. The respective button return values, as defined by the Windows API MessageBox, are 6 (IDYES), 7 (IDNO), and 2 (IDCANCEL). You must use the appropriate constant values in your script, either as number literals, or as constants defined as the number literals in the declare block of your script.

Tip: Advanced developers can use MB_STYLE directly as the first parameter of the SprintfBox function to replace the constants SEVERE, WARNING, or INFORMATION. The value of MB_STYLE is listed in the Windows.h file. You can either enter the value directly in the parameter nType, or you can use the #define preprocessor directive to define the constants associated with the value. szTitle Specifies the title of the message box. To display the default title Error, pass a null string ("") in this parameter. Specifies a string that includes a format specifier for each argument to be included in the message.

szFormat

1386

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SprintfBox

Table E-180: SprintfBox Parameters (cont.) Parameter arg Description Specifies up to 10 arguments to be included in the message. There must be one argument for each format specifier in the message; the type of each argument must match the type of its respective format specifier. SprintfBox generates a compiler error or fails at run time under the following conditions:

More than 10 format specifiers and arguments are specified: compiler error. The number of arguments does not match the number of format specifiers. When a specifier does not have a corresponding argument, the resulting string contains unpredictable characters in the specifier's position. When there are more arguments than specifiers, the excess arguments are not inserted into the resulting string. A variable does not match the type of its respective format specifier. A character itself is passed, rather than its numeric ASCII value or the return from the STRTOCHAR function, with the format specifier %c.

Return Values
The return value is not significant unless you are using standard Microsoft Windows message box styles. If you are using these styles, the return value is the same as the return value from the MessageBox API functions.

Additional Information
The dialog that is displayed by the SprintfBox function cannot be displayed with a skin; it appears the same regardless of whether you have specified a skin.

SprintfBox Example
Project: This information applies to the following project types:

Basic MSI InstallScript InstallScript MSI

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the SprintfBox function. * * This script gets the capacity of drive C: and then calls * SprintfBox to create and display a formatted message. That * message includes the drive letter and disk size, which are
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1387

Appendix E: Built-In Functions (S-T) SprintfMsiLog

* stored in variables. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_SprintfBox(HWND); function ExFn_SprintfBox(hMSI) STRING svResult; NUMBER nvResult; begin // Set up the string parameter for the call to GetSystemInfo. svResult = "C:"; // Get the capacity of drive C. GetSystemInfo (DISK_TOTALSPACE, nvResult, svResult); // Build and display a message that incorporates // the values returned by GetSystemInfo. SprintfBox (INFORMATION, "System Information", "Total disk space on drive %s is %ld bytes.", svResult, nvResult); end;

SprintfMsiLog
Project: This information applies to the following project types:

Basic MSI InstallScript MSI

The SprintfMsiLog function writes a message directly to the Windows Installer log file.

Syntax
SprintfMsiLog ( szFormat [,arg] [,...] );

1388

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLBrowse

Parameters
Table E-181: SprintfMsiLog Parameters Parameter szFormat Description Specifies a string than can include literal text and must include one format specifier for each argument to be embedded in the string returned by svResult. You can specify up to nine arguments to be included in the message. You must have one argument for each format specifier in the message. The type of each argument must match the type of its respective format specifier. SprintfMsiLog generates a compiler error or fail at run time under the following conditions:

arg

More than nine format specifiers and arguments are specified. This results in a compiler error. The number of arguments does not match the number of format specifiers. When a specifier does not have a corresponding argument, the resulting string contains unpredictable characters in the specifier's position. When there are more arguments than specifiers, the excess arguments are not inserted into the resulting string. A variable does not match the type of its respective format specifier. The resulting string contains unpredictable characters in the specifier's position.

Return Values
There are no return values for this function. If the function is successful, the values are written to the Windows Installer log file. If the function fails, the values are not written to the Windows Installer log file.

SQLBrowse
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLBrowse2 function supersedes the SQLBrowse function. The SQLBrowse function creates a dialog that lets an end user display a list of all SQL Servers that are available on the network. This function is in the SQLRT.obl file for InstallScript projects, and in the SQLCONV.obl file for InstallScript MSI projects. If you are using the SQL Scripts view in InstallShield, the appropriate file is automatically added to your linker settings. However, if you are not using this view, add the appropriate file to your linker settings: On the Build menu, click Settings, and then add it to the Libraries (.obl) box.

Syntax
SQLBrowse( svServer );
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1389

Appendix E: Built-In Functions (S-T) SQLBrowse2

Parameters
Table E-182: SQLBrowse Parameters Parameter svServer Description When the function returns, this parameter contains the string with the server name that the end user selected. If an alias name was used to connect to a SQL Server database, this parameter contains the alias name.

Return Values
Table E-183: SQLBrowse Return Values Return Value NEXT CANCEL < ISERR_SUCCESS Description The end user clicked the OK button. The end user clicked the Cancel button. The dialog could not be displayed.

SQLBrowse2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLBrowse2 function creates a dialog that lets an end user display a list of all database servers that are available on the network for the database technologies specified for a connection.

Syntax
SQLBrowse2( szConnection, svServer );

1390

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLDatabaseBrowse

Parameters
Table E-184: SQLBrowse2 Parameters Parameter szConnection svServer Description Specifies the name of the connection that you created in the SQL Scripts view. When the function returns, this parameter contains the string with the server name that the end user selected. If an alias name was used to connect to a SQL Server database, this parameter contains the alias name.

Return Values
Table E-185: SQLBrowse2 Return Values Return Value NEXT CANCEL < ISERR_SUCCESS Description The end user clicked the OK button. The end user clicked the Cancel button. The dialog could not be displayed.

SQLDatabaseBrowse
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLDatabaseBrowse function creates a dialog that lets the end user display a list of all database catalogs that are available on the specified database server. This function calls SQLRTGetDatabases, which uses SQLRT.dll for InstallScript projects and ISSQLSRV.dll for InstallScript MSI projects.

Note: The SQLDatabaseBrowse function uses settings from the SQL settings file; therefore, it can be called only after SQLRTInitialize2 has already been called.

Syntax
SQLDatabaseBrowse( szConnection, szServer, bvWindowsLogin, szUser, szPassword, svDBCatalog );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1391

Appendix E: Built-In Functions (S-T) SQLRTComponentInstall

Parameters
Table E-186: SQLDatabaseBrowse Parameters Parameter szConnection svServer Description Specifies the name of the connection that you created in the SQL Scripts view. When the function returns, this parameter contains the string with the server name the end user selected. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead. szUser Specifies the default string to display in the Login ID edit box. Once the dialog function returns, this parameter contains the Login ID that the end user entered in the edit field. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials. Specifies the default string to display in the Password edit field. Once the dialog function returns, this parameter contains the password that the end user entered in the edit field. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials. Specifies the name of the SQL database catalog.

bvWindowsLogin

szPassword

svDBCatalog

Return Values
Table E-187: SQLDatabaseBrowse Return Values Return Value NEXT CANCEL < ISERR_SUCCESS Description The end user clicked the OK button. The end user clicked the Cancel button. The dialog could not be displayed.

SQLRTComponentInstall
Project: This information applies to InstallScript projects.

The SQLRTComponentInstall function executes the SQL script that is associated with the specified component if the script is scheduled to run during installation.

1392

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTComponentUninstall

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTComponentInstall( szComponent );

Parameters
Table E-188: SQLRTComponentInstall Parameters Parameter szComponent Description Specifies the name of the component that contains the SQL script.

Return Values
Table E-189: SQLRTComponentInstall Return Values Return Value >=ISERR_SUCCESS <ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED (-10) Description This function was able to execute the SQL script. This function failed to execute the SQL script.
SQLRT.dll is not loaded.

SQLRTComponentUninstall
Project: This information applies to InstallScript projects.

The SQLRTComponentUninstall function executes the SQL script that is associated with the specified component if the script is scheduled to run during uninstallation.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTComponentUninstall( szComponent );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1393

Appendix E: Built-In Functions (S-T) SQLRTConnect

Parameters
Table E-190: SQLRTComponentUninstall Parameters Parameter szComponent Description Specifies the name of the component that contains the SQL script.

Return Values
Table E-191: SQLRTComponentUninstall Return Values Return Value >=ISERR_SUCCESS <ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED (-10) Description This function was able to execute the SQL script. This function failed to execute the SQL script.
SQLRT.dll is not loaded.

SQLRTConnect
Project: This information applies to InstallScript projects.

The SQLRTConnect2 function supersedes the SQLRTConnect function. The SQLRTConnect function establishes a connection using the specified credential.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTConnect( szConnection, szServer, bTrust, szUserName, szPassword );

1394

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTConnect2

Parameters
Table E-192: SQLRTConnect Parameters Parameter szConnection Description Specifies the name of the connection that you created in the SQL Scripts view. Specifies the SQL Server. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead. szUserName szPassword Specifies the SQL Server login information. Specifies the password associated with a user account.

szServer bTrust

Return Values
Table E-193: SQLRTConnect Return Values Return Value >=ISERR_SUCCESS <ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED (-10) Description This function was able to establish a connection. This function failed to establish a connection.
SQLRT.dll is not loaded.

SQLRTConnect2
Project: This information applies to InstallScript projects.

The SQLRTConnect2 function establishes a connection. This function must be called before file transfer if the connection is to be used to run scripts during installation. SQLRTConnect2 returns the database server name when it fails to establish the connection.

Note: The SQLRTConnect2 function uses SQLRT.dll; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1395

Appendix E: Built-In Functions (S-T) SQLRTConnect2

Syntax
SQLRTConnect2( szConnection, szServer, bWinLogin, szUser, szPassword, szDatabaseServer );

Parameters
Table E-194: SQLRTConnect2 Parameters Parameter szConnection Description Specifies the name of the connection that you created in the SQL Scripts view. Specifies the SQL Server. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead. szUser szPassword szDatabaseServer Specifies the SQL Server login information. Specifies the password associated with a user account. Specifies the database server.

szServer bWinLogin

Return Values
Table E-195: SQLRTConnect2 Return Values Return Value >=ISERR_SUCCESS <ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED (-10) Description This function was able to establish a connection. This function failed to establish a connection.
SQLRT.dll is not loaded.

Additional Information
If you want to be able to specify which catalog to connect to, replace the SQLRTConnect2 function call in the OnSQLServerInitialize event with the SQLRTConnectDB function call. For more information, see SQLRTConnectDB.

1396

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTConnectDB

SQLRTConnectDB
Project: This information applies to InstallScript projects.

To establish a connection to a specific catalog, replace the SQLRTConnect2 function call in the OnSQLServerInitialize event with the SQLRTConnectDB function call. Pass the catalog name as the szDB parameter for SQLRTConnectDB. If you want end users to be able to specify the catalog at run time, pass an end userdefined variable as szDB.

Note: The SQLRTConnectDB function uses SQLRT.dll; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTConnectDB( szConnection, szDB, szServer, bWinLogin, szUser, szPassword );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1397

Appendix E: Built-In Functions (S-T) SQLRTDoRollbackAll

Parameters
Table E-196: SQLRTConnectDB Parameters Parameter szConnection szDB Description Specifies the SQL Server connection. Specifies the catalog that you want to connect to. To specify multiple catalogs, separate each with a semicolon (;). If you want end users to be able to specify the catalog at run time, pass an end userdefined variable as szDB. szServer bWinLogin Specifies the SQL Server. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead. szUser szPassword Specifies the SQL Server login information. Specifies the password associated with a user account.

Return Values
Table E-197: SQLRTConnectDB Return Values Return Value >=ISERR_SUCCESS <ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED (-10) Description This function was able to establish a connection. This function failed to establish a connection.
SQLRT.dll is not loaded.

SQLRTDoRollbackAll
Project: This information applies to InstallScript projects.

The SQLRTDoRollbackAll function executes all of SQL scripts scheduled to run during rollback.

Note: The SQLRTDoRollbackAll function uses SQLRT.dll; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

1398

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTGetBatchList

Syntax
SQLRTDoRollbackAll();

Parameters
SQLRTDoRollbackAll takes no parameters.

Return Values
Table E-198: SQLRTDoRollbackAll Return Values Return Value >=ISERR_SUCCESS <ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED (-10) Description This function was able to execute a script. This function failed to execute a script.
SQLRT.dll is not loaded.

SQLRTGetBatchList
Project: This information applies to InstallScript projects.

The SQLRTGetBatchList function returns the list of components that are associated with SQL scripts that need to be run when batch mode is enabled.

Note: The SQLRTGetBatchList function uses SQLRT.dll; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetBatchList( nOperation );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1399

Appendix E: Built-In Functions (S-T) SQLRTGetBatchMode

Parameters
Table E-199: SQLRTGetBatchList Parameters Parameter nOperation Description Pass either of the following constants through this parameter:

SQL_BATCH_INSTALLObtains the list of SQL scripts scheduled to be run during installation. SQL_BATCH_UNINSTALLObtains the list of SQL scripts scheduled to be run during uninstallation.

Return Values
Table E-200: SQLRTGetBatchList Return Values Return Value listConnections Description Returns a list of component names.

Additional Information
For details about batch mode, see Specifying the Order for Running Multiple SQL Scripts That Are Associated with a Connection.

SQLRTGetBatchMode
Project: This information applies to InstallScript projects.

The SQLRTGetBatchMode function returns whether the batch mode is enabled or disabled.

Note: The SQLRTGetBatchMode function uses SQLRT.dll; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetBatchMode();

Parameters
SQLRTGetBatchMode takes no parameters.

1400

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTGetBrowseOption

Return Values
Table E-201: SQLRTGetBatchMode Return Values Return Value TRUE FALSE Description Batch mode is enabled. Batch mode is disabled.

Additional Information
For details about batch mode, see Specifying the Order for Running Multiple SQL Scripts That Are Associated with a Connection.

SQLRTGetBrowseOption
Project: This information applies to InstallScript projects.

The SQLRTGetBrowseOption function returns the current value of the browse option for the SQL Server browse combo box and list box controls, which can display local servers, remote servers, server aliases, or a combination of these types.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetBrowseOption( );

Parameters
SQLRTGetBrowseOption takes no parameters.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1401

Appendix E: Built-In Functions (S-T) SQLRTGetComponentScriptError

Return Values
Table E-202: SQLRTGetBrowseOption Return Values Return Value 0 Description The SQL Server browse combo box and list box controls show all available SQL Servers (local servers, remote servers , and server aliases). This is the return value if SQL_BROWSE_ALL or zero (0) is passed for the nBrowseOption parameter of SQLRTSetBrowseOption, or if the SQLRTSetBrowseOption function is not called. 1 The SQL Server browse combo box and list box controls show all available local SQL Servers. This is the return value if SQL_BROWSE_LOCAL or 1 is passed for the nBrowseOption parameter of SQLRTSetBrowseOption. 2 The SQL Server browse combo box and list box controls show all available remote SQL Servers. This is the return value if SQL_BROWSE_REMOTE or 2 is passed for the nBrowseOption parameter of SQLRTSetBrowseOption. 3 The SQL Server browse combo box and list box controls show all available local SQL Servers and remove SQL Servers. This is the return value if SQL_BROWSE_LOCAL | SQL_BROWSE_REMOTE or 3 is passed for the nBrowseOption parameter of SQLRTSetBrowseOption. 4 The SQL Server browse combo box and list box controls show all available SQL Server aliases. This is the return value if SQL_BROWSE_ALIAS or 4 is passed for the nBrowseOption parameter of SQLRTSetBrowseOption. 5 The SQL Server browse combo box and list box controls show all available local SQL Servers and SQL Server aliases. This is the return value if SQL_BROWSE_LOCAL | SQL_BROWSE_ALIAS or 5 is passed for the nBrowseOption parameter of SQLRTSetBrowseOption. 6 The SQL Server browse combo box and list box controls show all available remote SQL Servers and SQL Server aliases. This is the return value if SQL_BROWSE_REMOTE | SQL_BROWSE_ALIAS or 6 is passed for the nBrowseOption parameter of SQLRTSetBrowseOption. 7 The SQL Server browse combo box and list box controls show all available SQL Servers (local servers, remote servers , and server aliases). This is the return value if SQL_BROWSE_LOCAL | SQL_BROWSE_REMOTE | SQL_BROWSE_ALIAS or 7 is passed for the nBrowseOption parameter of SQLRTSetBrowseOption.

SQLRTGetComponentScriptError
1402 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTGetComponentScriptError

Project: This information applies to InstallScript projects.

The SQLRTGetComponentScriptError2 function supersedes the SQLRTGetComponentScriptError function. The SQLRTGetComponentScriptError function retrieves the last error while executing a SQL script that is associated with the component.

Note: The SQLRTGetComponentScriptError function uses SQLRT.dll; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetComponentScriptError( szComponent, szMessage, nvErrorType, nvErrorLine );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1403

Appendix E: Built-In Functions (S-T) SQLRTGetComponentScriptError2

Parameters
Table E-203: SQLRTGetComponentScriptError Parameters Parameter szComponent szMessage nvErrorType Description Specifies the name of the component that is associated with the script. Specifies the error message that the database server returned. Specifies the type of error. Valid types are:

nvErrorLine

SQL_ERROR_SCRIPT_UNABLE_OPEN_FILEFailed to open the script file. SQL_ERROR_SCRIPT_CONNECTION_NOT_OPENThe specified connection is not opened. SQL_ERROR_GET_SCHEMA_VERSIONError while attempting to get the schema version from the target database. SQL_ERROR_SET_SCHEMA_VERSIONError while attempting to set the schema version to the target database. SQL_ERROR_SCRIPT_COMMAND_ERRORFailed to execute a SQL batch.

Specifies the line number of the error.

Return Values
Table E-204: SQLRTGetComponentScriptError Return Values Return Value TRUE FALSE Description One or more errors occurred. No errors occurred.

SQLRTGetComponentScriptError2
Project: This information applies to InstallScript projects.

The SQLRTGetComponentScriptError2 function retrieves the last error while executing a SQL script that is associated with the component. This function takes several parameters (szScriptName, szTechnology, szServer, and szDB) that the SQLRTGetComponentScriptError function does not.

Note: The SQLRTGetComponentScriptError function uses SQLRT.dll; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

1404

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTGetComponentScriptError2

Syntax
SQLRTGetComponentScriptError2( szComponent, szMessage, nvErrorType, nvErrorLine, szScriptName, szTechnology, szServer, szDB );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1405

Appendix E: Built-In Functions (S-T) SQLRTGetConnectionAuthentication

Parameters
Table E-205: SQLRTGetComponentScriptError2 Parameters Parameter szComponent szMessage nvErrorType Description Specifies the name of the component that is associated with the script. Specifies the error message that the database server returned. Specifies the type of error. Valid types are:

nvErrorLine szScriptName szTechnology

SQL_ERROR_SCRIPT_UNABLE_OPEN_FILEFailed to open the script file. SQL_ERROR_SCRIPT_CONNECTION_NOT_OPENThe specified connection is not opened. SQL_ERROR_GET_SCHEMA_VERSIONError while attempting to get the schema version from the target database. SQL_ERROR_SET_SCHEMA_VERSIONError while attempting to set the schema version to the target database. SQL_ERROR_SCRIPT_COMMAND_ERRORFailed to execute a SQL batch.

Specifies the line number of the error. Specifies the name of the script. Specifies the name of the database server product: Microsoft SQL Server, Oracle, or MySQL. Specifies the name of the target database server. Specifies the name of the target database catalog.

szServer szDB

Return Values
Table E-206: SQLRTGetComponentScriptError Return Values Return Value TRUE FALSE Description One or more errors occurred. No errors occurred.

SQLRTGetConnectionAuthentication
Project: This information applies to the following project types:

InstallScript

1406

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTGetConnectionInfo

InstallScript MSI

The SQLRTGetConnectionAuthentication function gets the default SQL Server connection authentication type.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetConnectionAuthentication( szConnection );

Parameters
Table E-207: SQLRTGetConnectionAuthentication Parameters Parameter szConnection Description Specifies the SQL Server connection.

Return Values
Table E-208: SQLRTGetConnectionAuthentication Return Values Return Value TRUE FALSE Description Perform Windows authentication. Perform SQL authentication.

SQLRTGetConnectionInfo
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLRTGetConnectionInfo function retrieves strings containing the connection information (the default server, database, default user name, and default password).

Note: The SQLRTGetConnectionInfo function uses SQLRT.dll in InstallScript projects and ISSQLSRV.dll in InstallScript MSI projects; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1407

Appendix E: Built-In Functions (S-T) SQLRTGetConnections

Syntax
SQLRTGetConnectionInfo( szConnection, szServer, szDB, szUser, szPassword );

Parameters
Table E-209: SQLRTGetConnectionInfo Parameters Parameter szConnection szServer szDB szUser szPassword Description Specifies the SQL Server connection Specifies the SQL Server. Specifies the SQL Server database. Specifies the SQL Server login information. Specifies the password associated with a user account.

Return Values
Table E-210: SQLRTGetConnectionInfo Return Values Return Value >=ISERR_SUCCESS <ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED (-10) Description This function was able to establish a connection. This function failed to establish a connection.
SQLRT.dll is not loaded.

SQLRTGetConnections
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLRTGetConnections function retrieves a string list of connections that are present in the settings file.

Note: The SQLRTGetConnections function uses SQLRT.dll in InstallScript projects and ISSQLSRV.dll in InstallScript MSI projects; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetConnections( );
1408 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTGetDatabases

Parameters
SQLRTGetConnections takes no parameters.

Return Values
Table E-211: SQLRTGetConnections Return Values Return Value listConnections; Description Returns a list of connection names.

SQLRTGetDatabases
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLRTGetDatabases function returns a list of database catalogs that are available on the specified database server.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetDatabases( szConnection, szServer, bTrust, szUserName, szPassword );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1409

Appendix E: Built-In Functions (S-T) SQLRTGetErrorMessage

Parameters
Table E-212: SQLRTGetDatabases Parameters Parameter szConnection Description Specifies the name of the connection that you created in the SQL Scripts view. Specifies the SQL Server. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead. szUserName szPassword Specifies the SQL Server login information. Specifies the password associated with a user account.

szServer bTrust

Return Values
Returns a list of the database catalogs that are available on the target database server.

SQLRTGetErrorMessage
Project: This information applies to InstallScript projects.

The SQLRTGetErrorMessage function returns the descriptive message of the last error encountered by the SQL run time when a connection is being opened.

Note: SQLRTGetErrorMessage calls SQLRTGetLastError2, which uses SQLRT.dll and settings from the SQL settings file; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL RunTime Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetErrorMessage( svMessage );

1410

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTGetLastError

Parameters
Table E-213: SQLRTGetErrorMessage Parameters Parameter svMessage Description Specifies the SQL error message.

Return Values
Table E-214: SQLRTGetErrorMessage Return Values Return Value ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED Description The function was successfully executed.
SQLRT.dll is not loaded.

SQLRTGetLastError
Project: This information applies to InstallScript projects.

The SQLRTGetLastError2 function supersedes the SQLRTGetLastError function. The SQLRTGetLastError function returns the text of the last error encountered by the SQL run time. SQLRTGetLastError also loads the proper SQL error message.

Note: The SQLRTGetLastError function uses SQLRT.dll and settings from the SQL settings file; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetLastError( szError );

Parameters
Table E-215: SQLRTGetLastError Parameters Parameter szError Description Specifies the SQL error.

Return Values
None

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1411

Appendix E: Built-In Functions (S-T) SQLRTGetLastError2

SQLRTGetLastError2
Project: This information applies to InstallScript projects.

The SQLRTGetLastError2 function returns detailed information about the last error encountered by the SQL run time. SQLRTGetLastError2 also loads the proper SQL error message.

Note: The SQLRTGetLastError2 function uses SQLRT.dll and settings from the SQL settings file; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetLastError2( nvErrorCode, svMessage, svTechnology, svConnection, svServer, svDBCatalog );

Parameters
Table E-216: SQLRTGetLastError2 Parameters Parameter nvErrorCode svMessage svTechnology Description Specifies the SQL error code. Specifies the SQL error message. Specifies the type of server (such as Microsoft SQL Server or Oracle) that was used. Specifies the SQL error code. Specifies the name of the SQL database server. Specifies the name of the SQL database catalog.

svConnection svServer svDBCatalog

Return Values
None

SQLRTGetScriptErrorMessage
Project: This information applies to InstallScript projects.

The SQLRTGetScriptErrorMessage function returns the descriptive message of the last error encountered by the SQL run time when a SQL script is executing.

1412

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTGetServers

Note: SQLRTGetScriptErrorMessage calls SQLRTGetComponentScriptError2, which uses SQLRT.dll and settings from the SQL settings file; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetScriptErrorMessage( svMessage );

Parameters
Table E-217: SQLRTGetScriptErrorMessage Parameters Parameter svMessage Description Specifies the SQL error message.

Return Values
Table E-218: SQLRTGetScriptErrorMessage Return Values Return Value ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED Description The function was successfully executed.
SQLRT.dll is not loaded.

SQLRTGetServers
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLRTGetServers function returns a list of database servers on the network for all database technologies included in the installation. When bFilter is TRUE, it returns only local database servers.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetServers( bFilter );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1413

Appendix E: Built-In Functions (S-T) SQLRTGetServers2

Parameters
Table E-219: SQLRTGetServers Parameters Parameter bFilter Description Specifies whether the list of database servers that is returned includes only local database servers:

TRUEReturn only local database servers. FALSEReturn all database servers.

Return Values
Returns a list of the database servers available on the network for all database technologies included in the installation.

SQLRTGetServers2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLRTGetServers2 function returns a list of database servers for the database technologies that are specified for a connection. When szConnection is empty, this function behaves as SQLRTGetServers.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTGetServers2( szConnection, bFilter );

1414

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTInitialize

Parameters
Table E-220: SQLRTGetServers2 Parameters Parameter szConnection Description Specifies a connection. If this parameter is empty, the function returns a list of database servers on the network for all database technologies included in the installation. Specifies whether the list of database servers that is returned includes only local database servers:

bFilter

TRUEReturn only local database servers. FALSEReturn all database servers.

Return Values
Returns a list of the database servers available on the network for database technologies specified for a connection.

SQLRTInitialize
Project: This information applies to InstallScript projects.

The SQLRTInitialize2 function supersedes the SQLRTInitialize function. If the SQLRTInitialize function is used, it must be the first function called in SQLRT. SQLRTInitialize loads the SQLRT.dll and initializes it using the settings file.

Syntax
SQLRTInitialize( szSettingsFile );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1415

Appendix E: Built-In Functions (S-T) SQLRTInitialize2

Parameters
Table E-221: SQLRTInitialize Parameters Parameter szSettingsFile Description Specifies the path to the SQLRT.ini file. The following path should be specified for this parameter:
SUPPORTDIR ^ "SQLRT.ini"

The SQLRT.ini file should not be modified; otherwise, unexpected behavior may occur at run time. InstallShield creates this file based on SQL settings that are entered in the SQL Scripts view.

Return Values
None

SQLRTInitialize2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLRTInitialize2 must be the first function called in the SQL run time. SQLRTInitialize2 loads the SQLRT.dll file for InstallScript projects and the ISSQLSRV.dll file for InstallScript MSI projects, and it uses the settings file to initialize the .dll file.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTInitialize2 ();

Parameters
SQLRTInitialize2 takes no parameters.

Return Values
None

1416

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTPutConnectionAuthentication

SQLRTPutConnectionAuthentication
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLRTPutConnectionAuthentication function sets the default SQL Server connection authentication type.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTPutConnectionAuthentication( szConnection, bWinLogin );

Parameters
Table E-222: SQLRTPutConnectionAuthentication Parameters Parameter szConnection Description Specifies the name of the connection that you created in the SQL Scripts view. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead.

bWinLogin

Return Values
None

SQLRTPutConnectionInfo
Project: This information applies to the following project types:

InstallScript

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1417

Appendix E: Built-In Functions (S-T) SQLRTPutConnectionInfo2

InstallScript MSI

The SQLRTPutConnectionInfo2 function supersedes the SQLRTPutConnectionInfo function. The SQLRTPutConnectionInfo function sets the connection information (the default server, default user name, and default password). This is useful in situations when you need to recall what an end user previously entered, like use of the Back button.

Note: The SQLRTPutConnectionInfo function uses SQLRT.dll in InstallScript projects and ISSQLSRV.dll in InstallScript MSI projects; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTPutConnectionInfo( szConnection, szServer, szUser, szPassword );

Parameters
Table E-223: SQLRTPutConnectionInfo Parameters Parameter szConnection szServer szUser szPassword Description Specifies the SQL Server connection. Specifies the SQL Server. Specifies the SQL Server login information. Specifies the password associated with a user account.

Return Values
Table E-224: SQLRTPutConnectionInfo Return Values Return Value >=ISERR_SUCCESS <ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED (-10) Description This function was able to establish a connection. This function failed to establish a connection.
SQLRT.dll is not loaded.

SQLRTPutConnectionInfo2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

1418

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTServerValidate

The SQLRTPutConnectionInfo2 function sets the connection information (the default server, default database catalog, default user name, and default password). This is useful in situations when you need to recall what an end user previously entered, like use of the Back button.

Note: The SQLRTPutConnectionInfo2 function uses SQLRT.dll for InstallScript projects and ISSQLSRV.dll for InstallScript MSI projects; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTPutConnectionInfo2( szConnection, szServer, svDBCatalog, szUser, szPassword );

Parameters
Table E-225: SQLRTPutConnectionInfo2 Parameters Parameter szConnection szServer svDBCatalog szUser szPassword Description Specifies the SQL Server connection. Specifies the SQL Server. Specifies the name of the SQL database catalog. Specifies the SQL Server login information. Specifies the password associated with a user account.

Return Values
Table E-226: SQLRTPutConnectionInfo2 Return Values Return Value >=ISERR_SUCCESS <ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED (-10) Description This function was able to establish a connection. This function failed to establish a connection.
SQLRT.dll is not loaded.

SQLRTServerValidate
Project: This information applies to InstallScript MSI projects.

The SQLRTServerValidate function tests connections specified in the installation.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1419

Appendix E: Built-In Functions (S-T) SQLRTServerValidate

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTServerValidate\( hInstall );

Parameters
Table E-227: SQLRTServerValidate Parameters Parameter hInstall Description Specifies the handle to the installation. When IS_SQLSERVER_CONNECTIONS_TO_VALIDATE is specified, only the connections that are specified as the value of that Windows Installer property are tested.

Return Values
Table E-228: SQLRTServerValidate Return Values Return Value =ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED Description This function was able to establish a connection.
ISSQLSRV.dll is not loaded.

Additional Information
The result is used to set the value of the IS_SQLSERVER_STATUS property. Possible values are listed in the following table.
Table E-229: IS_SQLSERVER_STATUS Property Values Return Value 0 1 2 Description The function was able to establish one or more connections. The function failed to establish a connection. The function was able to establish a connection, but it failed to retrieve the product version from the target database server. The function was able to establish a connection, but the version requirement was not met. The function was able to establish a connection, but MSDE or the Express version was not allowed. The function was able to establish a connection, but it failed to retrieve the schema version from the target database catalog.

3 4 5

1420

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTSetBrowseOption

Table E-229: IS_SQLSERVER_STATUS Property Values (cont.) Return Value 6 Description The function was able to establish a connection, but it failed to set the schema version to the target database catalog. The function could not find the specified ODBC driver. The function was able to establish a connection to the default database catalog, but it failed to create the target database catalog (when Create Catalog If Absent check box in the SQL Scripts view is selected). The function was able to establish a connection to the default database catalog, but it failed to connect to the target database catalog. The function could not find a valid record in ISSQLDBMetaData table.

7 8

10

SQLRTSetBrowseOption
Project: This information applies to InstallScript projects.

The SQLRTSetBrowseOption function lets you specify whether the SQL Server browse combo box and list box controls show local servers, remote servers, server aliases, or a combination of these types.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTSetBrowseOption( nBrowseOption );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1421

Appendix E: Built-In Functions (S-T) SQLRTTestConnection

Parameters
Table E-230: SQLRTSetBrowseOption Parameters Parameter nBrowseOption Description Pass one or more of the following predefined constants in this parameter:

SQL_BROWSE_ALL (0)Show all of the available SQL Servers. Specifying this constant has the same effect as selecting the SQL_BROWSE_LOCAL, SQL_BROWSE_REMOTE, and SQL_BROWSE_ALIAS constants. SQL_BROWSE_LOCAL (1)Show local SQL Servers. SQL_BROWSE_REMOTE (2)Show remote SQL Servers. SQL_BROWSE_ALIAS (4)Show SQL Server aliases.

You can specify multiple browse options by combining constants with the bitwise OR operator (|).

Return Values
None

SQLRTTestConnection
Project: This information applies to InstallScript MSI projects.

The SQLRTTestConnection2 function supersedes the SQLRTTestConnection function. The SQLRTTestConnection function tests all of the connections specified in the installation using the specified credential.

Note: If you want to call any built-in SQL-related function before the OnSQLServerInitialize event handler is called in an InstallScript project or the OnSQLLogin event handler is called in an InstallScript MSI project, call the SQLRTInitialize2 function first. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTTestConnection( szServer, szDB, szUserName, szPassword, bTrust );

1422

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTTestConnection

Parameters
Table E-231: SQLRTTestConnection Parameters Parameter szServer szDB szUserName szPassword bTrust Description Specifies the SQL Server. Specifies the catalog. Specifies the SQL Server login information. Specifies the password associated with a user account. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead.

Return Values
Table E-232: SQLRTTestConnection Return Values Return Value =ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED Description This function was able to establish a connection.
ISSQLSRV.dll is not loaded.

Additional Information
The result is used to set the value of the IS_SQLSERVER_STATUS property. Possible values are listed in the following table.
Table E-233: IS_SQLSERVER_STATUS Property Values Return Value 0 1 2 Description The function was able to establish one or more connections. The function failed to establish a connection. The function was able to establish a connection, but it failed to retrieve the product version from the target database server. The function was able to establish a connection, but the version requirement was not met. The function was able to establish a connection, but MSDE or the Express version was not allowed.

3 4

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1423

Appendix E: Built-In Functions (S-T) SQLRTTestConnection2

Table E-233: IS_SQLSERVER_STATUS Property Values (cont.) Return Value 5 Description The function was able to establish a connection, but it failed to retrieve the schema version from the target database catalog. The function was able to establish a connection, but it failed to set the schema version to the target database catalog. The function could not find the specified ODBC driver. The function was able to establish a connection to the default database catalog, but it failed to create the target database catalog (when Create Catalog If Absent check box in the SQL Scripts view is selected). The function was able to establish a connection to the default database catalog, but it failed to connect to the target database catalog. The function could not find a valid record in ISSQLDBMetaData table.

7 8

10

SQLRTTestConnection2
Project: This information applies to InstallScript MSI projects.

The SQLRTTestConnection2 function establishes a connection.

Note: The SQLRTTestConnection2 function uses ISSQLSRV.dll; therefore, it can be called only after SQLRTInitialize2 has already been called. To learn more, see Using the SQL Run-Time Functions in InstallScript and InstallScript MSI Projects.

Syntax
SQLRTTestConnection2( szConnection, szServer, szDB, szUserName, szPassword, bTrust );

1424

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLRTTestConnection2

Parameters
Table E-234: SQLRTTestConnection2 Parameters Parameter szConnection szServer svDB szUser szPassword bTrust Description Specifies the SQL Server connection. Specifies the SQL Server. Specifies the catalog. Specifies the SQL Server login information. Specifies the password associated with a user account. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead.

Return Values
Table E-235: SQLRTTestConnection2 Return Values Return Value =ISERR_SUCCESS SQL_ERROR_NOT_INITIALIZED Description This function was able to establish a connection.
ISSQLSRV.dll is not loaded.

Additional Information
The result is used to set the value of the IS_SQLSERVER_STATUS property. Possible values are listed in the following table.
Table E-236: IS_SQLSERVER_STATUS Property Values Return Value 0 1 2 Description The function was able to establish one or more connections. The function failed to establish a connection. The function was able to establish a connection, but it failed to retrieve the product version from the target database server. The function was able to establish a connection, but the version requirement was not met. The function was able to establish a connection, but MSDE or the Express version was not allowed.

3 4

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1425

Appendix E: Built-In Functions (S-T) SQLServerLogin

Table E-236: IS_SQLSERVER_STATUS Property Values (cont.) Return Value 5 Description The function was able to establish a connection, but it failed to retrieve the schema version from the target database catalog. The function was able to establish a connection, but it failed to set the schema version to the target database catalog. The function could not find the specified ODBC driver. The function was able to establish a connection to the default database catalog, but it failed to create the target database catalog (when Create Catalog If Absent check box in the SQL Scripts view is selected). The function was able to establish a connection to the default database catalog, but it failed to connect to the target database catalog. The function could not find a valid record in ISSQLDBMetaData table.

7 8

10

SQLServerLogin
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLServerLogin function creates a dialog that is used by the script to specify SQL login credentials. These credentials include the login ID and password. This function is in the SQLRT.obl file for InstallScript projects, and in the SQLCONV.obl file for InstallScript MSI projects. If you are using the SQL Scripts view in InstallShield, the appropriate file is automatically added to your linker settings. However, if you are not using this view, add the appropriate file to your linker settings: On the Build menu, click Settings, and then add it to the Libraries (.obl) box.

Syntax
SQLServerLogin( szMsg, svUser, svPassword );

1426

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLServerSelect

Parameters
Table E-237: SQLServerLogin Parameters Parameter szMsg Description Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies the default string to display in the Login ID edit box. Once the dialog function returns, this parameter contains the Login ID that the end user entered in the edit box. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials. Specifies the default string to display in the Password edit field. Once the dialog function returns, this parameter contains the password that the end user entered in the edit field. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials.

svUser

svPassword

Return Vaues
Table E-238: SQLServerLogin Return Values Return Value NEXT BACK < ISERR_SUCCESS Description The end user selected the Next button. The end user selected the Back button. The dialog could not be displayed.

SQLServerSelect
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLServerSelect function creates a dialog that lets the end user select a database server. This function is in the SQLRT.obl file for InstallScript projects, and in the SQLCONV.obl file for InstallScript MSI projects. If you are using the SQL Scripts view in InstallShield, the appropriate file is automatically added to your linker settings. However, if you are not using this view, add the appropriate file to your linker settings: On the Build menu, click Settings, and then add it to the Libraries (.obl) box.

Syntax
SQLServerSelect( szMsg, svServer );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1427

Appendix E: Built-In Functions (S-T) SQLServerSelectLogin

Parameters
Table E-239: SQLServerSelect Parameters Parameter szMsg Description Specifies the message to display in the dialog. To display the default instructions for this dialog, pass a null string () in this parameter. Specifies the default server to initially display in the Server combo box. Once the dialog function returns, this parameter contains the server name that the end user selected or entered in the Server combo box.

szServer

Return Vaues
Table E-240: SQLServerSelect Return Values Return Value NEXT BACK < ISERR_SUCCESS Description The end user selected the Next button. The end user selected the Back button. The dialog could not be displayed.

SQLServerSelectLogin
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLServerSelectLogin2 function supersedes the SQLServerSelectLogin function. The SQLServerSelectLogin function creates a dialog that is used by the default script. It allows the targeted end user to specify which SQL Server is to be used for the current connection, along with which login credential should be used. When the dialog is displayed, a combo box shows a list of SQL Servers accessed through DSNs. A Browse button is available to bring up a list of all SQL Servers available on the network or the end user can type a server name into the combo box. Also, the end user has the option to use Windows login credentials or enter a SQL Server login ID and password. This function is in the SQLRT.obl file for InstallScript projects, and in the SQLCONV.obl file for InstallScript MSI projects. If you are using the SQL Scripts view in InstallShield, the appropriate file is automatically added to your linker settings. However, if you are not using this view, add the appropriate file to your linker settings: On the Build menu, click Settings, and then add it to the Libraries (.obl) box.

Syntax
SQLServerSelectLogin (byref string svServer, byref string svUser, byref string svPassword, byref BOOL bvWindowsLogin );

1428

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLServerSelectLogin2

Parameters
Table E-241: SQLServerSelectLogin Parameters Parameter szServer Description Specifies the default server to initially display in the Server combo box. Once the dialog function returns, this parameter contains the server name the end user selected or entered in the Server combo box. This parameter supports alias names for SQL Server database connections. svUser Specifies the default string to display in the Login ID edit box. Once the dialog function returns, this parameter contains the Login ID that the end user entered in the edit box. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials. Specifies the default string to display in the Password edit field. Once the dialog function returns, this parameter contains the Password that the end user entered in the edit field. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead.

svPassword

bvWindowsLogin

Return Values
Table E-242: SQLServerSelectLogin Return Values Return Value NEXT BACK < ISERR_SUCCESS Description The end user selected the Next button. The end user selected the Back button. The dialog could not be displayed.

SQLServerSelectLogin2
Project: This information applies to the following project types:

InstallScript InstallScript MSI

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1429

Appendix E: Built-In Functions (S-T) SQLServerSelectLogin2

The SQLServerSelectLogin2 function creates a login dialog that is used by the default script. It lets the targeted end user specify which SQL Server should be used for the current connection, as well as which login credential should be used. The dialog displays a combo box that contains a list of SQL Servers accessed through DSNs. The end user can type a server name in the combo box or click the Browse button next to the Server Name combo box; clicking this button displays a list of all SQL Servers that are available on the network. The end user has the option to use Windows login credentials or enter a SQL Server login ID and password. When bShowCxnName is set to TRUE, the dialog shows the connection name that is associated with the connection information. In addition, when bShowDBCatalog is set to TRUE, the dialog allows the end user to specify which database catalog should be used for the current connection. The end user can type a catalog name in the edit box or click the Browse button next to the name of database catalog edit box. Clicking the Browse button displays a list of all database catalogs that are available on the specified database server.

Syntax
SQLServerSelectLogin2( szConnection, svServer, svUser, svPassword, bvWindowsLogin, svCatalog, bShowCxnName, bShowDBCatalog );

1430

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) SQLServerSelectLogin2

Parameters
Table E-243: SQLServerSelectLogin2 Parameters Parameter szConnection szServer Description Specifies the SQL Server connection. Specifies the default server to initially display in the Server combo box. Once the dialog function returns, this parameter contains the server name the end user selected or entered in the Server combo box. This parameter supports alias names for SQL Server database connections. svUser Specifies the default string to display in the Login ID edit box. Once the dialog function returns, this parameter contains the Login ID that the end user entered in the edit box. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials. Specifies the default string to display in the Password edit field. Once the dialog function returns, this parameter contains the Password that the end user entered in the edit field. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead. svCatalog bShowCxnName Specifies the name of the database catalog. Specifies whether the dialog should show the name of the connection that is associated with the connection information. Pass one of the following predefined constants in this parameter:

svPassword

bvWindowsLogin

bShowDBCatalog

TRUEShow the name of the connection. FALSEDo not show the name of the connection.

Specifies whether the end user can select which database catalog should to be used for the current connection. Pass one of the following predefined constants in this parameter:

TRUEAllow the end user to select which database catalog should to be used for the current connection. The end user can type a catalog name in the edit box or click the Browse button next to the name of database catalog edit box. Clicking this Browse button displays a list of all database catalogs that are available on the specified database server. FALSEDo not allow the end user to select which database catalog should to be used for the current connection.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1431

Appendix E: Built-In Functions (S-T) SQLServerSelectLoginEx

Return Values
Table E-244: SQLServerSelectLogin2 Return Values Return Value NEXT BACK < ISERR_SUCCESS Description The end user selected the Next button. The end user selected the Back button. The dialog could not be displayed.

SQLServerSelectLoginEx
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The SQLServerSelectLogin2 function supersedes the SQLServerSelectLoginEx function. The SQLServerSelectLoginEx function creates a login dialog that is used by the default script. It lets the targeted end user specify which SQL Server should be used for the current connection, as well as which login credential should be used. The dialog also shows the connection name that is associated with the connection information. The dialog displays a combo box that contains a list of SQL Servers accessed through DSNs. The end user can type a server name in the combo box or click the Browse button next to the Server Name combo box; clicking this button displays a list of all SQL Servers that are available on the network. The end user has the option to use Windows login credentials or enter a SQL Server login ID and password.

Syntax
SQLServerSelectLoginEx (byval string szConnection, byref string svServer, byref string svUser, byref string svPassword, byref BOOL bvWindowsLogin)

1432

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StatusUpdate

Parameters
Table E-245: SQLServerSelectLoginEx Parameters Parameter szConnection szServer Description Specifies the SQL Server connection. Specifies the default server to initially display in the Server combo box. Once the dialog function returns, this parameter contains the server name the end user selected or entered in the Server combo box. This parameter supports alias names for SQL Server database connections. svUser Specifies the default string to display in the Login ID edit box. Once the dialog function returns, this parameter contains the Login ID that the end user entered in the edit box. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials. Specifies the default string to display in the Password edit field. Once the dialog function returns, this parameter contains the Password that the end user entered in the edit field. This information is only pertinent if the end user selected to use SQL Login instead of Windows credentials. Specifies the initial state of the radio buttons specifying login using Windows credentials vs. SQL Server credentials. When this is TRUE, the password and login ID fields are disabled. When it is FALSE, indicating that SQL Server credentials are to be used, the password and login fields are enabled. Once the function returns, this parameter contains TRUE if the Windows credentials radio button was specified by the end user and FALSE if the SQL Server credentials radio was selected instead.

svPassword

bvWindowsLogin

Return Values
Table E-246: SQLServerSelectLoginEx Return Values Return Value NEXT BACK < ISERR_SUCCESS Description The end user selected the Next button. The end user selected the Back button. The dialog could not be displayed.

StatusUpdate
The StatusUpdate function enables or disables the link between file transfer operations and the progress indicator of the status bar. When bLink is ON, the link is enabled and nFinalPercent specifies a final percentage to be displayed at the end of the next file transfer. During that file transfer, the status bar is updated smoothly from its current value to the value specified by nFinalPercent. When bLink is OFF, the link is disabled and the progress indicator of the status bar is not updated automatically during subsequent file transfers.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1433

Appendix E: Built-In Functions (S-T) StatusUpdate

This function works by computing the total number of bytes to be transferred by any of the file transfer functions. It then computes how often it will increment the progress bar starting from its current location to the maximum value in nFinalPercent. The StatusUpdate function does not work with the functions VerUpdateFile and VerSearchAndUpdateFile. When calling those functions, you should disable the status bar or update it manually. To set the status bar to an initial percentage, call SetStatusWindow before calling StatusUpdate.

Tip: If the status bar is enabled during file transfer, call StatusUpdate before each call to CopyFile or XCopyFile). Before calling FeatureMoveData to transfer files, call StatusUpdate with the parameters ON and 100. This sets the status bar to update smoothly to 100% during the file transfer stage of the setup.

Syntax
StatusUpdate ( bLink, nFinalPercent );

1434

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StatusUpdate

Parameters
Table E-247: StatusUpdate Parameters Parameter bLink Description Specifies whether to enable or disable the link between file transfer operations and the progress indicator of the status bar. Pass one of the following predefined constants in this parameter:

ONSpecifies that the progress indicator of the status bar should be linked to file transfer operations. OFFSpecifies that link between file transfer operations and the progress indicator of the status bar should be disabled. The link remains disabled until it is reestablished by a subsequent call to StatusUpdate with bLink set to ON.

Note: The status bar can be updated manually by calling SetStatusWindow. nFinalPercent Specifies the final percentage value that the progress indicator of the status bar should reach at the end of the next file transfer operation if bLink is ON. If the value passed in nFinalPercent is less than the current value in the progress indicator of the status bar, the progress indicator will not change. When bLink is OFF, this parameter is ignored.

Return Values
Table E-248: StatusUpdate Return Values Return Value 0 <0 Description Indicates that the function was successful. Indicates that the function was not successful.

StatusUpdate Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the StatusUpdate function. * * This script copies all files from a source directory to a

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1435

Appendix E: Built-In Functions (S-T) StrAddLastSlash

* target directory. StatusUpdate is called to set the limit * of the progress bar and to regulate the progress indicator * as the files are copied. * * Note: Before running this script, create the directories * referenced by SOURCE_DIR and TARGET_DIR and create two * or more files in SOURCE_DIR. * \*--------------------------------------------------------------*/ #define SOURCE_DIR "C:\\ISExampl\\Source" #define TARGET_DIR "C:\\ISExampl\\Target"; // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StatusUpdate(HWND); function ExFn_StatusUpdate(hMSI) begin // Enable the progress bar. Enable(STATUS); // Set the limit of the progress bar to 99% completion. StatusUpdate (ON, 99); // Copy the files. if (XCopyFile (SOURCE_DIR ^ "*.*", TARGET_DIR ^ "*.*", COMP_NORMAL) < 0 ) then MessageBox ("An error occurred while copying files.",SEVERE); endif; // Display a message; do not change the progress bar. SetStatusWindow (-1, "File Copying completed at 99%."); Delay (3); // Set the progress bar to 100% and displays a message. SetStatusWindow (100, "StatusUpdate example completed, now exiting..."); Delay (3); end;

StrAddLastSlash
The StrAddLastSlash function adds a trailing backslash to a path specification if it does not already have one.

Syntax
StrAddLastSlash ( svPath );

1436

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrCompare

Parameters
Table E-249: StrAddLastSlash Parameters Parameter svPath Description Specifies a string whose value must be a path specification; it returns the path with a trailing backslash. Note that if the path includes a trailing backslash, it is returned unchanged.

Return Values
Table E-250: StrAddLastSlash Return Values Return Value >= ISERR_SUCCESS Description Indicates that the function successfully added the trailing backslash or that the path contains a trailing backslash.

StrCompare
The StrCompare function compares two strings. The comparison is not case-sensitive.

Syntax
StrCompare ( szStringA, szStringB );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1437

Appendix E: Built-In Functions (S-T) StrCompare

Parameters
Table E-251: StrCompare Parameters Parameter szStringA szStringB Description Specifies the first string to compare. Specifies the second string to compare.

Return Values
Table E-252: StrCompare Return Values Return Value <0 Description Indicates that the string in szStringA has a lower value than the string in szStringB. Indicates that the two strings are equal. Indicates that the string in szStringA has a greater value than the string in szStringB.

0 >0

Additional Information
The StrCompare function compares the strings by checking the first character in each string, the second character in each string, and so onuntil it finds an inequality or reaches the ends of the strings. The language driver for the language that you select determines which string is greater or if the strings are the same. If you do not use a language driver, Windows uses an internal function. With a double-byte character set (DBCS) version of Windows, this function can compare two DBCS strings.

StrCompare Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the StrCompare function. * * StrCompare is called to compare two strings. The result of * the comparison is displayed in a message box. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "StrCompare Example" #define MSG_TEXT "Please enter two strings to compare:" #define FIELD_A "String A:"
1438 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrConvertSizeUnit

#define FIELD_B

"String B:"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StrCompare(HWND); function ExFn_StrCompare(hMSI) STRING svStringA, svStringB; NUMBER nResult; begin // Get two strings from the user. SdShowDlgEdit2 (TITLE_TEXT, MSG_TEXT, FIELD_A, FIELD_B, svStringA, svStringB); // Compare the strings. nResult = StrCompare (svStringA, svStringB); // Display the result. if (nResult = 0) then MessageBox (svStringA + " and " + svStringB + " are equal.", INFORMATION); elseif (nResult < 0) then MessageBox (svStringB + " is greater than " + svStringA, INFORMATION); else MessageBox (svStringA + " is greater value than " + svStringB, INFORMATION); endif; end;

StrConvertSizeUnit
The StrConvertSizeUnit function returns the appropriate display string for the InstallScript size unit constant that is specified.

Syntax
StrConvertSizeUnit (byval string nUnit);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1439

Appendix E: Built-In Functions (S-T) StreamFileFromBinary

Parameters
Table E-253: StrConvertSizeUnit Parameters Parameter nUnit Description Specify the unit constant that you want to be converted to a UI string. The following constants are supported:

BYTES KBYTES MBYTES GBYTES TBYTES

Return Values
Table E-254: StrConvertSizeUnit Return Values Return Value bytes KB MB GB TB Null ("") Description The function converted the BYTES constant. The function converted the KBYTES constant. The function converted the MBYTES constant. The function converted the GBYTES constant. The function converted the TBYTES constant. The function failed to convert nUnit.

StreamFileFromBinary
The StreamFileFromBinary function streams a binary key with a file.

Syntax
StreamFileFromBinary ( hInstall(HWND), svObjectBinaryKey, szFileName );

1440

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrFind

Parameters
Table E-255: StreamFileFromBinary Parameters Parameter hInstall (HWND) Description Provides a handle to the currently running application. Indicates the key to be streamed out of the binary table. Indicates the full path to the extracted file.

svObjectBinaryKey

szFileName

Return Values
Table E-256: StreamFileFromBinary Return Values Return Value 0 Description The function successfully streamed the binary key with the file. The function failed to stream the binary key with the file.

-1

StrFind
The StrFind function determines whether the string passed in the parameter szFindMe is found within the string passed in the parameter szString. If szFindMe is found in szString, StrFind returns the position within szString of the first character of szFindMe. (Note that the position of the first character in szString is zero.) This function is not case-sensitive and can be used only to find the first occurrence of szFindMe in szString. StrFind calls the following:
StrFindEx(szString, szFindMe, 0);

For more information about parameters and return values for StrFind, see StrFindEx.

StrFind Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the StrFind function.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1441

Appendix E: Built-In Functions (S-T) StrFindEx

* * StrFind is called to search for a substring within a string. * If successful, StrFind returns the location of the substring. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "StrFind Example"; // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StrFind(HWND); function ExFn_StrFind(hMSI) STRING szString, szFindMe, szTitle, szMsg; NUMBER nLocation; begin // Set up parameters for call to StrFind. szString = "This is a sample string to be searched."; szFindMe = "Sample String"; // Find the substring specified by szFindMe. nLocation = StrFind (szString, szFindMe); // Display the location of the text if it was found. if (nLocation < 0) then MessageBox (szFindMe + " not found in " + szString + ".", WARNING); else szMsg = "'%s' starts at byte %d of\n'%s'"; SprintfBox (INFORMATION, szTitle, szMsg, szFindMe, nLocation, szString); endif; end;

StrFindEx
The StrFindEx function determines whether the string passed in the parameter szFindMe is found within the string passed in the parameter szString; the function begins its search at the location specified by nStart. If szFindMe is found, StrFind returns the position within szString of the first character of szFindMe. This function is not case-sensitive and can be used only to find the first occurrence of szFindMe in szString.

Syntax
StrFindEx ( szString, szFindMe, nStart );

1442

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrGetTokens

Parameters
Table E-257: StrFindEx Parameters Parameter szString szFindMe nStart Description Specifies the string to search. Specifies the string to find in szString. Specifies an offset into szString that identifies the character at which to begin the search for szFindMe. Note that the position of the first character in szString is 0 (zero).

Return Values
Table E-258: StrFindEx Return Values Return Value X Description If szString contains szFindMe, X is the numeric position of the first character in szFindMe. The first character in szString is in position 0 (zero). Indicates szString does not contain szFindMe.

<0

Additional Information
In the example below, StrFind will return the value 19.
nStartPos = StrFind("Scripting means having fun","ing",7);

If you need only a TRUE or FALSE return value indicating whether one string contains another string, (that is, if the location if the substring is unimportant), use the string find operator (%) as shown below:
if (szString % szFindMe) then ...

You can use the string find operator (%) only in Boolean expressions that are resolved in if statements. You cannot use it in repeat statements or while statements.

StrGetTokens
The StrGetTokens function extracts substrings (tokens) from the string specified by szString and places them into the list specified by listID. The substrings in szString must be delimitedseparated from one anotherby one or more of the characters specified by szDelimiterSet. For example, if you call StrGetTokens with the string "One;Two;Three;Four;Five" as the second parameter and ";" as the third parameter, listID will be returned with five strings: "One", "Two", "Three", "Four", and "Five". Use the list functions, such as ListGetFirstString and ListGetNextString to access each token in the list.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1443

Appendix E: Built-In Functions (S-T) StrGetTokens

Note: 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.

Syntax
StrGetTokens ( listID, szString, szDelimiterSet );

Parameters
Table E-259: StrGetTokens Parameters Parameter listID Description Returns a list of tokens. The string list identified by listID must already have been initialized by a call to ListCreate. Specifies the string to be parsed. Specifies a set of one or more delimiters. Each delimiter is one character (1 byte). If you pass a null string ("") in this parameter, the function searches for null characters as the delimiters. This is useful if you are using the GetProfString function.

szString szDelimiterSet

Note: When a space is specified as the delimiter, StrGetTokens treats consecutive spaces as a single delimiter.

Return Values
Table E-260: StrGetTokens Return Values Return Value 0 Description Indicates that the function successfully separated the string and inserted the tokens into the specified list. Indicates that the function was unable to separate the string and insert the tokens into the list.

<0

StrGetTokens Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script
1444 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrGetTokens

* * Demonstrates the StrGetTokens function. * * First, the value of a key is retrieved from an initialization * file. The value returned is a search path. Then * StrGetTokens is called to build a list of the paths found in * the search path. Finally, the paths are displayed. * * In order for this script to run correctly, you must create * an initialization (text) file and add the following lines to * it: * * [Test Section] * searchpath=C:\Windows;C:\Windows\System;C:\Windows\Command * * Then set the constant EXAMPLE_INI to the fully qualified name * of that file. * \*--------------------------------------------------------------*/ #define FILE_NAME "C:\\ISExampl.ini" #define SECTION_NAME "Test Section" #define KEY_NAME "searchpath" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StrGetTokens(HWND); function ExFn_StrGetTokens(hMSI) LIST listID; STRING svSearchPath; STRING szTitle, szMsg; begin // Get the value of the specified key from the specified section // of the initialization file. if GetProfString (FILE_NAME, SECTION_NAME, KEY_NAME, svSearchPath) < 0 then // Report the error. MessageBox ("Unable to retrieve key value from "+ FILE_NAME + ".", INFORMATION); else // Create a list to hold the paths that make up the search path // that was returned by GetProfString. listID = ListCreate (STRINGLIST); // Get each path from the search path into the list. if (StrGetTokens (listID, svSearchPath, ";") > 0) then // Report the error. MessageBox ("StrGetTokens failed.", SEVERE); else // Display the individual paths from the list. Sprintf (szMsg, "Paths found in %s %s", SECTION_NAME,KEY_NAME); SdShowInfoList ("Search Path", szMsg, listID); endif; endif; // Remove the list from memory. ListDestroy (listID); end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1445

Appendix E: Built-In Functions (S-T) StrLength

StrLength
Use the StrLength function to find the number of bytes in a string. To determine the number of characters in a string, use StrLengthChars.

Syntax
StrLength ( szString );

Parameters
Table E-261: StrLength Parameters Parameter szString Description Specifies the string whose size is to be determined.

Return Values
Table E-262: StrLength Return Values Return Value X <0 Description Where X is the number of bytes in the string. Indicates that the function was unable to determine the number of bytes in the string.

StrLength Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the StrLength function. * * StrLength is called to retrieve the length of the string * entered by the user. The length is displayed in a message * box. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "StrLength Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h"

1446

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrLengthChars

export prototype ExFn_StrLength(HWND); function ExFn_StrLength(hMSI) STRING svString, szTitle, szMsg; NUMBER nLength; begin // Get a line of text from the user. AskText ("Enter a line of text. ", "", svString); // Get the length of the string in bytes. nLength = StrLength (svString); if (nLength < 0) then MessageBox ("StrLength failed.", SEVERE); else // Display the string length. szMsg = "String '%s' is %d bytes long."; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svString, nLength); endif; end;

StrLengthChars
Use the StrLengthChars function to find the number of characters in a string. To determine the number of bytes in a string, use StrLength.

Syntax
StrLengthChars ( szString );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1447

Appendix E: Built-In Functions (S-T) StrLengthChars

Parameters
Table E-263: StrLengthChars Parameters Parameter szString Description Specifies the string whose size is to be determined.

Return Values
Table E-264: StrLengthChars Return Values Return Value X <0 Description Where X is the number of characters in the string. Indicates that the function was unable to determine the number of characters in the string.

StrLengthChars Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the StrLengthChars function. * * StrLengthChars is called to retrieve the number of characters * in the string entered by the user. The number of characters * in that string is then displayed in a message box. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "StrLengthChars Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StrLengthChars(HWND); function ExFn_StrLengthChars(hMSI) STRING svString, szTitle, szMsg; NUMBER nLength; begin // Get a line of text from the user. AskText ("Enter a line of text. ", "", svString); // Get the number of characters in the string. nLength = StrLengthChars (svString); if (nLength < 0) then MessageBox ("StrLengthChars failed.", SEVERE); else // Display the number of characters in the string.
1448 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrPutTokens

szMsg = "String '%s' is %d characters long."; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svString, nLength); endif; end;

StrPutTokens
The StrPutTokens function extracts list items from the string list specified by listID and places them into the string specified by svString. The substrings placed into svString from listID are separated by szSeparator in the resulting string. Note that instances of szSeparator are not placed at the beginning and end of the string, only between list elements added to the string. For example, if you call StrPutTokens with the list containing the items "One", "Two", "Three", "Four", and "Five" as the first parameter and ";" as the third parameter, svString will contain "One;Two;Three;Four;Five" after the function is called. The value of bNull determines whether null characters are used to separate the substrings in the resulting string.

Syntax
StrPutTokens( listID, svString, szSeparator, bNull );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1449

Appendix E: Built-In Functions (S-T) StrRemoveLastSlash

Parameters
Table E-265: StrPutTokens Parameters Parameter listID Description Specifies the string list to be processed. The string list identified by listID must already have been initialized by a call to ListCreate. Note that this function does not work with number lists. Specifies the resulting string. Specifies a string to be used to separate each list item in the resulting string. Note that unlike the StrGetTokens function, passing a null string in this parameter will not result in a null separated string; it will result in the substrings being placed one after the other with no separators. Set bNULL to TRUE to create a null separated string. If bNull is set to TRUE, null characters will be used to separate the substrings in the resulting string, and szSeparator will be ignored. Note that the resulting string will be double null terminated in this case. If bNull is set to FALSE, the substrings in the resulting string will be separated by szSeparator.

svString szSeparator

bNull

Return Values
Table E-266: StrPutTokens Return Values Return Value 0 Description Indicates that the function successfully created the string from the specified string list. Indicates that the function was unable to create the specified string from the specified string list.

<0

StrRemoveLastSlash
The StrRemoveLastSlash function removes the trailing backslash from a path specification. Because its purpose is to produce a valid path, StrRemoveLastSlash does not remove the backslash from a root directory specification, such as A:\ or C:\.

Syntax
StrRemoveLastSlash ( svPath );

1450

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrRemoveLastSlash

Parameters
Table E-267: StrRemoveLastSlash Parameters Parameter svPath Description Specifies a string whose value must be a path specification; returns the path without the trailing backslash. Note that if the path does not include a trailing backslash, it is returned unchanged.

Return Values
Table E-268: StrRemoveLastSlash Return Values Return Value 0 Description Indicates that the function successfully removed the trailing backslash or that the path does not contain a trailing backslash. Indicates that the function was unable to remove the trailing backslash.

<0

Additional Information
StrRemoveLastSlash provides a convenient way to remove the trailing backslash from a path returned by AskPath or ParsePath. Because its purpose is to produce a valid path, StrRemoveLastSlash does not remove the backslash from a root directory specification, such as A:\ or C:\; doing so would turn a valid path into a drive specification. If you need to remove the trailing backslash from a path in all cases, use the following script segment as a guide.
AskPath("", "", svPath); if (StrLength(svPath) = 3) && (svPath[1] = ":") && (svPath[2] = "\\") then svTempString = svPath; StrSub(svPath,svTempString,0,2); else StrRemoveLastSlash(svPath); endif;

StrRemoveLastSlash Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1451

Appendix E: Built-In Functions (S-T) StrReplace

* * Demonstrates the StrRemoveLastSlash function. * * The AskPath dialog is displayed, prompting the user to * specify a path. StrRemoveLastSlash is then called to remove * the trailing backslash from the path returned by AskPath. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "StrRemoveLastSlash Example"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StrRemoveLastSlash(HWND); function ExFn_StrRemoveLastSlash(hMSI) STRING szDefaultPath, svString, szMsg, szTitle; begin // Get a path from the user. AskPath returns the // path with a trailing backslash. AskPath ("Specify a path:", INSTALLDIR, svString); // Remove the last slash from the path. if (StrRemoveLastSlash (svString) < 0) then // Report an error. MessageBox ("StrRemoveLastSlash failed.", SEVERE); else // Display the folder name after the last backslash // has been removed. MessageBox ("Specified path: " + svString, INFORMATION); endif; end;

StrReplace
The StrReplace function searches svResult, beginning at the location specified by nStart, and replaces all found instances of szFind with szReplace.

Syntax
StrReplace ( svResult, szFind, szReplace, nStart );

1452

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrSub

Parameters
Table E-269: StrReplace Parameters Parameter svResult Description Specifies the string to search. Returns the modified string. Specifies the string to find in svResult. Specifies the string with which to replace found instances of szFind. Specifies an offset into svResult that identifies the character at which to begin the search for szFind. Note that the position of the first character in szString is 0 (zero). If you want to replace all instances of szFind in svResult, specify 0 for nStart.

szFind szReplace

nStart

Return Values
Table E-270: StrReplace Return Values Return Value X Description The total number of replacements of szFind by szReplace. Indicates that the function failed. A value less than ISERR_SUCCESS is returned if szFind is a null string ("") or if nStart is greater than the length of svResult.

< ISERR_SUCCESS

StrSub
The StrSub function copies part of the string specified by szString, beginning at the location specified by nStart. The parameter nLength specifies the number of characters to copy.

Syntax
StrSub ( svSubStr, szString, nStart, nLength );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1453

Appendix E: Built-In Functions (S-T) StrSub

Parameters
Table E-271: StrSub Parameters Parameter svSubStr szString Description Returns the substring copied from szString. Specifies the string from which the substring is to be copied. Specifies an offset into szString that identifies the first character to be copied. Note that the position of the first character in szString is 0 (zero). If the value passed in nStart is equal to or greater than the length of szString, a null string () is returned in svSubStr. Specifies the number of characters to copy from szString. If this value specifies more characters than exist between nStart and the end of szString, all characters from nStart to the end of the string are returned in svSubStr.

nStart

nLength

Return Values
Table E-272: StrSub Return Values Return Value X Description Where X equals the number of characters in svSubStr.

StrSub Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the StrSub function. * * This script gets a date from the user and then calls StrSub * to extract the four-digit year. Finally, the year is * displayed in a message box. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "StrSub Example"

1454

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) STRTOCHAR

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StrSub(HWND); function ExFn_StrSub(hMSI) STRING svYear, svDate, szQuestion, szTitle, szMsg; NUMBER nYear; BOOL bDateOk; begin // Set up message parameter for call to AskText. szQuestion = "Please enter the date in this form MM/DD/YYYY:"; repeat // Get a date from the user. AskText (szQuestion, "09/28/1998", svDate); // Check the format of the date entered by the user. bDateOk = (StrLength(svDate) = 10) && (svDate[2] = "/") && (svDate[5] = "/"); // If the date format is incorrect, report an error. if !bDateOk then MessageBox(svDate + " is not a date in the specified format.", WARNING); endif; until bDateOk ; // Retrieve the four-digit year, which starts at byte six. if (StrSub (svYear, svDate, 6, 4) < 0) then MessageBox ("StrSub failed.", SEVERE); endif; // Validate the year field. if StrToNum(nYear, svYear) = 0 then // Display the edited string. szMsg = "You specified the year %s"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, svYear); else MessageBox(svDate + " is not a date in the specified format.", WARNING); endif; end;

STRTOCHAR
The STRTOCHAR function returns the first character of szString as data of type CHAR.

Syntax
STRTOCHAR ( szString );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1455

Appendix E: Built-In Functions (S-T) StrToLower

Parameters
Table E-273: STRTOCHAR Parameters Parameter szString Description Specifies the string whose first character will be returned as data of type CHAR.

Return Values
Table E-274: STRTOCHAR Return Values Return Value char Description The first character of szString expressed as data of type CHAR.

Additional Information
The STRTOCHAR function is useful when passing string literals to functions. Since InstallScript interprets double and single quotes as string delimiters, attempting to pass a literal character, for example, 'a', to a function that expects a character will cause a compiler error. To avoid this problem, pass the character literal to STRTOCHAR and pass the result of calling this function as the argument; for example:
Sprintf( szString, "%c", STRTOCHAR('a') );

StrToLower
The StrToLower function converts all the letters in a string to lowercase. This function does not affect non-alphabetic characters.

Syntax
StrToLower ( svTarget, szSource );

1456

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrToLower

Parameters
Table E-275: StrToLower Parameters Parameter svTarget Description Returns the string in szSource with all characters converted to lowercase. Specifies the string to convert to all lowercase characters.

szSource

Return Values
Table E-276: StrToLower Return Values Return Value 0 Description Indicates that the function successfully changed the case of the string. Indicates that the function was unable to change the case of the string.

<0

StrToLower Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the StrToUpper and StrToLower functions. * * StrToUpper is called to convert the characters in szSource * from lowercase to uppercase. * * StrToLower is then called to convert the uppercase * characters to lowercase. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "StrToUpper & StrToLower" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StrToLower(HWND); function ExFn_StrToLower(hMSI) STRING szSource, svTarget, szTitle, szMsg; NUMBER nReturn;
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1457

Appendix E: Built-In Functions (S-T) StrToNum

begin // Set up parameter for call to StrToUpper. szSource = "aBcDeF"; // Convert all characters to upper case. nReturn = StrToUpper (svTarget, szSource); if (nReturn < 0) then MessageBox ("StrToUpper failed.", SEVERE); endif; szMsg = "Original: %s\n\nModified: %s"; // Display the modified string. SprintfBox (INFORMATION, szTitle, szMsg, szSource, svTarget); // Set up parameter for call to StrToLower. szSource = "ABC123*&?d"; // Convert all characters to lower case. nReturn = StrToLower (svTarget, szSource); if (nReturn < 0) then MessageBox ("StrToLower failed.", SEVERE); endif; // Display the modified string. szMsg = "Original: %s\n\nModified: %s\n(Note--Non-alphabetic chars " + "are not changed)"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, szSource, svTarget); end;

StrToNum
The StrToNum function converts a string to a number, much like the C function atol(). It inspects svString, starting with the character at position 0 and continuing through the string until it reaches the end of the string or encounters a character that is not in the range "0"..."9". (The first character in the string can be a plus or minus sign.) Then one of the following processes occurs:

If all of the characters in the string are in the range "0".."9", the number represented by the string is assigned to nvVar. If the string begins with one or more characters in the range "0".."9" but also contains one or more non-numeric characters, a number based on the characters to the left of the first non-numeric character is assigned to nvVar. For example, if szString is "-123ABC456", nvResult will be -123. If the first character in the string is not in the range "0".."9" and is not a plus or minus sign, the function fails. If the first character in the string is a plus or minus sign and the second character is not in the range "0".."9", the function fails.

1458

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrToNum

Syntax
StrToNum ( nvVar, szString );

Parameters
Table E-277: StrToNum Parameters Parameter nvVar Description Returns the number created from the string in szString. Specifies the string to convert to a number. If the string corresponds to a number that is outside the range of allowed values for a number variable, this function gives unexpected results.

szString

Return Values
Table E-278: StrToNum Return Values Return Value 0 Description Indicates that the function successfully converted the string into a numeric value. Indicates that the function was unable to convert the string into a numeric value.

<0

StrToNum Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the StrToNum function. * * StrToNum is called to convert "1222240" to 1222240 and * "1222ABC40" to 1222. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "StrToNum Example" #define MSG_TEXT "String: %s\n\nNumber:

%d"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StrToNum(HWND);
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1459

Appendix E: Built-In Functions (S-T) StrToNumHex

function ExFn_StrToNum(hMSI) STRING szString, szMsg; NUMBER nVar; begin // Convert a string with numeric characters to a number. szString = "1222240"; if (StrToNum (nVar, szString) < 0) then MessageBox ("StrToNum failed.", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, MSG_TEXT, szString, nVar); endif; // Convert string with non-numeric characters to a number. szString = "1222ABC40"; if (StrToNum (nVar, szString) < 0) then MessageBox ("StrToNum failed.", SEVERE); else SprintfBox (INFORMATION, TITLE_TEXT, MSG_TEXT, szString, nVar); endif; end;

StrToNumHex
The StrToNumHex function converts a string to a number. It inspects szString, starting with the character at position 0 and continuing through the string until it reaches the end of the string or encounters a character that is not in the range "0"..."9", "a"..."f", "A"..."F". (The first two characters in the string may be "0x" or "0X".) Then one of the following processes occurs:

If all of the characters in the string are in the range "0".."9", the hexadecimal number represented by the string is assigned to nvVar. If the string begins with one or more characters in the hexadecimal range but also contains one or more non-hexadecimal characters, a number based on the characters to the left of the first nonhexadecimal character is assigned to nvVar. For example, if szString is "0x1A2GHI456", nvResult will be 418 (0x1A2). If the first character in the string is not in the hexadecimal range, the function fails. If the first two characters in the string are "0x" or "0X" and the third character is not in the hexadecimal range, the function fails.

Syntax
StrToNumHex ( nvVar, szString );

1460

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrToUpper

Parameters
Table E-279: StrToNumHex Parameters Parameter nvVar Description Returns the number created from the string in szString. Specifies the string to convert to a number.

szString

Return Values
Table E-280: StrToNumHex Return Values Return Value >= ISERR_SUCCESS Description Indicates that the function successfully converted the string into a numeric value. Indicates that the function was unable to convert the string into a numeric value.

< ISERR_SUCCESS

StrToUpper
The StrToUpper function converts all the letters in a string to uppercase. This function does not affect non-alphabetic characters.

Syntax
StrToUpper ( svTarget, szSource );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1461

Appendix E: Built-In Functions (S-T) StrToUpper

Parameters
Table E-281: StrToUpper Parameters Parameter svTarget Description Returns the string in szSource with all characters converted to uppercase. Specifies the string to convert to all uppercase characters.

szSource

Return Values
Table E-282: StrToUpper Return Values Return Value 0 Description Indicates that the function successfully changed the case of the string. Indicates that the function was unable to change the case of the string.

<0

StrToUpper Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the StrToUpper and StrToLower functions. * * StrToUpper is called to convert the characters in szSource * from lowercase to uppercase. * * StrToLower is then called to convert the uppercase * characters to lowercase. * \*--------------------------------------------------------------*/ #define TITLE_TEXT "StrToUpper & StrToLower" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_StrToUpper(HWND); function ExFn_StrToUpper(hMSI) STRING szSource, svTarget, szTitle, szMsg; NUMBER nReturn;
1462 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) StrTrim

begin // Set up parameter for call to StrToUpper. szSource = "aBcDeF"; // Convert all characters to upper case. nReturn = StrToUpper (svTarget, szSource); if (nReturn < 0) then MessageBox ("StrToUpper failed.", SEVERE); endif; szMsg = "Original: %s\n\nModified: %s"; // Display the modified string. SprintfBox (INFORMATION, szTitle, szMsg, szSource, svTarget); // Set up parameter for call to StrToLower. szSource = "ABC123*&?d"; // Convert all characters to lower case. nReturn = StrToLower (svTarget, szSource); if (nReturn < 0) then MessageBox ("StrToLower failed.", SEVERE); endif; // Display the modified string. szMsg = "Original: %s\n\nModified: %s\n(Note--Non-alphabetic chars " + "are not changed)"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, szSource, svTarget); end;

StrTrim
The StrTrim function removes the leading and trailing spaces and tabs from a string.

Syntax
StrTrim (byref string svString);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1463

Appendix E: Built-In Functions (S-T) System

Parameters
Table E-283: StrTrim Parameters Parameter svString Description Specify the string to be trimmed.

Return Values
Table E-284: StrTrim Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCESS Description The function successfully trimmed the string. The function failed to trim the string.

System
The System function is documented for backward compatibility with InstallShield Professional. With newer versions of InstallShield, RebootDialog and SdFinishReboot are better functions to use to restart Windows or reboot the system. Of these two, SdFinishReboot provides the most functionality. Refer to the individual function descriptions to see which one best meets your needs. Use the System function to restart Windows or reboot the system after an installation has completed. System does not perform an aborted setupthat is, it does not remove installed files. However, InstallShield does remove any temporary directories and temporary files it placed on the system to carry out the setup. To reboot the system immediately after calling the System function, use the exit keyword immediately after calling the System function. Some systems may not restart or may hang when this function is called. Many setup routines (including installation for system software such as MS-DOS) display a warning message to the user before they restart the system. This warning message indicates what is happening and instructs the user to reboot the system manually if the command fails.

Note: This function calls the Windows API ExitWindows. Due to the wide variety of BIOS types, this function is highly dependent on the BIOS interaction with the system.

Syntax
System ( nOp );

1464

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) TextSubGetValue

Parameters
Table E-285: System Parameters Parameter nOp Description Specifies which action to perform after terminating the setup. Pass the following predefined constant in this parameter:

SYS_BOOTMACHINEReboots the system.

System Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the System function. * * This script reboots the computer. * \*--------------------------------------------------------------*/ // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_System(HWND); function ExFn_System(hMSI) begin System (SYS_BOOTMACHINE); end;

TextSubGetValue
The TextSubGetValue function retrieves in svValue the text substitution string that is associated with szTextSub. The bGlobalOnly parameter specifies whether the function searches for local text substitutions.

Syntax
TextSubGetValue ( szTextSub, svValue, bGlobalOnly, bResolveEmbedded );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1465

Appendix E: Built-In Functions (S-T) TextSubGetValue

Parameters
Table E-286: TextSubGetValue Parameters Parameter szTextSub Description Specifies the string that is replaced by svValue when text substitution is performed. You can optionally enclose the string value in angle brackets, for example, "<MYTEXTSUB>". If you enclose the string value in angle brackets, you can include additional text in the string outside the angle brackets (for example, "additional<MYTEXTSUB>text") that is automatically removed before text substitution is performed. Returns the string that replaces occurrences of szTextSub when text substitution is performed. This string value can itself contain embedded text substitutions. For more information, see Text Substitutions. Specifies whether TextSubGetValue searches among only global text substitutions (TRUE) or both global and local text substitutions (FALSE). For more information, see Text Substitutions. Specifies whether to perform any embedded text substitutions. For more information, see Text Substitutions. See the following example code and comment lines:
TextSubSetValue ( "<MYTEXTSUB1>", "First Text Sub", FALSE ); TextSubSetValue ( "<MYTEXTSUB2>", "Second Text Sub <MYTEXTSUB1>", FALSE ); TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, TRUE ); // svValue is "Second Text Sub First Text Sub" TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, FALSE ); // svValue is "Second Text Sub <MYTEXTSUB1>"

svValue

bGlobalOnly

bResolveEmbedded

Return Values
Table E-287: TextSubGetValue Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description TextSubGetValue successfully retrieved the associated string. TextSubGetValue failed to retrieve the associated string.

TextSubGetValue Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the TextSub* functions: TextSubSetValue,
1466 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) TextSubParseTextSub

* TextSubSubstitute, TextSubGetValue, and TextSubParseTextSub. * \*--------------------------------------------------------------*/ function OnBegin( ) string svString, svValue; begin TextSubSetValue ( "<MYTEXTSUB1>", "First Text Sub", FALSE ); svString = "Text <MYTEXTSUB1> String"; TextSubSubstitute ( svString, FALSE ); MessageBox( svString, INFORMATION ); // svString is "Text First Text Sub String" TextSubSetValue ( "<MYTEXTSUB2>", "Second Text Sub <MYTEXTSUB1>", FALSE ); TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, TRUE ); MessageBox( svValue, INFORMATION ); // svValue is "Second Text Sub First Text Sub" TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, FALSE ); MessageBox( svValue, INFORMATION ); // svValue is "Second Text Sub <MYTEXTSUB1>" svString = "Text <MYTEXTSUB1> String"; TextSubParseTextSub ( svString ); MessageBox( svString, INFORMATION ); // svString is "MYTEXTSUB1" end;

TextSubParseTextSub
The TextSubParseTextSub function searches svTextSub for a substring that is enclosed in angle brackets (which is a standard way of denoting a text substitution string). If TextSubParseTextSub finds such a substring, it returns the first such substring, without the enclosing angle brackets, in svTextSub; otherwise, TextSubParseTextSub does not change svTextSub.

Syntax
TextSubParseTextSub ( svTextSub );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1467

Appendix E: Built-In Functions (S-T) TextSubParseTextSub

Parameters
Table E-288: TextSubParseTextSub Parameters Parameter svTextSub Description Specifies the string that is to be searched.

Return Values
Table E-289: TextSubParseTextSub Return Values Return Value ISERR_SUCCESS Description This function always returns ISERR_SUCCESS.

TextSubParseTextSub Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the TextSub* functions: TextSubSetValue, * TextSubSubstitute, TextSubGetValue, and TextSubParseTextSub. * \*--------------------------------------------------------------*/ function OnBegin( ) string svString, svValue; begin TextSubSetValue ( "<MYTEXTSUB1>", "First Text Sub", FALSE ); svString = "Text <MYTEXTSUB1> String"; TextSubSubstitute ( svString, FALSE ); MessageBox( svString, INFORMATION ); // svString is "Text First Text Sub String" TextSubSetValue ( "<MYTEXTSUB2>", "Second Text Sub <MYTEXTSUB1>", FALSE ); TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, TRUE ); MessageBox( svValue, INFORMATION ); // svValue is "Second Text Sub First Text Sub" TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, FALSE ); MessageBox( svValue, INFORMATION ); // svValue is "Second Text Sub <MYTEXTSUB1>" svString = "Text <MYTEXTSUB1> String"; TextSubParseTextSub ( svString ); MessageBox( svString, INFORMATION ); // svString is "MYTEXTSUB1" end;

1468

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) TextSubSetValue

TextSubSetValue
The TextSubSetValue function creates a text substitution association between szTextSub and szValue. The bGlobal parameter specifies whether the association is global or local.

Syntax
TextSubSetValue ( szTextSub, szValue, bGlobal );

Parameters
Table E-290: TextSubSetValue Parameters Parameter szTextSub Description Specifies the string that is replaced by szValue when text substitution is performed. You can optionally enclose the string value in angle brackets, for example, "<MYTEXTSUB>". If you enclose the string value in angle brackets, you can include additional text in the string outside the angle brackets (for example, "additional<MYTEXTSUB>text") that is automatically removed before text substitution is performed.

Note: In order to avoid conflicts with existing text substitutions that are created internally or by objects used by the installation, it is recommended that any values of szTextSub that you specify in TextSubSetValue use a prefix that is specific to the installation. szValue Specifies the string that replaces occurrences of szTextSub when text substitution is performed. This string value can itself contain embedded text substitutions. For more information, see Text Substitutions. Specifies whether the association between szTextSub and szValue is global or local; for more information, see Text Substitutions.

bGlobal

Return Values
Table E-291: TextSubSetValue Return Values Return Value ISERR_SUCCESS < ISERR_SUCCESS Description TextSubSetValue successfully associated the specified strings. TextSubSetValue failed to associate the specified strings.

TextSubSetValue Example
/*--------------------------------------------------------------*\ *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1469

Appendix E: Built-In Functions (S-T) TextSubSubstitute

* InstallShield Example Script * * Demonstrates the TextSub* functions: TextSubSetValue, * TextSubSubstitute, TextSubGetValue, and TextSubParseTextSub. * \*--------------------------------------------------------------*/ function OnBegin( ) string svString, svValue; begin TextSubSetValue ( "<MYTEXTSUB1>", "First Text Sub", FALSE ); svString = "Text <MYTEXTSUB1> String"; TextSubSubstitute ( svString, FALSE ); MessageBox( svString, INFORMATION ); // svString is "Text First Text Sub String" TextSubSetValue ( "<MYTEXTSUB2>", "Second Text Sub <MYTEXTSUB1>", FALSE ); TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, TRUE ); MessageBox( svValue, INFORMATION ); // svValue is "Second Text Sub First Text Sub" TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, FALSE ); MessageBox( svValue, INFORMATION ); // svValue is "Second Text Sub <MYTEXTSUB1>" svString = "Text <MYTEXTSUB1> String"; TextSubParseTextSub ( svString ); MessageBox( svString, INFORMATION ); // svString is "MYTEXTSUB1" end;

TextSubSubstitute
The TextSubSubstitute function performs text substitution on svString. The bGlobalOnly parameter specifies whether the function performs local text substitutions.

Syntax
TextSubSubstitute ( svString, bGlobalOnly );

1470

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix E: Built-In Functions (S-T) TextSubSubstitute

Parameters
Table E-292: TextSubSubstitute Parameters Parameter svString Description Specifies the string on which text substitution is performed. Specifies whether TextSubSubstitute performs only global text substitutions (TRUE) or both global and local text substitutions (FALSE); for more information, see Text Substitutions.

bGlobalOnly

Return Values
Table E-293: TextSubSubstitute Return Values Return Value ISERR_SUCCESS Description TextSubSubstitute successfully performed text substitution. TextSubSubstitute failed to perform text substitution.

< ISERR_SUCCESS

TextSubSubstitute Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the TextSub* functions: TextSubSetValue, * TextSubSubstitute, TextSubGetValue, and TextSubParseTextSub. * \*--------------------------------------------------------------*/ function OnBegin( ) string svString, svValue; begin TextSubSetValue ( "<MYTEXTSUB1>", "First Text Sub", FALSE ); svString = "Text <MYTEXTSUB1> String"; TextSubSubstitute ( svString, FALSE ); MessageBox( svString, INFORMATION ); // svString is "Text First Text Sub String" TextSubSetValue ( "<MYTEXTSUB2>", "Second Text Sub <MYTEXTSUB1>", FALSE ); TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, TRUE ); MessageBox( svValue, INFORMATION ); // svValue is "Second Text Sub First Text Sub" TextSubGetValue ( "<MYTEXTSUB2>", svValue, FALSE, FALSE ); MessageBox( svValue, INFORMATION ); // svValue is "Second Text Sub <MYTEXTSUB1>" svString = "Text <MYTEXTSUB1> String";

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1471

Appendix E: Built-In Functions (S-T) TextSubSubstitute

TextSubParseTextSub ( svString ); MessageBox( svString, INFORMATION ); // svString is "MYTEXTSUB1" end;

1472

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

F
Built-In Functions (U-Z)
For a list of functions by category, see Built-In Functions by Category.

UninstallApplication
Project: This information applies to InstallScript projects.

The UninstallApplication function launches the uninstallation that is specified by szUninstallKey.

Syntax
UninstallApplication ( szUninstallKey, szAdditionalCmdLine, nOptions );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1473

Appendix F: Built-In Functions (U-Z) UnUseDLL

Parameters
Table F-1: UninstallApplication Parameters Parameter szUninstallKey Description Specifies the name of a subkey under the target registry's <root key>\Software\Microsoft\Windows\CurrentVersion\ Uninstall key; the function first checks for the subkey under the root key HKEY_CURRENT_USER, and if it does not find the subkey there, it checks under HKEY_LOCAL_MACHINE. For setups created with InstallShield Professional 5.53 or earlier, this is typically the name of the application; for setups created with InstallShield Professional 6.0 or later, this is the application's product GUID including the surrounding braces ({}). Do not enter the product GUID of the current setup. Specifies any additional command line arguments that you want to pass to the uninstallation. You do not need to specify command line arguments that are already specified in szUninstallKey's UninstallString value's data. Specifies additional options. You can specify any option that is supported by LaunchApplication.

szAdditionalCmdLine

nOptions

Return Values
Table F-2: UninstallApplication Return Values Return Value >= ISERR_SUCCESS Description Indicates that the function successfully launched the uninstallation. Indicates that the function was unable to launch the uninstallation. You can obtain the error message text associated with a large negative return valuefor example, 2147024891 (0x80070005)by calling FormatMessage.

< ISERR_SUCCESS

UnUseDLL
The UnUseDLL function unloads a .dll file from memory. UnUseDLL decrements the lock count of the .dll file by one. When the lock count equals zero, InstallShield unloads the .dll file. Every call to UseDLL should have a matching call to UnUseDLL so that .dll files are not left in memory after they are no longer needed, using system resources. After you unload a .dll file, you cannot call the functions in that .dll file.

1474

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) UnUseDLL

If the script exits or terminates before properly unloading the .dll file with UnUseDLL, the .dll file is locked in memory. If you attempt to access the .dll file again, your script might fail. You must remove the .dll file from memory by restarting Windows.

Caution: Microsoft Windows system .dll files, such as User.exe, User32.dll, Gdi.exe, Gdi32.dll, Krnl386.exe, Krnl286.exe, and Kernel32.dll, are loaded and unloaded automatically by Windows. Do not call UseDLL and UnUseDLL to load and unload these .dll files.

Syntax
UnUseDLL ( szDLLName );

Parameters
Table F-3: UnUseDLL Parameters Parameter szDLLName Description Specifies the file name of the .dll file. Do not include the path in this parameter.

Return Values
Table F-4: UnUseDLL Return Values Return Value 0 Description Indicates that the function successfully unlocked and possibly unloaded the .dll file from memory. Indicates that the function was unable to unlock or unload the .dll file.

<0

UnUseDLL Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the UseDLL and the UnUseDLL functions. * * UseDLL is called to load an example .dll file into memory. A * function in this .dll file is then called to demonstrate how * .dll functions can be used in an installation . Finally, * UnUseDLL is called to unload the example .dll file from memory. *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1475

Appendix F: Built-In Functions (U-Z) UnUseDLL

* Note: This script requires that the constant DLL_FILE be set * to the fully qualified name of a .dll file that contains * a function called MydllReturn. The format of that * function must match the prototype declaration below. * \*--------------------------------------------------------------*/ #define DLL_FILE "MyDLL.dll;"

// Prototype MydllReturn in Mydll.dll. prototype Mydll.MydllReturn (INT, POINTER);

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_UnUseDLL(HWND); function ExFn_UnUseDLL(hMSI) STRING svString; INT nValue; POINTER psvString; NUMBER nResult; BOOL bDone; begin // Load the .dll file into memory. nResult = UseDLL (DLL_FILE); if (nResult = 0) then MessageBox ("UseDLL successful \n\n.dll file loaded.", INFORMATION); else MessageBox ("UseDLL failed.\n\nCouldn't load .dll file.", INFORMATION); abort; endif; // bDone controls the following while loop. bDone = FALSE; // Loop while bDone is FALSE. while (bDone = FALSE) // Disable the Back button in installation dialogs. Disable (BACKBUTTON); // Get a string from the user. AskText ("Enter an example string.", "Example string.", svString); // Get a pointer to the string to pass to MydllReturn. psvString = &svString; // Get the string length to pass to MydllReturn. nValue = StrLength (svString); // Call MydllReturn. MydllReturn (nValue, psvString); // Display the string to observe how it was altered by MydllReturn. SprintfBox (INFORMATION, "UseDLL", "MydllReturn() changed the string " + "to: %s", svString); // Give the user a chance to do another example. if (AskYesNo ("Do another example?", YES) = NO) then
1476 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) UpdateServiceCheckForUpdates

bDone = TRUE; endif; endwhile; // Remove the .dll file from memory. if (UnUseDLL (DLL_FILE) < 0) then MessageBox ("UnUseDLL failed.\n\n.dll file still in memory.", SEVERE); else MessageBox ("UnUseDLL successful.\n\n.dll file removed from memory.", INFORMATION); endif; end;

UpdateServiceCheckForUpdates
Project: This information applies to InstallScript projects.

This function is obsolete. If this function is called, it returns ISERR_NOT_IMPLEMENTED. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Syntax
UpdateServiceCheckForUpdates ( szProductCode, bWait );

UpdateServiceCreateShortcut
Project: This information applies to InstallScript projects.

This function is obsolete. If this function is called, it returns ISERR_NOT_IMPLEMENTED. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Syntax
UpdateServiceCreateShortcut ( szProductCode, szFolder, szItemName );

UpdateServiceEnableUpdateManagerInstall
Project: This information applies to InstallScript projects.

This function is obsolete. If this function is called, it returns ISERR_NOT_IMPLEMENTED.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1477

Appendix F: Built-In Functions (U-Z) UpdateServiceGetAgentTarget

For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Syntax
UpdateServiceEnableUpdateManagerInstall (BOOL bEnable);

UpdateServiceGetAgentTarget
Project: This information applies to InstallScript projects.

This function is obsolete. If this function is called, it returns a null string (""). For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Syntax
UpdateServiceGetAgentTarget ( );

UpdateServiceOnEnabledStateChange
Project: This information applies to InstallScript projects.

This function is obsolete. If this function is called, it returns ISERR_NOT_IMPLEMENTED. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Syntax
UpdateServiceOnEnabledStateChange ( );

UpdateServiceRegisterProduct
Project: This information applies to InstallScript projects.

This function is obsolete. If this function is called, it returns ISERR_NOT_IMPLEMENTED. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Syntax
UpdateServiceRegisterProduct ( szProductCode, szProductVersion, bRegister, nInterval );

1478

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) UpdateServiceRegisterProductEx

UpdateServiceRegisterProductEx
Project: This information applies to InstallScript projects.

This function is obsolete. If this function is called, it returns ISERR_NOT_IMPLEMENTED. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Syntax
UpdateServiceRegisterProductEx (BOOL bRegister);

UpdateServiceSetHost
Project: This information applies to InstallScript projects.

This function is obsolete. If this function is called, it returns ISERR_NOT_IMPLEMENTED. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Syntax
UpdateServiceSetHost ( szProductCode, szHostURL );

UpdateServiceSetLanguage
Project: This information applies to InstallScript projects.

This function is obsolete. If this function is called, it returns ISERR_NOT_IMPLEMENTED. For information on adding FlexNet Connect support to an InstallScript project, consult the Knowledge Base.

Syntax
UpdateServiceSetLanguage ( szProductCode, nLanguageID );

UseDLL
The UseDLL function loads a .dll file into memory. After the .dll file has been loaded into memory, your installation script can call a function from that .dll file. Note that if the .dll file specified by szDLLName requires other .dll files, those other .dll files must reside in the folder from which the .dll file attempts to

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1479

Appendix F: Built-In Functions (U-Z) UseDLL

load them. Normally this will be the current folder. To ensure that those .dll files can be located, call ChangeDirectory to change the current folder to the location of those .dll files before calling UseDLL. Failure to do so may prevent the .dll file from loading properly. Each time that you load a .dll file into memory, the .dll files lock count is incremented. The lock count counts the number of applications that are using a .dll file. You should call UnUseDLL to unload a .dll file as soon as you are done using it. If you do not unload a .dll file when you are done with it, the .dll file will remain in memory when no applications need it, thereby wasting system resources. Every call to UseDLL should have a matching call to UnUseDLL in the script.

Caution: Microsoft Windows system .dll files, such as User.exe, User32.dll, Gdi.exe, Gdi32.dll, Krnl386.exe, Krnl286.exe, and Kernel32.dll, are loaded and unloaded automatically by Windows. Do not call UseDLL and UnUseDLL to load and unload these .dll files.

Syntax
UseDLL ( szDLLName );

1480

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) UseDLL

Parameters
Table F-5: UseDLL Parameters Parameter szDLLName Description Specifies the name of the .dll file to be loaded. If you do not specify an extension, InstallShield assumes that the file has the extension .dll or .exe. Including a path in this parameter is recommended but optional. If the path for the .dll file is not specified in this parameter, InstallShield searches for the .dll file using the same search order used by the Windows API function LoadLibrary. See the description of this Windows API function for more information regarding the search order. To include the .dll file in your installation, add it to the appropriate subfolder of the Language Independent folder in the Support Files view. InstallShield compresses it into your installation. When Setup.exe executes, it automatically decompresses and copies the contents of your installation into the temporary directory specified by SUPPORTDIR. You can then append the .dll file name to SUPPORTDIR as follows in order to reference the .dll file:
szDLLName = SUPPORTDIR ^ "MyDll.dll"; UseDLL (szDLLName);

If you do not place your .dll file into your installation (by inserting it into the appropriate folder in the Support Files view), you can instead distribute the file along with the files of your application and then load it from the target system. However, if you do so, you must specify the location to which you install the .dll file so that your installation can reference it. You must also ensure that your installation does not attempt to load the .dll file before it has been transferred to the target system.

Note: The szDLLName parameter does not support uniform resource locators (URLs).

Return Values
Table F-6: UseDLL Return Values Return Value 0 Description Indicates that the function successfully loaded the .dll file into memory.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1481

Appendix F: Built-In Functions (U-Z) UseDLL

Table F-6: UseDLL Return Values (cont.) Return Value <0 Description Indicates that the function was unable to load the .dll file into memory. If UseDLL fails, the most likely cause is that the .dll file was not found. If this happens, make sure the correct path is specified in the parameter szDLLName. Another common cause of failure associated with using .dll files is related to .dll file dependencies.dll files accessed by the .dll file that you load. If the .dll files that your .dll file accesses are not loaded or found, your .dll file call may fail. If this occurs, make sure that the other .dll files are on the system and that they are accessible. If the script exits or terminates before properly unloading the .dll file with UnUseDLL, the .dll file will be locked in memory. If you attempt to access the .dll file again, your script may fail. You must remove the .dll file from memory by restarting Windows.

UseDLL Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the UseDLL and the UnUseDLL functions. * * UseDLL is called to load an example .dll file into memory. A * function in this .dll file is then called to demonstrate how * .dll functions can be used in an installation. Finally, * UnUseDLL is called to unload the example .dll file from memory. * * Note: This script requires that the constant DLL_FILE be set * to the fully qualified name of a .dll file that contains * a function called MydllReturn. The format of that * function must match the prototype declaration below. * \*--------------------------------------------------------------*/ #define DLL_FILE "MyDLL.dll;"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h"

// Prototype MydllReturn in Mydll.dll. prototype Mydll.MydllReturn (INT, POINTER); export prototype ExFn_UseDLL(HWND); function ExFn_UseDLL(hMSI) STRING svString; INT nValue;
1482 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) UseDLL

POINTER psvString; NUMBER nResult; BOOL bDone; begin // Load the .dll file into memory. nResult = UseDLL (DLL_FILE); if (nResult = 0) then MessageBox ("UseDLL successful \n\n.dll file loaded.", INFORMATION); else MessageBox ("UseDLL failed.\n\nCouldn't load .dll file.", INFORMATION); abort; endif; // bDone controls the following while loop. bDone = FALSE; // Loop while bDone is FALSE. while (bDone = FALSE) // Disable the Back button in installation dialogs. Disable (BACKBUTTON); // Get a string from the user. AskText ("Enter an example string.", "Example string.", svString); // Get a pointer to the string to pass to MydllReturn. psvString = &svString; // Get the string length to pass to MydllReturn. nValue = StrLength (svString); // Call MydllReturn. MydllReturn (nValue, psvString); // Display the string to observe how it was altered by MydllReturn. SprintfBox (INFORMATION, "UseDLL", "MydllReturn() changed the string " + "to: %s", svString); // Give the user a chance to do another example. if (AskYesNo ("Do another example?", YES) = NO) then bDone = TRUE; endif; endwhile; // Remove the .dll file from memory. if (UnUseDLL (DLL_FILE) < 0) then MessageBox ("UnUseDLL failed.\n\n.dll file still in memory.", SEVERE); else MessageBox ("UnUseDLL successful.\n\n.dll file removed from memory.", INFORMATION); endif; end;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1483

Appendix F: Built-In Functions (U-Z) VarInit

VarInit
The VarInit function initializes or reinitializes internal lists used by the VarSave and VarRestore functions. Calling this function effectively clears any information stored by previous VarSave calls and not yet used by subsequent VarRestore functions.

Syntax
VarInit (nType);

1484

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VarRestore

Parameters
Table F-7: VarInit Parameters Parameter nType Description Specifies which information to reset. Pass one of the following predefined constants in this parameter.

Project: These constants apply to InstallScript projects:

VAR_LOGGINGResets any stored uninstall logging entries. VAR_CURRENTDIRResets any stored current directory entries. VAR_ALLSUPPORTEDResets all stored entries. VAR_HKEYCURRENTROOTKEYResets any stored current root key entries. CURRENTROOTKEYThis constant is obsolete. Use VAR_HKEYCURRENTROOTKEY instead.

Project: This constant applies to Basic MSI, InstallScript, and InstallScript MSI projects:

VAR_SRCTARGETDIRResets any stored current entries for TARGETDIR (in InstallScript installations), and INSTALLDIR (in Basic MSI and InstallScript MSI installations), and SRCDIR.

Project: This constant applies to Basic MSI and InstallScript MSI projects:

SRCINSTALLDIRThis constant is obsolete. Use VAR_SRCTARGETDIR instead.

Return Values
Table F-8: VarInit Return Values Return Value ISERR_SUCCESS Description Indicates that the current values of the system variables were reset.

VarRestore
The VarRestore function reassigns the values that were saved by an earlier call to the VarSave function to the system variables TARGETDIR (in InstallScript installations), INSTALLDIR (in Basic MSI and InstallScript MSI installations), SRCDIR, or HKEYCURRENTROOTKEY. Call VarSave whenever you need to change the value of these system variables temporarily, for example, to set source and target directories before a call to XCopyFile. Afterwards, set those variables back to their previous values by calling VarRestore.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1485

Appendix F: Built-In Functions (U-Z) VarRestore

Syntax
VarRestore ( nType );

1486

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VarRestore

Parameters
Table F-9: VarRestore Parameters Parameter nType Description Specifies which system variables to restore. Pass one or more of the following predefined constants in this parameter. Note that you can pass multiple constants separated by the OR operator (||).

Project: These constants apply to InstallScript projects:

VAR_LOGGINGResets any stored uninstallation logging entries. VAR_CURRENTDIRResets any stored current directory entries. VAR_ALLSUPPORTEDResets all stored entries. VAR_HKEYCURRENTROOTKEYResets any stored current root key entries. VAR_REGOPTIONSResets any stored current registry options. CURRENTROOTKEYThis constant is obsolete. Use VAR_HKEYCURRENTROOTKEY instead.

Project: This constant applies to Basic MSI, InstallScript, and InstallScript MSI projects:

VAR_SRCTARGETDIR or SRCTARGETDIRResets any stored current TARGETDIR (in InstallScript installations), INSTALLDIR (in Basic MSI and InstallScript MSI installations), and SRCDIR entries.

Project: This constant applies to Basic MSI and InstallScript MSI projects:

SRCINSTALLDIRThis constant is obsolete. Use VAR_SRCTARGETDIR instead.

Return Values
Table F-10: VarRestore Return Values Return Value 0 <0 Description Indicates that the previously saved values of the system variables were restored. Indicates that there are no values in storage to be restored. This error occurs if you call VarRestore without calling VarSave first, or if you call VarRestore more times than you call VarSave.

Additional Information
Each time you call VarSave, the InstallScript engine pushes the current values of the system variables onto an internal stack, which operates as a last in, first out storage area. This method allows you to stack
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1487

Appendix F: Built-In Functions (U-Z) VarRestore

a series of values in memory. You can then make calls to VarRestore to retrieve those values from the stack in the opposite order that you stored them. For example, if you call VarSave three times with SRCTARGETDIR as its argument (without calling VarRestore in between those calls), there will be three sets of SRCDIR and TARGETDIR values on the stack. The first call to VarRestore with SRCTARGETDIR as its argument restores the values from the third call to VarSave. The next call to VarRestore restores the values from the second call to VarSave. The third call to VarRestore restores the values from the first call to VarSave. At that point, the stack is empty. To see a script fragment that illustrates this process, refer to VarSave Stack Example.

VarRestore Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the VarSave and VarRestore functions. * * This script starts by displaying the starting values of the * system variables SRCDIR and INSTALLDIR. It then calls VarSave * to save those values. Next, it assigns new values to SRCDIR * and INSTALLDIR, and it displays those values. Finally, it * calls VarRestore to restore the original values, which are * then displayed. * \*--------------------------------------------------------------*/ #define #define NEW_SOURCE_DIR "C:\\Source" NEW_INSTALL_DIR "C:\\Target"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_VarRestore(HWND); function ExFn_VarRestore(hMSI) begin // Display the values of SRCDIR and INSTALLDIR. SprintfBox (INFORMATION, "Starting Source and Target Folders", "Source:\n\n%s\n\n Target:\n\n%s ", SRCDIR, INSTALLDIR); // Save the current values of SRCDIR and INSTALLDIR. VarSave (SRCTARGETDIR); // Assign new values to SRCDIR and INSTALLDIR. SRCDIR = NEW_SOURCE_DIR; INSTALLDIR = NEW_INSTALL_DIR; // Display the values of SRCDIR and INSTALLDIR. SprintfBox (INFORMATION, "New Source and Target Folders", "New Source:\n\n%s\n\n New Target:\n\n%s",

1488

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VarSave

SRCDIR, INSTALLDIR); // Restore the old values. VarRestore (SRCTARGETDIR); // Display the values of SRCDIR and INSTALLDIR. SprintfBox (INFORMATION, "Restored Source and Target Folders", "Source:\n\n%s\n\n Target:\n\n%s ", SRCDIR, INSTALLDIR); end;

VarSave
The VarSave function saves the current values of the system variables TARGETDIR (in InstallScript installations), INSTALLDIR ( in Basic MSI and InstallScript MSI installations), SRCDIR, or HKEYCURRENTROOTKEY, which are used by many other InstallScript functions. Call VarSave whenever you need to change the value of these system variables temporarily, for example, to set source and target directories before a call to XCopyFile. Afterwards, set those variables back to their previous values by calling VarRestore.

Syntax
VarSave (nType);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1489

Appendix F: Built-In Functions (U-Z) VarSave

Parameters
Table F-11: VarSave Parameters Parameter nType Description Specifies which system variables to save. Pass one or more of the following predefined constants in this parameter. Note that you can pass multiple constants separated by the OR operator (||).

Project: This information applies to InstallScript projects:

VAR_LOGGINGResets any stored uninstallation logging entries. VAR_CURRENTDIRResets any stored current directory entries. VAR_ALLSUPPORTEDResets all stored entries. VAR_HKEYCURRENTROOTKEYResets any stored current root key entries. VAR_REGOPTIONSResets any stored current registry options. CURRENTROOTKEYThis constant is obsolete. Use VAR_HKEYCURRENTROOTKEY instead.

Project: This constant applies to Basic MSI, InstallScript, and InstallScript MSI projects:

VAR_SRCTARGETDIR or SRCTARGETDIRResets any stored current TARGETDIR (in InstallScript installations), INSTALLDIR (in Basic MSI and InstallScript MSI installations), and SRCDIR entries.

Project: This constant applies to Basic MSI and InstallScript MSI projects:

SRCINSTALLDIRThis constant is obsolete. Use VAR_SRCTARGETDIR instead.

Return Values
Table F-12: VarSave Return Values Return Value 0 <0 Description Indicates that the current values of the system variables were saved. Indicates that the values were not saved due to an internal error. This error should occur only if the system is low on available memory.

Additional Information
Each time you call VarSave, the InstallScript engine pushes the current values of the system variables onto an internal stack, which operates as a last in, first out storage area. This method allows you to stack a series of values in memory. You can then make calls to VarRestore to retrieve those values from the
1490 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VarSave

stack in the opposite order that you stored them. For example, if you call VarSave three times with SRCTARGETDIR as its argument (without calling VarRestore in between those calls), there will be three sets of SRCDIR and TARGETDIR values on the stack. The first call to VarRestore with SRCTARGETDIR as its argument restores the values from the third call to VarSave. The next call to VarRestore restores the values from the second call to VarSave. The third call to VarRestore restores the values from the first call to VarSave. At that point, the stack is empty. To see a script fragment that illustrates this process, refer to VarSave Stack Example.

VarSave Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the VarSave and VarRestore functions. * * This script starts by displaying the starting values of the * system variables SRCDIR and INSTALLDIR. It then calls VarSave * to save those values. Next, it assigns new values to SRCDIR * and INSTALLDIR, and it displays those values. Finally, it * calls VarRestore to restore the original values, which are * then displayed. * \*--------------------------------------------------------------*/ #define #define NEW_SOURCE_DIR "C:\\Source" NEW_INSTALL_DIR "C:\\Target"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_VarSave(HWND); function ExFn_VarSave(hMSI) begin // Display the values of SRCDIR and INSTALLDIR. SprintfBox (INFORMATION, "Starting Source and Target Folders", "Source:\n\n%s\n\n Target:\n\n%s ", SRCDIR, INSTALLDIR); // Save the current values of SRCDIR and INSTALLDIR. VarSave (SRCTARGETDIR); // Assign new values to SRCDIR and INSTALLDIR. SRCDIR = NEW_SOURCE_DIR; INSTALLDIR = NEW_INSTALL_DIR; // Display the values of SRCDIR and INSTALLDIR. SprintfBox (INFORMATION, "New Source and Target Folders", "New Source:\n\n%s\n\n New Target:\n\n%s", SRCDIR, INSTALLDIR);

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1491

Appendix F: Built-In Functions (U-Z) VarSave

// Restore the old values. VarRestore (SRCTARGETDIR); // Display the values of SRCDIR and INSTALLDIR. SprintfBox (INFORMATION, "Restored Source and Target Folders", "Source:\n\n%s\n\n Target:\n\n%s ", SRCDIR, INSTALLDIR); end;

VarSave Stack Example

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
// // // // This script fragment illustrates how VarSave and VarRestore work with an internal stack to save and retrieve the values assigned to SRCDIR and INSTALLDIR

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_VarSave Stack(HWND); function ExFn_VarSave Stack(hMSI) begin // Store the starting values of SRCDIR and INSTALLDIR VarSave(SRCTARGETDIR); // Assign new values to SRCDIR and INSTALLDIR SRCDIR = "E:\\"; INSTALLDIR = "C:\\Program Files"; // . . . // Store those values ("E:\\" and "C:\\Program Files") VarSave(SRCTARGETDIR); // Assign new values to SRCDIR and INSTALLDIR SRCDIR = "A:\\"; INSTALLDIR = "C:\\Windows"; // . . . // Store those new values ("A:\\" and "C:\\Windows") VarSave(SRCTARGETDIR); // . . . // Restore the values from the third call to VarSave VarRestore(SRCTARGETDIR); // SRCDIR is now "A:\\ // INSTALLDIR is now "C:\\Windows"

1492

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerCompare

// . . . // Restore the values from the second call to VarSave VarRestore(SRCTARGETDIR); // SRCDIR is now "E:\\" // INSTALLDIR is now "C:\\Program Files" // . . . // Restore the values from the first call to VarSave VarRestore(SRCTARGETDIR); // SRCDIR and INSTALLDIR now have their starting values. end;

VerCompare
The VerCompare function compares two strings that contain version information and returns whether the first one is less than, greater than, or equal to the second one.

Important: The format of the versions that you pass through the szVersionInfo1 and szVersionInfo2 parameters must be in the format w.x.y.z, where w, x, y, and z represent numbers. All four fields must be present; otherwise, VerCompare cannot successfully compare the two version strings. For example, the following entries are valid szVersionInfo1 and szVersionInfo2 parameters:

"1.0.0.0" "10.10.20.10" "3.21.01.2"

The following entries are not valid parameters: "1.20" "1.12.3" "2"

If one of the version strings has fewer than four fields, consider using the concatenate string operator (+) to add a decimal point and the number 0 as needed.

Syntax
VerCompare ( szVersionInfo1, szVersionInfo2, nCompareFlag );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1493

Appendix F: Built-In Functions (U-Z) VerCompare

Parameters
Table F-13: VerCompare Parameters Parameter szVersionInfo1 Description Specify the first version string in the format w.x.y.z, where w, x, y, and z represent numbers. Specify the second version string in the format w.x.y.z, where w, x, y, and z represent numbers. Specify the predefined constant VERSION to indicate that you are comparing version numbers. No other values are allowed in this parameter.

szVersionInfo2

nCompareFlag

Return Values
Table F-14: VerCompare Return Values Return Value EQUALS (2) LESS_THAN (1) GREATER_THAN (0) ISERR_GEN_FAILURE (-1) Description Indicates that the two strings are of equal value. Indicates that the first string contains a value less than the second. Indicates that the first string contains a value greater than the second. Indicates that the function could not compare the two strings.

VerCompare Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the VerFindFileVersion and VerCompare functions. * * This script calls VerFindFileVersion to find the target file * and retrieve its version information. If the specified * target file is not found, the source file is copied to * INSTALLDIR. If found, VerCompare is called to compare the * version number of the EXAMPLE file found on the target * system (the target file) to the version number of the file * in SRCDIR (the source file). If the source file version * number is newer than the target file, the target file is * overwritten with the source file. * \*--------------------------------------------------------------*/ #define EXAMPLE
1494

"Stirinfc.dll"
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerCompare

#define SOURCE_VER "2.0.1.0" #define TITLE "VerCompare and VerFindFileVersion" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_VerFindFileVersion(HWND); function ExFn_VerFindFileVersion(hMSI) STRING szFileName, svPath, svVersionNumber, szExistingVersion, szUpdateVersion; STRING szTitle, szMsg; NUMBER nResult, nCompareFlag; begin // Set the file to be updated. szFileName = EXAMPLE; // Find szFileName on the target system and retrieve its version number. nResult = VerFindFileVersion(szFileName, svPath, svVersionNumber); if (nResult = FILE_NOT_FOUND) then // If szFileName not found, copy source file to INSTALLDIR. szMsg = "Unable to locate %s. Copying %s to %s."; SprintfBox (INFORMATION, TITLE, szMsg, szFileName, szFileName, INSTALLDIR); CopyFile (szFileName, szFileName); abort; elseif (nResult = FILE_NO_VERSION) then // If no version number found, copy source file to svPath and exit. szMsg = "%s version number not found. Copying %s to %s."; SprintfBox (INFORMATION, TITLE, szMsg, szFileName, szFileName, INSTALLDIR); CopyFile (szFileName, szFileName); abort; elseif (nResult < 0) then MessageBox ("VerFindFileVersion failed.", SEVERE); abort; endif; // Compare the versions of the two files. It is assumed // that the source version number is known. szExistingVersion = svVersionNumber; MessageBox (szExistingVersion, INFORMATION); szUpdateVersion = SOURCE_VER; MessageBox (szUpdateVersion, INFORMATION); nCompareFlag = VERSION; nResult = VerCompare (szUpdateVersion, szExistingVersion, nCompareFlag); // If the source file is a more current version, install it. if (nResult = GREATER_THAN) then szMsg = "%s updated into the %s directory."; SprintfBox (INFORMATION, TITLE, szMsg, szFileName, INSTALLDIR); CopyFile (szFileName, szFileName); // If the target file is a more current version, do not install.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1495

Appendix F: Built-In Functions (U-Z) VerFindFileVersion

elseif (nResult = LESS_THAN) then szMsg = "No need for an upgrade, the most current version of %s is " + "installed."; SprintfBox (INFORMATION, TITLE, szMsg, szFileName); // If both the target and source versions are the same, do not install. elseif (nResult = EQUALS) then MessageBox ("Versions are equal. No update needed.", INFORMATION); endif; end;

VerFindFileVersion
The VerFindFileVersion function searches for a specified file and retrieves the file version and location.
VerFindFileVersion uses the following search algorithm to find the file (searches the folders in the

following order):
1. 2. 3. 4. 5.

Windows folder Windows system folder The folder specified by the TARGETDIR system variable (in InstallScript installations) or the INSTALLDIR system variable (in Basic MSI and InstallScript MSI installations) The folders specified by the PATH environment variable The folder from which Setup.exe is running

For information about the Windows system folder, see the documentation for the InstallScript system variable WINSYSDIR.

Note: When using VerFindFileVersion, you might need to set a value for TARGETDIR (in InstallScript installations) or INSTALLDIR (in Basic MSI and InstallScript installations) other than the value that is automatically set by the InstallScript engine. Since the function looks for the file in the TARGETDIR or INSTALLDIR folder, you might need to reset the value of the system variable temporarily to ensure that VerFindFileVersion finds the file. If you need to do this, use VarSave to save the value of TARGETDIR or INSTALLDIR before temporarily setting it to another folder. After the VerFindFileVersion function call, reset TARGETDIR or INSTALLDIR using VarRestore.

Syntax
VerFindFileVersion ( szFileName, svPath, svVersionNumber );

1496

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerFindFileVersion

Parameters
Table F-15: VerFindFileVersion Parameters Parameter szFileName Description Specifies the unqualified name of the file whose version is to be obtained. Do not specify a drive designation or path in this parameter. Returns the complete path (including the drive designation) to the folder in which the file resides. Returns the version number of the file in the following format:
<major version>.<minor version>

svPath

svVersionNumber

For example, if svVersionNumber returns 2.1.2.0, the major version number is 2.1 and the minor version number is 2.0.

Return Values
Table F-16: VerFindFileVersion Return Values Return Value 0 FILE_NO_VERSION (-8) FILE_NOT_FOUND (-2) Description Indicates that the function successfully returned the version information. Indicates that the file was found but did not contain version information. Indicates that the file was not found.

VerFindFileVersion Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the VerFindFileVersion and VerCompare functions. * * This script calls VerFindFileVersion to find the target file * and retrieve its version information. If the specified * target file is not found, the source file is copied to * INSTALLDIR. If found, VerCompare is called to compare the * version number of the EXAMPLE file found on the target * system (the target file) to the version number of the file * in SRCDIR (the source file). If the source file version * number is newer than the target file, the target file is * overwritten with the source file. * \*--------------------------------------------------------------*/

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1497

Appendix F: Built-In Functions (U-Z) VerFindFileVersion

#define EXAMPLE "Stirinfc.dll" #define SOURCE_VER "2.0.1.0" #define TITLE "VerCompare and VerFindFileVersion" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_VerFindFileVersion(HWND); function ExFn_VerFindFileVersion(hMSI) STRING szFileName, svPath, svVersionNumber, szExistingVersion, szUpdateVersion; STRING szTitle, szMsg; NUMBER nResult, nCompareFlag; begin // Set the file to be updated. szFileName = EXAMPLE; // Find szFileName on the target system and retrieve its version number. nResult = VerFindFileVersion(szFileName, svPath, svVersionNumber); if (nResult = FILE_NOT_FOUND) then // If szFileName not found, copy source file to INSTALLDIR. szMsg = "Unable to locate %s. Copying %s to %s."; SprintfBox (INFORMATION, TITLE, szMsg, szFileName, szFileName, INSTALLDIR); CopyFile (szFileName, szFileName); abort; elseif (nResult = FILE_NO_VERSION) then // If no version number found, copy source file to svPath and exit. szMsg = "%s version number not found. Copying %s to %s."; SprintfBox (INFORMATION, TITLE, szMsg, szFileName, szFileName, INSTALLDIR); CopyFile (szFileName, szFileName); abort; elseif (nResult < 0) then MessageBox ("VerFindFileVersion failed.", SEVERE); abort; endif; // Compare the versions of the two files. It is assumed // that the source version number is known. szExistingVersion = svVersionNumber; MessageBox (szExistingVersion, INFORMATION); szUpdateVersion = SOURCE_VER; MessageBox (szUpdateVersion, INFORMATION); nCompareFlag = VERSION; nResult = VerCompare (szUpdateVersion, szExistingVersion, nCompareFlag); // If the source file is a more current version, install it. if (nResult = GREATER_THAN) then szMsg = "%s updated into the %s directory."; SprintfBox (INFORMATION, TITLE, szMsg, szFileName, INSTALLDIR); CopyFile (szFileName, szFileName);

1498

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerGetFileLanguages

// If the target file is a more current version, do not install. elseif (nResult = LESS_THAN) then szMsg = "No need for an upgrade, the most current version of %s is " + "installed."; SprintfBox (INFORMATION, TITLE, szMsg, szFileName); // If both the target and source versions are the same, do not install. elseif (nResult = EQUALS) then MessageBox ("Versions are equal. No update needed.", INFORMATION); endif; end;

VerGetFileLanguages
The VerGetFileLanguages function retrieves the list of languages supported by the file that is specified by szFile.

Syntax
VerGetFileLanguages ( szFileName, listLanguages );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1499

Appendix F: Built-In Functions (U-Z) VerGetFileLanguages

Parameters
Table F-17: VerGetFileLanguages Parameters Parameter szFileName Description Specifies the fully qualified name of the file whose list of supported languages is to be retrieved. Returns the list of numeric language codes and code page IDs of the supported languages. Each list element is a 32-bit integer whose low-order word contains the supported language code and whose high-order word contains the corresponding code page ID, which can be extracted with the functions LOWORD and HIWORD. The number list identified by listLanguages must already have been initialized by a call to ListCreate(NUMBERLIST).

listLanguages

Return Values
Table F-18: VerGetFileLanguages Return Values Return Value >= ISERR_SUCCESS Description The function successfully retrieved the list of supported languages. The function failed to retrieve the list of supported languages.

< ISERR_SUCCESS

VerGetFileLanguages Example
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the VerGetFileLanguages function. * \*--------------------------------------------------------------*/ function OnBegin() number nListGetItem, nvLanguageInfo, nLanguageCode, nCodePage; string szFileName; LIST listLanguages, listLanguageCodes, listCodePages; begin // Get file language information. szFileName = "C:\\Program Files\\Internet Explorer\\Iexplore.exe"; listLanguages = ListCreate( NUMBERLIST ); VerGetFileLanguages( szFileName, listLanguages ); // Extract language codes and code page IDs // from list items and add to new lists.

1500

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerGetFileVersion

listLanguageCodes = ListCreate( NUMBERLIST ); listCodePages = ListCreate( NUMBERLIST ); nListGetItem = ListGetFirstItem( listLanguages ,nvLanguageInfo); while nListGetItem=0 nLanguageCode = LOWORD( nvLanguageInfo ); ListAddItem( listLanguageCodes, nLanguageCode, AFTER ); nCodePage = HIWORD( nvLanguageInfo ); ListAddItem( listCodePages, nCodePage, AFTER ); nListGetItem = ListGetNextItem( listLanguages ,nvLanguageInfo); endwhile; end;

VerGetFileVersion
The VerGetFileVersion function retrieves the numeric version information of the specified file.

Note: Although InstallScript's file version functions take version information in string format, the version information they reference in a file is the numeric version information. A file's string version information is not inspected or returned by InstallScript functions. Further, when Windows Explorer displays a file's properties, it shows the string version information, which might not be equivalent to the file's numeric version information. For that reason, the value returned in svVersionNumber by VerGetFileVersion might not match the version information displayed by Windows Explorer.

For more about file version information, consult the Windows documentation.

Syntax
VerGetFileVersion ( szFileName, svVersionNumber );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1501

Appendix F: Built-In Functions (U-Z) VerGetFileVersion

Parameters
Table F-19: VerGetFileVersion Parameters Parameter szFileName Description Specifies the fully qualified name of the file whose numeric version information is to be retrieved. Returns the numeric version information as a string in the following format:
<major version>.<minor version>

svVersionNumber

For example, if svVersionNumber returns 2.1.2.0, the major version number is 2.1 and the minor version number is 2.0.

Return Values
Table F-20: VerGetFileVersion Return Values Return Value 0 Description Indicates that the function successfully returned the version information. Indicates that the specified file was not found. Indicates that the file was found but did not contain version information.

FILE_NOT_FOUND (-2) FILE_NO_VERSION (-8)

VerGetFileVersion Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the VerGetFileVersion function. * * The script below calls VerGetFileVersion to retrieve the * version number of the Windows Notepad. The information is * displayed in a message box. * \*--------------------------------------------------------------*/ #define EXAMPLE_FILE WINDIR ^ "NotePad.exe" #define TITLE_TEXT "VerGetFileVersion Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h"

1502

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerProductCompareVersions

export prototype ExFn_VerGetFileVersion(HWND); function ExFn_VerGetFileVersion(hMSI) NUMBER nResult; STRING szFile, szPath, szMsg, svVersionNumber; begin // Get the version number of the specified file. nResult = VerGetFileVersion(EXAMPLE_FILE, svVersionNumber); // Report the results of VerGetFileVersion. if (nResult = FILE_NO_VERSION) then szMsg = EXAMPLE_FILE + " does not contain version information."; MessageBox (szMsg, INFORMATION); elseif (nResult = FILE_NOT_FOUND) then szMsg = EXAMPLE_FILE + " could not be found."; MessageBox (szMsg, INFORMATION); else szMsg = "The version number of %s is %s"; SprintfBox (INFORMATION, TITLE_TEXT, szMsg, EXAMPLE_FILE, svVersionNumber); endif; end;

VerProductCompareVersions
Project: This information applies to InstallScript projects.

The VerProductCompareVersions function compares version information and returns a value indicating the result of the comparison.

Syntax
VerProductCompareVersions ( );

Parameters
None.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1503

Appendix F: Built-In Functions (U-Z) VerProductGetInstalledVersion

Return Values
Table F-21: VerProductCompareVersions Return Values Return Value VERSION_COMPARE_RESULT_NOT_INSTALL ED Description No version of the product is installed or the installed version was not found (IFX_INSTALLED_VERSION is a null string). The update setup's version is the same as the version currently installed on the target system. The update setup's version is older than the version currently installed on the target system. The update setup's version is newer than the version currently installed on the target system, but the currently installed version is not supported by the update setup. The update setup's version is newer than the version currently installed on the target system, and the currently installed version is supported by the update setup. The function failed.

VERSION_COMPARE_RESULT_SAME

VERSION_COMPARE_RESULT_OLDER

VERSION_COMPARE_RESULT_NEWER_NOT_ SUPPORTED

VERSION_COMPARE_RESULT_NEWER

< ISERR_SUCCESS

Comments
The function compares the values of the system variables IFX_INSTALLED_VERSION and IFX_PRODUCT_VERSION to determine if the version currently installed on the target system is older than the update setup's version; if so, the function compares the values of the system variables IFX_INSTALLED_VERSION and IFX_SUPPORTED_VERSIONS to determine if the update setup applies to the currently installed version. VerProductCompareVersions is called by the default code for the OnSetUpdateMode and OnUpdateUIBefore event handler functions.

VerProductGetInstalledVersion
Project: This information applies to InstallScript projects.

The VerProductGetInstalledVersion function returns in svVersionInstalled the string equivalent of the data in the Version value of the application uninstallation registry key if that data is a packed DWORD.

Syntax
VerProductGetInstalledVersion ( svVersionInstalled );

1504

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerProductIsVersionSupported

Parameters
Table F-22: VerProductGetInstalledVersion Parameters Parameter svVersionInstalled Description Returns the string equivalent of the data in the application uninstallation registry key's Version value. If the function fails, the value of svVersionInstalled is not changed.

Return Values
Table F-23: VerProductGetInstalledVersion Return Values Return Value >= ISERR_SUCCESS Description The function successfully retrieved the installed version information. The function failed to retrieve the installed version information; the registry key or value does not exist or the data is not a packed DWORD.

< ISERR_SUCCESS

VerProductIsVersionSupported
Project: This information applies to InstallScript projects.

The VerProductIsVersionSupported function checks whether the version string in szVersionCheck is one of the versions in szVersionSupported.

Syntax
VerProductIsVersionSupported ( szVersionCheck, szVersionSupported );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1505

Appendix F: Built-In Functions (U-Z) VerProductNumToStr

Parameters
Table F-24: VerProductIsVersionSupported Parameters Parameter szVersionCheck Description Specifies a version string in packed DWORD format (for example, the initial value of the system variable IFX_PRODUCT_VERSION. Specifies a pipe(|)-delimited list of version strings in packed DWORD format (for example, the initial value of the system variable IFX_SUPPORTED_VERSIONS).

szVersionSupported

Return Values
Table F-25: VerProductIsVersionSupported Return Values Return Value TRUE Description szVersionCheck is one of the versions in szVersionSupported, or szVersionSupported is a null string (""). szVersionCheck is not one of the versions in szVersionSupported.

FALSE

VerProductNumToStr
Project: This information applies to InstallScript projects.

The VerProductNumToStr function returns in svVersion the version string corresponding to the packed DWORD specified in nVersion.

Syntax
VerProductNumToStr ( svVersion, nVersion );

1506

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerProductStrToNum

Parameters
Table F-26: VerProductNumToStr Parameters Parameter svVersion Description Returns the string equivalent, in packed DWORD format, of nVersion. Specifies version information as a four-byte value, that is, a number in the range 0 to 4294967295.

nVersion

Return Values
Table F-27: VerProductNumToStr Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description The function succeeded. The function failed.

VerProductStrToNum
Project: This information applies to InstallScript projects.

The VerProductStrToNum function returns in nvVersionResult the packed DWORD version information corresponding to the string specified in svVersion.

Syntax
VerProductStrToNum ( nvVersionResult, szVersion );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1507

Appendix F: Built-In Functions (U-Z) VerProductVerFromVerParts

Parameters
Table F-28: VerProductStrToNum Parameters Parameter nvVersionResult szVersion Description Returns the packed DWORD version information. Specifies version information in string form. The function fails unless szVersion meets all of the following conditions:

szVersion is in the format major.minor.build or major.minor.build.release (release is ignored when determining nvVersionResult). major and minor are the string equivalents of numbers in the range 0 to 255. build is the string equivalent of a number in the range 0 to 65535.

Return Values
Table F-29: VerProductStrToNum Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description The function succeeded. The function failed.

VerProductVerFromVerParts
Project: This information applies to InstallScript projects.

The VerProductVerFromVerParts function retrieves the packed DWORD that corresponds to the version parts specified by nVersionMajor, nVersionMinor, and nVersionBuild.

Syntax
VerProductVerFromVerParts ( nvVersion, nVersionMajor, nVersionMinor, nVersionBuild );

1508

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerProductVerPartsFromVer

Parameters
Table F-30: VerProductVerFromVerParts Parameters Parameter nvVersion Description Returns the four-byte value that corresponds to the version parts specified by nVersionMajor, nVersionMinor, and nVersionBuild. Specifies the first byte of version information. VerProductVerFromVerParts fails if this value is less than zero (0) or greater than 255. Specifies the second byte of version information. VerProductVerFromVerParts fails if this value is less than zero (0) or greater than 255. Specifies the last two bytes of version information. VerProductVerFromVerParts fails if this value is less than zero (0) or greater than 65535.

nVersionMajor

nVersionMinor

nVersionBuild

Return Values
Table F-31: VerProductVerFromVerParts Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description Indicates that the function succeeded. Indicates that the function failed.

VerProductVerPartsFromVer
Project: This information applies to InstallScript projects.

The VerProductVerPartsFromVer function retrieves as separate numeric values the version parts of the packed DWORD specified by nVersion.

Syntax
VerProductVerPartsFromVer ( nVersion, nvVersionMajor, nvVersionMinor, nvVersionBuild );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1509

Appendix F: Built-In Functions (U-Z) VerSearchAndUpdateFile

Parameters
Table F-32: VerProductVerPartsFromVer Parameters Parameter nVersion Description Specifies version information as a four-byte value, that is, a number in the range 0 to 4294967295. Returns the first byte of nVersion. Returns the second byte of nVersion. Returns the last two bytes of nVersion.

nvVersionMajor nvVersionMinor nvVersionBuild

Return Values
Table F-33: VerProductVerPartsFromVer Return Values Return Value ISERR_SUCCESS Description This function always returns ISERR_SUCCESS.

VerSearchAndUpdateFile
The VerSearchAndUpdateFile function searches for the specified file and installs a newer version of the file if necessary. If the function finds the file, it compares the version number of the existing file to the version number of the new file. If the existing file is older, it is replaced with the new file. The new file must be in the directory specified by the system variable SRCDIR. If the function does not find an existing file, it copies the new file to the target system. Windows decides where the file is installed depending on the type of the file. For example, DLLs and system drivers are installed in the Windows system folder. For information about the Windows system folder, see the documentation for the InstallScript system variable WINSYSDIR.
VerFindFileVersion uses the following search algorithm to find the file (searches the folders in the

following order):
1. 2. 3. 4. 5.

Windows folder Windows system folder The folder specified by the TARGETDIR system variable (in InstallScript installations) or the INSTALLDIR system variable (in Basic MSI or InstallScript MSI installations) The folders specified by the PATH environment variable The folder from which Setup.exe is running

Note: For file transfer, an alternative to VerSearchAndUpdateFile is XCopyFilewhich can do check version, mark locked .dll and .exe files for update after system reboot, and increment registry reference counters for shared .dll and .exe files.
1510 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerSearchAndUpdateFile

Syntax
VerSearchAndUpdateFile ( szFileName, nUpdateFlag, svInstalledFile );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1511

Appendix F: Built-In Functions (U-Z) VerSearchAndUpdateFile

Parameters
Table F-34: VerSearchAndUpdateFile Parameters Parameter szFileName Description Specifies the unqualified name of the file to install. Do not specify a drive designation or path in this parameter. Specifies whether the file should be updated unconditionally or only if the version of the file found on the target system is older than the version of the file that you have shipped. Pass one of the following predefined constants in this parameter:

nUpdateFlag

svInstalledFile

VER_UPDATE_CONDUpdates the existing file only if it is an older version. VER_UPDATE_ALWAYSUpdates the existing file even if it is a newer version.

Returns the fully qualified name of the file installed by the function. If the file you want to replace is in use, the file is installed to the same directory with a slightly different name. The file is renamed with a tilde (~) character in the first character of the extension. For example, if you are installing the file Shell.dll and the file is locked, the file is copied as Shell.~ll. The name is returned in this variable.

Return Values
Table F-35: VerSearchAndUpdateFile Return Values Return Value FILE_INSTALLED (0) FILE_IS_LOCKED (-4) Description Function was successful in installing the file. Indicates that the file is in use by Windows and cannot be replaced. The new file is copied to the same directory with a new name. Indicates that the file was found, but it did not contain version information. File update is not performed. Indicates that the existing file is write protected. The script should reset the read-only flag of the destination file before proceeding with the setup and then attempt to install the file again. Indicates that the file to install has the same date or is older than the preexisting file. Indicates that the function cannot create the file due to insufficient disk space on the destination drive. File update is not performed. Indicates Ver.dll was not found. File update is not performed. Indicates an unspecified error occurred. File update is not performed.

FILE_NO_VERSION (-8)

FILE_RD_ONLY (-5)

FILE_SRC_OLD (-7) OUT_OF_DISK_SPACE (-6)

VER_DLL_NOT_FOUND (-3) OTHER_FAILURE (-1)

VerSearchAndUpdateFile Example

1512

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerSearchAndUpdateFile

Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the VerSearchAndUpdateFile function. * * The first call to VerSearchAndUpdateFile replaces the file * specified by the constant UPDATE_FILE1 regardless of the * version on the target system. * * The second call to VerSearchAndUpdateFile replaces the file * specified by the constant UPDATE_FILE2 only if the version * in the source directory is newer than the version in the * target directory. * \*--------------------------------------------------------------*/ #define UPDATE_FILE1 #define UPDATE_FILE2 "Example.txt" "Readme.txt"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_VerSearchAndUpdateFile(HWND); function ExFn_VerSearchAndUpdateFile(hMSI) STRING szFileName, svInstalledFile, szTitle, szMsg; NUMBER nUpdateFlag, nResult; BOOL bDone; begin // Set up title and message parameters for call // to VerSearchAndUpdateFile. szTitle = "VerSearchAndUpdateFile Example"; szMsg = " was successfully updated."; // Update UPDATE_FILE1 regardless of version number. if (VerSearchAndUpdateFile (UPDATE_FILE1, VER_UPDATE_ALWAYS, svInstalledFile) = 0) then SprintfBox (INFORMATION, szTitle, UPDATE_FILE1 + szMsg); endif; // Set indicator to control loop exit. bDone = FALSE; // Begin the while loop. while (bDone = FALSE) // Update UPDATE_FILE2 only if existing file is older. nResult = VerSearchAndUpdateFile (UPDATE_FILE2, VER_UPDATE_COND, svInstalledFile); switch (nResult) case 0: // VerSearchAndUpdate successful. SprintfBox (INFORMATION, szTitle, UPDATE_FILE2 + szMsg); bDone = TRUE; // The target file does not have a version number.
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00 1513

Appendix F: Built-In Functions (U-Z) VerUpdateFile

case FILE_NO_VERSION: // Ask the user if the file should be updated regardless. if (AskYesNo ("Version number was not found.\nDo you still wish " + "to update " + UPDATE_FILE2 + "?", YES) = YES) then // Update the file UPDATE_FILE2 regardless of version number. VerSearchAndUpdateFile (UPDATE_FILE2, VER_UPDATE_ALWAYS, svInstalledFile); bDone = TRUE; else bDone = TRUE; endif; // The target file is locked. case FILE_IS_LOCKED: MessageBox ("The target file is locked.\n\nPlease close all " + "programs and run Setup again.", INFORMATION); bDone = TRUE; // The target file is read-only. case FILE_RD_ONLY: // Ask the user if Setup should remove the read-only attribute. if (AskYesNo ("File is read-only.\nShould Setup remove the " + "write-protection of " + UPDATE_FILE2 + "?", YES) = YES) then // Change the attribute of the target file to normal. SetFileInfo (svInstalledFile, FILE_ATTRIBUTE, FILE_ATTR_NORMAL, ""); bDone = FALSE; else bDone = TRUE; endif; // The target disk does not have enough space. case OUT_OF_DISK_SPACE: MessageBox ("You need more free space for this update.", SEVERE); bDone = TRUE; // The required VER.DLL file was not found. case VER_DLL_NOT_FOUND: MessageBox ("VER.DLL was not found.", SEVERE); bDone = TRUE; // Some other error occurred. case OTHER_FAILURE: MessageBox ("Update has failed.", SEVERE); bDone = TRUE; default: bDone = TRUE; endswitch; endwhile; end;

VerUpdateFile
The VerUpdateFile function uses the version information of a specified file to determine whether or not to install the file on the target directory. VerUpdateFile gets the file name specified in szFileName. VerFindFileVersion uses the following search algorithm to find the file (searches the folders in the following order):
1. 2.
1514

Windows folder Windows system folder

ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerUpdateFile

3. 4. 5.

The folder specified by the TARGETDIR system variable (in InstallScript installations) or the INSTALLDIR system variable (in Basic MSI or InstallScript MSI installations) The folders specified by the PATH environment variable The folder from which Setup.exe is running

VerUpdateFile then compares the version of the file with the same name in SRCDIR (the source file), if it exists, with the version of the target file. If the source file has a more recent version number than the target file, the target file is replaced by the source file. If the target file does not exist, InstallShield copies the source file to the target location. When the SHAREDFILE or LOCKEDFILE option is used in the parameter nUpdateFlag and .dll or .exe files to be updated are in use by the system, renamed copies of the source files are transferred to the target system and the system variable BATCH_INSTALL is set to TRUE. Then, when RebootDialog or SdFinishReboot is called at the end of the setup and the system is restarted, the locked files are updated. For more information on updating locked files, see RebootDialog and SdFinishReboot. The system variable BATCH_INSTALL can be tested to determine if locked .dll or .exe files were encountered. You cannot use the SHAREDFILE and LOCKEDFILE options simultaneously-you must use one or the other. For file transfer, preferable alternatives to VerUpdateFile may be XCopyFile, which can perform version checking, mark locked .dll and .exe files for update after system reboot, and increment registry reference counters for shared .dll and .exe files.

Syntax
VerUpdateFile ( szFileName, nUpdateFlag, svInstalledFilePath );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1515

Appendix F: Built-In Functions (U-Z) VerUpdateFile

Parameters
Table F-36: VerUpdateFile Parameters Parameter szFileName Description Specifies the qualified or unqualified name of the file to update. If the name is unqualified (that is, if it does not include a drive designation or path), InstallShield searches the Windows or Win95 directory, the System directory, the directories specified by the PATH environment variable, and then the path of the InstallShield executable file for a matching file. VerUpdateFile takes the file name portion of szFileName and uses it to identify the file in SRCDIR that is used as the source file. Specifies whether the file is updated unconditionally or updated only if the version of the target file found is older than the version of the source file. Pass one of the following predefined constants in this parameter. You can combine the constant SHAREDFILE with one of the other constants using the bitwise OR operator ( | ). However, you cannot combine SHAREDFILE and LOCKEDFILE.

nUpdateFlag

LOCKEDFILECauses VerUpdateFile to record locked .dll and .exe files for update when Windows or the system is rebooted. A locked file is a file that is in use by an application or the system when InstallShield attempts to access or update the file. The LOCKEDFILE option works like SHAREDFILE except that LOCKEDFILE does not create registry entries or modify the registry reference counter. You cannot use the LOCKEDFILE option when using the SHAREDFILE option. There are some unshared files (such as shell extensions) for which the script writer does not want a registry entry and reference counter. These files should never be uninstalled, except by the application itself. LOCKEDFILE allows VerUpdateFile to handle locked files that are not shared. SHAREDFILECombines shared and locked file handling by causing VerUpdateFile to treat all files as shared, and to record locked .dll and .exe files for update when Windows or the system restarts. See RebootDialog and SdFinishReboot. The SHAREDFILE option causes VerUpdateFile to treat all files as shared files and increment the registry reference counter by one when the file exists in the target directory and it has a reference count greater than 0. If the shared file does not exist in the target directory and it has no reference counter, InstallShield creates the counter and sets it to 1. If the shared file already exists in the target directory but has no reference counter, InstallShield creates the counter and initializes it to 2 as a precaution against accidental removal during uninstallation.

nUpdateFlag (continued)

SELFREGISTERCarries out the self-registration process immediately, when using the non-batch method of installing self-registering files. If you have called Enable(SELFREGISTERBATCH), this option queues up selfregistering files for registration. The files are registered once Do(SELFREGISTRATIONPROCESS) is called, when using the batch method of installing self-registering files. Always use SELFREGISTER together with the constant SHAREDFILE, using the bitwise OR operator ( | ).

VER_UPDATE_ALWAYSUpdates the file regardless of the version numbers. VER_UPDATE_CONDUpdates the file only if the file being replaced is an older version.

1516

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) VerUpdateFile

Table F-36: VerUpdateFile Parameters (cont.) Parameter svInstalledFilePath Description Returns the fully qualified name of the file that was installed. If the file you want to replace is in use, the file is installed to the same directory with a modified name. InstallShield uses a tilde (~) character to replace the first character of the file's extension. For example, if you are updating the file Shell.dll and the target file is locked, the source file is copied to the target directory as Shell.~ll. This name is returned in the parameter svInstalledFilePath. If the SHAREDFILE option is used in the parameter nUpdateFlag and locked files are properly committed for update when Windows or the system restarts, the ~ modified name versions of the files are deleted when the update takes place.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1517

Appendix F: Built-In Functions (U-Z) VerUpdateFile

Return Values
Table F-37: VerUpdateFile Return Values Return Value FILE_INSTALLED (0) Description Indicates that the function successfully installed the file. This constant is equal to 0 (zero). All other return values are less than zero (< 0). Indicates that the existing file is in use by Windows and cannot be replaced. The new file is copied to the same directory with a new name, as described above. Indicates that the file was found, but it did not contain version information in it. File update is not performed. Indicates that the existing file is write-protected. You must reset the read-only bit in the destination file before proceeding with the setup, and then attempt to install the file again. Indicates that the file you want to install has the same version as the existing file. File update is not performed if the VER_UPDATE_COND flag is set. Indicates that the file you want to install is older than the existing file. File update is not performed if the VER_UPDATE_COND flag is set. Indicates that the function cannot create the file due to insufficient disk space on the destination drive. File update is not performed. A self-registering file did not register successfully. Indicates an unspecified error occurred. File update is not performed.

FILE_IS_LOCKED (-4)

FILE_NO_VERSION (-8)

FILE_RD_ONLY (-5)

FILE_SRC_EQUAL (-9)

FILE_SRC_OLD (-7)

OUT_OF_DISK_SPACE (-6)

-51 OTHER_FAILURE (-1)

VerUpdateFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the VerUpdateFile function. * * This script calls VerUpdateFile twice to update a Windows * accessory. * \*--------------------------------------------------------------*/ #define APPFILE "Notepad.exe" #define TITLE "VerUpdateFile Example" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h"

1518

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) WaitForApplication

export prototype ExFn_VerUpdateFile(HWND); function ExFn_VerUpdateFile(hMSI) STRING svInstalledFilePath, szTitle, szMsg; NUMBER nResult; BOOL bDone; begin // Update the file regardless of file version. nResult = VerUpdateFile (APPFILE, VER_UPDATE_ALWAYS, svInstalledFilePath); if (nResult < 0) then MessageBox ("First call to VerUpdateFile failed.", SEVERE); else szMsg = "%s successfully updated."; SprintfBox (INFORMATION, TITLE, szMsg, APPFILE); endif; // Update the files only if the target files are more recent. nResult = VerUpdateFile (APPFILE, VER_UPDATE_COND, svInstalledFilePath); if (nResult < 0) then MessageBox ("Second call to VerUpdateFile failed.", SEVERE); endif; end;

WaitForApplication
The WaitForApplication function waits for a running application to terminate before returning. If the function fails to wait for the application to terminate before returning, verify that the application does not terminate until other sub-applications launched by the application terminate. The WaitForApplication function monitors the process handle of the specified application; if the application passes control to a secondary application or process and then terminates, the function returns immediately.

Syntax
WaitForApplication( byval number hProcess, byval number dwProcessId, byval number nTimeOut, byval number nOptions );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1519

Appendix F: Built-In Functions (U-Z) WaitForApplication

Parameters
Table F-38: WaitForApplication Parameters Parameter hProcess Description Specifies the process handle of the running process for which to wait. (If the application was launched with LaunchAppAndWait or LaunchApp, this handle is returned in the LAAW_PROCESS_INFORMATION.hProcess member.) Specifies the process ID of the running process for which to wait. You need to specify a non-zero value for this parameter only if you specify LAAW_OPTION_WAIT_INCL_CHILD in nOptions. If the application was launched with LaunchAppAndWait or LaunchApp and the process ID can be determined (as described for the description of LAAW_OPTION_WAIT_INCL_CHILD), this handle is returned in the LAAW_PROCESS_INFORMATION.dwProcessId member. nTimeOut Specifies the maximum amount of time (in milliseconds) to wait for the application to complete before returning. If this amount of time passes before the application terminates, the function ends the wait and returns failure. You can specify INFINITE to indicate that the function should wait indefinitely. (You can also pass the LAAW_PARAMTERS.nTimeOut value to mimic the behavior of the LaunchAppAndWait function.)

dwProcessId

1520

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) WaitForApplication

Table F-38: WaitForApplication Parameters (cont.) Parameter nOptions Description Pass one of the following predefined constants in this parameter. You can combine these constants by using the bitwise OR operator ( | ), with the following exceptions: you cannot combine LAAW_OPTION_NOWAIT with LAAW_OPTION_WAIT.

LAAW_OPTION_WAITSpecifies that the function should wait until the specified application has terminated.

Note: If the specified applications fails to terminate and nOptions is set to LAAW_OPTION_WAIT (and nTimeOut is set to INFINITE), the installation will wait indefinitely for the launched application to complete.

LAAW_OPTION_NOWAITSpecifies that the function should return immediately. LAAW_OPTION_USE_CALLBACKCauses the function to call the OnLaunchAppAndWaitCallback event every second, or whatever interval you set for the LAAW_PARAMETERS.nCallbackInterval member, while waiting for the application to terminate. LAAW_OPTION_WAIT_INCL_CHILDIndicates that the function should wait for the launched application and any of its direct child processes. When LAAW_OPTION_WAIT_INCL_CHILD is used, the function detects and waits for only direct child processes of the launched processnot for any additional child processes that are launched by child processes of the initially launched process. Note that to detect and wait for child processes with LAAW_OPTION_WAIT_INCL_CHILD, the function must receive or be able to determine the process ID of the launched process. Therefore, in order for this option to work, if dwProcessId is not specified, the Windows API GetProcessId must be available on the system so that the function can determine the process ID. According to the Windows API documentation, GetProcessId is available on Windows XP SP1 and later and Windows Server 2003 and later. If this API is not available, LAAW_OPTION_WAIT_INCL_CHILD behaves as LAAW_OPTION_WAIT.

You can specify any LaunchApplication option; however, only the aforementioned options will have any effect.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1521

Appendix F: Built-In Functions (U-Z) WaitOnDialog

Return Values
Table F-39: WaitForApplication Return Values Return Value >= ISERR_SUCCESS < ISERR_SUCCESS Description The application terminated and the function returned as a result. The function returned as a result of something other than the application terminating. You can check the value of LAAW_PARAMETERS.nWaitResult to determine additional information:

WAIT_OBJECT_0Indicates that the application terminated. WAIT_OBJECT_0 + 1Indicates that the installation received a message to terminate. WAIT_TIMEOUTIndicates that the timeout interval was reached or the callback function returned LAAW_CALLBACK_RETURN_END_WAIT. Check the value of LAAW_PARAMETERS.bCallbackEndedWait to determine which ended the wait.

WaitOnDialog
The WaitOnDialog function displays a custom dialog. You can write your script to handle different responses from the user based on the return value from this function.

Syntax
WaitOnDialog ( szDlgName );

1522

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) WaitOnDialog

Parameters
Table F-40: WaitOnDialog Parameters Parameter szDlgName Description Specifies the ID of the dialog to display.

Return Values
Table F-41: WaitOnDialog Return Values Return Value dialog control ID IDCANCEL (2) DLG_ERR (-1) DLG_INIT (-100) Description The ID of the dialog control that received the WM_COMMAND message. This message is received as a signal that the dialog is about to close. This message is received if any errors occurred. This message is received immediately before the dialog is displayed.

Additional Information
To enable end users to cancel the installation by clicking the close button in the upper-right corner of the InstallScript dialog, the dialog must have a button control whose Control Identifier property is set to 2. For more information, see Using InstallScript to Implement Custom Dialogs.

WaitOnDialog Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the DefineDialog, WaitOnDialog, EndDialog, and * ReleaseDialog functions. * * This script opens a simple custom dialog that displays * a bitmap. The dialog can be closed with any of three * buttons: Back, Next, or Cancel. * * The "custom" dialog used in this script is actually the * InstallShield Sd dialog that is displayed by the built-in * function SdBitmap. Because this dialog is stored in * the file _isres.dll, which is already compressed in * the installation, it can be used in a script as a custom * dialog. * * In order to use this dialog as a custom dialog, the

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1523

Appendix F: Built-In Functions (U-Z) WaitOnDialog

* script first defines it by calling DefineDialog. It then * displays the dialog by calling WaitOnDialog. When an event * ends dialog processing, EndDialog is called to close the * dialog. Then the dialog is released from memory by * a call to ReleaseDialog. * \*--------------------------------------------------------------*/ // Dialog and control IDs. #define RES_DIALOG_ID 12027 #define RES_PBUT_NEXT 1 #define RES_PBUT_CANCEL 9 #define RES_PBUT_BACK 12

// // // //

ID ID ID ID

of of of of

dialog itself Next button Cancel button Back button

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_WaitOnDialog(HWND); function ExFn_WaitOnDialog(hMSI) STRING szDialogName, szDLLName, szDialog; NUMBER nDialog, nResult, nCmdValue; BOOL bDone; HWND hInstance, hwndParent; begin // Define the name of a dialog to pass as first // parameter to DefineDialog. szDialogName = "ExampleDialog"; // DefineDialog's second parameter will be 0 because the // dll is in _isres.dll. hInstance = 0; // DefineDialog's third parameter will be null; installation // will search for the dialog in _isuser.dll and _isres.dll. szDLLName = ""; // DefineDialog's fifth parameter will be null because the // dialog is identified by its ID in the fourth parameter. szDialog = ""; // This value is reserved and must be 0. hwndParent = 0; // Define the dialog. The installation's main window will own // the dialog (indicated by HWND_INSTALL in parameter 7). nResult = DefineDialog (szDialogName, hInstance, szDLLName, RES_DIALOG_ID, szDialog, hwndParent, HWND_INSTALL, DLG_MSG_STANDARD|DLG_CENTERED); // Check for an error. if (nResult < 0) then MessageBox ("An error occurred while defining the dialog.", SEVERE); bDone = TRUE; abort; endif; // Initialize the indicator used to control the while loop. bDone = FALSE; // Loop until done.
1524 ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) Welcome

repeat // Display the dialog and return the next dialog event. nCmdValue = WaitOnDialog(szDialogName); // Respond to the event. switch (nCmdValue) case DLG_CLOSE: // The user clicked the window's Close button. Do (EXIT); case DLG_ERR: MessageBox ("Unable to display dialog. Setup canceled.", SEVERE); abort; case DLG_INIT: // Initialize the back, next, and cancel button enable/disable states // for this dialog and replace %P, %VS, %VI with // IFX_PRODUCT_DISPLAY_NAME, IFX_PRODUCT_DISPLAY_VERSION, and // IFX_INSTALLED_DISPLAY_VERSION, respectively, on control IDs 700-724 // and 202. hwndDlg = CmdGetHwndDlg("szDialogName"); SdGeneralInit("szDialogName", hwndDlg, 0, ""); case RES_PBUT_CANCEL: // The user clicked the Cancel button. Do (EXIT); case RES_PBUT_NEXT: bDone = TRUE; case RES_PBUT_BACK: bDone = TRUE; endswitch; until bDone; // Close the dialog. EndDialog (szDialogName); // Free the dialog from memory. ReleaseDialog (szDialogName); end;

Welcome
Project: This information applies to the following project types:

InstallScript InstallScript MSI

The Welcome function displays a dialog that welcomes the end user. In a procedural script, you must call SdProductName before calling Welcome so that InstallShield can insert the product name into the first paragraph of message text in the Welcome dialog. In an eventbased script, SdProductName is called automatically, with the PRODUCT_NAME string entry as its argument, before the Begin event. If you do not pass a product name using SdProductName, InstallShield cannot insert the product name but inserts extra spaces instead.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1525

Appendix F: Built-In Functions (U-Z) Welcome

Syntax
Welcome ( szTitle, nReserved );

Parameters
Table F-42: Welcome Parameters Parameter szTitle Description Specifies the title of this dialog. To display the default title Welcome, pass a null string ("") in this parameter. Pass 0 in this parameter.

nReserved

Return Values
Table F-43: Welcome Return Values Return Value NEXT (1) BACK (12) <0 Description Indicates that the end user clicked the NEXT button. Indicates that the end user clicked the BACK button. Indicates that Welcome failed to display the dialog.

Additional Information
To view an example of this or other dialogs for your installation, use the Dialog Sampler. In InstallShield, on the Tools menu, point to InstallScript, then click Standard Dialog Sampler or Skinned Dialog Sampler.

Welcome Example
Project: This information applies to the following project types:

InstallScript InstallScript MSI

/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the Welcome function. * * This script displays the installation Welcome dialog. * \*--------------------------------------------------------------*/ #define PRODUCT "ExampleProduct"

1526

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) WizardDirection

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_Welcome(HWND); function ExFn_Welcome(hMSI) STRING svLogFile; begin SdProductName ( PRODUCT ); // Display the Welcome dialog. if (Welcome ("Welcome Dialog Example", 0) < 0) then MessageBox ("Welcome dialog failed.", SEVERE); endif; end;

WizardDirection
Project: This information applies to InstallScript projects.

The WizardDirection function is called in an object script to report the argument that was passed to the most recent call in the main setup's (or parent object's) script to the ShowObjWizardPages function or one of the object's ShowxxxxxUIyyyyy methods.

Syntax
WizardDirection ( );

Parameters
None.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1527

Appendix F: Built-In Functions (U-Z) WriteArrayProperty

Return Values
Table F-44: WizardDirection Return Values Return Value NEXT Description Indicates that NEXT was passed as the argument in the most recent call in the main setup's (or parent object's) script to the ShowObjWizardPages function or one of the object's ShowxxxxxUIyyyyy methods. Indicates that BACK was passed as the argument in the most recent call in the main setup's (or parent object's) script to the ShowObjWizardPages function or one of the object's ShowxxxxxUIyyyyy methods.

BACK

Additional Information
The purpose of WizardDirection is to report the direction in which the end user was moving through the dialog sequence at the most recent transition to the object's dialog sequence from the main setup's (or parent object's) dialog sequence. For more information, see Creating the Object's Run-Time User Interface.

WriteArrayProperty
Project: This information applies to InstallScript projects.

The WriteArrayProperty function is called in an object script to enter a value for a specified property whose value is an array.

Syntax
WriteArrayProperty ( nPropertyBag, szPropertyName, ArrayPointer );

1528

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) WriteBoolProperty

Parameters
Table F-45: WriteArrayProperty Parameters Parameter nPropertyBag Description Specifies a reference to the object's property bag object, in which property values are stored. Specifies the name of the property whose value you want to enter. Specifies a pointer to the array property.

szPropertyName ArrayPointer

Return Values
Table F-46: WriteArrayProperty Return Values Return Value 0 Description This function always returns zero (0).

WriteBoolProperty
Project: This information applies to InstallScript projects.

The WriteBoolProperty function is called in an object script to enter a value for a specified property whose value is a Boolean.

Syntax
WriteBoolProperty ( nPropertyBag, szPropertyName, bPropertyValue );

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1529

Appendix F: Built-In Functions (U-Z) WriteBytes

Parameters
Table F-47: WriteBoolProperty Parameters Parameter nPropertyBag Description Specifies a reference to the object's property bag object, in which property values are stored. Specifies the name of the property whose value you want to enter. Specifies the value of the property.

szPropertyName bPropertyValue

Return Values
Table F-48: WriteBoolProperty Return Values Return Value 0 Description This function always returns zero (0).

WriteBytes
The WriteBytes function writes a specific number of bytes to a file opened in the binary mode. This function starts writing bytes at the current file pointer location.

Note: Before calling WriteBytes, you must open the file by calling OpenFileMode(FILE_MODE_BINARY) and then calling OpenFile.

The parameter nIndex is an index into svString; nBytes specifies how many bytes beyond the value of nIndex you want to write to the file. If nIndex plus nBytes exceeds the length of svString, InstallShield writes only the number of bytes from the index into the string to the end of the string. For example, if svString is 100 bytes long, nIndex is 50 and nBytes is 75, only the bytes between 51 and 100 (50 bytes instead of 75 bytes) are written to the file.

Syntax
WriteBytes (nFile, svString, nIndex, nBytes);

1530

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) WriteBytes

Parameters
Table F-49: WriteBytes Parameters Parameter nFile svString nIndex Description Specifies the file handle of a file that has been opened in binary mode. Specifies the string variable that contains the bytes to write to the output file. Specifies an index into svString. The bytes starting at this location are written to the output file. Note that the first byte is at index location 0. Specifies the number of bytes you want to write to the output file.

nBytes

Return Values
Table F-50: WriteBytes Return Values Return Value X <0 Description Where X is the number of bytes actually written. Indicates that the function was unable to write the bytes.

WriteBytes Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the WriteBytes function. * * WriteBytes is called to write a company name to a binary file. * * Note: Before running this script, set the preprocessor * constants so that they reference an existing directory * and file on the target system. Because the script will * write to this file -- overwriting any existing data -* you should create a file or make a copy of an existing * file for use with this example. * \*--------------------------------------------------------------*/ #define EXAMPLE_DIR "C:\\" #define EXAMPLE_FILE "ISExampl.bin" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h"

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1531

Appendix F: Built-In Functions (U-Z) WriteLine

export prototype ExFn_WriteBytes(HWND); function ExFn_WriteBytes(hMSI) STRING szQuestion, svCompany[28]; NUMBER nFileHandle, nOffset, nIndex, nBytes; begin // Set the file open mode. OpenFileMode (FILE_MODE_BINARY); // Open the file and get the file handle. if (OpenFile (nFileHandle, EXAMPLE_DIR, EXAMPLE_FILE) < 0) then MessageBox ("Unable to open the file.", SEVERE); abort; endif; // Ask user for his or her company name. szQuestion = "Please enter your company name. You may enter up to " + "twenty-seven characters."; AskText (szQuestion, "My Software Company", svCompany); // Move the file pointer 15 bytes from the start of the file. nOffset = 15; SeekBytes (nFileHandle, nOffset, FILE_BIN_START); // Write the company name to the file. nIndex = 0; nBytes = 27; if (WriteBytes (nFileHandle, svCompany, nIndex, nBytes) < 0) then MessageBox ("WriteBytes failed.", SEVERE); else MessageBox ("Bytes successfully written to file.", INFORMATION); endif; // Close the file. CloseFile (nFileHandle); end;

WriteLine
The WriteLine function writes a line of text to a text file opened in append mode. You must first set the file mode to append mode with OpenFileMode, and then either create the file with CreateFile, or open the file with OpenFile, before calling WriteLine. This function places the line at the end of the file.
WriteLine produces lines that have a carriage return and line feed character at the end of the line. To write to a binary file, use WriteBytes.

Caution: This function does not work with files opened in read-only mode.

Syntax
WriteLine ( nvFileHandle, szLine );

1532

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) WriteLine

Parameters
Table F-51: WriteLine Parameters Parameter nvFileHandle Description Specifies the file handle of an open file. The handle is obtained from OpenFile or CreateFile. Specifies a string that contains the text to write to the file.

szLine

Note: You can embed double quotation marks inside a string by delimiting the string with single quotation marks. For example, if you want to write the string "This string contains a double "quotation mark."", you can use the following code:
WriteLine(nvFileHandle, 'This string contains a double "quotation mark."');

Caution: Do not attempt to write multiple lines by embedding newline characters in the string you pass in szLine. The following code writes the string as one line, with an unprintable character between "one" and "This":
szString = "This is line one\nThis is two"; WriteLine(nvFileHandle, szString);

To write two lines with one call to WriteLine, you must embed a return and a newline (in that order):
szString = "This is line one\r\nThis is two";

Return Values
Table F-52: WriteLine Return Values Return Value 0 <0 Description Indicates that the function successfully wrote the line to the file. Indicates that the function was unable to write the line to the file.

WriteLine Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the CreateFile and WriteLine functions.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1533

Appendix F: Built-In Functions (U-Z) WriteLine

* * Createfile is called to create a file to store a string. The * string is written into the file by the WriteLine function. * * Note: Before running this script, set the preprocessor * constant EXAMPLE_DIR so that it references an existing * directory on the target system. Note that if the file * specified by EXAMPLE_FILE already exists, it will be * overwritten. * \*--------------------------------------------------------------*/ #define EXAMPLE_DIR "C:\\" #define EXAMPLE_FILE "ISExampl.txt" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_WriteLine(HWND); function ExFn_WriteLine(hMSI) STRING szTitle, szMsg; NUMBER nvFileHandle; begin // Set the file mode to append. OpenFileMode (FILE_MODE_APPEND); // Create a new file and leave it open. if (CreateFile (nvFileHandle, EXAMPLE_DIR, EXAMPLE_FILE) < 0) then // Report the error. MessageBox ("CreateFile failed.", SEVERE); abort; else // Set the message to write to the file. szMsg = "This line was appended by an example InstallShield script."; // Append the message to the file. if (WriteLine(nvFileHandle, szMsg) < 0) then // Report the error. MessageBox ("WriteLine failed.", SEVERE); else // Report success. szTitle = "CreateFile & WriteLine"; szMsg = "Successfully created and wrote to %s."; SprintfBox (INFORMATION, szTitle, szMsg, EXAMPLE_FILE); endif; endif; // Close the file. CloseFile (nvFileHandle); end;

1534

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) WriteNumberProperty

WriteNumberProperty
Project: This information applies to InstallScript projects.

The WriteNumberProperty function is called in an object script to enter a value for a specified property whose value is a number.

Syntax
WriteNumberProperty ( nPropertyBag, szPropertyName, nPropertyValue );

Parameters
Table F-53: WriteNumberProperty Parameters Parameter nPropertyBag Description Specifies a reference to the object's property bag object, in which property values are stored. Specifies the name of the property whose value you want to enter. Specifies the value of the property.

szPropertyName

nPropertyValue

Return Values
Table F-54: WriteNumberProperty Return Values Return Value 0 Description This function always returns zero (0).

WriteProfInt
Tip: All INI file changes should be created in the INI Files view of the IDE. Handling all of your INI file changes in this way allows for a clean uninstallation through the Windows Installer service.

The WriteProfInt function modifies an .ini file by inserting or updating a profile string that assigns an integer value to a key. Note the following important points:

Because of the way in which Windows caches file changes, you should flush the cache buffer after calls to WriteProfString. Changes made to .ini files can be logged for uninstallation. To write a string value to an .ini file, call WriteProfString instead.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1535

Appendix F: Built-In Functions (U-Z) WriteProfInt

Use the AddProfString and ReplaceProfString functions when you want to modify the System.ini file.

Syntax
WriteProfInt ( szFileName, szSectionName, szKeyName, iValue );

Parameters
Table F-55: WriteProfInt Parameters Parameter szFileName Description Specifies the name of the .ini file. If the file name is unqualified (that is, if a drive designation and path are not included), InstallShield searches for the file in the Windows folder. If the file does not exist, it is created in the specified folder; if a path is not included in file name, the file is created in the Windows folder. Note that if the file name is qualified with a path that does not exist, WriteProfInt will fail. Specifies the name of the .ini file section in which szKeyName will be inserted or modified. The section name should not be enclosed within delimiting brackets ( [ ] ). The search for this name is not case sensitive. Specifies the unique key to be updated. If a key that is to be updated does not exist in the specified section, it is created.

szSectionName

szKeyName

Note: To delete an entire section from an .ini file, pass a null string ("") in szKeyName. To delete one or more keys from a section in an .ini file, use WriteProfString. iValue Specifies an integer value to assign to the unique key identified by szKeyName.

Return Values
Table F-56: WriteProfInt Return Values Return Value 0 <0 Description Indicates that the function successfully updated the specified .ini file. Indicates that the function was unable to update the specified .ini file.

Additional Information
The WriteProfInt function uses the Windows API WritePrivateProfileString to access the .ini file. Therefore, its functionality is limited by the functionality provided by the Windows API. Consult Microsoft documentation for more information on .ini files. Windows 95 and later cache .ini files, which can cause a delay in writing changes to the specified files. This in turn can interfere with subsequent file operations, such as calls to CopyFile and XCopyFile. Therefore, you should flush the cache buffer after using WriteProfInt if you are using file
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

1536

Appendix F: Built-In Functions (U-Z) WriteProfInt

operations shortly afterward. Simply call WriteProfInt with null parameters to force Windows 95 or later to write the data to the .ini file immediately, as shown below:
WriteProfInt ("c:\\Test.ini", "Windows", "KeyboardDelay", 100); WriteProfInt ("", "", "", 0); // null string in first three parameters //CopyFile should now have access to updated file. CopyFile ("c:\\test.ini", "d:\\test.ini");

WriteProfInt Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the WriteProfInt function. * * This script updates an integer value in an initialization file * in the Windows directory. If the file does not exist, it is * created. * \*--------------------------------------------------------------*/ // Define the initialization file name. #define EXAMPLE_INI WINDIR^"ISExampl.ini" // Define the initialization item and its new value. #define SECTION "Windows" #define KEYNAME "OurAppVal" #define KEYVAL 0 // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_WriteProfInt(HWND); function ExFn_WriteProfInt(hMSI) begin // Update a field in the initialization file. if (WriteProfInt (EXAMPLE_INI, SECTION, KEYNAME, KEYVAL) // Report the error. SprintfBox (SEVERE, "WriteProfString", "%s could not be updated", EXAMPLE_INI); else // Report success. SprintfBox (INFORMATION, "WriteProfString", "%s was modified.", EXAMPLE_INI); endif; end;

< 0 ) then

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1537

Appendix F: Built-In Functions (U-Z) WriteProfString

WriteProfString
The WriteProfString function writes a profile string to an .ini file. Depending on the values passed to WriteProfString, it can create a section, delete an entire section, create a unique KEY=VALUE entry, delete a KEY=VALUE entry, or update a key's value. Note the following important points:

To write an integer value to an .ini file, call WriteProfInt instead. Use the AddProfString and ReplaceProfString functions when you want to modify the System.ini file. Changes made to .ini files can be logged for uninstallation. However, there are some important restrictions to be aware of. For more information, see Uninstalling Initialization (.ini) File Entries. WriteProfString uses the Windows API WritePrivateProfileString to access the .ini file. Therefore, its functionality is limited by the functionality provided by the Windows API. Consult Windows programming documentation for more information on .ini files. Windows caches .ini files, which can cause a delay in writing changes to the specified files. This in turn can interfere with subsequent file operations, such as calls to CopyFile and XCopyFile. Therefore, you should flush the cache buffer after using WriteProfString if you are using file operations shortly afterward. Simply call WriteProfString with null parameters to force Windows to write the data to the .ini file immediately:
WriteProfString ("C:\\Test.ini", "Windows", "KeyboardDelay", "100"); WriteProfString ("", "", "", ""); // null string for all four parameters // CopyFile should now have access to updated file. CopyFile ("C:\\Test.ini", "C:\\Temp\\Test.ini");

Syntax
WriteProfString ( szFileName, szSectionName, szKeyName, szValue );

1538

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) WriteProfString

Parameters
Table F-57: WriteProfString Parameters Parameter szFileName Description Specifies the name of the .ini file. If the file name is unqualified (that is, if a drive designation and path are not included), InstallShield searches for the file in the Windows folder. If the file does not exist, it is created in the specified folder; if a path is not included in file name, the file is created in the Windows folder. Note that if the file name is qualified with a path that does not exist, WriteProfString will fail. Specifies the name of the .ini file section to search for szKeyName. The section name should not be enclosed within delimiting brackets ( [ ] ). The search for this name is not case sensitive. Specifies the unique key to be updated or deleted. If a key that is to be updated does not exist, it is created. To delete the key specified here, pass a null string ("") in szValue. To delete the entire section specified by szSectionName, including all entries within that, pass a null string ("") in this parameter. Specifies the value to assign to the unique key identified by szKeyName. To delete the key, pass a null string ("") in this parameter. To delete the value of the key but retain the key itself, pass a blank space in this parameter.

szSectionName

szKeyName

szValue

Return Values
Table F-58: WriteProfString Return Values Return Value 0 Description Indicates that the function successfully wrote the string to the specified .ini file. Indicates that the function was unable to write the string to the specified .ini file.

<0

WriteProfString Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the WriteProfString function. *

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1539

Appendix F: Built-In Functions (U-Z) WriteStringProperty

* This script updates a field in an initialization file in the * Windows directory. If the file does not exist, it is created. * \*--------------------------------------------------------------*/ // Define the initialization file name. #define EXAMPLE_INI WINDIR ^ "ISExampl.ini" // Define the initialization item and its new value. #define SECTION "Windows" #define KEYNAME "Keyboard" #define KEYVALUE "English" // Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_WriteProfString(HWND); function ExFn_WriteProfString(hMSI) begin // Update a field in the initialization file. if (WriteProfString (EXAMPLE_INI, SECTION, KEYNAME, KEYVALUE) < 0) then // Report the error. SprintfBox (SEVERE, "WriteProfString", "%s could not be updated", EXAMPLE_INI); else // Report success. SprintfBox (INFORMATION, "WriteProfString", "%s was modified.", EXAMPLE_INI); endif; end;

WriteStringProperty
Project: This information applies to InstallScript projects.

The WriteStringProperty function is called in an object script to enter a value for a specified property whose value is a string.

Syntax
WriteStringProperty ( nPropertyBag, szPropertyName, szPropertyValue );

1540

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) XCopyFile

Parameters
Table F-59: WriteStringProperty Parameters Parameter nPropertyBag Description Specifies a reference to the object's property bag object, in which property values are stored. Specifies the name of the property whose value you want to enter. Specifies the value of the property.

szPropertyName

szPropertyValue

Return Values
Table F-60: WriteStringProperty Return Values Return Value 0 Description This function always returns zero (0).

XCopyFile
The XCopyFile function copies one or more files from a source directory to a target directory. The function creates and logs the target directory if necessary. This function can copy subdirectories as well as files. XCopyFile creates subdirectories on the target directory if necessary when the constant INCLUDE_SUBDIR is passed in the parameter nOp. If you are copying files to WINSYSDIR64, you must first disable file system redirection using WOW64FSREDIRECTION. Otherwise, files being copied to WINSYSDIR64 are incorrectly redirected to the 32-bit Windows system folder. Since some Windows functionality that could be used by the installation requires that redirection be enabled to work, Windows documentation recommends that you disable redirection only for as long as necessary. It is recommended that you then enable file system redirection as soon as you have completed installing the necessary files to WINSYSDIR64. You cannot rename files using XCopyFile. To rename a file during a file copy operation, use the CopyFile function.

Tip: It is strongly recommended that you disable the Cancel button using the Disable function before calling the XCopyFile function if the status dialog is displayed during the copy. If you do not disable the Cancel button and the end user cancels during the copy file operation, the OnCancelling event handler is not called. Instead, the copy file operation returns a failure error code, which your script must handle by calling the appropriate event and then relaunching the copy file operation. You can enable and disable the Cancel button using the Enable and Disable functions.

Note: If you use unqualified file names and set values for SRCDIR and TARGETDIR when using XCopyFile, save the current values using VarSave before calling XCopyFile and then restore them using VarRestore.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1541

Appendix F: Built-In Functions (U-Z) XCopyFile

Syntax
XCopyFile ( szSrcFile, szTargetPath, nOp );

1542

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) XCopyFile

Parameters
Table F-61: XCopyFile Parameters Parameter szSrcFile Description Specifies which files to copy. If the file specified is qualifiedif it includes a path XCopyFile copies the file from the specified location. If szSrcFile contains an unqualified file namewithout path informationXCopyFile copies from the folder that is identified by the system variable SRCDIR. To copy multiple files, use wildcard characters in this parameter. Specifies the directory to which the files specified by szSrcFile should be copied. If this parameter contains a null string (""), the files are copied to the directory that is specified by the system variable TARGETDIR (in InstallScript installations) or INSTALLDIR (in Basic MSI and InstallScript MSI installations). Specifies the type of copy operation to perform. Pass one of the following predefined constants in this parameter. To specify more than one option, combine constants with the OR (|) operator.

szTargetPath

nOp

COMP_NORMALCopies files to the target system, updating existing samenamed files regardless of date, time, or version information. COMP_UPDATE_SAMEUpdate the files even if the date, time, or version of the source file is identical to the target file. You must also specify either COMP_UPDATE_DATE or COMP_UPDATE_VERSION with this constant. Otherwise, this constant is ignored. COMP_UPDATE_DATEUpdates the files based on the file date and time. This constant updates the file if the source file is newer than the target file. COMP_UPDATE_VERSIONUpdates the files based on the file version. This constant updates the file if the source file is newer than the target file. If the file version does not exist in both the source and the target files, date and time are used for comparison. If the file version does not exist for only one file, InstallShield treats the file containing version information as the newer file. SELFREGISTERCarries out the self-registration process immediately, when using the "non-batch method" of installing self-registering files. If you have called Enable(SELFREGISTERBATCH), this option queues up selfregistering files for registration. The files are registered once Do(SELFREGISTRATIONPROCESS) is called, when using the "batch method" of installing self-registering files. Always use SELFREGISTER together with the SHAREDFILE option, combining them with the bitwise OR operator ( | ).

SHAREDFILECombines shared and locked file handling by causing XCopyFile to treat all files as shared, and to record locked .dll and .exe files for update when Windows or the system restarts. For more information, see RebootDialog and SdFinishReboot. The SHAREDFILE option causes XCopyFile to treat all files as shared files and increment the registry reference counter by one when the file exists in the target directory and it has a reference count greater than 0. If the shared file does not exist in the target directory and it has no reference counter, the installation creates the counter and sets it to 1. If the shared file already exists in the target directory but has no reference counter, the installation creates the counter and initializes it to 2 as a precaution against accidental removal during uninstallation.

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1543

Appendix F: Built-In Functions (U-Z) XCopyFile

Table F-61: XCopyFile Parameters (cont.) Parameter Description

LOCKEDFILECauses XCopyFile to record locked .dll and .exe files for update when Windows or the system is rebooted. A locked file is a file that is in use by an application or the system when the installation attempts to access or update the file. The LOCKEDFILE option works like SHAREDFILE except that LOCKEDFILE does not create registry entries or modify the registry reference counter. You cannot use the LOCKEDFILE option when using the SHAREDFILE option. There are some unshared files (such as shell extensions) for which the script writer does not want a registry entry and reference counter. These files should never be uninstalled, except by the application itself. LOCKEDFILE allows XCopyFile to handle locked files that are not shared. EXCLUDE_SUBDIRSpecifies to exclude subdirectories contained in the source path. Note that empty subdirectories are not copied. INCLUDE_SUBDIRSpecifies that subdirectories below the source path must also be copied. CLEAR_FILE_ATTRSpecifies to clear the attributes of the copied file. When you use this parameter, the file in the target folder does not have any file attributes set by default. If you do not use this parameter, XCopyFile uses the attributes of the original file for the copied file.

Return Values
Table F-62: XCopyFile Return Values Return Value 0 ISERR_INVALID_ARG All other negative values Description Indicates that the function successfully copied the files. Indicates that an invalid argument was passed to the function. Indicates that the function was unable to copy the files. You can obtain the error message text associated with a large negative return value for example, -2147024891 (0x80070005)by calling FormatMessage.

Additional Information
After you modify .ini files with WriteProfString, you must flush the cache buffer before using XCopyFile. All .ini files are cached; this behavior can cause a delay in writing changes to the specified files. This in turn can interfere with subsequent file operations. To avoid this problem, simply call WriteProfString with null parameters to force Windows to write the data to the .ini file immediately, as show below:
WriteProfString ("C:\\Test.ini", "Windows", "KeyboardDelay", "100"); // null string ("") for all four parameters WriteProfString ("", "", "", ""); // XCopyFile should now have access to updated file. XCopyFile ("C:\\Test.ini", "C:\\Temp", EXCLUDE_SUBDIR);

1544

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Appendix F: Built-In Functions (U-Z) XCopyFile

XCopyFile Example
Note: To call this function in a Basic MSI setup, you must first create a custom action for the entry-point function, execute the custom action in a sequence or as the result of a dialog's control event, and then build the release.
/*--------------------------------------------------------------*\ * * InstallShield Example Script * * Demonstrates the XCopyFile function. * * The first call to XCopyFile copies all text files, * regardless of date, time, or version. * * The second call copies program files and creates the * subdirectories that these files need to be located in. * * The third call copies template files based upon the date, * writing over target files that have the same or earlier date * as the source files. * * The fourth call copies sample files based upon the version * number, writing over target files that have an older version * number. * * Note: In order for this script to run correctly, you must * set the preprocessor constants to a valid file name * and path on the target system. * \*--------------------------------------------------------------*/ #define #define #define #define #define SDIR SDIR_PROGRAM SDIR_TEMPLATE SDIR_SAMPLES TDIR "C:\\ISExampl\\Source\\" "C:\\ISExampl\\Source\\Program\\" "C:\\ISExampl\\Source\\Template\\" "C:\\ISExampl\\Source\\Samples\\" "C:\\ISExampl\\Target\\"

// Include Ifx.h for built-in InstallScript function prototypes. #include "Ifx.h" export prototype ExFn_XCopyFile(HWND); function ExFn_XCopyFile(hMSI) STRING szSrcFile; NUMBER nResult; begin // Set variable to filespec for source files. szSrcFile = "*.txt"; // Copy all text files in the source directory // into the target directory. if (XCopyFile (SDIR ^ szSrcFile, TDIR ^ "*.*", COMP_NORMAL) < 0) then MessageBox ("XCopyFile failed", SEVERE); else MessageBox ("Text files successfully copied.", INFORMATION); endif;

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1545

Appendix F: Built-In Functions (U-Z) XCopyFile

// Set new variables. szSrcFile = "*.*"; // Copy all program files in a source subdirectory to // a subdirectory of the target directory. if (XCopyFile (SDIR_PROGRAM ^ szSrcFile, TDIR ^ "PROGRAM" ^ "*.*", INCLUDE_SUBDIR) < 0) then MessageBox ("XCopyFile failed", SEVERE); else MessageBox ("Program files successfully copied.", INFORMATION); endif; // Copy all template files in a source subdirectory // to a subdirectory of the target directory. if (XCopyFile (SDIR_TEMPLATE ^ szSrcFile, TDIR ^ "TEMPLATE" ^ "*.*", COMP_UPDATE_SAME | COMP_UPDATE_DATE) < 0) then MessageBox ("XCopyFile failed", SEVERE); else MessageBox ("Template files successfully copied.", INFORMATION); endif; // Copy all sample files within a source subdirectory // to a subdirectory of the target directory. if (XCopyFile (SDIR_SAMPLES ^ szSrcFile, TDIR ^ "SAMPLES" ^ "*.*", COMP_UPDATE_VERSION) < 0) then MessageBox ("XCopyFile failed", SEVERE); else MessageBox ("Sample files successfully copied.", INFORMATION); endif; end;

1546

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

Symbols
! operator 443 != operator 444 #define 318 #elif 319 #error 319 #if. . .#else. . .#endif 320 #ifdef 320 #ifndef 320 #include 321 #undef 322 #warning 323 % operator 446 % sign 12 & operator 257, 439 && operator 443 * operator 437, 442 + operator 437, 442, 446 . operator 443 .swf 1061 / operator 437 < operator 444 << operator 439 <= operator 444 - operator 437 = operator 444 -> operator 447 > operator 444 >= operator 444

>> operator 439 @ operator 252, 446 ^ operator 436, 439, 446 __FILE__ 239 __LINE__ 239 _FONTFILEINFO 247 _isres.dll 291 _isuser.dll 719 _MAX_PATH 238 | operator 439 || operator 443 ~ operator 439

A
abort 15 Accelerator keys 907 AskOptions 471 Handler 907 AddFolderIcon 457 AddFolderIcon Example 460461, 463 Adding 464 configuration file statements 522 elements to a list 937 environment variables 483 features 724 lines to initialization files 464 path to batch file 700 path to search path 1036 strings to batch files 703
ISP-1800-RG00 1547

InstallShield 2012 InstallScript Reference Guide

Index

AddProfString 464 AddProfString Example 466 ADDREMOVE 267 ADDREMOVE_COMBINEDBUTTON 267 ADDREMOVE_HIDECHANGEOPTION 267 ADDREMOVE_HIDEREMOVEOPTION 268 ADDREMOVE_STRING_REMOVEONLY 268 ADDREMOVE_SYSTEMCOMPONENT 268 Address operator 436 AdminAskPath 467 AdminAskPath example 468 Advanced 383 batch file functions 382 configuration file functions 383 Advanced Event Handlers 375 AFTER 29, 941 After Data Move Handlers 349 ALLCONTENTS 30, 641 ALLCONTROLS 30, 611 ALLUSERS InstallScript variable 268 And operator 443 APPEND 30, 831 Append to path operator 436 Application 925 launching 395 Arithmetic operators 437 Arrays 262 character 262 data type 251 ASCII characters displaying with escape sequences 11 ASKDESTPATH 30 AskDestPath 468 AskDestPath Example 470 ASKOPTIONS 31 AskOptions 471 AskOptions Example 474 ASKPATH 31 AskPath 476 AskPath Example 477 ASKTEXT 31 AskText 479 AskText Example 480 AskYesNo 481 AskYesNo Example 482 Assignment operator 439

Attributes 94 file 94 Autoexec.bat 700 Autosizing strings 262 AVI files 1061

B
BACK 31, 468 BACKBUTTON 32, 668 BACKGROUND 33, 668 BACKGROUNDCAPTION 33, 1352 Backslash character 1450 BASEMEMORY 33 BASICMSI script variable 240 Batch files 489 adding paths 700 adding strings 703 advanced batch file functions 382 backup copy 494 default batch file name 505 deleting lines 489 Ez batch file functions 381 finding reference keys 497 loading into memory 491 moving a line 502 replacing text 706 saving after edit 494 BATCH_INSTALL 274 testing 1514 BatchAdd 483 BatchAdd Example 486 BatchDeleteEx 489 BatchDeleteEx Example 490 BatchFileLoad 491 BatchFileLoad Example 492 BatchFileSave 289 BatchFileSave Example 496 BatchFind 497 BatchFind Example 498 BatchGetFileName 500 BatchGetFileName Example 501 BatchMoveEx 502 BatchMoveEx Example 504 BatchSetFileName 505 BatchSetFileName Example 506 Beep 1020
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

1548

Index

BEFORE 34, 941 Before Data Move Handlers 334 BIF_BROWSEFORCOMPUTER 34 BIF_BROWSEFORPRINTER 34 BIF_DONTGOBELOWDOMAIN 35 BIF_EDITBOX 35 BIF_RETURNFSANCESTORS 35 BIF_RETURNONLYFSDIRS 36 BIF_STATUSTEXT 36 BILLBOARD 36, 1057 billboards in InstallScript and InstallScript MSI projects disabling 668 moving 1057 resizing 1380 special effects (SetDisplayEffect) 1329 specifying size 1380 Binary arithmetic operators 438 BINARY data type 247 Binary files 560 closing 514 creating 560 file pointer 1303 opening 1027 random access 1303 reading 1074 seeking 1303 writing 1530 Bit operators 439 BITMAPICON 36, 1052 Bitmaps 1329 displaying in dialog 651 placing 1052 setting display effects 1329 BK_BLUE 37, 1324 BK_GREEN 37, 1324 BK_MAGENTA 37, 1324 BK_ORANGE 37, 1324 BK_PINK 37, 1324 BK_RED 38, 1324 BK_SMOOTH 38, 1324 BK_SOLIDBLACK 38, 1324 BK_SOLIDBLUE 38, 1324 BK_SOLIDGREEN 38, 1324 BK_SOLIDMAGENTA 39, 1324 BK_SOLIDORANGE 39, 1324 BK_SOLIDPINK 39, 1324

BK_SOLIDRED 39, 1324 BK_SOLIDWHITE 39, 1324 BK_SOLIDYELLOW 40, 1324 BK_YELLOW 40, 1324 BLACK 40, 1352 BLUE 40, 1352 BOOL 15 data type 247 Boolean operators 317 Boot drive 891 BOOTUPDRIVE 40, 891 Built-in dialogs 385 Built-in functions 378 by category 379 BUTTON_CHECKED 41, 590 BUTTON_UNCHECKED 41, 590 Buttons 471 AskOptions 471 BYREF operator 440 BYTES 41, 860 Bytes 1530 BYTES, KBYTES, MBYTES 891 Bytes, reading from file 1074 copying from strings 551 seeking in file 1303 writing to file 1530 BYVAL Operator 441

C
CalculateAndAddFileCost 507 CallDLLFx 508 CallDLLFx Example 509 Calling 508 CANCEL 41, 1306 CANCELBUTTON 41 Carriage return 11 Case 1456 case 24 changing 1456 cdecl keyword 15 CD-ROM 1029 CDROM 42, 891 CDROM_DRIVE 42, 901 CENTERED 42, 1052 ChangeDirectory 510 ChangeDirectory Example 511
1549

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

Index

Changing 510 elements in a list 985 folder 510 char data type 247 CharReplace 512 CharReplace Example 513 Check 891 Check boxes 471 AskOptions 471 CHECKBOX 42, 651, 656 CHECKBOX95 43, 656 CD-ROM 891 CPU 891 date 891 drive type 891 feature selection 777 for disk drive 698 for folder 697 language 891 CHECKBOX95 dialog style 657 CHECKLINE 43, 656 CHECKLINE dialog style 659 CHECKMARK 43, 656 memory 891 operating system 891 ports 891 time 891 video 891 Windows version 891 CHECKMARK dialog style 658 Class object 1089 CLEAR_FILE_ATTR 43 CloseFile 514 CloseFile Example 515 Closing 514 custom dialogs 688 files 514 CmdGetHwndDlg 516 CmdGetHwndDlg Example 517 CMDLINE 274 CoCreateObject 519 CoCreateObjectDotNet 520 CoGetObject 520 CoGetObject Example 521 Color 891 colors available 891 COLORS 43, 891

setting background and status bar 1324 setting custom colors 1156 COM objects 519520, 679 unloading application domains 681 Combine strings 442 COMMAND 44, 489 Command-Line Compiler 3 Comments 8 COMMON 44, 1066 COMMONFILES 275 COMMONFILES64 275 COMP_NORMAL 45 COMP_UPDATE_DATE 45, 1541 COMP_UPDATE_SAME 46, 1541 COMP_UPDATE_VERSION 46, 1541 COMPACT 44, 1270 Company name 912 COMPARE_DATE 44, 821 COMPARE_MD5_SIGNATURE 45 COMPARE_SIZE 45, 821 COMPARE_VERSION 45, 821 Comparing 1493 files 821 strings 1437 versions 1493 Compiler IDE 2 InstallScript limits for 5 preprocessor directives for 317 Component Event Handlers 331 Component functions 382 ComponentAddItem 382 ComponentCompareSizeRequired 382 ComponentDialog 382 ComponentError 382 ComponentErrorInfo 382 ComponentFileEnum 382 ComponentFileInfo 382 ComponentFilterLanguage 382 ComponentFilterOS 382 ComponentGetData 382 ComponentGetItemSize 382 ComponentGetTotalCost 382 ComponentInitialize 382 ComponentIsItemSelected 382 ComponentListItems 382 ComponentLoadTarget 382

1550

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

ComponentMoveData 382 ComponentReinstall 382 ComponentRemoveAll 382 ComponentRemoveAllInLogOnly 382 ComponentRemoveAllInMedia 382 ComponentRemoveAllInMediaAndLog 382 ComponentSaveTarget 382 ComponentSelectItem 382 ComponentSelectNew 382 ComponentSetData 382 ComponentSetTarget 382 ComponentSetupTypeEnum 382 ComponentSetupTypeGetData 382 ComponentSetupTypeSet 382 ComponentTotalSize 382 ComponentTransferData 382 ComponentUpdate 382 ComponentValidate 382 Concatenate strings 442 Config.sys 538 ConfigAdd 522 ConfigAdd Example 524 ConfigDelete 525 ConfigDelete Example 526 ConfigFileLoad 527 ConfigFileLoad Example 528 ConfigFileSave 529 ConfigFileSave Example 531 ConfigFind 533 ConfigFind Example 535 ConfigGetFileName 536 ConfigGetFileName Example 537 ConfigGetInt 538 ConfigGetInt Example 539 ConfigMove 541 ConfigMove Example 542 ConfigSetFileName 544 ConfigSetFileName Example 545 ConfigSetInt 546 ConfigSetInt Example 547 Configuration files 709 adding a device driver 709 adding statements 522 adding strings 712 advanced configuration file functions 383 backup copy 529 deleting statements 525

Ez configuration file functions 383 finding a reference key 533 getting default configuration file name 536 getting integer values 538 getting numeric parameter values 715 loading into memory 527 moving lines 541 saving 529 setting default file name 544 setting integer values 546 setting values 717 Constants defining 6 predefined 29 user defined 252 CONTINUE 46, 1042 Converting 1461 lower to upper case 1461 number to string 1026 string to number 1458 unit constant to UI string 1439 upper to lower case 1456 ConvertSizeToUnits 549 ConvertWinHighLowSizeToISHighLowSize 551 COPY_ERR_CREATEDIR 46, 554 COPY_ERR_MEMORY 47, 1541 COPY_ERR_NODISKSPACE 47, 554 COPY_ERR_OPENINPUT 47, 554 COPY_ERR_OPENOUTPUT 47, 554 COPY_ERR_TARGETREADONLY 48, 1541 CopyBytes 551 CopyBytes Example 552 CopyCHARArrayToISStringArray 553 CopyFile 554 CopyFile Example 557 Copying 551 files 554 substrings 551 CPU 48, 891 CreateDir 558 CreateDir Example 559 CreateFile 560 CreateFile Example 561 CreateInstallationInfo 563 CreateObject 564 CreateProgramFolder 565 CreateProgramFolder Example 566

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1551

Index

CreateRegistrySet 567 CreateRegistrySet Example 568 CreateShellObjects 569 CreateShellObjects Example 570 Creating 558 files 560 folders 558 program folders 565 Critical files 766 CtrlClear 571 CtrlClear Example 572 CtrlDir 575 CtrlDir Example 576 CtrlGetCurSel 578 CtrlGetCurSel Example 579 CtrlGetDlgItem 582 CtrlGetMLEText 583 CtrlGetMLEText Example 583 CtrlGetMultCurSel 586 CtrlGetMultCurSel Example 587 CtrlGetState 590 CtrlGetState Example 591 CtrlGetSubCommand 594 CtrlGetSubCommand Example 594 CtrlGetText 597 CtrlGetText Example 597 CtrlGetUrlForLinkClicked 600 CtrlGetUrlForLinkClicked example 600 CtrlPGroups 602 CtrlPGroups Example 602 CtrlSelectText 605 CtrlSelectText Example 605 CtrlSetCurSel 607 CtrlSetCurSel Example 608 CtrlSetFont 611 CtrlSetFont Example 611 CtrlSetList 614 CtrlSetList Example 615 CtrlSetMLEText 619 CtrlSetMLEText Example 620 CtrlSetMultCurSel 623 CtrlSetMultCurSel Example 624 CtrlSetState 627 CtrlSetState Example 628 CtrlSetText 631 CtrlSetText Example 632 CURRENTROOTKEY 48

CUSTOM 48, 1270 Custom dialogs 590 check box controls 590 clearing contents 571 closing 688 creating section names 1245 defining 719 displaying 1522 displaying file names 575 displaying program folders 602 fonts 611 freeing from memory 1144 getting commands 594 getting selected items 578 multi-line edit control 583 multi-selection list box controls 623 radio button controls 590 registering in a script 634 response file 1374 retrieving window handles 516 setting list controls 614 text controls 631 Custom handler 907

D
Data 6 Data structures 447 member operator 443 overview 253 pointer to 257 structure pointer operator 447 DATA_COMPONENT 48, 1374 DATA_LIST 49, 1374 DATA_NUMBER 49, 1369 DATA_STRING 49, 1369 declaring 6 DATE 49, 891 Declaring 6 functions 6 variables 6 DEFAULT 50 default 24 Default batch file 505 DefineDialog 634 DefineDialog Example 637 Defining 6
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

1552

Index

custom dialogs 634 DEFWINDOWMODE 50, 683 DeinstallSetReference 639 DeinstallStart 639 Delay 639 Delay Example 640 DELETE 50 DELETE_EOF 50, 825 DeleteCharArray 640 DeleteDir 641 DeleteDir Example 642 DeleteFile 643 DeleteFile Example 644 DeleteFolderIcon 645 DeleteFolderIcon Example 646 DeleteProgramFolder 647 DeleteProgramFolder Example 648 DeleteWCharArray 649 Deleting 641 directories 641 elements from a list 956 files 643 folder item 645 folders 641 lines 825 path from search path 1039 program folders 647 Desktop folder 278 Destination folder 1159 Device Drivers InstallScript functions 384 Device drivers 709 installing into Config.sys 709 Dialog styles 656 DIALOGCACHE 51, 683 Dialogs built-in 385 confirming folder selection 1173 confirming registration 1175 custom 627 custom dialog 1277 displaying bitmaps 1170 displaying file modifications 1286 displaying help topics 1188 feature 732 finishing setup 1211 general 1279

getting a destination path 1306 getting text 479 getting user options 471 getting yes/no input 481 InstallScript 385 functions for customizing 393 license agreement 1226, 1236 messages 1291 product name 1256 prompting for next distribution disk 691 prompting to reboot 1078 registering the user 1258 selecting a destination folder 1159 selecting features 1193 selecting folders 1312 selecting program folders 1266 selecting setup types 1275 setting elements in SD dialogs 651 setting titles 1327 start file transfer 1293 styles 656 welcome message 1525 DialogSetFont 650 DialogSetInfo 651 DialogSetInfo Example 655 DIFXAPI_ERROR 51 DIFXAPI_INFO 51 DIFXAPI_SUCCESS 51 DIFXAPI_WARNING 51 DIFxDriverPackageGetPath 659 DIFxDriverPackageInstall 660 DIFxDriverPackagePreinstall 664 DIFxDriverPackageUninstall 666 DIR_WRITEABLE 52, 912 Directives, compiler 317 DIRECTORY 52, 1032 changing 510 checking 697 creating 558 deleting 641 finding 834 InstallScript functions 401 searching 836 Directory 401 Disable 668 Disable Example 672 DISABLE_ALLUSERBTN 52

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1553

Index

DISABLE_PERUSERBTN 52 DISK 53, 1032 Disk 858 DISK_INFO_QUERY_ALL 53 DISK_INFO_QUERY_BYTES_PER_CLUSTER 53 DISK_INFO_QUERY_DISK_FREE_SPACE 54 DISK_INFO_QUERY_DISK_TOTAL_SPACE 54 DISK_INFO_QUERY_DRIVE_TYPE 54 DISK_TOTALSPACE 54, 891 DISK_TOTALSPACE_EX 55, 891 DISK1COMPONENT 53 DISK1SETUPEXENAME 276 DISK1TARGET 276 boot drive 891 drive 698 drive designation 854 drive type 891 free space 860 total space 891 valid drive list 901 volume label 891 Displaying 1256 ASCII characters with escape sequences 11 product name 1256 program folder 1365 DLG_ASK_OPTIONS 55, 1327 DLG_ASK_PATH 55, 1327 DLG_ASK_TEXT 55, 1327 DLG_ASK_YESNO 55, 1327 DLG_CENTERED 56, 634 DLG_CLOSE 56, 688 DLG_DIR_DIRECTORY 56, 575 DLG_DIR_DRIVE 56, 575 DLG_DIR_FILE 56, 575 DLG_ENTER_DISK 57, 1327 DLG_ERR 57, 1522 DLG_ERR_ALREADY_EXISTS 57, 634 DLG_ERR_ENDDLG 57, 1144 DLG_INFO_ALTIMAGE 58, 651 DLG_INFO_ALTIMAGE_REVERT_IMAGE 58, 651 DLG_INFO_ALTIMAGE_VERIFY_BMP 58, 651 DLG_INFO_CHECKSELECTION 58, 651 DLG_INFO_KUNITS 58, 651 DLG_INFO_USEDECIMAL 59, 651 DLG_INIT 59, 611 DLG_INIT routine 516 DLG_MSG_ALL 59, 634

DLG_MSG_INFORMATION 59, 1327 DLG_MSG_SEVERE 59, 1327 DLG_MSG_STANDARD 60, 634 DLG_MSG_WARNING 60, 1327 DLG_STATUS 60, 1327 DLG_USER_CAPTION 60, 1327 DLLs 634 calling functions 508 custom dialogs 634 InstallScript functions 395 loading into memory 1479 unloading from memory 1474 Do 673 Do Example 674 DoInstall 675 DoInstall Example 678 DOINSTALL_OPTION_NOHIDEPROGRESS 60 DOINSTALL_OPTION_NOHIDESPLASH 61 DOINSTALL_OPTION_NOLANGSWITCH 61 DOINSTALL_OPTION_NOSETBATCHINSTALL 61 DotNetCoCreateObject 679 DOTNETFRAMEWORKINSTALLED 61 DOTNETSERVICEPACKINSTALLED 62 DotNetUnloadAppDomain 681 downto 16 DRIVE 62, 891 DRIVE_CDROM 62 DRIVE_FIXED 62 DRIVE_NO_ROOT_DIR 62 DRIVE_RAMDISK 63 DRIVE_REMOTE 63 DRIVE_REMOVABLE 63 DRIVE_UNKNOWN 63 DRIVER_PACKAGE_DELETE_FILES 63 DRIVER_PACKAGE_FORCE 64 DRIVER_PACKAGE_LEGACY_MODE 64 DRIVER_PACKAGE_ONLY_IF_DEVICE_PRESENT 64 DRIVER_PACKAGE_REPAIR 64 DRIVER_PACKAGE_SILENT 65

E
EDITBOX_CHANGE 65, 594 EFF_BOXSTRIPE 65, 1329 EFF_FADE 65, 1329 EFF_HORZREVEAL 65, 1329 EFF_HORZSTRIPE 66, 1329
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

1554

Index

EFF_NONE 66, 1329 EFF_REVEAL 66, 1329 EFF_VERTSTRIPE 66, 1329 else 19 elseif 20 Enable 683 Enable Example 686 ENABLED_ISERVICES 276 END_OF_FILE 66, 828 END_OF_LIST 67, 985 EndCurrentDialog 687 EndDialog 688 EndDialog Example 689 endfor 16 endif 20 endprogram 7 endswitch 24 endwhile 25 ENGINECOMMONDIR 276 ENGINEDIR 276 ENTERDISK 67 EnterDisk 691 EnterDisk Example 692 EnterDiskError 693 EnterLoginInfo 694 EnterPassword 696 Enumerating setup types 802 Environment space 891 Environment variables 1111 adding and modifying 483 getting 862 registry 1111 EQUALS 67, 1493 Err Object 449 ERR_ABORT 75 ERR_BOX_BADPATH 75, 1332 ERR_BOX_BADTAGFILE 75, 1332 ERR_BOX_DISKID 75, 1332 ERR_BOX_DRIVEOPEN 75, 1332 ERR_IGNORE 76 ERR_NO 76 ERR_PERFORM_AFTER_REBOOT 76 ERR_RETRY 76 ERR_YES 77 ERROR_ACCESS_DENIED 68 ERROR_CIRCULAR_DEPENDENCY 68 ERROR_DATABASE_DOES_NOT_EXIST 68

ERROR_DEPENDENT_SERVICES_RUNNING 69 ERROR_DUP_NAME 69 ERROR_FILE_NOT_FOUND 69 ERROR_INVALID_HANDLE 69 ERROR_INVALID_PARAMETER 70 ERROR_INVALID_SERVICE_ACCOUNT 70 ERROR_INVALID_SERVICE_CONTROL 70 ERROR_PATH_NOT_FOUND 71 ERROR_SERVICE_ALREADY_RUNNING 71 ERROR_SERVICE_CANNOT_ACCEPT_CTRL 71 ERROR_SERVICE_DATABASE_LOCKED 71 ERROR_SERVICE_DEPENDENCY_DELETED 72 ERROR_SERVICE_DEPENDENCY_FAIL 72 ERROR_SERVICE_DISABLED 72 ERROR_SERVICE_DOES_NOT_EXIST 73 ERROR_SERVICE_EXISTS 73 ERROR_SERVICE_LOGON_FAILED 73 ERROR_SERVICE_NO_THREAD 74 ERROR_SERVICE_NOT_ACTIVE 73 ERROR_SERVICE_REQUEST_TIMEOUT 74 ERROR_TIMEOUT 74 ERRORFILENAME 277 ErrorInfo.Feature 359 ErrorInfo.Feature.Description 359 ErrorInfo.Feature.DisplayName 359 ErrorInfo.Feature.Name 359 ErrorInfo.FileError.Description 359 ErrorInfo.FileError.File 359 ErrorInfo.FileGroup 359 ErrorInfo.LastError 359 Errors 735 getting information 864 run-time 735 setting information 1336 user-defined 319 Escape sequences 12 Event Handlers 325, 327 Event handlers 907 EXCLUDE_SUBDIR 77, 834 EXCLUSIVE 77, 1164 Executing a program from a setup script 924 Existence, check for specific program item or subfolder 1067 EXISTS 77, 698 ExistsDir 697 ExistsDir Example 697 ExistsDisk 698

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1555

Index

file 912 program item 1067 program subfolder 1067 registry key 1116 ExistsDisk Example 699 EXIT 78, 907 Exit handler 673 exit keyword 16 export keyword 16 EXTENDEDMEMORY 78, 891 Extensibility functions 395 EXTENSION_ONLY 78, 1032 external keyword 16 Ez configuration file functions 383 EzBatchAddPath 700 EzBatchAddPath Example 701 EzBatchAddString 703 EzBatchAddString Example 705 EzBatchReplace 706 EzBatchReplace Example 707 EzConfigAddDriver 709 EzConfigAddDriver Example 710 EzConfigAddString 712 EzConfigAddString Example 713 EzConfigGetValue 715 EzConfigGetValue Example 716 EzConfigSetValue 717 EzConfigSetValue Example 718 EzDefineDialog 719 EzDefineDialog Example 721

F
FALSE 78, 1009 Feature event handlers 351 Feature Functions 396 FEATURE_FIELD_CDROM_FOLDER 79 FEATURE_FIELD_DESCRIPTION 79 FEATURE_FIELD_DISPLAYNAME 80 FEATURE_FIELD_ENCRYPT 80 FEATURE_FIELD_FILENEED 81 FEATURE_FIELD_FTPLOCATION 81 FEATURE_FIELD_GUID 81 FEATURE_FIELD_HANDLER_ONINSTALLED 82 FEATURE_FIELD_HANDLER_ONINSTALLING 82 FEATURE_FIELD_HANDLER_ONUNINSTALLED 82 FEATURE_FIELD_HANDLER_ONUNINSTALLING 83
1556

FEATURE_FIELD_HTTPLOCATION 83 FEATURE_FIELD_IMAGE 83 FEATURE_FIELD_MISC 84 FEATURE_FIELD_PASSWORD 84 FEATURE_FIELD_SELECTED 84 FEATURE_FIELD_SIZE 85 FEATURE_FIELD_STATUS 85 FEATURE_FIELD_VISIBLE 85 FEATURE_INFO_ATTRIBUTE 86 FEATURE_INFO_COMPONENT_FLAGS 86 FEATURE_INFO_COMPSIZE_HIGH 86 FEATURE_INFO_COMPSIZE_LOW 87 FEATURE_INFO_DATE 87 FEATURE_INFO_DATE_EX 87 FEATURE_INFO_DESTINATION 88 FEATURE_INFO_HTTPLOCATION 88 FEATURE_INFO_LANGUAGE 89 FEATURE_INFO_MD5_SIGNATURE 89 FEATURE_INFO_MISC 89 FEATURE_INFO_ORIGSIZE_HIGH 90 FEATURE_INFO_ORIGSIZE_LOW 90 FEATURE_INFO_OS 90 FEATURE_INFO_OVERWRITE 91 FEATURE_INFO_PLATFORM_SUITE 91 FEATURE_INFO_TIME 91 FEATURE_INFO_VERSIONLS 91 FEATURE_INFO_VERSIONMS 92 FEATURE_INFO_VERSIONSTR 92 FEATURE_OPCOST_UNINSTALL_FILE 93 FEATURE_OPCOST_UNINSTALL_REGORINI 93 FEATURE_OPCOST_UNINSTALL_UNREGFILE 93 FEATURE_VALUE_CRITICAL 93 FEATURE_VALUE_HIGHLYRECOMMENDED 94 FEATURE_VALUE_STANDARD 94 FeatureAddCost 723 FeatureAddItem 724 FeatureAddItem Example 726 FeatureAddUninstallCost 727 FeatureCompareSizeRequired 728 FeatureCompareSizeRequired Example 730 FeatureDialog 732 FeatureDialog Example 734 FeatureError 735 FeatureError Example 737 FeatureErrorInfo 739 FeatureErrorInfo Example 740 FeatureFileEnum 741

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

FeatureFileEnum Example 743 FeatureFileInfo 745 FeatureFileInfo Example 751 FeatureFilterLanguage 754 FeatureFilterLanguage Example 756 FeatureFilterOS 757 FeatureFilterOS Example 760 FeatureGetCost 763 FeatureGetCostEx 765 FeatureGetData 766 FeatureGetData Example 770 FeatureGetItemSize 771 FeatureGetItemSize Example 772 FeatureGetTotalCost 773 FeatureInitialize 774 FeatureInitialize Example 775 FeatureIsItemSelected 777 FeatureIsItemSelected Example 778 FeatureListItems 779 FeatureListItems Example 780 FeatureLoadTarget 781 FeatureMoveData 782 FeatureMoveData Example 783 FeaturePatch 787 FeatureReinstall 788 FeatureRemoveAll 788 FeatureRemoveAllInLogOnly 789 FeatureRemoveAllInMedia 790 FeatureRemoveAllInMediaAndLog 791 Features adding items 724 FeatureSaveTarget 792 destination location 732 dialog 732 FeatureSelectItem 793 FeatureSelectItem Example 794 FeatureSelectNew 795 enumerating setup types 802 errors 735 FeatureSetData 796 FeatureSetData Example 799 FeatureSetTarget 800 FeatureSetTarget Example 801 FeatureSetupTypeEnum 802 FeatureSetupTypeEnum Example 802 FeatureSetupTypeGetData 803 FeatureSetupTypeGetData Example 804

FeatureSetupTypeSet 807 fields 796 filtering 754 listing items 779 retrieving feature information 766 retrieving setup type data 803 selecting 732 selection status 777 setting data 796 setting the setup type 807 validating 819 FeatureSetupTypeSet Example 808 FeatureSpendCost 809 FeatureSpendUninstallCost 810 FeatureStandardSetupTypeSet 811 FeatureTotalSize 813 FeatureTotalSize Example 814 FeatureTransferData 816 FeatureUpdate 817 FeatureValidate 819 FeatureValidate Example 819 FF_FLAGS 81 FI_FTPLOCATION 88 File attributes 94 File media library 401 File transfer 554 CopyFile 554 features 782 XCopyFile 1541 FILE_ADD_FILE 95 FILE_ADD_SUBDIRECTORY 95 FILE_ALL_ACCESS 95 FILE_APPEND_DATA 95 FILE_ATTR_ARCHIVED 95, 1337 FILE_ATTR_HIDDEN 96, 1337 FILE_ATTR_NORMAL 96, 1337 FILE_ATTR_READONLY 96, 1337 FILE_ATTR_SYSTEM 96, 1337 FILE_ATTRIBUTE 96, 1337 FILE_BIN_CUR 97, 1303 FILE_BIN_END 97, 1303 FILE_BIN_START 97, 1303 FILE_DATE 97, 867 FILE_DELETE_CHILD 97 FILE_EXECUTE 98 FILE_EXISTS 98, 912 FILE_INSTALLED 98, 1510

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1557

Index

FILE_IS_LOCKED 98, 1514 FILE_LINE_LENGTH 98, 831 FILE_LIST_DIRECTORY 99 FILE_LOCKED 99, 912 FILE_MD5_SIGNATURE 99 FILE_MODE_APPEND 99, 560 FILE_MODE_APPEND_UNICODE 99 FILE_MODE_BINARY 100, 1029 FILE_MODE_BINARYREADONLY 100, 1029 FILE_MODE_NORMAL 100, 1029 FILE_NO_VERSION 101, 1501 FILE_NOT_FOUND 100, 1501 FILE_RD_ONLY 101, 825 FILE_READ_ATTRIBUTES 101 FILE_READ_DATA 101 FILE_READ_EA 102 FILE_SHARED_COUNT 102 FILE_SIZE 102, 867 FILE_SIZE_HIGH 102 FILE_SIZE_LOW 103 FILE_SRC_OLD 103, 1510 FILE_TIME 103, 867 FILE_TRAVERSE 103 FILE_WRITE_ATTRIBUTES 103 FILE_WRITE_DATA 104 FILE_WRITE_EA 104 FILE_WRITEABLE 104, 912 FileCompare 821 FileCompare Example 823 FileDeleteLine 825 FileDeleteLine Example 826 FileGrep 828 FileGrep Example 829 FileInsertLine 831 FileInsertLine Example 832 FILENAME 104, 1032 FILENAME_ONLY 105, 1032 Files attributes 867 closing 514 comparing 821 copying 1541 creating 560 critical 766 date and time 1337 deleting 643 deleting lines 825

exist 912 File attributes 94 file pointer 1303 finding 840 hidden 94 inserting lines 831 InstallScript functions 401 InstallShield Silent 1245 locked 413 mode 1029 opening 1027 random access 1303 reading 1074 read-only 94 renaming 1147 searching 828 seeking 1303 self-registering files 673 setting the file mode 1029 shared files 413 supported languages 1499 system 94 writing 1530 Fill with blanks or zeros 12 Filtering 754 languages 754 operating systems 757 FindAllDirs 834 FindAllDirs Example 835 FindAllFiles 836 FindAllFiles Example 838 FindFile 840 FindFile Example 841 Finding 834 directories 834 files 836 folders 834 path in search path 1042 substring 447 FindWindow 842 FindWindow Example 843 FIXED_DRIVE 105, 901 FlexNet Connect 403 GetUpdateStatus 900 GetUpdateStatusReboot 901 SdFinishUpdate 1218 SdFinishUpdateEx 1218

1558

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

SdFinishUpdateReboot 1220 SetUpdateStatus 1356 SetUpdateStatusReboot 1356 UPDATE_SERVICE_INSTALL constant 229 UpdateServiceCheckForUpdates 1477 UPDATESERVICECOMPONENT constant 230 UpdateServiceCreateShortcut 1477 UpdateServiceEnableUpdateManagerInstall 1477 UpdateServiceGetAgentTarget 1478 UpdateServiceOnEnabledStateChange 1478 UpdateServiceRegisterProduct 1478 UpdateServiceRegisterProductEx 1479 UpdateServiceSetHost 1479 UpdateServiceSetLanguage 1479 Flow control 27 FOLDER_APPDATA 277 FOLDER_APPLICATIONS 277 FOLDER_APPLICATIONS64 278 FOLDER_COMMON_APPDATA 278 FOLDER_DESKTOP 871 FOLDER_DOTNET_10 278 FOLDER_DOTNET_11 279 FOLDER_DOTNET_20 279 FOLDER_DOTNET_30 279 FOLDER_DOTNET_35 279 FOLDER_DOTNET_40 279 FOLDER_FONTS 279 FOLDER_LOCAL_APPDATA 280 FOLDER_PERSONAL 280 FOLDER_PROGRAMS 871 FOLDER_STARTMENU 871 FOLDER_STARTUP 281 FOLDER_TEMP 281 Folders 836 adding icons 457 changing 510 checking 697 creating 558 deleting 641 deleting items 645 finding 834 InstallScript functions 401 replacing icons 1150 retrieving shortcuts and subfolder names 871 searching 836 selecting 1312 shared support 304

support 305 FONT_AVAILABLE 105 Fonts 611 dialogs 874 for 16 Format specifiers 1384 FormatMessage 844 FormatMessage Example 845 Free memory 880 FTP location 766 FULL 105, 1042 FULLSCREEN 105, 1052 FULLSCREENSIZE 106, 1052 FULLWINDOWMODE 106, 683 Function block 7 function keyword 378 declaring 6 overview 377 FUNCTION_EXPORTED 106

G
GBYTES 106, 860 GENERIC_ALL 107 GENERIC_EXECUTE 107 GENERIC_READ 107 GENERIC_WRITE 107 GetAndAddAllFilesCost 845 GetAndAddFileCost 847 GetCArrayFromISArray 848 GetCHARArrayFromISStringArray 849 GetCurrentDialogName 850 GetCurrentDir 851 GetDir 852 GetDir Example 853 GetDisk 854 GetDisk Example 854 GetDiskInfo 855 GetDiskInfo example 857 GetDiskSpace 858 GetDiskSpace Example 858 GetDiskSpaceEx 860 GetDiskSpaceEx Example 861 GetEnvVar 862 GetEnvVar Example 863 GetExtendedErrInfo 864 GetExtents 865
1559

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

Index

GetExtents Example 866 GetFileInfo 867 GetFileInfo Example 869 GetFolderNameList 871 GetFolderNameList Example 873 GetFont 874 GetFont Example 875 GetLine 878 GetLine Example 879 GetMemFree 880 GetObject 880 GetObjectByIndex 881 GetObjectCount 882 GetProfInt 883 GetProfInt Example 884 GetProfSectionKeyCount 884 GetProfString 885 GetProfString Example 887888 GetProfStringList 888 GetStatus 890 GetSystemInfo 891 GetSystemInfo Example 895 GetTempFileNameIS 898 Getting 500 configuration file value 538 date 891 default batch file name 500 default system configuration file name 536 destination folder 468 environment variables 862 feature data 766 file attributes 867 file's supported languages 1499 free disk space 858 free memory 880 integer values from initialization files 883 lines from a file 878 list elements 970 media information 1017 path 1045 project settings 1017 screen dimensions 865 status of an object 890 string length (bytes) 1446 string length (chars) 1447 string values from initialization files 885 time 891

total memory 891 valid drive list 901 window handle 516 GetTrueTypeFontFileInfo 900 GetUpdateStatus 900 GetUpdateStatusReboot 901 GetValidDrivesList 901 GetValidDrivesList Example 902 GetWCHARArrayFromISStringArray 904 GetWindowHandle 904 GetWindowHandle Example 905 Global Event Handlers 331 Global variables 260 goto 18 Graphics 1170 displaying in dialog 1170 GREATER_THAN 107, 1493 GREEN 108, 1324 Grep 828 GTFIS_OPTION_DELETE_TEMP_FILE 108 GTFIS_OPTION_DONT_CREATE_DIR 108 GTFIS_OPTION_DONT_RESOLVE_TEXTSUBS 108 GTFIS_OPTION_NONE 108

H
Handle 516 Handler window 904 HandlerEx example 909 HELP 907 HELP (InstallScript constant) 109 Help handler 673 Help topics 1188 Hexadecimal values 12 HIBYTE 910 Hidden files 706 HIDE_DISABLED_BTNS 109 HIWORD 911 HIWORD Example 911 HKEY_CLASSES_ROOT 109, 1095 HKEY_CURRENT_USER 110, 1128 HKEY_LOCAL_MACHINE 110, 1080 HKEY_USER_SELECTABLE 111 HKEY_USER_SELECTABLE_AUTO 282 HKEY_USERS 110, 1080 HKEYCURRENTROOTKEY 282
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

1560

Index

HOURGLASS 111, 668 HTTP location 766 Hungarian notation 9 HWND data type 247 HWND_DESKTOP 111, 904 HWND_INSTALL 111, 904

I
Icons 645 adding to program folder 457 deleting from program folder 645 replacing in folders 1150 IDCANCEL 112 Identifiers 7 IDOK 112 IDS_IFX_ERROR_INVALID_MEDIA_PASSWORD 112 if 18 IFX_COMPANY_NAME 282 IFX_DISK1INSTALLED 282 IFX_INITIALIZED 283 IFX_INSTALLED_DISPLAY_VERSION 283 IFX_INSTALLED_VERSION 283 IFX_KEYPATH_PRODUCT_INFO 283 IFX_MULTI_INSTANCE_SUFFIX 284 IFX_ONNEXTDISK_PACKAGE_CAPTION 113 IFX_ONNEXTDISK_PACKAGE_MSG 113 IFX_PRODUCT_COMMENTS 284 IFX_PRODUCT_DISPLAY_NAME 284 IFX_PRODUCT_DISPLAY_VERSION 284 IFX_PRODUCT_ICON 285 IFX_PRODUCT_KEY 285 IFX_PRODUCT_NAME 285 IFX_PRODUCT_README 285 IFX_PRODUCT_REGISTEREDCOMPANY 286 IFX_PRODUCT_REGISTEREDOWNER 286 IFX_PRODUCT_REGISTEREDSERIALNUM 286 IFX_PRODUCT_SUPPORT_CONTACT 287 IFX_PRODUCT_SUPPORT_PHONE 287 IFX_PRODUCT_SUPPORT_URL 287 IFX_PRODUCT_UPDATE_URL 287 IFX_PRODUCT_URL 288 IFX_PRODUCT_VERSION 288 IFX_SETUP_TITLE 288 IFX_SUPPORTED_VERSIONS 288 Include files 321 specifying 321
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00

INCLUDE_SUBDIR 113, 1541 Indirection operator 442 INDVFILESTATUS 113 INFOFILENAME 494 INFORMATION 114, 1384 Information functions 405 Initialization files 1538 adding lines 464 changing strings 1153 getting values 883 InstallScript functions 406 restarting Windows 1215 writing 1538 Initialization Handlers 331 initialize 774 InitProperties 453 Inserting 831 lines into a text file 831 INSTALL_GUID 289 InstallationInfo 1525 INSTALLDIR 289 InstallScript Language Reference 1 INSTALLSCRIPTMSI script variable 240 INSTALLSCRIPTMSIEEUI script variable 240 InstallShield Silent 1245 SdMakeName 1245 int data type 247 Is 912 Is Example 919 IS_386 143, 891 IS_486 143, 891 IS_ALPHA 144, 891 IS_CDROM 144, 891 IS_EGA 144, 891 IS_FIXED 144, 891 IS_FOLDER 144, 1150 IS_ITEM 145, 1150 IS_NULLSTR_PTR 290 IS_PENTIUM 145, 891 IS_PERMISSIONS_OPTION_ALLOW_ACCESS 114 IS_PERMISSIONS_OPTION_DENY_ACCESS 114 IS_PERMISSIONS_OPTION_NO_APPLYDOWN 114 IS_PERMISSIONS_TYPE_FILE 115 IS_PERMISSIONS_TYPE_FOLDER 115 IS_PERMISSIONS_TYPE_REGISTRY 115 IS_REMOTE 145, 891 IS_REMOVABLE 145, 891

1561

Index

IS_SVGA 145, 891 IS_UNKNOWN 146, 891 IS_UVGA 146, 891 IS_VGA 146, 891 IS_WINDOWS 146, 891 IS_WINDOWS9X 146, 891 IS_WINDOWSNT 147, 891 IS_XVGA 147, 891 ISCompareServicePack 920 ISCompareServicePack Example 921 ISDeterminePlatform 922 ISDIFX_OPTION_DONT_ASSOCIATE 115 ISDIFX_OPTION_DONT_RESOVE_TEXTSUBS 115 ISDIFX_OPTION_LOG_IN_DRIVER_PACKAGE_PATH 116 ISDIFX_OPTION_NO_REPAIR 116 ISDIFXAPPID 289 IsEmpty 922 IsEmpty Example 923 ISERR_GEN_FAILURE 116 ISERR_SUCCESS 116 ISLANG constants 256 ISLANG_AFRIKAANS 117 ISLANG_AFRIKAANS_STANDARD 117 ISLANG_ALBANIAN 117 ISLANG_ALBANIAN_STANDARD 117 ISLANG_ALL 117 ISLANG_ARABIC 117 ISLANG_ARABIC_ALGERIA 118 ISLANG_ARABIC_BAHRAIN 118 ISLANG_ARABIC_EGYPT 118 ISLANG_ARABIC_IRAQ 118 ISLANG_ARABIC_JORDAN 118 ISLANG_ARABIC_KUWAIT 118 ISLANG_ARABIC_LEBANON 118 ISLANG_ARABIC_LIBYA 118 ISLANG_ARABIC_MOROCCO 119 ISLANG_ARABIC_OMAN 119 ISLANG_ARABIC_QATAR 119 ISLANG_ARABIC_SAUDIARABIA 119 ISLANG_ARABIC_SYRIA 119 ISLANG_ARABIC_TUNISIA 119 ISLANG_ARABIC_UAE 119 ISLANG_ARABIC_YEMEN 119 ISLANG_BASQUE 120 ISLANG_BASQUE_STANDARD 120 ISLANG_BELARUSIAN 120 ISLANG_BELARUSIAN_STANDARD 120

ISLANG_BULGARIAN 120 ISLANG_BULGARIAN_STANDARD 120 ISLANG_CATALAN 120 ISLANG_CATALAN_STANDARD 120 ISLANG_CHINESE 121 ISLANG_CHINESE_HONGKONG 121 ISLANG_CHINESE_PRC 121 ISLANG_CHINESE_SINGAPORE 121 ISLANG_CHINESE_TAIWAN 121 ISLANG_CROATIAN 121 ISLANG_CROATIAN_STANDARD 121 ISLANG_CZECH 121 ISLANG_CZECH_STANDARD 122 ISLANG_DANISH 122 ISLANG_DANISH_STANDARD 122 ISLANG_DUTCH 122 ISLANG_DUTCH_BELGIAN 122 ISLANG_DUTCH_STANDARD 122 ISLANG_ENGLISH 122 ISLANG_ENGLISH_AUSTRALIAN 122 ISLANG_ENGLISH_BELIZE 123 ISLANG_ENGLISH_CANADIAN 123 ISLANG_ENGLISH_CARIBBEAN 123 ISLANG_ENGLISH_IRELAND 123 ISLANG_ENGLISH_JAMAICA 123 ISLANG_ENGLISH_NEWZEALAND 123 ISLANG_ENGLISH_SOUTHAFRICA 123 ISLANG_ENGLISH_TRINIDAD 123 ISLANG_ENGLISH_UNITEDKINGDOM 124 ISLANG_ENGLISH_UNITEDSTATES 124 ISLANG_ESTONIAN 124 ISLANG_ESTONIAN_STANDARD 124 ISLANG_FAEROESE 124 ISLANG_FAEROESE_STANDARD 124 ISLANG_FARSI 124 ISLANG_FARSI_STANDARD 124 ISLANG_FINNISH 125 ISLANG_FINNISH_STANDARD 125 ISLANG_FRENCH 125 ISLANG_FRENCH_BELGIAN 125 ISLANG_FRENCH_CANADIAN 125 ISLANG_FRENCH_LUXEMBOURG 125 ISLANG_FRENCH_STANDARD 125 ISLANG_FRENCH_SWISS 125 ISLANG_GERMAN 126 ISLANG_GERMAN_AUSTRIAN 126 ISLANG_GERMAN_LIECHTENSTEIN 126

1562

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

ISLANG_GERMAN_LUXEMBOURG 126 ISLANG_GERMAN_STANDARD 126 ISLANG_GERMAN_SWISS 126 ISLANG_GREEK 126 ISLANG_GREEK_STANDARD 126 ISLANG_HEBREW 127 ISLANG_HEBREW_STANDARD 127 ISLANG_HUNGARIAN 127 ISLANG_HUNGARIAN_STANDARD 127 ISLANG_ICELANDIC 127 ISLANG_ICELANDIC_STANDARD 127 ISLANG_INDONESIAN 127 ISLANG_INDONESIAN_STANDARD 127 ISLANG_ITALIAN 128 ISLANG_ITALIAN_STANDARD 128 ISLANG_ITALIAN_SWISS 128 ISLANG_JAPANESE 128 ISLANG_JAPANESE_STANDARD 128 ISLANG_KOREAN 128 ISLANG_KOREAN_JOHAB 128 ISLANG_KOREAN_STANDARD 128 ISLANG_LATVIAN 129 ISLANG_LATVIAN_STANDARD 129 ISLANG_LITHUANIAN 129 ISLANG_LITHUANIAN_STANDARD 129 ISLANG_NORWEGIAN 129 ISLANG_NORWEGIAN_BOKMAL 129 ISLANG_NORWEGIAN_NYNORSK 129 ISLANG_POLISH 129 ISLANG_POLISH_STANDARD 130 ISLANG_PORTUGUESE 130 ISLANG_PORTUGUESE_BRAZILIAN 130 ISLANG_PORTUGUESE_STANDARD 130 ISLANG_ROMANIAN 130 ISLANG_ROMANIAN_STANDARD 130 ISLANG_RUSSIAN 130 ISLANG_RUSSIAN_STANDARD 130 ISLANG_SERBIAN_CYRILLIC 131 ISLANG_SERBIAN_LATIN 131 ISLANG_SLOVAK 131 ISLANG_SLOVAK_STANDARD 131 ISLANG_SLOVENIAN 131 ISLANG_SLOVENIAN_STANDARD 131 ISLANG_SPANISH 131 ISLANG_SPANISH_ARGENTINA 131 ISLANG_SPANISH_BOLIVIA 132 ISLANG_SPANISH_CHILE 132

ISLANG_SPANISH_COLOMBIA 132 ISLANG_SPANISH_COSTARICA 132 ISLANG_SPANISH_DOMINICANREPUBLIC 132 ISLANG_SPANISH_ECUADOR 132 ISLANG_SPANISH_ELSALVADOR 132 ISLANG_SPANISH_GUATEMALA 132 ISLANG_SPANISH_HONDURAS 133 ISLANG_SPANISH_MEXICAN 133 ISLANG_SPANISH_MODERNSORT 133 ISLANG_SPANISH_NICARAGUA 133 ISLANG_SPANISH_PANAMA 133 ISLANG_SPANISH_PARAGUAY 133 ISLANG_SPANISH_PERU 133 ISLANG_SPANISH_PUERTORICO 133 ISLANG_SPANISH_TRADITIONALSORT 134 ISLANG_SPANISH_URUGUAY 134 ISLANG_SPANISH_VENEZUELA 134 ISLANG_SW 134 ISLANG_SWEDISH 134 ISLANG_SWEDISH_STANDARD 134 ISLANG_THAI 134 ISLANG_THAI_STANDARD 134 ISLANG_TURKISH 135 ISLANG_TURKISH_STANDARD 135 ISLANG_UKRAINIAN 135 ISLANG_UKRAINIAN_STANDARD 135 ISLANG_VIETNAMESE 135 ISLANG_VIETNAMESE_STANDARD 135 ISMSI_HANDLE 290 IsObject 924 ISOS_ST_ALL 137 ISOS_ST_BACKOFFICE 137 ISOS_ST_DATACENTER 138 ISOS_ST_ENTERPRISE 138 ISOS_ST_PROC_ARCH_32 138 ISOS_ST_PROC_ARCH_AMD64 139 ISOS_ST_PROC_ARCH_IA64 139 ISOS_ST_SERVER 139 ISOS_ST_SERVER2003_R2 139 ISOS_ST_SMALLBUSINESS 140 ISOS_ST_SMALLBUSINESS_RESTRICTED 140 ISOS_ST_TERMINAL 140 ISOS_ST_WORKSTATION 141 ISOS_ST_XP_HOME 141 ISOS_ST_XP_PRO 141 ISOSL_ALL 135, 757 ISOSL_NT40 757

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1563

Index

ISOSL_NT40_ALPHA 757 ISOSL_SUPPORTED 136 ISOSL_WIN2000 136, 757 ISOSL_WIN2000_ALPHA 757 ISOSL_WIN7_SERVER2008R2 136 ISOSL_WIN95 757 ISOSL_WIN98 757 ISOSL_WINSERVER2003 136 ISOSL_WINVISTA 136 ISOSL_WINVISTA_SERVER2008 137 ISOSL_WINXP 137 ISRES 291 ISURL_COMPONENTS 247 ISUS_AGENT_FEATURE 141 ISUS_MAIN_FEATURE 142 ISUS_PRODUCT_CODE 241 ISUS_TEXTSUB_HOST 142 ISUS_TEXTSUB_INTERVAL 142 ISUS_TEXTSUB_LANGUAGE 142 ISUS_TEXTSUB_LOGO 142 ISUS_TEXTSUB_MANAGER 143 ISUS_TEXTSUB_VERSION 143 ISUS_UPDATEMANAGER_FEATURE 143 ISUSER 291 ISVERSION 291

endswitch 24 endwhile 25 exit 16 export 16 external 16 for 16 goto 17 if 20 method 21 program 7 property() 21 prototype 22 repeat 22 return 22 step 16 switch 24 then 18 to 16 typedef 253 until 22 while 25

L
LAAW_OPTION_CHANGEDIRECTORY 148 LAAW_OPTION_FIXUP_PROGRAM 149 LAAW_OPTION_HIDDEN 149 LAAW_OPTION_MAXIMIZED 149 LAAW_OPTION_MINIMIZED 150 LAAW_OPTION_NO_CHANGEDIRECTORY 150 LAAW_OPTION_NOWAIT 150 LAAW_OPTION_SET_BATCH_INSTALL 151 LAAW_OPTION_SHOW_HOURGLASS 151 LAAW_OPTION_USE_CALLBACK 151 LAAW_OPTION_USE_SHELLEXECUTE 152 LAAW_OPTION_WAIT 152 LAAW_OPTION_WAIT_INCL_CHILD 152 LAAW_PARAMETERS 291 LAAW_PROCESS_INFORMATION 293 LAAW_SHELLEXECUTEINFO 293 LAAW_SHELLEXECUTEVERB 294 LAAW_STARTUPINFO 295 Label 17 LANGUAGE 153 Language 256 AskYesNo dialog 481 filtering 754
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

K
KBYTES 147, 860 KEY_CREATE_LINK 147 KEY_CREATE_SUB_KEY 147 KEY_ENUMERATE_SUB_KEYS 148 KEY_NOTIFY 148 KEY_QUERY_VALUE 148 KEY_SET_VALUE 148 Keywords 16 abort 15 BYREF 440 BYVAL 441 case 24 default 24 downto 16 else 19 elseif 20 endfor 16 endif 19 endprogram 7
1564

Index

IDs 256 keywords 15 selected language 304 supported by file 1499 LANGUAGE_SUPPORTED constant 153 LaunchApp 924 LaunchApp Example 924 LaunchAppAndWait 925 LaunchAppAndWait Example 925 LaunchAppAndWaitInitStartupInfo 927 LaunchApplication 929 LaunchApplicationInit 935 Launching 395 another setup script 395 program from a setup script 925 LESS_THAN 153, 821 License agreement 1226, 1228, 1231, 1234, 1236, 1239 LINE_NUMBER 153, 825 LIST data type 247 List 941 LIST_NULL 155, 949 adding elements 941 ListAddItem 937 ListAddItem Example 938 ListAddList 940 ListAddString 941 ListAddString Example 942 ListAppendFromArray 943 ListAppendToArray 944 LISTBOX_ENTER 154, 594 LISTBOX_SELECT 154, 594 components 779 ListConvertNumToStr 945 ListConvertStrToNum 946 ListCount 947 counting elements 947 ListCount Example 948 ListCreate 949 creating 949 ListCreate Example 950 ListCurrentItem 951 ListCurrentItem Example 952 ListCurrentString 953 ListCurrentString Example 954 ListDeleteAll 955

ListDeleteItem 956 ListDeleteItem Example 957 ListDeleteString 959 ListDeleteString Example 959 ListDestroy 961 destroying 961 finding an element 967 ListDestroy Example 962 ListFindItem 963 ListFindItem Example 964 ListFindKeyValueString 965 ListFindString 967 ListFindString Example 968 LISTFIRST 154, 987 ListGetFirstItem 970 ListGetFirstItem Example 970 ListGetFirstString 972 ListGetFirstString Example 972 ListGetIndex 974 ListGetNextItem 974 ListGetNextItem Example 975 ListGetNextString 977 getting elements 953 InstallScript functions 406 ListGetNextString Example 977 ListGetType 979 ListGetType Example 979 LISTLAST 154, 987 LISTNEXT 154, 987 LISTPREV 155, 987 ListProcessing 994 ListReadFromFile 980 ListReadFromFile Example 981 ListSetCurrentItem 982 ListSetCurrentItem Example 983 ListSetCurrentString 985 ListSetCurrentString Example 986 ListSetIndex 987 ListSetIndex Example 989 ListValid 991 ListValidType 992 ListWriteToFile 994 ListWriteToFile Example 995 ListWriteToFileEx 996 LoadStringFromStringTable 997 LOBYTE 998 Local variables 260

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1565

Index

Locked files 912 InstallScript functions 413 testing 912 LOCKEDFILE 155, 912 Log file 560 LOGGING 155, 912 Logical operators 443 LogReadCustomNumber 999 LogReadCustomNumber Example 1000 LogReadCustomString 1001 LogReadCustomString Example 1003 LogWriteCustomNumber 1004 LogWriteCustomNumber Example 1005 LogWriteCustomString 1006 LogWriteCustomString Example 1007 LONG data type 247 Long file name functions 408 Long filenames 1008 LongPathFromShortPath 1008 LongPathFromShortPath Example 1008 LongPathToQuote 1009 LongPathToQuote Example 1010 LongPathToShortPath 1011 LongPathToShortPath Example 1012 Loop 22 LOWER_LEFT 156, 1052 LOWER_RIGHT 156, 1057 LOWORD 1013 LOWORD Example 1014 LPSTR data type 247 LPWSTR data type 247 LWFT_OPTION_WRITE_AS_ANSI 156 LWFT_OPTION_WRITE_AS_UNICODE 157 LWTF_OPTION_APPEND_TO_FILE 156 LWTF_OPTION_WRITE_AS_UNICODE 157

M
MAGENTA 157, 1324 MAINT_OPTION 298 MAINT_OPTION_MULTI_INSTANCE 298 MAINT_OPTION_NONE 298 MAINT_OPTION_STANDARD 298 MAINTENANCE 298 MaintenanceStart 1015 Math coprocessor 912 MATH_COPROCESSOR 157, 912
1566

MB_STYLE 1384 MBYTES 157, 860 MEDIA 298 Media library 298 MEDIA_FIELD_COMPANY_NAME 158 MEDIA_FIELD_MEDIA_FLAGS 159 MEDIA_FIELD_PREVIOUS_VERSIONS 159 MEDIA_FIELD_PRODUCT_COMMENTS 159 MEDIA_FIELD_PRODUCT_EXE 159 MEDIA_FIELD_PRODUCT_ICON 160 MEDIA_FIELD_PRODUCT_NAME 160 MEDIA_FIELD_PRODUCT_NOMODIFY 158 MEDIA_FIELD_PRODUCT_NOREMOVE 158 MEDIA_FIELD_PRODUCT_README 160 MEDIA_FIELD_PRODUCT_SUPPORT_CONTACT 161 MEDIA_FIELD_PRODUCT_SUPPORT_PHONE 161 MEDIA_FIELD_PRODUCT_SUPPORT_URL 161 MEDIA_FIELD_PRODUCT_UPDATE_URL 162 MEDIA_FIELD_PRODUCT_URL 162 MEDIA_FIELD_PRODUCT_VERSION 162 MEDIA_FIELD_TARGETDIR 163 MEDIA_FLAG_FORMAT_DIFFERENTIAL 163 MEDIA_FLAG_FORMAT_PATCH 163 MEDIA_FLAG_UPDATEMODE_SUPPORTED 164 MEDIA_PASSWORD_KEY 164 MediaGetData 1017 MediaGetDataEx 1018 Member 253 data structure 253 operator 443 Memory 891 extended 891 free 880 total 891 MessageBeep 1020 MessageBeep Example 1021 MessageBox 1022 MessageBox Example 1023 MessageBoxEx 1024 send to windows 1314 METAFILE 164, 1380 Metafiles 1329 method 21 MIDI files 1061 Miscellaneous Event Handlers 354 Miscellaneous functions 408 MMEDIA_AVI 164, 1061

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

MMEDIA_MIDI 165, 1061 MMEDIA_PLAYASYNCH 165, 1061 MMEDIA_PLAYCONTINUOUS 165, 1061 MMEDIA_PLAYSYNCH 165, 1061 MMEDIA_STOP 166, 1061 MMEDIA_SWF 166, 1061 MMEDIA_WAVE 166, 1061 MODE 299 MODIFY 166 modulus operator 438 Move Data Handlers 339 Moving 1047 lines in a batch file 502 path in path buffer 1047 MSI_TARGETDIR 299 MULTI_INSTANCE_COUNT 299

O
Object handlers 452 InitProperties 453 ReadProperties 453 WriteProperties 453 Objects 449 InstallScript functions 409 Objects object setting status 1348 OFF 170, 1433 OK 170 ON 170, 1433 OnAbort 357 OnAdminInstallUIAfter 357 OnAdminInstallUIBefore 358 OnAdminPatchUIAfter 358 OnAdminPatchUIBefore 358 OnAdvertisementAfter 358 OnAdvertisementBefore 358 OnAppSearch 336 OnBegin 336 OnCanceling 359 OnCCPSearch 337 OnCheckMediaPassword 332 OnComponentError 359 OnCustomizeUninstInfo 341 OnDIFxLogCallback 360 OnEnd 351 OnError 361 OnException 361 OnFileError 362 OnFileLocked 362 OnFileReadOnly 363 OnFilesInUse 364 OnFilterComponents 332 OnFirstUIAfter 350 OnFirstUIBefore 337 OnGeneratedMSIScript 341 OnGeneratingMSIScript 342 OnHelp 365 OnIISComponentInstalled 342 OnIISInitialize 337 OnIISUninitialize 350 OnIISVRootUninstalling 342 OnInstalled 352 OnInstalledFile 342
1567

N
Nested if-then-else structure 19 Nested while Example 26 Networks 901 getting driver name from System.ini 891 mapping drives 901 remote registry 1080 Newline character 11 NEXT 167, 1188 NEXTBUTTON 168, 668 NO 168, 481 NO_SUBDIR 169 NONEXCLUSIVE 168, 1164 NORMAL_PRIORITY_CLASS 169 NORMALMODE 168, 299 NOSET 169, 703 Not operator 443 NOTEXISTS 169, 697 NOTHING 23 NOWAIT 675 NULL 170, 457 NUMBER data type 247 NUMBERLIST 170, 949 NumToStr 1026 NumToStr Example 1026

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

Index

OnInstalledFontFile 343 OnInstallFilesActionAfter 343 OnInstallFilesActionBefore 343 OnInstalling 353 OnInstallingFile 343 OnInternetError 365 OnLaunchAppAndWaitCallback 366 OnLogonUserSetMsiProperties 367 ONLYDIR 171, 641 OnMaintUIAfter 350 OnMaintUIBefore 337 OnMD5Error 367 OnMoved 344 OnMoveData 344 OnMoving 345 OnMsiSilentInstall 368 OnNetApiCreateUserAccount 345 OnNextDisk 369 OnOutOfDiskSpace 369 OnPatchUIAfter 369 OnPatchUIBefore 370 OnRebooted 370 OnRemovingSharedFile 370 OnResumeUIAfter 371 OnResumeUIBefore 372 OnRMFilesInUse 372 OnSelfRegistrationError 373 OnSetTARGETDIR 333 OnSetUpdateMode 334 OnShowUI 375 OnSQLBatchScripts 345 OnSQLComponentInstalled 338 OnSQLComponentUninstalled 338 OnSQLLogin 338 OnSQLServerInitialize 338 OnSQLServerInitializeMaint 339 OnUninstall (InstallScript) 376 OnUnInstalled 353 OnUninstalledFile 346 OnUnInstalling 354 OnUninstallingDIFxDriverFile 347 OnUninstallingFile 346 OnUninstallingFontFile 347 OnUpdateUIAfter 350 OnUpdateUIBefore 339 OnWarning 374 OnXMLComponentInstalled 348

OnXMLComponentUninstalling 348 OnXMLInitialize 339 OnXMLUninitialize 350 OpenFile 1027 OpenFile Example 1028 OpenFileMode 1029 OpenFileMode Example 1030 Opening 1027 files 1027 Operating system filtering 757 type 891 version 891 Operators 435 address 257 arithmetic 437 assignment 439 bit 439 BYREF 440 BYVAL 441 indirection 442 logical 443 member 443 precedence 437 preprocessor directives 317 relational 445 string 446 string constant 446 string entries 252 structure pointer 447 Options 471 getting user options 1250 Or operator 443 OTHER_FAILURE 171, 821 OUT_OF_DISK_SPACE 171, 831

P
PACKAGE_LOCATION 300 Pad with blanks or zeros 12 PARALLEL 171, 891 Parallel ports 891 ParsePath 1032 ParsePath Example 1033 ParseUrl 1035 Parsing, strings 1443 PARTIAL 172, 1039
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

1568

Index

Password 766 PATH 172, 1032 Path 436 Path buffer 1039 adding a search directory 1036 deleting a search directory 1039 getting a path string 1045 InstallScript functions 410 repositioning a search directory 1047 searching for a directory 1042 storing a search directory 1050 PATH_EXISTS 172, 912 PathAdd 1036 adding to batch file 483 appending to 436 PathAdd Example 1037 PathDelete 1039 exists 912 PathDelete Example 1040 PathFind 1042 PathFind Example 1043 PathGet 1045 PathGet Example 1045 PathMove 1047 parsing 1032 removing a trailing backslash 1450 removing drive designation 852 PathMove Example 1048 PathSet 1050 PathSet Example 1051 Pausing 639 PCRESTORE 172 Percent sign 12 PERSONAL 173, 1066 PlaceBitmap 1052 Placebitmap Examples 1056 Placeholders 1299 PlaceWindow 1057 PlaceWindow Example 1060 PlayMMedia 1061 PlayMMedia Example 1063 POINTER data type 247 Ports 891 parallel 891 serial 891 PostShowComponentDlg 1064 Predefined constants 29

Predefined Script Variables 239 Preprocessor directives 317 Preprocessor statements 317 #define 252 #elif 319 #error 319 #ifdef 320 #ifndef 320 #include 321 #undef 322 #warning 323 PreShowComponentDlg 1065 PROCESSOR_AMD_X8664 310 PROCESSOR_ARCH_AMD64 306 PROCESSOR_ARCH_IA64 306 PROCESSOR_ARCH_INTEL 306 PROCESSOR_ARCHITECTURE_AMD64 310 PROCESSOR_ARCHITECTURE_IA64 310 PROCESSOR_ARCHITECTURE_INTEL 310 PROCESSOR_ARCHITECTURE_UNKNOWN 310 PROCESSOR_INTEL_386 310 PROCESSOR_INTEL_486 310 PROCESSOR_INTEL_IA64 310 PROCESSOR_INTEL_PENTIUM 310 Product 1256 PRODUCT_GUID 300 name 1283 PRODUCT_INSTALLED 300 ProgDefGroupType 281 program 7 Program folder items 457 adding 457 Program folders 281 creating 565 deleting 647 deleting icons 645 displaying 1365 FOLDER_PROGRAMS 281 selecting 1188 PROGRAMFILES 300 PROGRAMFILES64 301 Progress indicator 1350 initializing 1350 updating 1433 property() keyword 21 prototype keyword 22 Punctuation rules 7

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1569

Index

Q
Query 1119 QueryProgItem 1067 registry 1119 QueryProgItem Example 1069 QueryShellMgr 1071 QueryShellMgr Example 1072 Quotation marks 12 inserting in a string 11

R
READ_CONTROL 173 ReadArrayProperty 1072 ReadBoolProperty 1073 ReadBytes 1074 ReadBytes Example 1075 Reading 980 binary files 1074 text files 878 ReadNumberProperty 1076 Read-only files 94 ReadProperties 453 ReadStringProperty 1077 RebootDialog 1078 RebootDialog Example 1079 REBOOTED 173 Rebooting target machine through SdFinishReboot 1215 RECORDMODE 173 RED 174, 1324 Reference keys 500 batch files 497 configuration files 533 REGDB_APPPATH 174, 1131 REGDB_APPPATH_DEFAULT 174, 1106 REGDB_BINARY 175, 1125 REGDB_ERR_CONNECTIONEXISTS 175, 1080 REGDB_ERR_CORRUPTEDREGISTRY 175, 1080 REGDB_ERR_INITIALIZATION 175, 1080 REGDB_ERR_INVALIDHANDLE 176, 1080 REGDB_ERR_INVALIDNAME 176, 1080 REGDB_KEYPATH_APPPATHS 176 REGDB_KEYPATH_DOTNET_10 176 REGDB_KEYPATH_DOTNET_11 176

REGDB_KEYPATH_DOTNET_20 177 REGDB_KEYPATH_DOTNET_30 177 REGDB_KEYPATH_DOTNET_30_SP 178 REGDB_KEYPATH_DOTNET_35 178 REGDB_KEYPATH_DOTNET_40_CLIENT 178 REGDB_KEYPATH_DOTNET_40_FULL 179 REGDB_KEYPATH_ISUNINSTINFO 179 REGDB_KEYPATH_RUN 179 REGDB_KEYPATH_RUNONCE 179 REGDB_KEYPATH_RUNONCEEX 180 REGDB_KEYPATH_SHAREDDLLS 180 REGDB_KEYPATH_UNINSTALL 180 REGDB_KEYPATH_WINCURRVER 180 REGDB_KEYPATH_WINCURRVER_AUTO 180 REGDB_KEYPATH_WINNTCURRVER 180 REGDB_KEYS 181, 1119 REGDB_NAMES 181, 1119 REGDB_NUMBER 181, 1125 REGDB_OPTION_DISABLETEXTSUBS 301 REGDB_OPTION_NO_DELETE_OLD_MAJMIN_VERSION 301 REGDB_OPTION_USE_DEFAULT_OPTIONS 301 REGDB_OPTION_WOW64_64KEY 301 REGDB_OPTIONS 301 REGDB_STRING 181, 1125 REGDB_STRING_EXPAND 182, 1111 REGDB_STRING_MULTI 182, 1136 REGDB_UNINSTALL_COMMENTS 182 REGDB_UNINSTALL_CONTACT 182 REGDB_UNINSTALL_DISPLAY_VERSION 183 REGDB_UNINSTALL_DISPLAYICON 183 REGDB_UNINSTALL_HELPLINK 183 REGDB_UNINSTALL_HELPTELEPHONE 184 REGDB_UNINSTALL_INSTALLDATE 184 REGDB_UNINSTALL_INSTALLLOC 184 REGDB_UNINSTALL_INSTALLSOURCE 185 REGDB_UNINSTALL_LANGUAGE 185 REGDB_UNINSTALL_LOGFILE 185 REGDB_UNINSTALL_MAINT_OPTION 186 REGDB_UNINSTALL_MAJOR_VERSION 186 REGDB_UNINSTALL_MAJOR_VERSION_OLD 186 REGDB_UNINSTALL_MINOR_VERSION 187 REGDB_UNINSTALL_MINOR_VERSION_OLD 187 REGDB_UNINSTALL_MODIFYPATH 187 REGDB_UNINSTALL_NAME 188, 1131 REGDB_UNINSTALL_NOMODIFY 188 REGDB_UNINSTALL_NOREMOVE 188

1570

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

REGDB_UNINSTALL_NOREPAIR 188 REGDB_UNINSTALL_PRODUCTGUID 189 REGDB_UNINSTALL_PRODUCTID 189 REGDB_UNINSTALL_PUBLISHER 189 REGDB_UNINSTALL_README 190 REGDB_UNINSTALL_REGCOMPANY 190 REGDB_UNINSTALL_REGOWNER 190 REGDB_UNINSTALL_STRING 191 REGDB_UNINSTALL_SYSTEMCOMPONENT 191 REGDB_UNINSTALL_URLINFOABOUT 191 REGDB_UNINSTALL_URLUPDATEINFO 192 REGDB_UNINSTALL_VERSION 192 REGDB_VALUENAME_APPPATH 192 REGDB_VALUENAME_APPPATHDEFAULT 192 REGDB_VALUENAME_INSTALL 193 REGDB_VALUENAME_INSTALLSUCCESS 193 REGDB_VALUENAME_SP 193 REGDB_VALUENAME_UNINSTALL_COMMENTS 193 REGDB_VALUENAME_UNINSTALL_CONTACT 193 REGDB_VALUENAME_UNINSTALL_DISPLAYICON 193 REGDB_VALUENAME_UNINSTALL_DISPLAYNAME 194 REGDB_VALUENAME_UNINSTALL_DISPLAYVERSION 194 REGDB_VALUENAME_UNINSTALL_HELPLINK 194 REGDB_VALUENAME_UNINSTALL_HELPTELEPHONE 194 REGDB_VALUENAME_UNINSTALL_INSTALLDATE 194 REGDB_VALUENAME_UNINSTALL_INSTALLLOCATION 195 REGDB_VALUENAME_UNINSTALL_INSTALLSOURCE 195 REGDB_VALUENAME_UNINSTALL_LANGUAGE 195 REGDB_VALUENAME_UNINSTALL_LOGFILE 195 REGDB_VALUENAME_UNINSTALL_LOGMODE 195 REGDB_VALUENAME_UNINSTALL_MAJORVERSION 196 REGDB_VALUENAME_UNINSTALL_MAJORVERSION_OLD 196 REGDB_VALUENAME_UNINSTALL_MINORVERSION 196 REGDB_VALUENAME_UNINSTALL_MINORVERSION_OLD 196 REGDB_VALUENAME_UNINSTALL_MODIFYPATH 196 REGDB_VALUENAME_UNINSTALL_NOMODIFY 197 REGDB_VALUENAME_UNINSTALL_NOREMOVE 197 REGDB_VALUENAME_UNINSTALL_NOREPAIR 197 REGDB_VALUENAME_UNINSTALL_PRODUCTGUID 197 REGDB_VALUENAME_UNINSTALL_PRODUCTID 197 REGDB_VALUENAME_UNINSTALL_PUBLISHER 197 REGDB_VALUENAME_UNINSTALL_README 198 REGDB_VALUENAME_UNINSTALL_REGCOMPANY 198

REGDB_VALUENAME_UNINSTALL_REGOWNER 198 REGDB_VALUENAME_UNINSTALL_SYSTEMCOMPONENT 198 REGDB_VALUENAME_UNINSTALL_UNINSTALLSTRING 198 REGDB_VALUENAME_UNINSTALL_URLINFOABOUT 199 REGDB_VALUENAME_UNINSTALL_URLUPDATEINFO 199 REGDB_VALUENAME_UNINSTALL_VERSION 199 REGDB_VALUENAME_UNINSTALLKEY 199 REGDB_VALUENAME_WINCURRVER_REGORGANIZATION 199 REGDB_VALUENAME_WINCURRVER_REGOWNER 200 REGDB_WINCURRVER_REGORGANIZATION 200 REGDB_WINCURRVER_REGOWNER 200 RegDBConnectRegistry 1080 RegDBConnectRegistry Example 1083 RegDBCopyKeys 1084 RegDBCopyValues 1087 RegDBCreateKeyEx 1089 RegDBCreateKeyEx Example 1091 RegDBDeleteItem 1092 RegDBDeleteKey 1095 RegDBDeleteKey Example 1096 RegDBDeleteValue 1097 RegDBDeleteValue Example 1098 RegDBDisConnectRegistry 1099 RegDBDisConnectRegistry Example 1100 RegDBGetAppInfo 1102 RegDBGetAppInfo Example 1103 RegDBGetDefaultRoot 1105 RegDBGetItem 1106 RegDBGetItem Example 1110 RegDBGetKeyValueEx 1111 RegDBGetKeyValueEx Example 1113 RegDBGetUninstCmdLine 1115 RegDBKeyExist 1116 RegDBKeyExist Example 1117 RegDBQueryKey 1119 RegDBQueryKey Example 1120 RegDBQueryKeyCount 1122 RegDBQueryStringMultiStringCount 1123 REGDBREMOTEREGCONNECTED 174 RegDBSetAppInfo 1125 RegDBSetAppInfo Example 1126 RegDBSetDefaultRoot 1128 RegDBSetDefaultRoot Example 1129 RegDBSetItem 1131

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1571

Index

RegDBSetItem Example 1134 RegDBSetKeyValueEx 1136 RegDBSetKeyValueEx Example 1139 RegDBSetVersion 1140 REGFONT_OPTION_DEFAULT 200 REGFONT_OPTION_DONTBROADCASTFONTCHANGEMS G 200 REGFONT_OPTION_DONTUPDATEREGISTRY 201 RegisterFontResource 1141 Registration 1260 Registry 411 check whether a key exists 1116 company name 1260 connecting to remote registry 1080 creating registry keys 1089 creating registry sets 567 default root 1128 delete a key's value 1097 delete registry keys 1095 disconnecting from remote registry 1099 REGISTRYFUNCTIONS_USETEXTSUBS 201 getting information from the registry 1102 InstallScript functions 411 querying keys 1119 serial number 1260 setting information in the registry 1136 user name 1258 REINSTALLMODE 303 Relational operators 445 ReleaseDialog 1144 ReleaseDialog Example 1145 Remote registry 1080 REMOTE_DRIVE 201, 901 REMOVE 201, 1052 REMOVEABLE_DRIVE 202, 901 REMOVEALL 202 REMOVEALLMODE 303 REMOVEONLY 303 RenameFile 1147 RenameFile Example 1148 Renaming 1147 files 1147 REPAIR 202 repeat 22 REPLACE 202, 703 ReplaceFolderIcon 1150 ReplaceFolderIcon Example 1152

ReplaceProfString 1153 ReplaceProfString Example 1155 Replacing 706 string in initialization file 1153 text in batch files 706 Reserved words 14 RESET 203, 840 Resize 1156 Response file 1369 RESTART 203, 1042 Restarting target machine through SdFinishReboot 1215 return 22 RGB 1156 RGB Example 1157 ROOT 203, 641 RUN_MAXIMIZED 203, 1150 RUN_MINIMIZED 204, 1067 RUN_SEPARATEMEMORY 1150 runas 929 Running a program from a setup script 924

S
Saving 994 Screen dimensions 865 Script 7 Script files 8 Script-created features 399 declarations 6 identifiers 7 overview 5 program block 7 punctuation rules 7 structure 6 using white space 8 SdAskDestPath 1159 SdAskDestPath Example 1161 SdAskDestPath2 1161 SdAskOptions 1164 SdAskOptions Example 1166 SdAskOptionsList 1167 SdAskOptionsList Example 1169 SdBitmap 1170 SdBitmap Example 1172 SdComponentDialog 382 SdComponentDialog2 382
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

1572

Index

SdComponentDialogAdv 382 SdComponentMult 382 SdComponentTree 382 SdConfirmNewDir 1173 SdConfirmNewDir Example 1174 SdConfirmRegistration 1175 SdConfirmRegistration Example 1176 SdCustomerInformation 1177 SdCustomerInformation Example 1180 SdCustomerInformationEx 1181 SdCustomerInformationEx Example 1184 SdDiskSpace2 1185 SdDiskSpace2 Example 1186 SdDiskSpaceRequirements 1187 SdDisplayTopics 1188 SdDisplayTopics Example 1189 SdExceptions 1191 SdExceptions Example 1192 SdFeatureDialog 1193 SdFeatureDialog Example 1195 SdFeatureDialog2 1196 SdFeatureDialog2 Example 1198 SdFeatureDialogAdv 1199 SdFeatureDialogAdv Example 1201 SdFeatureMult 1202 SdFeatureMult Example 1204 SdFeatureTree 1205 SdFeatureTree Example 1207 SdFilesInUse 1208 SdFilesInUse Example 1210 SdFinish 1211 SdFinish Example 1212 SdFinishEx 1214 SdFinishEx Example 1215 SdFinishReboot 1215 SdFinishReboot Example 1217 SdFinishUpdate 1218 SdFinishUpdateEx 1218 SdFinishUpdateReboot 1220 SdFinishUpdateReboot Example 1222 SdGeneralInit 1222 SdGeneralInit example 1223 SdInit 1225 SdInit Example 1225 SdLicense 1226 SdLicense Example 1227 SdLicense2 1228

SdLicense2Ex 1231 SdLicense2Rtf 1234 SdLicenseEx 1236 SdLicenseRtf 1239 SdLoadString 1241 SdLoadString Example 1242 SdLogonUserBrowse 1243 SdLogonUserCreateUser 1243 SdLogonUserInformation 1243 SdLogonUserListGroups 1244 SdLogonUserListServers 1245 SdLogonUserListUsers 1245 SdMakeName 1245 SdMakeName Example 1246 SdOptionsButtons 1250 SdOptionsButtons Example 1252 SdOutOfDiskSpace 1254 SdPatchWelcome 1255 SdPatchWelcome Example 1256 SdProductName 1256 SdProductName Example 1257 SdRegisterUser 1258 SdRegisterUser Example 1260 SdRegisterUserEx 1260 SdRegisterUserEx Example 1263 SdRMFilesInUse 1264 Sdsadlg.rul 1277 SdSelectFolder 1266 SdSelectFolder Example 1267 SdSetupCompleteError 1268 SdSetupCompleteError Example 1269 SdSetupType 1270 SdSetupType Example 1271 SdSetupType2 1272 SdSetupType2 Example 1274 SdSetupTypeEx 1275 SdSetupTypeEx Example 1276 SdShowAnyDialog 1277 SdShowAnyDialog Example 1278 SdShowDlgEdit1 1279 SdShowDlgEdit1 Example 1280 SdShowDlgEdit2 1281 SdShowDlgEdit2 Example 1282 SdShowDlgEdit3 1283 SdShowDlgEdit3 Example 1285 SdShowFileMods 1286 SdShowFileMods Example 1287

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1573

Index

SdShowInfoList 1289 SdShowInfoList Example 1290 SdShowMsg 1291 SdShowMsg Example 1293 SdStartCopy 1293 SdStartCopy Example 1295 SdStartCopy2 1296 SdSubstituteProductInfo 1299 SdWelcome 1299 SdWelcome Example 1300 SdWelcomeMaint 1301 SdWelcomeMaint Example 1302 Search path 1042 Searching 1441 string 1441 text files 828 Secondary shell 924 SeekBytes 1303 SeekBytes Example 1304 SelectDir 1306 SelectDir Example 1308 SelectDirEx 1309 SelectDirEx Example 1311 SELECTED_LANGUAGE 304 SELECTFOLDER 204 SelectFolder 1312 SelectFolder Example 1313 Selecting 1312 features 1250 program folders 1312 SELFREGISTER 204, 1541 SELFREGISTERBATCH 204, 683 SELFREGISTRATIONPROCESS 205, 673 SendMessage 1314 SendMessage Example 1315 SERIAL 205, 891 Serial number 1260 Serial ports 891 SERVICE_ADAPTER 205 SERVICE_ALL_ACCESS 205 SERVICE_AUTO_START 206 SERVICE_BOOT_START 206 SERVICE_CHANGE_CONFIG 206 SERVICE_CONTINUE_PENDING 206 SERVICE_DEMAND_START 207 SERVICE_DIFX_32 671, 685 SERVICE_DIFX_AMD64 671, 685

SERVICE_DIFX_IA64 671, 685 SERVICE_DISABLED 207 SERVICE_ENUMERATE_DEPENDENTS 207 SERVICE_ERROR_CRITICAL 208 SERVICE_ERROR_IGNORE 208 SERVICE_ERROR_NORMAL 208 SERVICE_ERROR_SEVERE 208 SERVICE_FILE_SYSTEM_DRIVER 209 SERVICE_FLAG_DIFX_32 209 SERVICE_FLAG_DIFX_AMD64 209 SERVICE_FLAG_DIFX_IA64 210 SERVICE_FLAG_ISFONTREG 210 SERVICE_INTERACTIVE_PROCESS 210 SERVICE_INTERROGATE 210 SERVICE_IS_PARAMS 241 SERVICE_IS_STATUS 243 SERVICE_ISFONTREG 211 SERVICE_ISUPDATE 211 SERVICE_KERNEL_DRIVER 211 SERVICE_PAUSE_CONTINUE 212 SERVICE_PAUSE_PENDING 212 SERVICE_PAUSED 211 SERVICE_QUERY_CONFIG 212 SERVICE_QUERY_STATUS 213 SERVICE_RECOGNIZER_DRIVER 213 SERVICE_RUNNING 213 SERVICE_START 213 SERVICE_START_PENDING 214 SERVICE_STOP 214 SERVICE_STOP_PENDING 215 SERVICE_STOPPED 214 SERVICE_SYSTEM_START 215 SERVICE_USER_DEFINED_CONTROL 215 SERVICE_WIN32_OWN_PROCESS 215 SERVICE_WIN32_SHARE_PROCESS 216 ServiceAddService 1317 ServiceExistsService 1318 ServiceGetServiceState 1319 ServiceInitParams 1320 ServiceRemoveService 1321 ServiceStartService 1322 ServiceStopService 1323 SET command 700 adding to batch file 700 set keyword 23 SetColor 1324 SetColor Example 1326

1574

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

SetDialogTitle 1327 SetDialogTitle Example 1328 SetDisplayEffect 1329 SetDisplayEffect Example 1330 SetErrorMsg 1332 SetErrorMsg Example 1333 SetErrorTitle 1334 SetErrorTitle Example 1335 SetExtendedErrInfo 1336 SetFileInfo 1337 SetFileInfo Example 1339 SetFont 1340 SetFont Example 1341 SetInstallationInfo 1342 SetObjectPermissions 1343 SetObjectPermissions Example 1346 SetStatus 1347 SetStatusEx 1348 SetStatusExStaticText 1349 SetStatusWindow 1350 SetStatusWindow Example 1351 Setting 1324 background and status bar 1324 color 1156 configuration file value 546 default batch file name 505 default registry root 1128 default system configuration file 544 dialog titles 1327 display effects 1329 error message box 1334 feature properties and data 796 file mode 1029 setup type 807 SetTitle 1352 SetTitle Example 1355 Setup script 7 comments 8 declarations 6 including 321 launching 675 limits for 5 overview 5 program block 7 punctuation rules 7 structure 6 using white space 8

Setup types 1275 getting setup type data 803 selecting 1270 setting 807 Setup.exe 291 version 291 Setup.ini limits for 5 Setup.inx 675 Setup.rul limits for 5 SETUP_PACKAGE 217 SetUpdateStatus 1356 SetUpdateStatusReboot 1356 SETUPTYPE 216 SetupType 1356 SetupType Example 1359 SETUPTYPE_INFO_DESCRIPTION 216 SETUPTYPE_INFO_DISPLAYNAME 216 SETUPTYPE_STR_COMPACT 217 SETUPTYPE_STR_COMPLETE 217 SETUPTYPE_STR_CUSTOM 217 SETUPTYPE_STR_TYPICAL 217 SetupType2 1361 SetupType2 Example 1363 SEVERE 218, 1022 Shared files 413 SHAREDFILE 218, 1514 SHAREDSUPPORTDIR 304 Shell 414 SHELL_OBJECT_FOLDER 304 alternate 871 getting name 1071 InstallScript functions 414 secondary 925 SHORT data type 247 Shortcuts 871 SHOW_PASSWORD_DIALOG 305 ShowObjWizardPages 1365 ShowProgramFolder 1365 ShowProgramFolder Example 1366 ShowWindow 1367 Silent installations 1369 reading the log file 1369 silent mode 299 writing the log file 1374 Silent mode 299

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1575

Index

SILENTMODE 218, 299 SilentReadData 1369 SilentReadData Example 1371 SilentWriteData 1374 SilentWriteData Example 1376 SizeOf 1379 SizeWindow 1380 SizeWindow Example 1381 SKIN_LOADED 218 Sound 1061 playing sound files 1061 Special Registry-Related Functions 414 Sprintf 12 Sprintf Example 1383 SprintfBox 12 SprintfBox Example 1387 SprintfMsiLog 1388 SQL InstallScript functions 416 SQL_BATCH_INSTALL 219 SQL_BATCH_UNINSTALL 219 SQL_BROWSE_ALIAS 219 SQL_BROWSE_ALL 219 SQL_BROWSE_LOCAL 220 SQL_BROWSE_REMOTE 220 SQL_ERROR_GET_SCHEMA_VERSION 220 SQL_ERROR_SCRIPT_COMMAND_ERROR 220 SQL_ERROR_SCRIPT_CONNECTION_NOT_OPEN 221 SQL_ERROR_SCRIPT_UNABLE_OPEN_FILE 221 SQL_ERROR_SET_SCHEMA_VERSION 221 SQLBrowse 1389 SQLBrowse2 1390 SQLDatabaseBrowse 1391 SQLRTComponentInstall 1392 SQLRTComponentUninstall 1393 SQLRTConnect 1394 SQLRTConnect2 1395 SQLRTConnectDB 1397 SQLRTDoRollbackAll 1398 SQLRTGetBatchList 1399 SQLRTGetBatchMode 1400 SQLRTGetBrowseOption 1401 SQLRTGetComponentScriptError 1402 SQLRTGetComponentScriptError2 1404 SQLRTGetConnectionAuthentication 1406 SQLRTGetConnectionInfo 1407 SQLRTGetConnections 1408

SQLRTGetDatabases 1409 SQLRTGetErrorMessage 1410 SQLRTGetLastError 1411 SQLRTGetLastError2 1412 SQLRTGetScriptErrorMessage 1412 SQLRTGetServers 1413 SQLRTGetServers2 1414 SQLRTInitialize 1415 SQLRTInitialize2 1416 SQLRTPutConnectionAuthentication 1417 SQLRTPutConnectionInfo 1417 SQLRTPutConnectionInfo2 1418 SQLRTServerValidate 1419 SQLRTSetBrowseOption 1421 SQLRTTestConnection 1422 SQLRTTestConnection2 1424 SQLServerLogin 1426 SQLServerSelect 1427 SQLServerSelectLogin 1428 SQLServerSelectLogin2 1429 SQLServerSelectLoginEx 1432 SRCDIR 305 SRCDISK 305 SRCINSTALLDIR 221 SRCTARGETDIR 222 STANDARD_RIGHTS_ALL 222 STANDARD_RIGHTS_EXECUTE 222 STANDARD_RIGHTS_READ 222 STANDARD_RIGHTS_REQUIRED 223 STANDARD_RIGHTS_WRITE 223 Start Programs menu 281 Startup 281 folder 281 STATUS 223, 683 Status bar 1324 Status, setting object status 1348 STATUSBAR 223, 1324 STATUSBBRD 224 STATUSDLG 224, 683 STATUSEX 224, 668 STATUSOLD 224, 668 StatusUpdate 1433 StatusUpdate Example 1435 stdcall 23 step 16 StrAddLastSlash 1436 StrCompare 1437

1576

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

StrCompare Example 1438 StrConvertSizeUnit 1439 StreamFileFromBinary 1440 StrFind 1441 StrFind Example 1441 StrFindEx 1442 StrGetTokens 1443 StrGetTokens Example 1444 STRING data type 247 String Variables 262 STRINGLIST 225, 949 Strings 1450 adding to batch file 703 adding to configuration file 712 appending to path 436 changing case 1461 comparing 1437 comparing versions 1493 concatenating 442 constants 252 convert a number to a string 1026 convert a string to a character 1455 convert a string to a number 1458 converting unit constants to 1439 copy substrings 551 create formatted string 1382 embedding quotation marks 12 find substring 447 getting drive designation from path 854 getting substring 1453 indexing 262 inserting special characters 11 InstallScript functions 420 length (bytes) 1446 length (chars) 1447 operators 446 parsing 1443 parsing path 1032 removing a trailing backslash 1450 removing drive designation from path 852 removing leading and trailing spaces and tabs from 1463 sizing 262 string constant operator 446 string entries 252 StrLength 1446 StrLength Example 1446

StrLengthChars 1447 StrLengthChars Example 1448 StrPutTokens 1449 StrRemoveLastSlash 1450 StrRemoveLastSlash Example 1451 StrReplace 1452 StrSub 1453 StrSub Example 1454 STRTOCHAR 1455 StrToLower 1456 StrToLower Example 1457 StrToNum 1458 StrToNum Example 1459 StrToNumHex 1460 StrToUpper 1461 StrToUpper Example 1462 StrTrim 1463 Structure pointer operator 447 STYLE_BOLD 225, 874 STYLE_ITALIC 225, 874 STYLE_NORMAL 225, 874 STYLE_SHADOW 225, 1340 STYLE_UNDERLINE 226, 874 Substring 551 copying 551 finding 447 getting 1453 SUPPORTDIR 305 SW_MAXIMIZE 226, 1365 SW_MINIMIZE 226, 1365 SW_RESTORE 226, 1365 SW_SHOW 227, 1365 switch 24 SYNCHRONIZE 227 Syntax 12 identifiers 7 punctuation rules 7 quotation marks in strings 12 SYS_BOOTMACHINE 227, 1215 SYS_BOOTWIN 1078 SYSINFO 306 SYSPROCESSORINFO 310 System 536 System (InstallScript function) 1464 System Example 1465 System variables 281 configuration file 715

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1577

Index

DISK1SETUPEXENAME 276 DISK1TARGET 276 ERRORFILENAME 277 files 1337 FOLDER_DESKTOP 278 FOLDER_PROGRAMS 281 FOLDER_STARTMENU 281 FOLDER_STARTUP 281 INFOFILENAME 289 information 891 IS_NULLSTR_PTR 290 ISRES 291 ISUSER 291 ISVERSION 291 MEDIA 298 MODE 299 overview 263 PRODUCT_GUID 300 PROGRAMFILES 300 REMOVEONLY 303 SELECTED_LANGUAGE 304 SHAREDSUPPORTDIR 304 SHELL_OBJECT_FOLDER 304 SRCDIR 305 SRCDISK 305 SUPPORTDIR 305 TARGETDIR 311 TARGETDISK 311 UNINST 312 UNINSTALL_STRING 313 WINDIR 314 WINDISK 314 WINSYSDIR 315 WINSYSDISK 316

opening 1027 reading 878 searching 828 writing 1532 Text substitution 422 TextSubGetValue 1465 TextSubGetValue Example 1466 TextSubParseTextSub 1467 TextSubParseTextSub Example 1468 TextSubSetValue 1469 TextSubSetValue Example 1469 TextSubSubstitute 1470 TextSubSubstitute Example 1471 then 19 TILED 228, 1052 TIME 228, 891 Title 1327 dialog 1327 to 16 Transferring files 1541 CopyFile 554 features 782 XCopyFile 1541 TRUE 228, 1009 TTFONTFILEINFO_FONTTITLE 229 typedef 253 TYPICAL 229, 1356

U
Unary arithmetic operators 438 UNINST 312 UNINSTALL_DISPLAYNAME 313 UNINSTALL_STRING 313 UninstallApplication 1473 Uninstallation Functions 423 Uninstaller 639 abort 15 enabling 639 registry 1089 uninstallation key 312 UNINSTALLKEY 312 until 22 UnUseDLL 1474 UnUseDLL Example 1475 UPDATE_SERVICE_INSTALL 229 used with Disable 671
ISP-1800-RG00 InstallShield 2012 InstallScript Reference Guide

T
Tab character 11 TARGETDIR InstallScript variable 311 TARGETDISK 311 TBYTES 227 Text files 831 closing 514 creating 560 deleting lines 825 inserting lines 831
1578

Index

used with Enable 686 UPDATEMODE 314 UpdateServiceCheckForUpdates 1477 UPDATESERVICECOMPONENT 230 UpdateServiceCreateShortcut 1477 UpdateServiceEnableUpdateManagerInstall 1477 UpdateServiceGetAgentTarget 1478 UpdateServiceOnEnabledStateChange 1478 UpdateServiceRegisterProduct 1478 UpdateServiceRegisterProductEx 1479 UpdateServiceSetHost 1479 UpdateServiceSetLanguage 1479 UPPER_LEFT 230, 1057 UPPER_RIGHT 230, 1057 URL 230 URLs 1035 parsing 1035 USE_LOADED_SKIN 231 UseDLL 1479 UseDLL Example 1482 User 1258 User interface InstallScript functions 423 User name 1175 USER_ADMINISTRATOR 231, 912 USER_INADMINGROUP 231 USER_POWERUSER 231, 912 USERPROFILE 1067 registering 1175 Using white space 8

V
VALID_PATH 232, 912 Validating features 819 Variables 263 declaring 259 local vs. global 260 scope 260 system 281 VARIANT data type 247 VarInit 1484 VarRestore 1485 VarRestore Example 1488 VarSave 1489 VarSave Example 1491 VarSave Stack Example 1492
InstallShield 2012 InstallScript Reference Guide ISP-1800-RG00

VER_DLL_NOT_FOUND 234, 1510 VER_NT_DOMAIN_CONTROLLER 306 VER_NT_SERVER 306 VER_NT_WORKSTATION 306 VER_SUITE_BACKOFFICE 306 VER_SUITE_DATACENTER 306 VER_SUITE_ENTERPRISE 306 VER_SUITE_PERSONAL 306 VER_SUITE_SMALLBUSINESS 306 VER_SUITE_SMALLBUSINESS_RESTRICTED 306 VER_SUITE_TERMINAL 306 VER_UPDATE_ALWAYS 234, 1514 VER_UPDATE_COND 234, 1510 VER_UPDATE_CONDFILE_INSTALLED 1514 VerCompare 1493 VerCompare Example 1494 VerFindFileVersion 1496 VerFindFileVersion Example 1497 VerGetFileLanguages 1499 VerGetFileVersion 1501 VerGetFileVersion Example 1502 VerProductCompareVersions 1503 VerProductGetInstalledVersion 1504 VerProductIsVersionSupported 1505 VerProductNumToStr 1506 VerProductStrToNum 1507 VerProductVerFromVerParts 1508 VerProductVerPartsFromVer 1509 VerSearchAndUpdateFile 1510 VerSearchAndUpdateFile Example 1512 Version checking 1496 comparing versions 1493 finding file version and location 1496 getting files based on version 1501 installing newer versions of files 1510 InstallScript functions 424 product version 1503 Version, 1503 VERSION_COMPARE_RESULT_NEWER 232 VERSION_COMPARE_RESULT_NEWER_NOT_SUPPORTE D 232 VERSION_COMPARE_RESULT_NOT_INSTALLED 232 VERSION_COMPARE_RESULT_OLDER 233 VERSION_COMPARE_RESULT_SAME 233 VERSION_PREVIOUS_VERSION_DELIMITER 233 VerUpdateFile 1514 VerUpdateFile Example 1518

1579

Index

VIDEO 234, 891 Video 1061 adapter type 891 displaying animation files 1061 VIRTUAL_MACHINE_TYPE 234 Visual interface 1433 disabling elements 668 enabling elements 683 getting window handle 842 placing bitmaps 1052 placing window 1057 playing video and sound 1061 progress indicator 1350 setting background and status bar color 1324 setting custom colors 1156 setting dialog titles 1327 setting display effects 1329 setting error message box 1332 setting fonts 1340 setting main window title 1352 sizing objects 1380 updating the progress indicator 1433 void 25 Volume label 891 VOLUMELABEL 235, 891

W
WAIT 675 WaitForApplication 1519 WaitOnDialog 1522 WaitOnDialog Example 1523 WARNING 235, 1384 WAV files 1061 WEB_BASED_SETUP 235 WELCOME 235 Welcome 1525 Welcome Example 1526 while 25 WHITE 235, 1352 WILL_REBOOT 236, 1215 WINDIR 314 Windir environment variable 1067 WINDISK 314 Window 1352 getting handle for 904 placing 1057
1580

Windows 925 Windows Installer APIs 425 sample script 432 Windows Installer Functions 425 Windows NT 1099 adding icons 457 administrator 912 GetProfInt 883 InstallShield system variables 281 program group type 1066 remote registry 1099 Service Pack number 920 setting group type 1066 USERPROFILE 1067 WINDOWS_SHARED 236, 912 API 1384 disk 314 DLLs 1479 folder 314 identifying shell 1071 InstallShield system variables 281 restart 1078 setting main window title 1352 System folder 316 windir environment variable 871 WINMAJOR 236, 891 WINMINOR 236, 891 WINSYSDIR 315 WINSYSDIR64 315 WINSYSDISK 316 WizardDirection 1527 WM_COMMAND 1522 Working with Batch Files 381 WOW64FSREDIRECTION 237 WRITE_DAC 237 WRITE_OWNER 237 WriteArrayProperty 1528 WriteBoolProperty 1529 WriteBytes 1530 WriteBytes Example 1531 WriteLine 1532 WriteLine Example 1533 WriteNumberProperty 1535 WriteProfInt 1535 WriteProfInt Example 1537 WriteProfString 1538 WriteProfString Example 1539

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide

Index

WriteProperties 453 WriteStringProperty 1540 Writing 994 binary files 1530 initialization files 1538 text files 1532 WSTRING data type 247

X
XCopyFile 1541 XCopyFile Example 1545

Y
YELLOW 237, 1352 YES 238, 481

InstallShield 2012 InstallScript Reference Guide

ISP-1800-RG00

1581

Index

1582

ISP-1800-RG00

InstallShield 2012 InstallScript Reference Guide